Polymarket API rate limits — Gamma, Data & CLOB

Polymarket-API-Rate-Limits sind die Drosseln, um die Sie Ihre Architektur herum entwerfen müssen, wenn Sie Bots, Dashboards oder Analytics bauen. Dieser Leitfaden legt die dokumentierten Limits für jede öffentliche Oberfläche dar (Gamma, Data, CLOB und der Market WebSocket), erklärt die wichtigen Gamma-/markets-Einschränkungen (einschließlich der Regel 300 req / 10 s für /markets und cursor-basierter Paginierung) und gibt konkrete Strategien — Batchung, Caching, Cursor-Paginierung, exponentielles Backoff — um Ihren Client unter Last zuverlässig zu halten.

Wesentliche Erkenntnisse

• Gammas /markets-Endpoint: 300 Anfragen pro 10 Sekunden; verwenden Sie den Parameter limit und after_cursor für die Paginierung (verwenden Sie nicht offset).
• Kombinierte Listing-Limits: /markets + /events-Listing-Aufrufe teilen sich ein Limit von 900 req / 10 s; Gamma gesamt: 4000 req / 10 s.
• Verwenden Sie die CLOB- und Data-APIs für spezialisierte Lesevorgänge; CLOB erfordert API key + HMAC für Trading-Aufrufe, Lesefunktionen sind öffentlich.
• WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) liefert Echtzeitdaten; bevorzugen Sie WS für Live-Book-Updates anstatt Polling.
• Abschwächungsmuster: Anfrage-Koaleszenz, Caching-TTLs, exponentielles Backoff mit Jitter, rate-aware Queuing und paginationsbewusstes Abrufen.

Warum Rate-Limits wichtig sind

Rate-Limits schützen die geteilte Infrastruktur von Polymarket und verhindern, dass laute Clients die Erfahrung anderer verschlechtern. Für Entwickler, die Arbitrage-Bots oder Analytics-Systeme bauen, führt das Erreichen eines Limits zu sofortiger Ablehnung von Anfragen und kann zeitkritische Abläufe unterbrechen. Planen Sie Anfrage-Muster im Voraus, um Überraschungen zu vermeiden und Systeme robuster zu machen.

Dokumentierte Polymarket-Rate-Limits und Endpunkte

Gamma (primäre Marktmatrix-Metadaten)

• Base URL: https://gamma-api.polymarket.com
• Bemerkenswerte Limits:
  • /markets: maximal 300 Anfragen pro 10 Sekunden. Verwenden Sie den Parameter limit (max 1000) und cursor-basierte Paginierung über after_cursor. Die API lehnt offset mit HTTP 422 ab.
  • Kombiniertes /markets + /events-Listing-Limit: 900 Anfragen pro 10 Sekunden.
  • Gesamte Gamma-API-Oberfläche: 4000 Anfragen pro 10 Sekunden.

Praktische Hinweise:

• Bevorzugen Sie immer das after_cursor, das vom vorherigen Aufruf zurückgegeben wurde; versuchen Sie nicht, Keyset-Emulation mit offset.
• Passen Sie limit an, um Round-Trips zu reduzieren. Wenn Sie vollständige Marktlisten benötigen, reduziert limit=1000 die Anzahl der Aufrufe.

Data (Positionen, Trades, Inhaber)

• Base URL: https://data-api.polymarket.com
• Auth: Keine für öffentliche Leseaufrufe.
• Die Kurzdokumentation beschreibt die Oberfläche, listet aber keine per-Endpunkt-Rate-Werte für Data auf. Behandeln Sie Data als öffentlich, implementieren Sie aber dieselben konservativen clientseitigen Kontrollen wie bei Gamma (Batching, Caching, Backoff).

CLOB (Orderbuch und Trading)

• Base URL: https://clob.polymarket.com
• Lesefunktionen sind öffentlich. Trading erfordert API key + HMAC.
• Die CLOB-Oberfläche stellt Orderbuch, Midpoint, Preishistorie sowie Order-Placement/-Cancellation bereit. Die Dokumentation veröffentlicht keine expliziten Per-Endpoint-Rate-Zahlen für CLOB-Reads; behandeln Sie Trading-Pfade als rate-sensitiv und verwenden Sie nach Möglichkeit die CLOB-WebSocket oder den Market WS für Live-Book-Daten.

