Polymarket API rate limits — Gamma, Data & CLOB

Ang mga rate limit ng Polymarket API ay mga throttle na kailangan mong isaalang-alang kapag nagbuo ng mga bot, dashboard, o analytics. Ipinapaliwanag ng gabay na ito ang dokumentadong limitasyon para sa bawat public surface (Gamma, Data, CLOB, at ang Market WebSocket), tinutukoy ang mahahalagang constraints ng Gamma /markets (kasama ang /markets 300 req / 10 s rule at cursor-based pagination), at nagbibigay ng konkretong mga estratehiya—batching, caching, cursor pagination, exponential backoff—para panatilihing maaasahan ang iyong client sa ilalim ng load.

Key takeaways

• Gamma's /markets endpoint: 300 requests per 10 seconds; gamitin ang limit parameter at after_cursor para sa pagination (huwag gumamit ng offset).
• Combined listing limits: /markets + /events listing calls share a 900 req / 10 s cap; Gamma overall: 4000 req / 10 s.
• Gamitin ang CLOB at Data APIs para sa specialized reads; ang CLOB ay nangangailangan ng API key + HMAC para sa trading calls; ang mga read ay public.
• WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) nagbibigay ng real-time data; mas mainam gumamit ng WS para sa live book updates kaysa mag-poll.
• Mitigation patterns: request coalescing, caching TTLs, exponential backoff with jitter, rate-aware queuing, at pagination-aware fetching.

Bakit mahalaga ang rate limits

Pinoprotektahan ng rate limits ang shared infrastructure ng Polymarket at pumipigil sa mga noisy client na sirain ang karanasan ng iba. Para sa mga developer na gumagawa ng arbitrage bot o analytics system, ang pag-hit sa limit ay nagdudulot ng agarang pagtanggi ng request at maaaring masira ang time-sensitive na flows. Ang pagpaplano ng request patterns nang maaga ay nagbabawas ng mga sorpresa at nagpapalakas ng katatagan ng system.

Documented Polymarket rate limits and endpoints

Gamma (primary market metadata)

• Base URL: https://gamma-api.polymarket.com
• Notable limits:
  • /markets: max 300 requests per 10 seconds. Gamitin ang limit parameter (max 1000) at cursor-based pagination via after_cursor. Tinatanggihan ng API ang offset na may HTTP 422.
  • Combined /markets + /events listing limit: 900 requests per 10 seconds.
  • Overall Gamma API surface: 4000 requests per 10 seconds.

Practical notes:

• Laging paboran ang after_cursor na ibinalik ng previous call; huwag subukang mag-emulate ng keyset gamit ang offset.
• I-tune ang limit para bawasan ang round trips. Kung kailangan mo ng full market lists, limit=1000 ang magpapababa ng calls.

Data (positions, trades, holders)

• Base URL: https://data-api.polymarket.com
• Auth: None para sa public reads.
• Ang dokumento ay naglalarawan ng surface pero hindi nagbibigay ng per-endpoint rate numbers para sa Data. Tratuhin ang Data bilang public, ngunit magpatupad ng parehong konserbatibong client-side controls tulad ng Gamma (batching, caching, backoff).

CLOB (order book and trading)

• Base URL: https://clob.polymarket.com
• Ang mga read ay public. Nangangailangan ng API key + HMAC ang trading.
• Ipinapakita ng CLOB surface ang order book, midpoint, price history, at order placement/cancellation. Hindi inilathala ang dokumento ng eksaktong per-endpoint rate numbers para sa CLOB reads; tratuhin ang trading paths bilang rate-sensitive at gumamit ng CLOB WebSocket o ang Market WS para sa live book data kung posible.

Market WebSocket (real-time market updates)

• URL: wss://ws-subscriptions-clob.polymarket.com/ws/market
• Walang auth na kailangan para sa market data.
• Feeds: real-time book, price_change, best_bid_ask (i-enable gamit ang custom_feature_enabled: true), last_trade_price, tick_size_change.
• PING heartbeat bawat 10 seconds. Max 500 instruments per connection.

Gamma /markets specifics you must follow

• Pagination: after_cursor lang. Nagbabalik ang API ng next_cursor — ipasa ito nang walang pagbabago sa susunod na call.
• limit default ay 20, max 1000. Gumamit ng mas malaking limit para sa bulk-syncs.
• Tinatawag na filter parameters ang mga arrays para sa slug, id, condition_ids, clob_token_ids, question_ids, market_maker_address at iba pa tulad ng closed, active, archived, tag_id.
• Ordering: tumatanggap ang order ng comma-separated field lists (hal. volume24hr,liquidity) at ang ascending ay boolean na default true.

Common error signals and how to react

• HTTP 429 (rate limited): ihinto ang immediate polling, mag-back off, at mag-retry gamit ang exponential backoff at jitter.
• HTTP 422 kapag gumagamit ng offset: lumipat sa after_cursor pagination.
• Partial responses o empty pages: igalang ang cursors; i-verify ang iyong filters. Kung naniniwala kang naabot mo ang server-side quota, bawasan ang client request concurrency.

Design patterns to avoid throttles

1. Cache aggressively

