Polymarket API 全景图：Gamma、CLOB 与 Data API
新手总会因为同一个问题浪费一天：Polymarket 没有一个 API，而是有四个，你想要的端点很少在你第一个尝试的那个上。这是一份完整的地图。
关于 Polymarket API，首先要明白的是：并不存在一个单一的 Polymarket API。它有四个 REST API 和四个 WebSocket 数据流，各自负责集成中的不同部分，各自有独立的主机名、速率限制和认证要求。
几乎每一个“Polymarket API 没有 X”的问题，最后都会变成“X 在另一个主机上”。下面把全部接口集中在一处。
四个 REST API
| API | Base URL | 用途 | 认证 |
|---|---|---|---|
| Gamma | gamma-api.polymarket.com | 发现事件和市场；元数据 | 无 |
| CLOB | clob.polymarket.com | 价格、订单簿、下单和管理订单 | 读取无需认证，交易需要 L1/L2 |
| Data | data-api.polymarket.com | 持仓、活动、市场参与情况 | 无 |
| Relayer | relayer-v2.polymarket.com | 无需持有 POL 支付 gas 即可提交钱包交易 | 签名 |
30 秒路由规则
有哪些市场？→ Gamma。价格是多少 / 我要交易 → CLOB。这个钱包持有什么？→ Data API。我需要在没有 gas 的情况下转移资金 → Relayer。如果你在 CLOB 里找事件端点，或在 Gamma 里找订单簿，那就找错了。
Gamma API：发现与元数据
Gamma 是起点。它回答有什么：事件、事件中的市场、标签、搜索，以及处理其他一切所需的元数据，其中最关键的是每个 CLOB 端点都需要的代币 ID。
/events：列出事件，支持键集分页/markets：列出市场；还支持by id、by slug、by token/public-search：跨事件和市场搜索/tags、/comments：分类和讨论- 未平仓量、实时成交量、主要持有人
/markets 的限制是全平台最严格的
每 10 秒 300 次请求，比 Gamma 自己每 10 秒 4,000 次的通用限制严格 13 倍。如果你在循环中对完整市场列表分页，最先出问题的就是它。缓存市场元数据；在一个市场的生命周期内它几乎不变。完整数字见速率限制参考。
CLOB API：价格、订单簿与订单
订单簿本身，也是唯一可以交易的地方。读取是公开的；交易需要凭证。
| 分组 | 端点 | 认证 |
|---|---|---|
| 订单簿 | /book、/books、/midpoint、/midpoints、/spread、/spreads | 公开 |
| 定价 | /price、/prices、/prices-history、最新成交价、/tick-size、费率 | 公开 |
| 订单 | POST /order、POST /orders、DELETE /order、/orders、/cancel-all、/cancel-market-orders | L2 + 钱包签名 |
| 账本 | /trades、/data/orders、/data/trades、/notifications | L2 |
| 认证 | /auth/api-key、/auth/api-keys、/auth/derive-api-key | L1 |
| 账户 | 余额授权额度（查询 / 更新） | L2 |
单数与复数是实实在在的区别
几乎每个 CLOB 市场数据端点都有一个批量版本：/book 和 /books，/price 和 /prices。单数端点的限制是每 10 秒 1,500 次，复数端点是每 10 秒 500 次，但一次复数调用可以覆盖许多代币，所以批量请求在每单位速率限制额度下能拿到多得多的数据。基本上永远优先用 /books，而不是循环调用 /book。
Data API：持仓与活动
面向投资组合的问题：/positions、/closed-positions、/trades，以及用户盈亏 API。注意，它是三个主要 API 中限制最严格的：通用限制为每 10 秒 1,000 次，/positions 和 /closed-positions 各自只有每 10 秒 150 次。它是为仪表盘设计的，而不是为轮询循环。
四个 WebSocket 数据流
如果你正在用定时器轮询 /book，停下来：数据流正是为此而生的。轮询是白白耗尽速率限制额度最常见的方式。
| 数据流 | URL | 内容 |
|---|---|---|
| CLOB Market | wss://ws-subscriptions-clob.polymarket.com/ws/market | 公开的订单簿、价格和市场生命周期更新 |
| CLOB User | wss://ws-subscriptions-clob.polymarket.com/ws/user | 你账户的已认证订单和成交更新 |
| RTDS | wss://ws-live-data.polymarket.com | 公开的参考价格、评论、交易动态 |
| Sports | wss://sports-api.polymarket.com/ws | 实时比赛状态和比分 |
User 频道是大家最容易忽略的。如果你的机器人轮询 /data/orders 来确认订单是否成交，你就是在为 User 频道会在第一时间推送给你的信息支付速率限制额度，而且延迟还更高。
认证：L1 与 L2
公开市场数据完全不需要凭证：你可以用一个裸的 curl 直接访问 Gamma、CLOB 读取端点和 Data API。交易需要两层认证，弄清楚哪层是哪层，就能解决大多数认证错误。
| 层级 | 工作方式 | 用途 |
|---|---|---|
| L1 | 钱包对一条 EIP-712 消息签名 | 证明对钱包的控制权；创建或派生 API 凭证 |
| L2 | 使用 API 凭证以 HMAC-SHA256 对请求签名 | 认证私有 CLOB 请求 |
下单同时使用两者：L2 认证请求，钱包签名授权订单。L1 类型化数据是一个位于 chainId: 137（Polygon）上的 ClobAuth 载荷，包含你的签名者地址、以秒为单位的 Unix 时间戳、一个 nonce（除非你在管理多套凭证，否则用 0），以及固定的消息字符串。
获取 API 密钥
- 用你的 Polygon 私钥对
ClobAuthEIP-712 载荷签名。 - 带上 L1 请求头调用
POST /auth/api-key来创建凭证。你会拿到一个 key、一个 secret 和一个 passphrase，L2 三者缺一不可。 - 之后运行时，调用
GET /auth/derive-api-key来获取已有的凭证，而不是创建新的。
占据大多数支持问题的两种认证失败
凭证不完整：L2 需要 key、secret 以及 passphrase；只有其中两样，会产生一个格式正确但签名无法验证的请求。时钟漂移：签名中嵌入了时间戳，所以时钟偏差几秒的容器产生的签名会被服务器判定为无效。两者都表现为 Unauthorized/Invalid api key，这也是这条消息被如此广泛搜索的原因。见错误参考。
SDK
Polymarket 维护着统一的 TypeScript 和 Python SDK，用类型化接口封装了上述全部内容，并处理分页、错误格式和钱包设置。如果你用其中任一语言从头开始，就用它们：手写 EIP-712 签名和 HMAC 请求签名，是一种非常容易出错的打发周末的方式。
当你的运行时不在 SDK 覆盖范围内、当你需要精确控制签名、请求头、重试或传输方式，或者当你需要一个 SDK 尚未暴露的端点时，就直接使用 REST。注意这些是统一 SDK：如果你在用旧客户端，有文档化的迁移路径，而大量凭证过时的 bug 正是来自旧客户端。
Polymarket API 要花多少钱？
不花钱。没有付费档，没有 API 价格页，也没有订阅：Polymarket 的 API 免费使用，访问受速率限制而不是计费约束。公开市场数据甚至不需要密钥。
唯一与钱挂钩的是按签名者计算的交易限制，它按你的 maker 钱包 30 天成交量分档，从 Standard 的每秒 40 个订单令牌到 Elite 的 600 个，但那是吞吐量分配，而不是费用。
这些 API 都给不了你的一样东西
梳理完全部接口之后，值得知道的是什么不在其中：历史订单簿深度。
上面的每个端点提供的都是当前状态。/book 返回的是现在的订单簿。/prices-history 给你价格，但没有深度，所以它无法告诉你当时的成交会是什么样。而当市场结算后，/book 返回 404。剩下的只是一条稀疏的价格序列，大约每分钟一个点，需要显式传入开始和结束时间才能获取。任何套餐或速率限制档位都改变不了这一点。
| 问题 | 能通过 Polymarket API 回答吗？ |
|---|---|
| 现在的订单簿是什么样？ | 能：/book |
| 昨天的价格是多少？ | 能，大约每分钟一个点，通过带开始和结束时间的 /prices-history |
| 昨天 14:03:17 的深度是多少？ | 不能 |
| 我那笔 500 份的订单当时会以什么价格成交？ | 不能 |
| 给我看一个上周结算的市场 | 它的记录和结果可以（closed=true）。它的订单簿不行。 |
这个缺口正是为什么回测 Polymarket 策略需要一个在市场运行期间记录了订单簿的独立数据源。PolyTest 为加密货币 Up/Down 市场做的正是这件事：240M+ 条时点快照，每边 8 档深度，亚秒级时间戳，已结算的市场会被保留而不是丢弃。一个请求头，干净的 JSON，还有 3 天免费试用：
curl -H "X-API-Key: $POLYTEST_KEY" \
"https://api.polytest.io/api/v1/markets?coin=btc&market_type=5m&limit=20"完整端点参考见 PolyTest 文档，或开始免费试用。
常见问题
- Polymarket API 有哪些端点？
- Polymarket 运行着四个 REST API：Gamma（gamma-api.polymarket.com）用于事件、市场和元数据；CLOB（clob.polymarket.com）用于价格、订单簿和交易；Data API（data-api.polymarket.com）用于持仓和活动；Relayer（relayer-v2.polymarket.com）用于免 gas 交易。另外还有四个 WebSocket 数据流，覆盖公开的 market 频道、需要认证的 user 频道、实时数据和体育。
- Polymarket API 免费吗？
- 免费。没有付费档、订阅或 API 价格页：访问受速率限制而不是计费约束，公开市场数据完全不需要 API 密钥。唯一会变化的是按签名者计算的交易吞吐量档位，它基于你钱包 30 天的交易量，而不是付费。
- 如何获取 Polymarket API 密钥？
- 用你的 Polygon 私钥对 ClobAuth EIP-712 类型化数据载荷签名，然后带上 L1 请求头调用 POST /auth/api-key 创建凭证。你会收到 key、secret 和 passphrase，L2 请求签名三者都需要。之后运行时使用 GET /auth/derive-api-key 获取已有凭证，而不是创建新的。公开市场数据不需要密钥。
- Gamma API 和 CLOB API 有什么区别？
- Gamma 用于发现：有哪些事件和市场、它们的元数据，以及其他端点需要的代币 ID。CLOB 用于订单簿：当前价格、订单簿深度，以及下单或撤单。如果你需要找到一个市场，用 Gamma；如果你需要给它定价或交易它，用 CLOB。
- Polymarket 有 Python SDK 吗？
- 有。Polymarket 维护着统一的 TypeScript 和 Python SDK，用类型化接口覆盖全部四个 REST API，并处理分页、错误格式和钱包设置。从旧客户端迁移有文档化的路径。当你的运行时不受支持、需要精确控制签名和重试，或者需要 SDK 尚未暴露的端点时，直接使用 REST 才有意义。
- 能从 Polymarket API 获取历史订单簿深度吗？
- 不能。Polymarket 的每个端点提供的都是当前状态。/prices-history 端点返回一条大约每分钟一个点的价格序列，没有背后的深度，所以它无法告诉你某个订单规模当时会以什么价格成交；已结算市场的订单簿返回 404。回测需要在市场运行期间记录的时点快照，比如 PolyTest 存档中 240M+ 条加密货币 Up/Down 市场快照。
获取 Polymarket 不保留的历史数据
PolyTest 在 Polymarket 加密货币 Up/Down 市场运行期间实时记录：240M+ 条快照，包含 8 档订单簿深度、亚秒级时间戳，并保留已结算的市场。从 3 天免费试用开始。
继续阅读
2026 年的 Polymarket Python SDK（以及如何迁移出 py-clob-client）
如果你的代码还在从 py_clob_client 导入 ClobClient，那它就建立在一个已被取代的包之上，AI 助手为你写的大部分 Polymarket 代码也是如此。下面介绍当前的 SDK 以及如何迁移。
Polymarket WebSocket：不掉线的实时数据
轮询订单簿是白白耗尽速率限制额度最常见的方式。下面介绍四个数据流、没人写进文档的订阅选项，以及那种让你的机器人收到一片沉默、却以为市场很平静的失效模式。
Polymarket API 速率限制：完整参考
Polymarket 把它的速率限制分散在好几个页面上，分属两套完全不同的系统，而且使用的是几乎没人预料到的 10 秒窗口。这里把它们全部整理成一组表格，并说明超出限制时实际会发生什么。