Polymarket Gamma API-Tutorial

Dieses Polymarket Gamma API-Tutorial zeigt Ihnen, wie Sie Märkte und Events von Polymarket's Gamma-Oberfläche abrufen, Paginierung handhaben und gängige Filter anwenden. Beispiele verwenden curl und TypeScript, damit Sie Reads in Bots, Dashboards oder Analytics-Pipelines integrieren können.

Wesentliche Erkenntnisse

• Gammas Basis-URL ist https://gamma-api.polymarket.com und erfordert für Lesezugriffe keine Authentifizierung.
• Verwenden Sie die Endpunkte /markets und /events mit Cursor-basierter Paginierung über after_cursor; nutzen Sie nicht offset.
• Beachten Sie die Ratenlimits: /markets hat 300 req / 10 s; kombinierte /markets + /events Listing-Grenze ist 900 req / 10 s. Gesamtes API-Limit ist 4000 req / 10 s.
• Filtern Sie nach Feldern wie condition_ids, clob_token_ids, slug und tag_id, um Payload zu reduzieren und Limits zu vermeiden.
• Verwenden Sie kleine Seitengrößen und exponentielles Backoff für Produktionsclients.

1. Gamma-Grundlagen: Endpunkte und Limits

Die Gamma-Lese-Basis-URL ist:

https://gamma-api.polymarket.com

Endpunkte, die Sie in diesem Tutorial verwenden:

• GET /markets — Marktliste und Abfragen einzelner Märkte
• GET /events — gruppierte Events (nützlich für Event-Level-Metadaten)

Wichtige Ratenlimits, um die Sie Ihr Design herum planen sollten:

• /markets: 300 Anfragen pro 10 Sekunden
• /markets + /events Listing kombiniert: 900 Anfragen pro 10 Sekunden
• Gesamte Gamma API: 4000 Anfragen pro 10 Sekunden

Wenn Ihr Client große Datensätze pollt oder nachholt, batchen und staffeln Sie Anfragen und halten Sie diese Limits ein.

2. Märkte abrufen: minimales curl-Beispiel

Eine minimale Anfrage, um Märkte mit Standardparametern aufzulisten:

curl "https://gamma-api.polymarket.com/markets"

Um Seitenumfang (limit) und Sortierung zu steuern:

curl "https://gamma-api.polymarket.com/markets?limit=100&order=volume24hr&ascending=false"

Hinweise:

• Das Maximum für limit ist 1000. Standard ist 20.
• Gamma lehnt offset-basierte Paginierung mit HTTP 422 ab. Verwenden Sie stattdessen after_cursor für Keyset-Paginierung.

3. Cursor-basierte Paginierung (after_cursor)

Gamma liefert in Listing-Antworten ein next_cursor. Verwenden Sie diesen Wert in after_cursor, um die nächste Seite abzurufen. Ein TypeScript-Beispiel (node-fetch oder native fetch) folgt.

TypeScript example (node-fetch or native fetch):

import fetch from 'node-fetch';

const BASE = 'https://gamma-api.polymarket.com';

type MarketsResponse = {
  markets: any[];
  next_cursor?: string | null;
};

async function fetchAllMarkets(limit = 200) {
  let cursor: string | undefined;
  const all: any[] = [];

  while (true) {
    const url = new URL('/markets', BASE);
    url.searchParams.set('limit', String(limit));
    if (cursor) url.searchParams.set('after_cursor', cursor);

    const res = await fetch(url.toString());
    if (!res.ok) throw new Error(`Gamma error ${res.status}`);

    const body: MarketsResponse = await res.json();
    all.push(...body.markets);

    if (!body.next_cursor) break;
    cursor = body.next_cursor;

    // small delay to avoid spike; tune for your rate budget
    await new Promise((r) => setTimeout(r, 100));
  }

  return all;
}

Gezeigte Best Practices:

• Verwenden Sie limit, um Seitenumfang und Netzwerkverkehr zu steuern.
• Beachten Sie next_cursor und stoppen Sie, wenn dieser fehlt.
• Fügen Sie kleine Pausen oder Backoff ein, wenn Sie sich den Ratenlimits nähern.

4. Filter und Abfrageparameter, die Sie kennen sollten

Gamma unterstützt viele Abfrageparameter. Die nützlichsten, wenn Sie gezielte Reads benötigen:

• slug, id, question_ids, condition_ids, clob_token_ids, market_maker_address — alle als Arrays
• closed (boolean), active, archived
• tag_id — Filter nach Kategorie
• order — kommaseparierte Felder wie volume24hr, volume, liquidity, endDate
• ascending — boolean (Standard true)

Beispiel: aktive Märkte in einem Tag abrufen, sortiert nach 24h-Volumen absteigend:

curl "https://gamma-api.polymarket.com/markets?active=true&tag_id=123&order=volume24hr&ascending=false&limit=100"

Wenn Sie nur bestimmte Märkte benötigen, übergeben Sie Arrays für slug oder id, um Payload zu reduzieren und Listenscans zu vermeiden.

5. Events-Endpunkt

Der Endpunkt /events gruppiert Märkte unter Event-Level-Metadaten (z. B.: "2026 Presidential Election" als Event, das mehrere Markt-Conditions enthält).

Basisaufruf:

curl "https://gamma-api.polymarket.com/events?limit=50"

Events verwenden ebenfalls after_cursor für Paginierung und teilen das kombinierte Listing-Limit mit /markets (900 req / 10 s für kombinierte Listings).

6. Praktisches TypeScript-Beispiel: Märkte nach condition_ids abrufen

