Polymarket API rate limits — Gamma, Data & CLOB

Les limites de débit des API Polymarket sont les bornes autour desquelles vous devez concevoir vos bots, tableaux de bord ou pipelines d'analytics. Ce guide expose les limites documentées pour chaque surface publique (Gamma, Data, CLOB et le Market WebSocket), explique les contraintes importantes de Gamma /markets (dont la règle 300 req / 10 s pour /markets et la pagination par curseur), et propose des stratégies concrètes — batching, mise en cache, pagination par curseur, backoff exponentiel — pour maintenir la fiabilité de votre client sous forte charge.

Points clés

• L'endpoint /markets de Gamma : 300 requêtes par 10 secondes ; utilisez le paramètre limit et after_cursor pour la pagination (n'utilisez pas offset).
• Plafonds de listings combinés : les appels /markets + /events partagent une limite de 900 req / 10 s ; Gamma globalement : 4000 req / 10 s.
• Utilisez les API CLOB et Data pour des lectures spécialisées ; CLOB requiert une clé API + HMAC pour les appels de trading, les lectures sont publiques.
• Le WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) fournit des données en temps réel ; préférez WS pour les mises à jour du carnet live plutôt que le polling.
• Modèles d'atténuation : coalescence des requêtes, TTL de cache, backoff exponentiel avec jitter, file d'attente consciente du débit et récupération pagination-aware.

Pourquoi les limites de débit sont importantes

Les limites de débit protègent l'infrastructure partagée de Polymarket et empêchent des clients bruyants de dégrader l'expérience des autres. Pour les développeurs qui construisent des bots d'arbitrage ou des systèmes d'analytics, atteindre une limite provoque un rejet immédiat des requêtes et peut casser des flux sensibles au temps. Planifier les schémas de requêtes en amont réduit les surprises et rend les systèmes plus robustes.

Limites documentées et endpoints Polymarket

Gamma (métadonnées marchés principales)

• Base URL: https://gamma-api.polymarket.com
• Limites notables :
  • /markets : maximum 300 requêtes par 10 secondes. Utilisez le paramètre limit (max 1000) et la pagination par curseur via after_cursor. L'API rejette offset avec HTTP 422.
  • Limite combinée /markets + /events pour les listings : 900 requêtes par 10 secondes.
  • Surface globale de l'API Gamma : 4000 requêtes par 10 secondes.

Notes pratiques :

• Préférez toujours le after_cursor retourné par l'appel précédent ; ne tentez pas d'émuler un keyset avec offset.
• Ajustez limit pour réduire les allers-retours. Si vous avez besoin de listes complètes de marchés, limit=1000 réduit le nombre d'appels.

Data (positions, trades, holders)

• Base URL: https://data-api.polymarket.com
• Auth : aucune pour les lectures publiques.
• La documentation est brève sur cette surface et n'énumère pas de chiffres de débit par endpoint pour Data. Traitez Data comme publique, mais appliquez les mêmes contrôles clients conservateurs que pour Gamma (batching, cache, backoff).