• I-cache ang market lists at metadata para sa maiikling TTL (30s–2m) depende sa paggamit. Bihira magbago ang markets at event lists bawat segundo.
• I-cache ayon sa query key (filters + order). I-invalidate ang cache lamang kapag nakatanggap ka ng change events (hal., mula sa WebSocket) o kapag nag-expire ang TTL.

2. Batch and increase limit

• Para sa full-syncs, gamitin ang limit=1000 para bawasan ang round trips laban sa /markets.
• Kunin ang malalaking pages sa off-peak windows at gamitin ang incremental updates mula sa WebSocket.

3. Use the WebSocket for real-time data

• Para sa live order-book updates o price movements, mag-subscribe sa Market WS sa halip na mag-poll sa Gamma o CLOB reads. Sinusuportahan ng WS hanggang 500 instruments per connection; i-shard ang mga client kung kailangan mo ng >500.

4. Rate-aware queuing and backoff

• Magpatupad ng leaky-bucket o token-bucket client-side limiter na tumutugma sa dokumentadong peaks (hal., 300/10s para sa /markets).
• Kapag nakatanggap ka ng 429, ilapat ang exponential backoff na may jitter at unti-unting palawakin ang retry window.

5. Coalesce identical concurrent requests

• Kung maraming bahagi ng app ang humihiling ng parehong /markets query sabay-sabay, i-coalesce ang mga ito sa isang in-flight request at i-fan out ang response.

6. Cursor-first synchronization

• Laging sundin ang cursor-based pagination. Para sa live syncs, humiling ng unang pahina at pagkatapos ay mag-subscribe sa deltas kung sinusuportahan. Huwag subukang gumawa ng naive concurrent cursored fetches na maaaring lumampas sa per-endpoint limit ng Gamma.

Example fetch strategies

• Bulk indexing job (non-real-time): kunin ang /markets?limit=1000 pagkatapos sundan ang next_cursor hanggang maubos. Mag-sleep nang kaunti sa pagitan ng pages, at igalang ang 300/10s endpoint limit.
• Near-real-time UI: kunin ang base set isang beses (cache 30s), pagkatapos buksan ang WebSocket para sa deltas at best_bid_ask updates.
• Watchlist micro-client: i-shard ang watchlists across multiple WS connections kung >500 instruments.

Operational guidance for bots and high-throughput clients

• Gamitin ang CLOB WebSocket o CLOB reads para sa book-level data at Gamma para sa mas mabagal na metadata.
• Itago nang ligtas ang trading credentials (CLOB API key + HMAC); authenticated ang trading endpoints.
• I-monitor ang iyong 429 rate at instrument per-endpoint latency metrics. Kung palagi mong naabot ang dokumentadong caps, humiling ng access o makipag-ugnayan sa opisyal na Polymarket channels (ang Builder Program ang daan para sa higher-volume integrations at attribution).

How this affects your development and deployment

Kung gagawa ka ng trading bot o analytics service, magplano para sa layered data flows: isang initial bulk fetch mula sa Gamma na may malaking limit, sinundan ng WebSocket subscriptions para sa live updates, at isang maliit na set ng periodic Gamma polls (cached) para sa anumang metadata na wala sa WS feed. Magpatupad ng client-side rate limiting, coalescing, at cursor-aware pagination upang maiwasang ma-hit ang dokumentadong /markets 300 req / 10 s cap at ang combined listing at overall Gamma caps.

Closing summary

Ang Polymarket API rate limits ay malinaw para sa mga listing surface ng Gamma at nag-aalok ang Market WS ng scalable na alternatibo para sa live feeds. Magdisenyo ayon sa cursor-based pagination (after_cursor), gamitin ang limit nang may layunin, at paboran ang WebSockets para sa high-frequency data. Ang pagsunod sa mga pattern na ito ay magbabawas ng throttling at gagawing mas maaasahan ang iyong mga integration.

Frequently asked questions

What is the /markets rate limit on Gamma?

Ang /markets endpoint ng Gamma ay limitado sa 300 requests per 10 seconds. Gamitin ang limit (max 1000) at cursor-based pagination via after_cursor. Huwag gumamit ng offset—tinatanggihan ito ng API na may HTTP 422.

Are there combined limits for Gamma endpoints?

Oo. Ang listing calls sa /markets at /events ay may pinagsamang cap na 900 requests per 10 seconds. Dagdag pa rito, ang kabuuang Gamma API surface ay limitado sa 4000 requests per 10 seconds.

Should I poll Gamma or use the WebSocket for live updates?

Mas mainam ang Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) para sa live book at price updates—mas epektibo ito at iniiwasan ang paulit-ulit na polling. Gamitin ang Gamma para sa mas mabagal na nagbabagong metadata at initial bulk syncs.

What should my client do on HTTP 429 responses?

Ituring ang 429 bilang senyales na itigil ang agresibong polling. Magpatupad ng exponential backoff na may jitter, bawasan ang concurrency, at i-coalesce ang magkaparehong requests. I-track ang mga 429 para i-adjust ang iyong rate limiter dynamically.

Does the CLOB API require authentication?

Ang CLOB reads ay public. Ang trading operations sa CLOB ay nangangailangan ng API key plus HMAC authentication. Igalang ang trading rate limits at paboran ang WS feeds para sa book updates.