Polymarket API 限速 — Gamma、Data 与 CLOB

Polymarket API 限速是在构建机器人、仪表盘或分析系统时必须围绕设计的节流约束。本指南列出各公共面（Gamma、Data、CLOB 与 Market WebSocket）的已记录限制，说明 Gamma /markets 的重要约束（包括 /markets 的 300 req / 10 s 规则和基于游标的分页），并提供具体策略——批量、缓存、游标分页、指数退避——以在高负载下保持客户端可靠。

要点总结

• Gamma 的 /markets 端点：300 次请求 / 10 秒；使用 limit 参数和 after_cursor 分页（不要使用 offset）。
• 联合列表限制：/markets + /events 列表调用共享 900 req / 10 s 的上限；Gamma 整体：4000 req / 10 s。
• 对于专门的读取使用 CLOB 和 Data API；CLOB 对交易调用需要 API key + HMAC，读取是公开的。
• WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) 提供实时数据；对于实时订单簿更新优先使用 WS 而非轮询。
• 缓解模式：请求合并、缓存 TTL、带抖动的指数退避、感知速率的排队和分页感知的抓取。

为什么限速很重要

限速保护 Polymarket 的共享基础设施，防止噪声客户端降级其他用户体验。对于构建套利机器人或分析系统的开发者，触及限制会导致请求被立即拒绝并可能破坏时间敏感的流程。事先规划请求模式可以减少意外并使系统更健壮。

已记录的 Polymarket 限速与端点

Gamma（主要的市场元数据）

• 基本 URL: https://gamma-api.polymarket.com
• 主要限制：
  • /markets：最多 300 次请求 / 10 秒。使用 limit 参数（最大 1000）以及通过 after_cursor 的基于游标的分页。API 会以 HTTP 422 拒绝 offset。
  • /markets + /events 的联合列表限制：900 次请求 / 10 秒。
  • Gamma API 整体面：4000 次请求 / 10 秒。

实用注意：

• 始终优先使用上一次调用返回的 after_cursor；不要尝试用 offset 仿真键集分页。
• 调整 limit 以减少往返次数。如果需要完整市场列表，limit=1000 可以减少调用次数。

Data（持仓、交易、持有人）

• 基本 URL: https://data-api.polymarket.com
• 认证：公开读取无需认证。
• 本文档简要描述了该面但未列出 Data 的每端点速率数字。将 Data 视为公开，但对客户端仍应实施与 Gamma 相同的保守控制（批量、缓存、退避）。

CLOB（订单簿与交易）

• 基本 URL: https://clob.polymarket.com
• 读取是公开的。交易需要 API key + HMAC。
• CLOB 面暴露订单簿、中点、价格历史以及下单/撤单。文档未公布 CLOB 读取的显式每端点速率数字；将交易路径视为对速率敏感，并在可能时使用 CLOB WebSocket 或 Market WS 以获取实时簿数据。

Market WebSocket（实时市场更新）

• URL: wss://ws-subscriptions-clob.polymarket.com/ws/market
• 市场数据无需认证。
• 提供的数据流：实时订单簿、price_change、best_bid_ask（通过 custom_feature_enabled: true 启用）、last_trade_price、tick_size_change。
• PING 心跳每 10 秒一次。每个连接最大支持 500 个合约（instruments）。

必须遵循的 Gamma /markets 细节

• 分页：仅支持 after_cursor。API 返回 next_cursor —— 原封不动地传回下一次调用。
• limit 默认 20，最大 1000。对批量同步使用更大的 limit。
• 可接受的过滤参数包括数组形式的 slug、id、condition_ids、clob_token_ids、question_ids、market_maker_address 以及 closed、active、archived、tag_id 等。
• 排序：order 接受以逗号分隔的字段列表（例如 volume24hr,liquidity），ascending 为布尔值，默认 true。

常见错误信号及应对方式

• HTTP 429（超出速率）：停止立即轮询，退避并使用带抖动的指数退避重试。
• HTTP 422（使用 offset 时）：改用 after_cursor 分页。
• 部分响应或空页面：遵守游标；核验你的过滤器。如果你认为触发了服务器端配额，请降低客户端并发。

避免被节流的设计模式

1. 充分缓存