Dieses Beispiel ruft Märkte für eine Liste von Condition-IDs ab, mit Concurrency-Control und exponentiellem Backoff.

import fetch from 'node-fetch';

const BASE = 'https://gamma-api.polymarket.com';

async function fetchMarketsByCondition(conditionIds: string[]) {
  const results: any[] = [];

  for (const id of conditionIds) {
    let cursor: string | undefined;
    let retries = 0;

    while (true) {
      const url = new URL('/markets', BASE);
      url.searchParams.set('limit', '200');
      url.searchParams.set('condition_ids', id);
      if (cursor) url.searchParams.set('after_cursor', cursor);

      const res = await fetch(url.toString());
      if (res.status === 429) {
        // respect rate limits with exponential backoff
        await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, retries)));
        retries = Math.min(retries + 1, 5);
        continue;
      }

      if (!res.ok) throw new Error(`Gamma ${res.status}`);

      const body = await res.json();
      results.push(...body.markets);

      if (!body.next_cursor) break;
      cursor = body.next_cursor;
    }
  }

  return results;
}

Hinweise für den Produktionseinsatz:

• Verwenden Sie einen Concurrency-Limiter (z. B. p-map, p-limit), wenn conditionIds groß ist.
• Cachen Sie unveränderte Ergebnisse (ETag/If-None-Match), falls die API dies für Ihren Anwendungsfall unterstützt.
• Überwachen Sie Ihre Anfrage-Rate im Verhältnis zu den dokumentierten Limits.

7. Häufige Fallen und Troubleshooting

• Verwenden Sie nicht offset — Gamma antwortet mit HTTP 422 auf Offset-Parameter.
• Sehr große Seiten ohne Cursors anzufordern kann Ratenlimits und Memory-Pressure auslösen; bevorzugen Sie kleinere limits und Cursor-Traversal.
• Die kombinierten /markets + /events Listing-Limits bedeuten, dass intensives Polling beider Endpunkte schnell zu Throttling führen kann.
• Die API gibt next_cursor für Keyset-Paginierung zurück; behandeln Sie ihn als undurchsichtig und geben Sie ihn unverändert zurück.

8. Integration mit Echtzeitdaten

Gamma ist die REST-Oberfläche für Metadaten und historische Listings. Für Echtzeit-Orderbook- und Tick-Events verwenden Sie den Market WebSocket unter wss://ws-subscriptions-clob.polymarket.com/ws/market. Der WebSocket unterstützt bis zu 500 Instrumente pro Verbindung und sendet price_change, best_bid_ask, last_trade_price und tick_size_change Events.

Behalten Sie REST für Backfills und den WebSocket für Live-Updates.

9. Auswirkungen auf Ihr Trading oder Ihre Tools

Wenn Sie Trading-Bots, Dashboards oder Daten-Pipelines bauen, ist Gamma die kanonische Lesequelle für Marktmetadaten, Tags und Listings. Verwenden Sie Cursor-Paginierung, filtern Sie aggressiv und kombinieren Sie Gamma-Reads mit der CLOB API oder dem Market WebSocket für Preis- und Orderbook-Daten. Planen Sie Ihre Polling-Frequenz um die dokumentierten Ratenlimits, um Throttling zu vermeiden.

Gamma ist für öffentliche Daten read-only; für die obigen Beispiele ist kein API-Key erforderlich. Für Order-Platzierung und Book-Operationen verwenden Sie die CLOB API unter https://clob.polymarket.com, die API key + HMAC erfordert.

Abschluss

Dieses Polymarket Gamma API-Tutorial hat die praktischen Schritte zum Abrufen von Märkten und Events, zur Handhabung der Cursor-Paginierung und zur Vermeidung häufiger Fallen behandelt. Nutzen Sie diese Muster als Basis für zuverlässige Bots und Analytics, die Gammas Ratenlimits und Paginierungsmodell respektieren.

Häufig gestellte Fragen

Benötige ich einen API-Key, um von der Gamma API zu lesen?

Nein. Gammas öffentliche Leseendpunkte erfordern keine Authentifizierung. Die Basis-URL ist https://gamma-api.polymarket.com. Nur der CLOB-Endpunkt benötigt API key + HMAC für Trading.

Wie blättere ich durch große Marktlisten?

Verwenden Sie Cursor-basierte Paginierung. Jede Listing-Antwort enthält next_cursor; übergeben Sie diesen Wert als after_cursor, um die nächste Seite abzurufen. Gamma lehnt offset-basierte Paginierung mit HTTP 422 ab.

Welche wichtigen Ratenlimits sollte ich beachten?

/markets hat ein Limit von 300 Anfragen pro 10 Sekunden. Kombinierte /markets + /events Listing-Aufrufe zählen auf ein kombiniertes Limit von 900 req / 10 s. Das gesamte Gamma API-Limit beträgt 4000 req / 10 s. Staffeln Sie Anfragen und implementieren Sie Backoff, um Throttling zu vermeiden.

Sollte ich Gamma oder den Market WebSocket für Echtzeitdaten verwenden?

Verwenden Sie Gamma für Metadaten, Listings und historische Reads. Verwenden Sie den Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) für Echtzeit-Orderbook- und Tick-Events; der WebSocket unterstützt bis zu 500 Instrumente pro Verbindung.

Kann ich Märkte nach Tag oder Condition filtern?

Ja. Gamma unterstützt Filter wie tag_id, condition_ids, clob_token_ids, slug und weitere. Durch die Übergabe spezifischer Filter reduzieren Sie Payload und bleiben eher innerhalb der Ratenlimits.