Polymarket Gamma API tutorial

Questa guida alla Gamma API di Polymarket ti insegna come recuperare mercati ed eventi dalla surface Gamma, gestire la paginazione e applicare i filtri più comuni. Gli esempi usano curl e TypeScript in modo da poter integrare le letture in bot, cruscotti o pipeline di analytics.

Punti chiave

• L'URL base di Gamma è https://gamma-api.polymarket.com e non richiede autenticazione per le letture.
• Usa gli endpoint /markets e /events con paginazione basata su cursore usando after_cursor; non usare offset.
• Rispetta i rate limit: /markets ha 300 req / 10 s; il limite combinato /markets + /events per listing è 900 req / 10 s. Il limite complessivo dell'API è 4000 req / 10 s.
• Filtra per campi come condition_ids, clob_token_ids, slug e tag_id per ridurre il payload ed evitare di raggiungere i limiti.
• Usa dimensioni di pagina piccole e backoff esponenziale per client di produzione.

1. Gamma basics: endpoints and limits

L'URL base per le letture Gamma è:

https://gamma-api.polymarket.com

Gli endpoint che userai in questo tutorial:

• GET /markets — elenco mercati e query per singolo mercato
• GET /events — eventi raggruppati (utile per metadata a livello di evento)

Rate limit importanti da considerare nella progettazione:

• /markets: 300 richieste ogni 10 secondi
• /markets + /events listing combinati: 900 richieste ogni 10 secondi
• Gamma API complessiva: 4000 richieste ogni 10 secondi

Se il tuo client fa polling o backfill di dataset grandi, raggruppa e distribuisci le richieste e rispetta questi limiti.

2. Fetching markets: minimal curl example

Una richiesta minima per elencare i mercati con i parametri di default:

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

Per controllare la dimensione della pagina (limit) e l'ordinamento:

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

Note:

• il valore massimo di limit è 1000. Il valore di default è 20.
• Gamma respinge la paginazione basata su offset (HTTP 422). Usa after_cursor per la paginazione keyset.

3. Cursor-based pagination (after_cursor)

Gamma restituisce un next_cursor nelle risposte di listing. Usa quel valore in after_cursor per ottenere la pagina successiva. Segue un esempio in TypeScript.

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;
}

Best practice mostrate:

• Usa limit per controllare la dimensione della pagina e l'uso della rete.
• Rispetta next_cursor e interrompi quando non è presente.
• Aggiungi piccoli ritardi o backoff quando sei vicino ai rate limit.

4. Filtering and query parameters worth knowing

Gamma supporta molti parametri di query. I più utili quando vuoi letture mirate:

• slug, id, question_ids, condition_ids, clob_token_ids, market_maker_address — tutti array
• closed (booleano), active, archived
• tag_id — filtra per categoria
• order — campi separati da virgola come volume24hr, volume, liquidity, endDate
• ascending — booleano (default true)

Esempio: recupera mercati attivi in un tag, ordinati per volume 24h decrescente:

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

Quando ti servono solo mercati specifici, passa array per slug o id per ridurre il payload ed evitare scansioni di lista.

5. Events endpoint

L'endpoint /events raggruppa i mercati sotto metadata a livello di evento (per esempio: "2026 Presidential Election" come evento che contiene più condizioni di mercato).

Chiamata di base:

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

Anche gli eventi usano after_cursor per la paginazione e condividono il limite combinato di listing con /markets (900 req / 10 s per listati combinati).

6. Practical TypeScript example: fetch markets by condition_ids

Questo esempio recupera i mercati per una lista di condition ID, con controllo di concorrenza e backoff esponenziale.

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;
}

Note per l'uso in produzione:

• Usa un limiter di concorrenza (p-map, p-limit) se conditionIds è grande.
• Cache i risultati invariati (ETag/If-None-Match) se l'API li supporta per il tuo caso d'uso.
• Monitora il tasso di richieste rispetto ai limiti documentati.

7. Common pitfalls and troubleshooting

• Non usare offset — Gamma restituisce HTTP 422 per i parametri offset.
• Richiedere pagine enormi senza cursori può colpire i rate limit e causare pressione di memoria; preferisci limiti più piccoli e attraversamento tramite cursore.
• Il limite combinato /markets + /events significa che il polling intensivo di entrambi gli endpoint può rapidamente limitarti.
• L'API restituisce next_cursor per la paginazione keyset; trattalo come opaco e ritrasmettelo esattamente.

8. Integrating with real-time data

Gamma è la surface REST per metadata e listing storici. Per dati in tempo reale sull'order-book e eventi tick, usa il Market WebSocket a wss://ws-subscriptions-clob.polymarket.com/ws/market. Il WebSocket supporta fino a 500 strumenti per connessione ed emette price_change, best_bid_ask, last_trade_price e tick_size_change.

Mantieni REST per backfill e WebSocket per aggiornamenti live.

9. How this affects your trading or tooling

Se stai costruendo bot di trading, dashboard o pipeline di dati, Gamma è la sorgente canonica per metadata di mercato, tag e listing. Usa la paginazione a cursore, filtra in modo aggressivo e abbina le letture Gamma con la CLOB API o il Market WebSocket per prezzi e dati di order-book. Pianifica la cadenza del polling attorno ai rate limit documentati per evitare throttling.

Gamma è in sola lettura per i dati pubblici; non è richiesta alcuna API key per gli esempi sopra. Per l'invio di ordini e le operazioni sul book usa la CLOB API a https://clob.polymarket.com, che richiede API key + HMAC.

Closing

Questa guida alla Gamma API di Polymarket ha coperto i passaggi pratici per recuperare mercati ed eventi, gestire la paginazione a cursore e evitare gli errori più comuni. Usa questi pattern come base per bot e sistemi di analytics affidabili che rispettino i rate limit e il modello di paginazione di Gamma.

Frequently asked questions

Do I need an API key to read from the Gamma API?

No. Gli endpoint pubblici di lettura di Gamma non richiedono autenticazione. L'URL base è https://gamma-api.polymarket.com. Solo l'endpoint CLOB richiede API key + HMAC per il trading.

How do I page through large market lists?

Usa la paginazione basata su cursore. Ogni listing restituisce next_cursor; passa quel valore come after_cursor per ottenere la pagina successiva. Gamma respinge la paginazione basata su offset con HTTP 422.

What are the important rate limits to consider?

/markets ha un limite di 300 richieste ogni 10 secondi. Le chiamate di listing combinate /markets + /events contano verso un limite combinato di 900 req / 10 s. Il limite complessivo della Gamma API è 4000 req / 10 s. Distribuisci le richieste e implementa backoff per evitare throttling.

Should I use Gamma or the Market WebSocket for real-time data?

Usa Gamma per metadata, listing e letture storiche. Usa il Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) per order-book in tempo reale e eventi tick; il WebSocket supporta fino a 500 strumenti per connessione.

Can I filter markets by tag or condition?

Sì. Gamma supporta filtri come tag_id, condition_ids, clob_token_ids, slug e altri. Passare filtri specifici riduce il payload e aiuta a rimanere nei limiti di richiesta.