polymarket-api

Polymarket API

Polymarket 是运行于 Polygon 主网上的预测市场。每个市场都由 Conditional Token Framework（CTF）发行的一对 YES/NO ERC-1155 代币组成，并以 USDC 按 1:1 抵押。链下通过 CLOB 撮合，链上结算，吃单者零手续费。价格以 [0.00, 1.00] USDC 计价；每个市场的 YES + NO ≈ 1.0。

---

编写任何 API 代码之前——请先阅读最新文档。

• 文档：https://docs.polymarket.com
• 官方 Python SDK：https://github.com/Polymarket/py-clob-client

Polymarket 的端点和身份验证流程可能会在不另行通知的情况下变更。优先使用官方 py-clob-client SDK，而不是手动编写 HTTP 请求；它会处理 EIP-712 派生、API 凭据管理和订单签名。只有在 SDK 未提供所需功能时，才手动编写。

---

标识符模型

你会用到四种不同的 ID——如果混淆它们，查询可能会悄无声息地返回错误数据。

ID	含义
condition_id	市场的链上十六进制 ID（CTF 条件）
clob_token_ids	YES/NO ERC-1155 代币 ID 对——由两个元素组成的列表
token_id	单个结果代币——用于订单簿和 WebSocket 查询
event_id	父级分组（例如“今天纽约市最高气温”的所有区间）

---

快速开始

1. 读取市场——Gamma API（无需身份验证）

import httpx

# CRITICAL: default sort is OLDEST-first — always override or you silently get closed markets
events = httpx.get("https://gamma-api.polymarket.com/events", params={
    "tag_id": 103040,        # category tag (e.g. weather)
    "order": "endDate",
    "ascending": "false",    # must be string "false", not bool
    "closed": "false",
}).json()

# Each event → markets[], each market has:
#   condition_id, clob_token_ids (YES/NO pair), question, outcomes, outcomePrices
for event in events:
    for mkt in event.get("markets", []):
        yes_token, no_token = mkt["clobTokenIds"]  # split the pair here
        print(mkt["question"], mkt["outcomePrices"])

分页：limit=100&offset=N，每次递增 100。

2. 订单簿和交易——CLOB API（EIP-712 身份验证）

uv pip install py-clob-client

import os
from py_clob_client.client import ClobClient

client = ClobClient(
    "https://clob.polymarket.com",
    chain_id=137,                                     # Polygon mainnet
    key=os.environ["POLYMARKET_PRIVATE_KEY"],          # wallet private key — env only, NEVER hardcode
    signature_type=2,                                  # 2 = Gnosis Safe proxy (Polymarket UI accounts)
                                                       # 0 = direct EOA you fully control
)
# Derives API key/secret/passphrase from the wallet signature — call once per session
client.set_api_creds(client.create_or_derive_api_creds())

token_id = "<yes_token_from_clob_token_ids>"
book = client.get_order_book(token_id)     # bids/asks for one outcome token
price = client.get_price(token_id, side="BUY")

signature_type=2 适用于 Polymarket 网页界面创建的代理/Safe 账户（出资方地址是 Safe）。如果直接使用你控制的普通 EOA，请使用 signature_type=0。请阅读最新 SDK 文档——所选类型会影响订单在链上的签名方式。

钱包环境变量：POLYMARKET_PRIVATE_KEY、POLYMARKET_FUNDER。切勿将密钥硬编码。

---

API 概览

API	主机	身份验证	用途
Gamma	https://gamma-api.polymarket.com	无	事件/市场/条件/价格元数据
CLOB	https://clob.polymarket.com	EIP-712	订单簿、下单/撤单
Data	https://data-api.polymarket.com	无	历史交易
WebSocket	wss://ws-subscriptions-clob.polymarket.com/ws/	无（市场）/ JWT（用户）	实时订单簿 + 交易变动

链：Polygon 主网，chain_id=137。抵押品：位于 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 的 USDC.e。

---

WebSocket

# Connect to: wss://ws-subscriptions-clob.polymarket.com/ws/market
# Subscribe message:
{"type": "market", "assets_ids": ["<token_id>", "<token_id2>"]}

事件类型：book（订阅时发送完整快照）、price_change（增量更新）、last_trade_price。

如需接收用户级订单/成交事件，请使用 API 凭据派生 JWT，并连接到 /ws/user。

---

链上结算和赎回

Polymarket 天气市场通过 Weather Underground（“History”标签页）结算，采用都会区的当地时间（含夏令时），从午夜到午夜。这与使用 LST（不含夏令时）和 NWS CLI 的 Kalshi 不同——有关差异，请参见 kalshi-weather-markets。

结算后，必须手动在链上赎回获胜代币：

# Call CTF contract redeemPositions() — the SDK or direct web3.py call
# Winnings are NOT auto-swept to your wallet

国际盘的争议会升级至 UMA 乐观预言机（代币持有者投票）。与 Kalshi 由 CFTC-CCP 结算相比，这确实存在结算结果不一致的风险——进行任何跨平台比较时都应考虑这一点。

---

美国地理位置 / KYC 限制

禁止美国人士使用 Polymarket。从美国 IP 发起的 API 调用通常需要通过获准司法管辖区的 SOCKS5 代理（使用 USE_PROXY 环境变量标记模式；切勿硬编码代理地址）。这一限制，再加上链上资金锁定以及 USDC/USD 转换摩擦，是大多数 Kalshi/Polymarket 套利难以在零售规模上执行的原因。

---

交叉引用

• 有关适用于各平台的策略、仓位规模和回测：prediction-market-strategy
• 有关 Kalshi 对应内容（RSA-PSS 身份验证、REST 主机、代码、订单架构）：kalshi-api
• 有关天气结算细节（WU 当地时间 + 夏令时与 Kalshi LST、KLGA 与 KNYC 气象站）：kalshi-weather-markets

---

文件

参考资料

• references/clob-and-gamma-apis.md — 完整的 API 概览、所有端点、EIP-712 身份验证详情、分页、订单架构、交易参数默认值
• references/settlement-and-ops.md — WU/UMA 结算、redeemPositions、真值来源优先级（IEM > WU > Open-Meteo）、已知异常日期、地理位置/KYC、主机隔离、双交易所架构说明