Market WebSocket (Echtzeit-Marktdaten)

• URL: wss://ws-subscriptions-clob.polymarket.com/ws/market
• Für Marktdaten ist keine Auth erforderlich.
• Feeds: Echtzeit-Book, price_change, best_bid_ask (aktivierbar mit custom_feature_enabled: true), last_trade_price, tick_size_change.
• PING-Heartbeat alle 10 Sekunden. Maximal 500 Instrumente pro Verbindung.

Gamma-/markets-Spezifika, die Sie befolgen müssen

• Paginierung: nur after_cursor. Die API gibt next_cursor zurück — übergeben Sie ihn unverändert an den nächsten Aufruf.
• limit Standard ist 20, maximal 1000. Verwenden Sie größere limit für Bulk-Synchronisationen.
• Akzeptierte Filter-Parameter umfassen Arrays für slug, id, condition_ids, clob_token_ids, question_ids, market_maker_address und andere wie closed, active, archived, tag_id.
• Sortierung: order akzeptiert kommaseparierte Feldlisten (z. B. volume24hr,liquidity) und ascending ist boolean mit Standard true.

Gängige Fehlersignale und wie Sie reagieren sollten

• HTTP 429 (rate limited): stoppen Sie sofortiges Polling, führen Sie Backoff durch und versuchen Sie mit exponentiellem Backoff und Jitter erneut.
• HTTP 422 bei Verwendung von offset: wechseln Sie zur Paginierung mit after_cursor.
• Teilantworten oder leere Seiten: respektieren Sie Cursors; prüfen Sie Ihre Filter. Wenn Sie glauben, eine serverseitige Quote erreicht zu haben, reduzieren Sie die Client-Anfrage-Konkurrenz.

Designmuster, um Throttling zu vermeiden

1. Aggressiv cachen

• Cachen Sie Marktlisten und Metadaten für kurze TTLs (30s–2m), abhängig vom Use-Case. Märkte und Event-Listen ändern sich selten jede Sekunde.
• Cachen Sie nach Query-Key (Filter + Order). Invalidieren Sie den Cache nur, wenn Sie Änderungsereignisse erhalten (z. B. über WebSocket) oder die TTL abläuft.

2. Batchen und limit erhöhen

• Für Full-Syncs verwenden Sie limit=1000, um Round-Trips gegen /markets zu reduzieren.
• Ziehen Sie breite Seiten während Off-Peak-Zeiten und verwenden Sie inkrementelle Updates vom WebSocket.

3. Verwenden Sie den WebSocket für Echtzeitdaten

• Für Live-Order-Book-Updates oder Preisbewegungen abonnieren Sie den Market WS statt Gamma oder CLOB-Reads zu polllen. Der WS unterstützt bis zu 500 Instrumente pro Verbindung; sharden Sie Clients, wenn Sie >500 benötigen.

4. Rate-aware Queuing und Backoff

• Implementieren Sie einen leaky-bucket- oder token-bucket-Client-Limiter, der sich an dokumentierten Spitzenwerten orientiert (z. B. 300/10s für /markets).
• Wenn Sie 429 erhalten, wenden Sie exponentielles Backoff mit Jitter an und vergrößern Sie schrittweise das Retry-Fenster.

5. Identische gleichzeitige Anfragen koaleszieren

• Wenn mehrere Teile Ihrer App dieselbe /markets-Abfrage gleichzeitig anfordern, koaleszieren Sie diese zu einer einzigen laufenden Anfrage und verteilen Sie die Antwort.

6. Cursor-first-Synchronisation

• Folgen Sie immer der cursor-basierten Paginierung. Für Live-Synchronisationen fordern Sie die erste Seite an und abonnieren dann Deltas, falls unterstützt. Versuchen Sie nicht naive gleichzeitige cursored Fetches, die Gammas Per-Endpoint-Limit überschreiten könnten.

