Polymarket API rate limits — Gamma, Data & CLOB

I rate limit delle API di Polymarket sono i vincoli attorno ai quali devi progettare quando costruisci bot, dashboard o sistemi di analytics. Questa guida descrive i limiti documentati per ogni superficie pubblica (Gamma, Data, CLOB e il Market WebSocket), spiega i vincoli importanti di Gamma /markets (inclusa la regola 300 req / 10 s e la paginazione basata su cursore) e fornisce strategie concrete—batching, caching, paginazione con cursore, exponential backoff—per mantenere il client affidabile sotto carico.

Punti chiave

• L'endpoint /markets di Gamma: 300 richieste ogni 10 secondi; usa il parametro limit e after_cursor per la paginazione (non usare offset).
• Limiti per liste combinate: le chiamate di listing /markets + /events condividono un tetto di 900 req / 10 s; Gamma complessivo: 4000 req / 10 s.
• Usa le API CLOB e Data per letture specializzate; CLOB richiede API key + HMAC per le chiamate di trading, le letture sono pubbliche.
• WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) fornisce dati in tempo reale; preferisci WS per gli aggiornamenti live del book invece di polling.
• Pattern di mitigazione: coalescenza delle richieste, TTL di cache, exponential backoff con jitter, code consapevoli dei rate e fetching aware della paginazione.

Perché i rate limit sono importanti

I rate limit proteggono l'infrastruttura condivisa di Polymarket e impediscono a client rumorosi di degradare l'esperienza per gli altri. Per chi costruisce bot di arbitraggio o sistemi di analytics, superare un limite causa il rifiuto immediato delle richieste e può interrompere flussi sensibili al tempo. Pianificare i pattern di richiesta in anticipo riduce sorprese e rende i sistemi più robusti.

Limiti documentati e endpoint di Polymarket

Gamma (metadati primari dei mercati)

• Base URL: https://gamma-api.polymarket.com
• Limiti rilevanti:
  • /markets: massimo 300 richieste ogni 10 secondi. Usa il parametro limit (max 1000) e la paginazione basata su cursore tramite after_cursor. L'API rifiuta offset con HTTP 422.
  • Limite combinato /markets + /events per le liste: 900 richieste ogni 10 secondi.
  • Superficie complessiva dell'API Gamma: 4000 richieste ogni 10 secondi.

Note pratiche:

• Preferisci sempre after_cursor restituito dalla chiamata precedente; non tentare di emulare keyset usando offset.
• Sintonizza limit per ridurre i round trip. Se ti servono liste complete di mercati, limit=1000 riduce il numero di chiamate.

Data (posizioni, trade, holder)

• Base URL: https://data-api.polymarket.com
• Auth: nessuna per letture pubbliche.
• La documentazione menziona la superficie ma non elenca numeri di rate per endpoint specifici di Data. Tratta Data come pubblico, ma implementa gli stessi controlli conservativi lato client di Gamma (batching, caching, backoff).

CLOB (order book e trading)

• Base URL: https://clob.polymarket.com
• Le letture sono pubbliche. Il trading richiede API key + HMAC.
• La superficie CLOB espone order book, midpoint, cronologia prezzi e placement/cancellazione ordini. Il documento non pubblica numeri espliciti per endpoint di lettura CLOB; considera i percorsi di trading sensibili ai rate e usa il WebSocket CLOB o il Market WS per dati live del book quando possibile.

Market WebSocket (aggiornamenti di mercato in tempo reale)

• URL: wss://ws-subscriptions-clob.polymarket.com/ws/market
• Nessuna autenticazione richiesta per i dati di mercato.
• Feed: real-time book, price_change, best_bid_ask (abilita con custom_feature_enabled: true), last_trade_price, tick_size_change.
• Heartbeat PING ogni 10 secondi. Massimo 500 strumenti per connessione.

Dettagli di Gamma /markets che devi seguire

• Paginazione: solo after_cursor. L'API restituisce next_cursor — passalo esattamente alla chiamata successiva.
• limit di default è 20, massimo 1000. Usa limit più alto per bulk-sync.
• I parametri di filtro accettano array per slug, id, condition_ids, clob_token_ids, question_ids, market_maker_address e altri come closed, active, archived, tag_id.
• Ordinamento: order accetta liste di campi separati da virgola (es. volume24hr,liquidity) e ascending è booleano con default true.

Segnali di errore comuni e come reagire

• HTTP 429 (rate limited): interrompi il polling immediato, fai back off e ritenta con exponential backoff e jitter.
• HTTP 422 quando usi offset: passa alla paginazione con after_cursor.
• Risposte parziali o pagine vuote: rispetta i cursori; verifica i filtri. Se ritieni di aver raggiunto una quota lato server, riduci la concorrenza delle richieste client.

Pattern di progettazione per evitare throttling

1. Cache aggressiva

