Polymarket 是按未平仓量计当前最大的去中心化预测市场，二元合约在 Polygon 链上结算，由 USDC 抵押。它的 API 拆成三套独立的子系统 —— Gamma（发现）、Data（分析）、CLOB（盘口 + 交易）—— 而且交易这一半刚刚完成了一次 breaking 的 V2 升级。本指南是对 V2 切换之后 API 现状的忠实讲解，基于 docs.polymarket.com 在 CLOB V2 上线后的最新文档校准。如果你参考的博客里出现 nonce、feeRateBps、USDC.e 或 @polymarket/clob-client（没有 -v2 后缀），先扫一遍 §0 —— 这些引用在切换那天就停止工作了，旧代码会静默失效。
0. V2 切换改了什么
Polymarket 在 2026-04-28 把 CLOB 切到了 V2 合约（迁移文档说 4/22；4/17 写的 changelog 把实际切换日期定在 4/28 —— 上线前请去 status.polymarket.com 复查）。Order struct 大概一半字段变了，抵押币从 USDC.e 换成了 pUSD，SDK 包名也换了。差异：
| 主题 | 旧版 (V1, 2026-04-28 退役) | 当前版 (V2) |
|---|---|---|
| Order struct 移除 | nonce、feeRateBps、taker | （已移除 —— 不要再传） |
| Order struct 新增 | — | timestamp (ms)、metadata (bytes32)、builder (bytes32) |
| 手续费 | 嵌入到签名订单里 | 撮合时由协议设定，不在订单上 |
| EIP-712 Exchange domain | version: "1"，V1 verifyingContract | version: "2"，V2 verifyingContract（neg-risk 用不同地址） |
| Builder 归因 | 单独 SDK + 4 个 POLY_BUILDER_* headers | 订单里一个 builder 字段 (bytes32) |
| 抵押币 | USDC.e（桥接） | pUSD（1:1 USDC 担保） |
| TypeScript SDK | @polymarket/clob-client | @polymarket/clob-client-v2 |
| Python SDK | py-clob-client | py-clob-client-v2 |
| Constructor | 位置参数，chainId | options 对象，chain |
切换没动、但容易踩的三件事：L1 ClobAuthDomain 永远是 version: "1"（这是鉴权 domain，与 Exchange domain 不同）；POLY_TIMESTAMP headers 还是 秒（只有 Order struct 的 timestamp 字段是毫秒）；地理封锁没变 —— 美国、英国、欧盟大多数国家仍然完全无法交易。
1. 30 秒：第一个 Polymarket API 响应
Polymarket 最快的一次调用根本不需要鉴权。Gamma API 公开发布所有市场和事件元数据，单个请求就能拉到。从这步出发再决定要不要鉴权 —— 只有交易需要签名；读盘口、价格、历史、持仓、成交都不要。
curl -sS 'https://gamma-api.polymarket.com/markets/keyset?limit=5' \
| jq '.markets[] | {slug, question, outcomes, last_trade_price}'
npx parlay-mcp@latest
>>> polymarket.list_markets(limit=5)
同一查询：直接 HTTP vs 走 Parlay 的预测市场 MCP。
两个开始之前要知道的事：
- 交易在美国、英国、法国、德国和很多其他司法辖区被完全封锁。 新加坡、波兰、泰国、台湾是 close-only（能平仓不能开新仓）。读端点不被封锁。 在被封地区可以做研究、做 dashboard、做聚合，唯独不能下单。
- 旧教程引用的 V1 字段已失效。 出现
nonce、feeRateBps、taker、USDC.e 或@polymarket/clob-client（没-v2）就是 V1，2026-04-28 之后停止工作。本指南整篇基于 V2。
2. 概念入门：market、token、三套 API
Polymarket 的数据模型与多数交易所 API、与 Kalshi 都不一样，前一小时的困惑很多来自跳过模型直接做鉴权。
Event / Market / Token：现实问题（"2028 美国总统大选谁赢？"）= event；每个候选人一个 market（"Trump 会赢吗？"YES/NO 二元）；每个 market 的每一边（YES / NO）是一个独立的 ERC-1155 token，各有自己的 asset_id。盘口在 token 层级而非 market 层级 —— 同一 market 的 YES 和 NO 是两个独立的 book。condition_id 是链上 market ID（CTF Exchange 合约用），asset_id 是 token ID（你向 /book、/price、POST /order 传的就是这个）。
三套独立的 API：
| API | Base URL | 用途 | 鉴权 |
|---|---|---|---|
| Gamma | gamma-api.polymarket.com | 发现：markets、events、tags、search、profiles | 公开 |
| Data | data-api.polymarket.com | 分析：positions、trades、leaderboard、open interest | 公开 |
| CLOB | clob.polymarket.com | 实时盘口 + 交易：orderbook、prices、orders | 读公开；下单需 L1+L2 |
Negative risk markets：N 选 1 的互斥事件（典型例子：2028 总统大选所有候选人 markets）。读盘口拿到的 neg_risk: true 字段决定 EIP-712 Exchange domain 用哪个 verifyingContract —— 用错的话签名是合法的（但对错误 domain），撮合引擎拒绝为 invalid signature。SDK 自动处理，自己写就要先读 /book 的 neg_risk。
3. 鉴权：L1 (EIP-712) + L2 (HMAC) 分步走
Polymarket 的鉴权分两层。先想清楚分层逻辑再写代码。
L1 (EIP-712, 每个 key 跑一次)：钱包级身份。用钱包私钥对固定 message 签 EIP-712（domain ClobAuthDomain、version "1"、chainId 137）。带 5 个 POLY_* header，一次性拿凭证用。
L2 (HMAC-SHA256, 每个请求都跑)：请求级身份。L1 给你 apiKey (UUID)、secret (base64)、passphrase (随机串)。每个 CLOB 鉴权请求 HMAC 签 timestamp + method + path + body。5 个 POLY_* header 携带 API key、passphrase、timestamp、address、签名。
三件易踩的事：
ClobAuthDomain永远version: "1"，V2 切换后也不变。只有 Exchange domain（签订单用）升到version: "2"。- L1 / L2 timestamp 都是 Unix 秒，不是毫秒。（Polymarket 全平台只有 Order struct 的
timestamp字段是毫秒，§6。） signer≠funder。Magic Link / Gnosis Safe proxy wallet 模式下，签名地址和持仓地址是两个不同的地址。signatureType设对：0= 普通 EOA；1= Magic Link / Google login proxy；2= Gnosis Safe（公网最常见）。
Step 2 — 完整签名实现
完整 Python / TypeScript / cURL 三语言实现见英文版 polymarket-api.mdx §3 Step 2，照搬 docs.polymarket.com 的官方示例 —— L1 derive 凭证 + L2 签名两段都包含。
Step 3 — 四个真实陷阱
陷阱 A — signer 与 funder 混用。 Gnosis Safe 模式下 maker 必须是 funder（Safe 地址），不是 signer（你的 EOA）。错了报 the order owner has to be the owner of the API KEY。
陷阱 B — 两个 EIP-712 domain 混淆。 ClobAuthDomain (L1) 永远 v1；Exchange domain (订单) v2。复制粘贴时容易串。
陷阱 C — 毫秒 vs 秒。 两类 POLY_TIMESTAMP 都是秒；Order struct 的 timestamp 是毫秒。看起来一样的字符串，错了不立即报错。
陷阱 D — 私钥管理。 Polymarket 不托管私钥；丢了无法找回。生产环境用 secrets manager + Gnosis Safe 而非 hot EOA，方便轮换。
Step 5 — 同一调用，三层抽象
# 见英文版 §3 Step 5：完整 L1 derive + Gamma keyset 分页 ≈ 60 行
from py_clob_client_v2 import ClobClient
from py_clob_client_v2.constants import POLYGON
client = ClobClient(host="https://clob.polymarket.com", chain=POLYGON,
key="0x...", signature_type=2, funder="0x...")
client.derive_api_key()
markets = list(client.gamma.markets(tag_id="trump-2028"))
from parlay import Parlay
p = Parlay()
markets = p.polymarket.list_markets(tag="trump-2028")
kalshi = p.kalshi.list_markets(series="KXPRES") # 同一形状跨平台
≈ 60 行 → 10 行 → 3 行；只有第三个能跨平台。
4. 三套 API 的核心端点
完整端点目录见英文版 §4。要点：
- Gamma（发现，无鉴权）：
/markets/keyset、/events/keyset、/markets/{slug}、/search、/tags、/sports。新代码统一用 keyset 端点；旧的 offset 分页将废弃。 - CLOB 读端点（无鉴权）：
/book?token_id=...（bids 和 asks 都返回，与 Kalshi 相反）、/price、/midpoint、/spread、/prices-history（fidelity 1m–1w）、/ohlc、/tick-size、/fee-rate。下单前一定要读/book拿tick_size和neg_risk。 - CLOB 交易端点（L2 + EIP-712 订单签名）：
POST /order（单笔）、POST /orders（最多 15 笔批量）、DELETE /order/{id}、DELETE /cancel-all、POST /heartbeat（dead-man's switch）、GET /orders、GET /trades。 - Data（分析，无鉴权）：
/positions、/closed-positions、/activity、/trades、/holders、/leaderboard、/open-interest。
5. 分页与限流：throttle 而非 reject
详见英文版 §5。要点：
- Keyset / cursor 分页：
/markets/keyset和/events/keyset用after_cursor，最后一页省略next_cursor。给 keyset 端点传offset会返回 422 —— 不允许混用。 - Cloudflare 限流，无 tier：所有用户共享。超限不立即 429，而是 throttle（排队 / 慢响应）。常见 10 秒窗口：Gamma 4,000、
/markets300、Data 1,000、CLOB 9,000、/book1,500、TradingPOST /orderburst 3,500/10s + sustained 36,000/10min。 - 重要陷阱：很多 retry 库把"5 秒没响应"当作失败重试 —— 在 Polymarket 上反而把 throttle 队列加长。把 client timeout 设到 30 秒，只在真 429 / 5xx 上重试。
- Trading 端点有 burst + sustained 双层：单次冲量没问题，10 分钟均速也得控好。
# 见英文版 §5 Step 2：cursor 持久化 + 30s timeout + throttle-aware 退避
from parlay import Parlay
p = Parlay()
markets = p.polymarket.list_markets(tag="trump-2028", all_pages=True)
60 行生产级 keyset paginator → 一行调用。
6. 下单：V2 order struct + 4 种类型 + EIP-712
整段详见英文版 §6。
4 种 order type：GTC（默认，挂单直到撤）、FOK（必须立刻全成交否则全撤）、GTD（到 expiration 自动撤）、FAK（立刻成交能成的部分剩余撤；2025-05-28 新增 —— 旧教程通常没有）。
V1 → V2 字段差异（每条都是踩过的坑）：
| 字段 | V1 | V2 |
|---|---|---|
nonce / feeRateBps / taker | 必填 | 移除 |
timestamp (ms) / metadata / builder | 不存在 | 新增 |
Exchange domain version | "1" | "2" |
verifyingContract | V1 地址 | V2 地址（neg-risk 用不同地址） |
V1 字段没删干净最常见的报错是 Invalid order payload。先 grep 代码里有没有 nonce、feeRateBps、taker。
3 个生产陷阱：tick_size 不查死价格违反 → Price breaks minimum tick size rule；neg_risk 用错合约 → invalid signature；Gnosis Safe 时 maker = funder ≠ signer 别搞反。
# 见英文版 §6.5：完整 V2 Order struct（含 timestamp/metadata/builder 不含 nonce/feeRateBps/taker）
# + Exchange domain v2 EIP-712 签名 + L2 headers ≈ 80 行
from parlay import Parlay
p = Parlay()
resp = p.polymarket.place_order(
token_id="102936...",
side="BUY", price=0.45, size=100.0, order_type="GTC",
)
# tick_size、neg_risk verifyingContract、V2 字段、签名、L2 都自动处理
≈ 80 行 EIP-712 + struct + 提交 → 一行调用。
7. WebSocket 实时数据
完整代码见英文版 §7。
- Market channel（公开）：
wss://ws-subscriptions-clob.polymarket.com/ws/market，订阅{"assets_ids": [...], "type": "market"}。心跳是客户端发起（每 10 秒发{}，与 Kalshi 相反）；忘记发 ~30 秒后服务端断你。事件类型book、price_change、last_trade_price、tick_size_change。 - User channel（L2 鉴权）：
/ws/user，鉴权放在 订阅消息的auth字段 而不是连接 header。事件order和trade。 - 2025 重要变化：100 token 订阅上限已移除；
price_changepayload 字段名 2025-09-15 改过（changes→price_changes）—— 旧 parser 会静默丢更新。
8. 常见错误及修复
完整 17 条详见英文版 §8。挑几个高频的：
9. 跨平台聚合
如果应用只跟 Polymarket 打交道，官方 clob-client-v2 已经够用，重新写一遍 EIP-712 没价值。
差异化的场景从"跨平台"开始：Polymarket 是 4 个二元事件价格主源之一，另外是 Kalshi（CFTC 监管、美国本土、RSA-PSS）、Manifold（玩具币、REST、API key）、Opinion.trade（英国监管、REST + GraphQL、API key）。每家自己一套鉴权、分页、限流和市场标识符 —— Polymarket 自己就是三套 API，加上其他三家做四方聚合是真实工作量。
具体差距：鉴权 4 套；schema Polymarket asset_id + condition_id、Kalshi 字符串 ticker、Manifold question slug、Opinion.trade GraphQL node ID；限流 Cloudflare throttle / token bucket / 简单 RPS / tiered API 各不相同；价格表达 0–1 字符串 / 定点美元 / 百分比 double / 便士整数。
Parlay 的 MCP server 把这一层做了：四家上 list_markets、get_orderbook、place_order 是同一组调用，标识规范化，鉴权统一。Polymarket 特有的 neg-risk verifyingContract、V2 订单签名、三套 API 拆分仍能下钻访问。单平台用官方 SDK；跨平台才是 Parlay 价值层。配套阅读：Kalshi API 指南、Polymarket vs Kalshi 对比。
10. 常见问题
11. 下一步
如果你专注 Polymarket，下一步建议看官方 rate-limits 页 和 V2 迁移指南。如果是多平台，看本站的 Kalshi API 指南 和 Polymarket vs Kalshi 平台对比。