Beispielhafte Fetch-Strategien

• Bulk-Indexing-Job (nicht Echtzeit): holen Sie /markets?limit=1000 und folgen Sie next_cursor, bis erschöpft. Pausieren Sie kurz zwischen Seiten und respektieren Sie das Endpoint-Limit 300/10s.
• Near-Echtzeit-UI: holen Sie einmal den Basissatz (Cache 30s), dann öffnen Sie WebSocket für Deltas und best_bid_ask-Updates.
• Watchlist-Micro-Client: sharden Sie Watchlists über mehrere WS-Verbindungen, wenn >500 Instrumente überwacht werden.

Betriebsleitfaden für Bots und hochdurchsatzfähige Clients

• Verwenden Sie die CLOB-WebSocket oder CLOB-Reads für Book-Level-Daten und Gamma für langsamere Metadaten.
• Halten Sie Trading-Zugangsdaten (CLOB API key + HMAC) sicher; Trading-Endpunkte sind authentifiziert.
• Überwachen Sie Ihre 429-Rate und per-Endpoint-Latenzmetriken. Wenn Sie regelmäßig an dokumentierte Grenzen herankommen, beantragen Sie Zugang oder wenden Sie sich über offizielle Polymarket-Kanäle (das Builder Program ist der Weg für höhervolumige Integrationen und Attribution) an das Team.

Wie sich das auf Entwicklung und Deployment auswirkt

Wenn Sie einen Trading-Bot oder einen Analytics-Service bauen, planen Sie mehrschichtige Datenflüsse: ein initialer Bulk-Fetch von Gamma mit großem limit, gefolgt von WebSocket-Abonnements für Live-Updates und einer kleinen Menge periodischer Gamma-Polls (gecached) für Metadaten, die nicht im WS-Feed enthalten sind. Implementieren Sie clientseitiges Rate-Limiting, Koaleszenz und cursor-aware Paginierung, um das dokumentierte /markets-Limit von 300 req / 10 s und die kombinierten Listing- und Gesamtlimes von Gamma zu vermeiden.

Abschließende Zusammenfassung

Polymarket-API-Rate-Limits sind für Gammas Listing-Oberflächen explizit, und der Market WS bietet eine skalierbare Alternative für Live-Feeds. Entwerfen Sie um cursor-basierte Paginierung (after_cursor), verwenden Sie limit strategisch und bevorzugen Sie WebSockets für hochfrequente Daten. Das Befolgen dieser Muster reduziert Throttling und macht Ihre Integrationen zuverlässiger.

Frequently asked questions

What is the /markets rate limit on Gamma?

Gammas /markets-Endpoint ist auf 300 Anfragen pro 10 Sekunden begrenzt. Verwenden Sie limit (max 1000) und cursor-basierte Paginierung über after_cursor. Verwenden Sie nicht offset — die API lehnt es mit HTTP 422 ab.

Are there combined limits for Gamma endpoints?

Ja. Listing-Aufrufe zu /markets und /events teilen sich ein kombiniertes Limit von 900 Anfragen pro 10 Sekunden. Zusätzlich ist die gesamte Gamma-API-Oberfläche auf 4000 Anfragen pro 10 Sekunden beschränkt.

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

Bevorzugen Sie den Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) für Live-Book- und Preis-Updates — er ist effizienter und vermeidet wiederholtes Polling. Verwenden Sie Gamma für langsamer ändernde Metadaten und initiale Bulk-Syncs.

What should my client do on HTTP 429 responses?

Behandeln Sie 429 als Signal, aggressives Polling einzustellen. Implementieren Sie exponentielles Backoff mit Jitter, reduzieren Sie die Konkurrenz und koaleszieren Sie identische Anfragen. Verfolgen Sie 429s, um Ihren Rate-Limiter dynamisch anzupassen.

Does the CLOB API require authentication?

CLOB-Reads sind öffentlich. Trading-Operationen auf CLOB erfordern einen API key plus HMAC-Authentifizierung. Respektieren Sie Trading-Rate-Limits und bevorzugen Sie WS-Feeds für Book-Updates.