• Memorizza le liste di mercati e i metadata con TTL brevi (30s–2m) a seconda dell'uso. I mercati e le liste di eventi raramente cambiano ogni secondo.
• Cache per chiave di query (filtri + ordine). Invalida la cache solo quando ricevi eventi di cambiamento (es. dal WebSocket) o alla scadenza del TTL.

2. Raggruppa e aumenta limit

• Per full-sync usa limit=1000 per ridurre i round trip contro /markets.
• Scarica pagine ampie durante le finestre off-peak e usa aggiornamenti incrementali dal WebSocket.

3. Usa il WebSocket per dati in tempo reale

• Per aggiornamenti live dell'order-book o movimenti di prezzo, sottoscrivi il Market WS invece di fare polling su Gamma o letture CLOB. Il WS supporta fino a 500 strumenti per connessione; shard i client se ti servono >500.

4. Code consapevoli del rate e backoff

• Implementa un limiter client-side tipo leaky-bucket o token-bucket che rispecchia i picchi documentati (es. 300/10s per /markets).
• Quando ricevi 429, applica exponential backoff con jitter e aumenta progressivamente la finestra di retry.

5. Coalescenza delle richieste concorrenti identiche

• Se più parti della tua app richiedono la stessa query /markets simultaneamente, coalesciale in una singola richiesta in flight e distribuisci la risposta.

6. Sincronizzazione basata sul cursore

• Segui sempre la paginazione basata su cursore. Per sync live, richiedi la prima pagina e poi sottoscriviti alle delta se supportate. Non tentare fetch concorrenti naïf con cursori che possano eccedere il limite per endpoint di Gamma.

Strategie di fetch - esempi

• Job di indicizzazione bulk (non realtime): fetcha /markets?limit=1000 poi segui next_cursor finché non esaurisci. Fai brevi pause tra le pagine e rispetta il limite 300/10s dell'endpoint.
• UI near-real-time: recupera il set base una volta (cache 30s), poi apri WebSocket per delta e aggiornamenti best_bid_ask.
• Micro-client per watchlist: shard le watchlist su più connessioni WS se >500 strumenti.

Guida operativa per bot e client ad alto throughput

• Usa il WebSocket CLOB o le letture CLOB per dati a livello di book e Gamma per metadata più lenti.
• Proteggi le credenziali di trading (CLOB API key + HMAC); gli endpoint di trading sono autenticati.
• Monitora il tuo tasso di 429 e le metriche di latenza per endpoint. Se ti avvicini regolarmente ai limiti documentati, richiedi accesso o contatta canali ufficiali di Polymarket (il Builder Program è la via per integrazioni ad alto volume e attribuzione).

Impatto su sviluppo e deployment

Se costruisci un trading bot o un servizio di analytics, pianifica flussi di dati stratificati: un fetch bulk iniziale da Gamma con limit elevato, seguito da sottoscrizioni WebSocket per aggiornamenti live e un piccolo insieme di poll periodici Gamma (cachati) per qualsiasi metadata non presente nel feed WS. Implementa rate limiting lato client, coalescenza e paginazione consapevole dei cursori per evitare di superare il limite documentato /markets di 300 req / 10 s e i limiti combinati e complessivi di Gamma.

Riepilogo finale

I rate limit delle API Polymarket sono espliciti per le superfici di listing di Gamma e il Market WS offre un'alternativa scalabile per i feed live. Progetta attorno alla paginazione basata su cursore (after_cursor), usa limit in modo strategico e preferisci WebSocket per i dati ad alta frequenza. Seguire questi pattern ridurrà il throttling e renderà le tue integrazioni più affidabili.

Frequently asked questions

What is the /markets rate limit on Gamma?

L'endpoint /markets di Gamma è limitato a 300 richieste ogni 10 secondi. Usa limit (max 1000) e la paginazione basata su cursore tramite after_cursor. Non usare offset—l'API lo rifiuta con HTTP 422.

Are there combined limits for Gamma endpoints?

Sì. Le chiamate di listing a /markets e /events condividono un tetto combinato di 900 richieste ogni 10 secondi. Inoltre, la superficie complessiva dell'API Gamma è limitata a 4000 richieste ogni 10 secondi.

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

Preferisci il Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) per aggiornamenti live di book e prezzi—è più efficiente ed evita polling ripetuto. Usa Gamma per metadata che cambiano più lentamente e per i bulk sync iniziali.

What should my client do on HTTP 429 responses?

Tratta 429 come un segnale per fermare il polling aggressivo. Implementa exponential backoff con jitter, riduci la concorrenza e coalesci le richieste identiche. Monitora i 429 per aggiustare dinamicamente il tuo rate limiter.

Does the CLOB API require authentication?

Le letture CLOB sono pubbliche. Le operazioni di trading su CLOB richiedono API key più HMAC per l'autenticazione. Rispetta i rate limit di trading e preferisci i feed WS per aggiornamenti sul book.