几行代码，把整天 Polymarket 盘口、成交与链上交割拉回本地。

60 秒上手

在 账户中心 创建一把 API Key（格式如 ck_26b2e758d05d.Gdyk-ZieGdBCeo2yFCj13t51GLzM95zU），放进环境变量即可开始：

export API_KEY="ck_26b2e758d05d.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export BASE_URL="https://your-domain.example"

1. 看一眼有哪些数据（以及你的订阅窗口）

curl -s "$BASE_URL/v1/meta" \
  -H "Authorization: Bearer $API_KEY" | jq

返回示例：

{
  "firstDay": "2026-02-23",
  "lastDay": "2026-10-24",
  "days": 146,
  "venues": ["polymarket"],
  "assets": ["BTC", "ETH", "SOL", "XRP", "BNB", "DOGE", "HYPE"],
  "intervals": ["5m", "15m"],
  "datasets": {
    "polymarket": [
      "book",
      "trades",
      "activity_trades",
      "onchain_fills",
      "spot_snapshots",
      "twap30s",
      "twap60s",
      "markets",
      "binance_spot"
    ]
  },
  "scope": {
    "expiresMs": 1795409052124,
    "floor": "2026-02-23",
    "ceiling": "2026-10-24"
  }
}

2. 列出某一天的文件清单

curl -s "$BASE_URL/v1/files?asset=btc&interval=15m&date=2026-10-23" \
  -H "Authorization: Bearer $API_KEY" | jq

返回结果里的每个文件对象都自带可直接下载的 url、bytes、rows 与 sha256：

{
  "from": "2026-10-23",
  "to": "2026-10-23",
  "days": 1,
  "count": 8,
  "bytes": 54128940,
  "files": [
    {
      "date": "2026-10-23",
      "name": "BTC-15m-polymarket-book-2026-10-23.parquet",
      "venue": "polymarket",
      "dataset": "book",
      "asset": "BTC",
      "interval": "15m",
      "bytes": 38412096,
      "rows": 214890,
      "sha256": "8f9d2a7c1e4b3081a9c2e0f1d7b6a5c4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8",
      "url": "https://your-domain.example/v1/dl/2026-10-23/BTC-15m-polymarket-book-2026-10-23.parquet"
    },
    {
      "date": "2026-10-23",
      "name": "BTC-15m-polymarket-trades-2026-10-23.parquet",
      "venue": "polymarket",
      "dataset": "trades",
      "asset": "BTC",
      "interval": "15m",
      "bytes": 4192304,
      "rows": 48210,
      "sha256": "40f2863235c4fd947dfb05ed30bf56bdbdf981f14cc6c22904c2d6388c1f343d",
      "url": "https://your-domain.example/v1/dl/2026-10-23/BTC-15m-polymarket-trades-2026-10-23.parquet"
    }
  ]
}

3. 下载到本地

拿上面任意一条的 url，加 -L 跟随 302 跳转到签名地址即可流式落盘：

curl -L "$BASE_URL/v1/dl/2026-10-23/BTC-15m-polymarket-trades-2026-10-23.parquet" \
  -H "Authorization: Bearer $API_KEY" \
  -o BTC-15m-polymarket-trades-2026-10-23.parquet

在 Python / Polars / DuckDB 里一行读入

下载端点 /v1/dl/:date/:name 同时支持 ?api_key= 查询参数，因此无需先下载到本地磁盘，就能直接把 URL 交给常用数据分析引擎：

import os, requests, pandas as pd

KEY = os.environ["API_KEY"]
BASE = "https://your-domain.example"

r = requests.get(
    f"{BASE}/v1/files",
    params={"asset": "btc", "interval": "15m", "dataset": "trades", "date": "2026-10-23"},
    headers={"Authorization": f"Bearer {KEY}"},
)
r.raise_for_status()

for f in r.json()["files"]:
    df = pd.read_parquet(f"{f['url']}?api_key={KEY}")
    print(f["name"], len(df), df.columns.tolist())

import polars as pl
import duckdb

url = f"https://your-domain.example/v1/dl/2026-10-23/BTC-15m-polymarket-book-2026-10-23.parquet?api_key={KEY}"

# Polars 直接扫描
df = pl.read_parquet(url)

# DuckDB 直接 SQL 聚合
res = duckdb.sql(f"""
  SELECT outcome, COUNT(*) AS snapshots, AVG(spread) AS avg_spread
  FROM read_parquet('{url}')
  GROUP BY outcome
""").df()

常见任务

拿最新一天的数据

每日归档在 UTC 次日凌晨自动封盘同步。脚本无需硬编码日期，先读 /v1/meta 的 lastDay 再拉列表：

LAST=$(curl -s "$BASE_URL/v1/meta" -H "Authorization: Bearer $API_KEY" | jq -r .lastDay)
curl -s "$BASE_URL/v1/files?date=$LAST&asset=btc" -H "Authorization: Bearer $API_KEY" | jq

批量拉整月数据并校验 SHA-256

列表里的每条文件都带 sha256，配合 sha256sum -c 可以确保网络传输零损坏、断点可重入：

curl -s "$BASE_URL/v1/files?asset=btc&interval=15m&dataset=trades&from=2026-10-01&to=2026-10-23" \
  -H "Authorization: Bearer $API_KEY" \
| jq -r '.files[] | "\(.url) \(.name) \(.sha256)"' \
| while read -r url name sha; do
    curl -sL "$url" -H "Authorization: Bearer $API_KEY" -o "$name"
    echo "$sha  $name" | sha256sum -c -
  done

把多天拼成一张 DataFrame

files = requests.get(
    f"{BASE}/v1/files",
    params={"asset": "btc", "interval": "15m", "dataset": "twap60s", "from": "2026-10-01", "to": "2026-10-23"},
    headers={"Authorization": f"Bearer {KEY}"},
).json()["files"]

df = pd.concat([pd.read_parquet(f"{f['url']}?api_key={KEY}") for f in files], ignore_index=True)

API 端点参考

所有端点只读、幂等，均使用 GET。支持以下任意一种方式传入 API Key：

• 请求头（推荐）：Authorization: Bearer ck_... 或 X-API-Key: ck_...
• 查询参数（方便交给下载器 / Parquet 引擎）：?api_key=ck_...

状态码与错误响应

字段规格 (Schemas)

标准文件名格式为 {ASSET}-{INTERVAL}-polymarket-{DATASET}-{YYYY-MM-DD}.parquet （例如 BTC-15m-polymarket-trades-2026-10-23.parquet）。 跨周期全市场链上表与结果表命名为 ALL-polymarket-{DATASET}-{YYYY-MM-DD}.parquet。 所有时间戳统一为 UTC 微秒（timestamp_us）或毫秒整数。