• 根据用途对市场列表和元数据做短 TTL 缓存（30s–2m）。市场和事件列表通常不会每秒变更。
• 按查询键（过滤器 + 排序）缓存。仅当收到变更事件（例如来自 WebSocket）或 TTL 到期时才使缓存失效。

2. 批量与增大 limit

• 对于全量同步，使用 limit=1000 来减少对 /markets 的往返次数。
• 在非高峰时拉取宽页面，并使用 WebSocket 的增量更新。

3. 对实时数据使用 WebSocket

• 对于实时订单簿或价格变动，订阅 Market WS 而不是轮询 Gamma 或 CLOB 读取。WS 每个连接最多支持 500 个合约；若需超过 500 个，请对客户端分片。

4. 感知速率的排队与退避

• 实现一个漏桶或令牌桶的客户端限流器，使其匹配已记录的峰值（例如 /markets 的 300/10s）。
• 收到 429 时，应用带抖动的指数退避并逐步增加重试窗口。

5. 合并相同的并发请求

• 如果应用的多个部分同时请求相同的 /markets 查询，将它们合并为一个正在进行的请求，然后将响应向外分发。

6. 以游标为先的同步

• 始终遵循基于游标的分页。对实时同步，先请求第一页然后订阅增量（如果支持）。不要尝试天真的并发游标抓取，这可能超出 Gamma 的单端点限制。

示例抓取策略

• 批量索引作业（非实时）：抓取 /markets?limit=1000 然后跟随 next_cursor 直到遍历完。页面之间短暂休眠，并遵守 300/10s 的端点限制。
• 几乎实时的 UI：一次抓取基础集合（缓存 30s），然后打开 WebSocket 获取增量和 best_bid_ask 更新。
• 观察列表微客户端：如果 >500 个合约，跨多个 WS 连接对观察列表做分片。

面向机器人和高吞吐客户端的操作性指导

• 对簿级数据使用 CLOB WebSocket 或 CLOB 读取，Gamma 用于较慢的元数据。
• 将交易凭证（CLOB API key + HMAC）妥善保管；交易端点需要认证。
• 监控你的 429 频率和各端点的延迟指标。如果你经常接近已记录上限，请申请更高配额或通过官方 Polymarket 渠道联系（Builder Program 是获取更高流量整合和归属的路径）。

这如何影响你的开发与部署

如果你构建交易机器人或分析服务，请为分层数据流做规划：来自 Gamma 的一次大规模抓取（大 limit），随后订阅 WebSocket 以获取实时更新，并对任何 WS 不包含的元数据以小范围周期性地轮询 Gamma（并缓存）。实现客户端限速、合并与游标感知分页以避免触及 /markets 的 300 req / 10 s 限制以及联合列表和整体 Gamma 上限。

结语摘要

Polymarket 的 API 限速对 Gamma 的列表面是明确的，而 Market WS 为实时数据提供了可扩展的替代方案。围绕基于游标的分页（after_cursor）进行设计，策略性使用 limit，并在高频数据场景下优先使用 WebSocket。遵循这些模式将减少节流并使你的集成更可靠。

常见问题

Gamma 的 /markets 限速是多少？

Gamma 的 /markets 端点限制为 300 次请求 / 10 秒。使用 limit（最大 1000）和通过 after_cursor 的基于游标分页。不要使用 offset——API 会以 HTTP 422 拒绝它。

Gamma 的端点是否有联合限制？

有。对 /markets 和 /events 的列表调用共享 900 次请求 / 10 秒的联合上限。此外，Gamma API 整体面限制为 4000 次请求 / 10 秒。

我应该轮询 Gamma 还是使用 WebSocket 获取实时更新？

优先使用 Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) 获取实时订单簿和价格更新——它更高效且避免重复轮询。将 Gamma 用于变化较慢的元数据和初始的全量同步。

客户端收到 HTTP 429 应该怎么做？

将 429 视为停止激进轮询的信号。实现带抖动的指数退避、降低并发并合并相同请求。追踪 429 次数以动态调整限速器。

CLOB API 是否需要认证？

CLOB 的读取是公开的。CLOB 的交易操作需要 API key 以及 HMAC 认证。尊重交易速率限制并在获取簿更新时优先使用 WS 数据流。