Polymarket API rate limits — Gamma, Data & CLOB

Polymarket API 的速率限制是你在構建機器人、儀表板或分析工具時必須考量的節流機制。本指南列出各公開介面（Gamma、Data、CLOB 與 Market WebSocket）的已記錄限制，說明 Gamma /markets 的重要約束（包括 /markets 的 300 req / 10 s 規則與基於游標的分頁），並提供具體策略──批次、快取、游標分頁、指數退避──以在高負載下維持客戶端可靠性。

重點摘要

• Gamma 的 /markets 端點：10 秒內最多 300 次請求；使用 limit 參數與 after_cursor 進行分頁（不要使用 offset）。
• 合併列舉上限：/markets + /events 的列舉呼叫共享 10 秒內 900 次的上限；Gamma 整體表面為 10 秒內 4000 次。
• 針對專用讀取請使用 CLOB 與 Data API；CLOB 的交易路徑需要 API key + HMAC，讀取則是公開的。
• WebSocket（wss://ws-subscriptions-clob.polymarket.com/ws/market）提供即時資料；對於即時簿資料更新，優先使用 WS 而非輪詢。
• 緩解模式：請求合併、快取 TTL、帶抖動的指數退避、具速率感知的佇列，以及分頁意識的抓取。

為何速率限制重要

速率限制保護 Polymarket 的共享基礎設施，避免噪音客戶端降低其他使用者的體驗。對於構建套利機器人或分析系統的開發者來說，觸及限制會導致請求被立即拒絕，並可能破壞時間敏感的流程。事先規劃請求模式可降低突發狀況並提高系統韌性。

已記錄的 Polymarket 速率限制與端點

Gamma（主要市場所屬 metadata）

• Base URL: https://gamma-api.polymarket.com
• 顯著限制：
  • /markets：每 10 秒最多 300 次請求。使用 limit 參數（最大 1000）與透過 after_cursor 的基於游標分頁。API 會以 HTTP 422 拒絕 offset。
  • 合併 /markets + /events 的列舉上限：每 10 秒 900 次請求。
  • Gamma API 表面的整體上限：每 10 秒 4000 次請求。

實務注意事項：

• 始終優先使用先前呼叫回傳的 after_cursor；不要嘗試用 offset 模擬 keyset 分頁。
• 調整 limit 以減少來回次數。如果你需要整個市場清單，limit=1000 可以減少呼叫次數。

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

• Base URL: https://data-api.polymarket.com
• 認證：公開讀取不需認證。
• 文件簡要描述該表面，但未列出 Data 各端點的速率數字。將 Data 視為公開介面，但仍建議採用與 Gamma 相同的保守客戶端控制（批次、快取、退避）。

CLOB（訂單簿與交易）

• Base URL: https://clob.polymarket.com
• 讀取為公開。交易需要 API key + HMAC。
• CLOB 表面公開訂單簿、Midpoint、價格歷史，以及下單/取消訂單。文件未對 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。
• 每 10 秒送出 PING 心跳。每條連線最多 500 個商品。

你必須遵守的 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（被速率限制）：停止立即輪詢，退避後重試，並使用帶抖動的指數退避機制。
• 使用 offset 時出現 HTTP 422：改用 after_cursor 分頁。
• 部分回應或空頁：尊重游標並檢查你的篩選條件。如果你懷疑觸及到伺服器端配額，請降低客戶端的併發量。

避免被節流的設計模式

1. 大量快取

• 對市場清單與 metadata 進行短 TTL 的快取（30 秒至 2 分鐘），視使用情境而定。市場與事件清單通常不會每秒改變。
• 以查詢鍵（篩選 + 排序）作為快取鍵。僅在收到變更事件（例如來自 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 直到耗盡。在分頁之間稍作停頓，並尊重 /markets 的 300/10s 端點限制。
• 準即時 UI：先抓一次基礎集合（快取 30 秒），然後打開 WebSocket 以取得增量與 best_bid_ask 更新。
• 觀察清單微型客戶端：若超過 500 個商品，請在多個 WS 連線間分片 watchlist。

機器人與高吞吐客戶端的營運建議

• 對於簿級資料使用 CLOB WebSocket 或 CLOB 讀取，對較慢的 metadata 使用 Gamma。
• 妥善保管交易憑證（CLOB API key + HMAC）；交易端點需經驗證。
• 監控你的 429 數量與各端點的延遲指標。如果你經常接近已記錄上限，請申請更高的存取權或透過官方 Polymarket 管道聯絡（Builder Program 是高流量整合與歸屬的途徑）。

這如何影響你的開發與部署

若你在構建交易機器人或分析服務，請規劃分層資料流程：先從 Gamma 做一次大批抓取（較大的 limit），接著透過 WebSocket 訂閱即時更新，並對任何 WS 未涵蓋的 metadata 保持少量週期性 Gamma 輪詢（並快取）。實作客戶端速率限制、請求合併與游標感知的分頁，以避免觸及 /markets 的 10 秒 300 次上限以及合併列舉與 Gamma 整體上限。

結語摘要

Polymarket 的 API 速率限制在 Gamma 的列舉表面是明確的，而 Market WS 為即時資料提供可擴展的替代方案。以基於游標的分頁（after_cursor）為中心設計，策略性使用 limit，並對於高頻資料優先採用 WebSocket。遵循這些模式可減少被節流的機率並提升整合的可靠性。

常見問題

Gamma 的 /markets 速率限制是多少？

Gamma 的 /markets 端點限制為每 10 秒 300 次請求。使用 limit（最大 1000）與透過 after_cursor 的基於游標分頁。不要使用 offset——API 會以 HTTP 422 拒絕。

Gamma 各端點是否有合併上限？

有。對 /markets 與 /events 的列舉呼叫共享每 10 秒 900 次的合併上限。此外，Gamma API 表面的整體上限為每 10 秒 4000 次請求。

我應該輪詢 Gamma 還是使用 WebSocket 取得即時更新？

優先使用 Market WebSocket（wss://ws-subscriptions-clob.polymarket.com/ws/market）以取得即時簿與價格更新——這比重複輪詢更有效且可避免頻繁請求。將 Gamma 用於變化較慢的 metadata 與初次的大量同步。

客戶端在收到 HTTP 429 時應該怎麼做？

將 429 視為停止積極輪詢的信號。實作帶抖動的指數退避、降低併發，並合併相同請求。追蹤 429 的發生以動態調整你的速率限制器。

CLOB API 是否需要驗證？

CLOB 的讀取為公開。CLOB 的交易操作需要 API key 與 HMAC 驗證。尊重交易速率限制，並對簿層更新優先使用 WS 資料。