CLOB (carnet d'ordres et trading)

• Base URL: https://clob.polymarket.com
• Les lectures sont publiques. Le trading nécessite une clé API + HMAC.
• La surface CLOB expose le carnet d'ordres, le midpoint, l'historique des prix, et le placement/annulation d'ordres. La doc ne publie pas de chiffres explicites par endpoint pour les lectures CLOB ; considérez les chemins de trading comme sensibles au débit et utilisez le WebSocket CLOB ou le Market WS pour les données du carnet live quand c'est possible.

Market WebSocket (mises à jour marché en temps réel)

• URL: wss://ws-subscriptions-clob.polymarket.com/ws/market
• Aucune authentification requise pour les données marché.
• Feeds : real-time book, price_change, best_bid_ask (activez avec custom_feature_enabled: true), last_trade_price, tick_size_change.
• PING heartbeat toutes les 10 secondes. Maximum 500 instruments par connexion.

Spécificités Gamma /markets à respecter

• Pagination : uniquement after_cursor. L'API renvoie next_cursor — transmettez-le inchangé à l'appel suivant.
• limit par défaut = 20, max = 1000. Utilisez un limit plus élevé pour les synchronisations en masse.
• Les paramètres de filtre acceptent des tableaux pour slug, id, condition_ids, clob_token_ids, question_ids, market_maker_address et d'autres comme closed, active, archived, tag_id.
• Tri : order accepte des listes de champs séparés par des virgules (p. ex. volume24hr,liquidity) et ascending est un booléen avec true par défaut.

Signaux d'erreur courants et réactions appropriées

• HTTP 429 (rate limited) : arrêtez le polling immédiat, reculez et retentez avec backoff exponentiel et jitter.
• HTTP 422 lors de l'utilisation de offset : basculez vers la pagination after_cursor.
• Réponses partielles ou pages vides : respectez les curseurs ; vérifiez vos filtres. Si vous pensez avoir atteint une quota côté serveur, réduisez la concurrence des requêtes côté client.

Schémas de conception pour éviter le throttling

1. Mettre en cache agressivement

• Mettez en cache les listes de marchés et les métadonnées pour des TTL courts (30s–2m) selon l'utilisation. Les listes de marchés et d'événements changent rarement chaque seconde.
• Cachez par clé de requête (filtres + order). Invalidez le cache uniquement lorsque vous recevez des événements de changement (par exemple via WebSocket) ou après l'expiration du TTL.

2. Batcher et augmenter limit

• Pour les synchronisations complètes, utilisez limit=1000 pour réduire les allers-retours contre /markets.
• Récupérez de larges pages pendant les fenêtres hors-pointe et utilisez des mises à jour incrémentales depuis le WebSocket.

3. Utiliser le WebSocket pour les données en temps réel

• Pour les mises à jour du carnet live ou les mouvements de prix, abonnez-vous au Market WS plutôt que de poller Gamma ou les lectures CLOB. Le WS supporte jusqu'à 500 instruments par connexion ; shardez les clients si vous avez besoin de >500.

4. File d'attente consciente du débit et backoff

• Implémentez un limiteur client-side de type leaky-bucket ou token-bucket qui correspond aux pics documentés (par ex. 300/10s pour /markets).
• Lorsque vous recevez des 429, appliquez un backoff exponentiel avec jitter et augmentez progressivement votre fenêtre de retry.

5. Coalescer les requêtes concurrentes identiques

• Si plusieurs parties de votre app demandent la même requête /markets simultanément, coalescez-les en une seule requête en vol et diffusez la réponse.

6. Synchronisation « cursor-first »

• Suivez toujours la pagination par curseur. Pour les synchronisations live, requêtez la première page puis abonnez-vous aux deltas si supporté. Ne tentez pas des fetchs concurrentiels naïfs avec curseurs qui pourraient dépasser la limite par endpoint de Gamma.

Exemples de stratégies de fetch

• Job d'indexation en masse (non temps réel) : fetch /markets?limit=1000 puis suivez next_cursor jusqu'à exhaustion. Faites de courtes pauses entre les pages et respectez la limite endpoint 300/10s.
• UI quasi temps réel : fetch du jeu de base une fois (cache 30s), puis ouvrez un WebSocket pour les deltas et les mises à jour best_bid_ask.
• Micro-client watchlist : shardez les watchlists sur plusieurs connexions WS si >500 instruments.

Guidance opérationnelle pour bots et clients à haut débit

• Utilisez le WebSocket CLOB ou les lectures CLOB pour les données au niveau du carnet et Gamma pour les métadonnées plus lentes.
• Gardez les identifiants de trading (clé API CLOB + HMAC) sécurisés ; les endpoints de trading sont authentifiés.
• Surveillez vos 429 et la latence par endpoint. Si vous approchez régulièrement des plafonds documentés, demandez l'accès ou contactez les canaux officiels de Polymarket (le Builder Program est la voie pour des intégrations à volume plus élevé et l'attribution).

Comment cela affecte votre développement et déploiement

Si vous construisez un bot de trading ou un service d'analytics, prévoyez des flux de données en couches : un fetch initial en masse depuis Gamma avec un limit élevé, suivi d'abonnements WebSocket pour les mises à jour live, et un petit ensemble de polls périodiques Gamma (cachés) pour toute métadonnée non fournie par le WS. Implémentez un throttling côté client, la coalescence et la pagination consciente des curseurs pour éviter d'atteindre le plafond documenté de 300 req / 10 s pour /markets ainsi que les plafonds combinés et globaux de Gamma.

Résumé de clôture

Les limites de débit des API Polymarket sont explicites pour les surfaces de listing de Gamma et le Market WS offre une alternative évolutive pour les flux live. Concevez autour de la pagination par curseur (after_cursor), utilisez limit de façon stratégique et préférez les WebSockets pour les données à haute fréquence. Suivre ces modèles réduira le throttling et rendra vos intégrations plus fiables.

Frequently asked questions

What is the /markets rate limit on Gamma?

L'endpoint /markets de Gamma est limité à 300 requêtes par 10 secondes. Utilisez limit (max 1000) et la pagination par curseur via after_cursor. N'utilisez pas offset — l'API le rejette avec HTTP 422.

Are there combined limits for Gamma endpoints?

Oui. Les appels de listing vers /markets et /events partagent un plafond combiné de 900 requêtes par 10 secondes. De plus, la surface globale de l'API Gamma est limitée à 4000 requêtes par 10 secondes.

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

Préférez le Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) pour les mises à jour live du carnet et des prix — c'est plus efficace et évite le polling répété. Utilisez Gamma pour les métadonnées qui changent plus lentement et pour les synchronisations initiales en masse.

What should my client do on HTTP 429 responses?

Considérez le 429 comme un signal pour arrêter le polling agressif. Implémentez un backoff exponentiel avec jitter, réduisez la concurrence et coalescez les requêtes identiques. Suivez les 429 pour ajuster dynamiquement votre limiteur de débit.

Does the CLOB API require authentication?

Les lectures CLOB sont publiques. Les opérations de trading sur CLOB nécessitent une clé API plus une authentification HMAC. Respectez les limites de trading et préférez les feeds WS pour les mises à jour du carnet.