Polymarket Gamma API tutorial

Este tutorial de la API Gamma de Polymarket te enseña cómo obtener markets y events desde la superficie Gamma de Polymarket, manejar paginación y aplicar filtros comunes. Los ejemplos usan curl y TypeScript para que puedas integrar lecturas en bots, dashboards o pipelines de análisis.

Puntos clave

• La URL base de Gamma es https://gamma-api.polymarket.com y no requiere autenticación para lecturas.
• Usa los endpoints /markets y /events con paginación basada en cursor vía after_cursor; no uses offset.
• Respeta los límites de tasa: /markets tiene 300 req / 10 s; el límite combinado de listados /markets + /events es 900 req / 10 s. El límite global de la API es 4000 req / 10 s.
• Filtra por campos como condition_ids, clob_token_ids, slug y tag_id para reducir el payload y evitar alcanzar los límites.
• Usa tamaños de página pequeños y backoff exponencial en clientes de producción.

1. Fundamentos de Gamma: endpoints y límites

La URL base de lectura de Gamma es:

https://gamma-api.polymarket.com

Endpoints que usarás en este tutorial:

• GET /markets — lista de markets y consultas de mercado único
• GET /events — events agrupados (útil para metadatos a nivel de evento)

Límites de tasa importantes para diseñar alrededor:

• /markets: 300 requests por 10 segundos
• /markets + /events listados combinados: 900 requests por 10 segundos
• API Gamma en general: 4000 requests por 10 segundos

Si tu cliente va a hacer polling o backfill de conjuntos de datos grandes, agrupa y escalona las peticiones y respeta estos límites.

2. Obtener markets: ejemplo mínimo con curl

Una request mínima para listar markets con parámetros por defecto:

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

Para controlar el tamaño de página (limit) y el orden:

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

Notas:

• el máximo de limit es 1000. El valor por defecto es 20.
• Gamma rechaza la paginación basada en offset (HTTP 422). Usa after_cursor para paginación por keyset.

3. Paginación basada en cursor (after_cursor)

Gamma devuelve un next_cursor en las respuestas de listado. Usa ese valor en after_cursor para obtener la siguiente página. A continuación hay un flujo de ejemplo en TypeScript.

Ejemplo en TypeScript (node-fetch o fetch nativo):

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

Buenas prácticas mostradas:

• Usa limit para controlar el tamaño de página y el uso de red.
• Respeta next_cursor y detente cuando no exista.
• Añade pequeñas demoras o backoff cuando te acerques a los límites de tasa.

4. Filtros y parámetros de consulta útiles

Gamma soporta muchos parámetros de consulta. Los más útiles cuando quieres lecturas dirigidas:

• slug, id, question_ids, condition_ids, clob_token_ids, market_maker_address — todos son arrays
• closed (booleano), active, archived
• tag_id — filtra por categoría
• order — campos separados por comas como volume24hr, volume, liquidity, endDate
• ascending — booleano (por defecto true)

Ejemplo: obtener markets activos en una etiqueta, ordenados por volumen 24h descendente:

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

Cuando solo necesitas markets específicos, pasa arrays para slug o id para reducir el payload y evitar escaneos extensos.

5. Endpoint de events

El endpoint /events agrupa markets bajo metadatos a nivel de evento (por ejemplo: "2026 Presidential Election" como un event que contiene múltiples condiciones de mercado).

Llamada básica:

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

Los events también usan after_cursor para paginación y comparten el límite combinado de listados con /markets (900 req / 10 s para listados combinados).

6. Ejemplo práctico en TypeScript: obtener markets por condition_ids

Este ejemplo obtiene markets para una lista de condition IDs, con control de concurrencia y backoff exponencial.

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

Notas sobre uso en producción:

• Usa un limitador de concurrencia (p-map, p-limit) si conditionIds es grande.
• Cachea resultados inmutables (ETag/If-None-Match) si la API los soporta para tu caso de uso.
• Monitorea tu tasa de peticiones respecto a los límites documentados.

7. Errores comunes y resolución de problemas

• No uses offset — Gamma devuelve HTTP 422 para parámetros offset.
• Solicitar páginas enormes sin cursors puede alcanzar límites de tasa y provocar presión de memoria; prefiere límites más pequeños y recorrer con cursor.
• Los límites combinados /markets + /events significan que el polling intensivo de ambos endpoints puede throttlearte rápido.
• La API devuelve next_cursor para paginación por keyset; trátalo como opaco y pásalo de vuelta tal cual.

8. Integración con datos en tiempo real

Gamma es la superficie REST para metadatos y listados históricos. Para el order-book en tiempo real y eventos de ticks, usa el Market WebSocket en wss://ws-subscriptions-clob.polymarket.com/ws/market. El WebSocket soporta hasta 500 instrumentos por conexión y emite price_change, best_bid_ask, last_trade_price y tick_size_change.

Usa REST para backfills y WebSocket para actualizaciones en vivo.

9. Cómo esto afecta tu trading o tooling

Si estás construyendo bots de trading, dashboards o pipelines de datos, Gamma es la fuente canónica de lectura para metadatos de mercado, tags y listados. Usa paginación por cursor, filtra agresivamente y combina lecturas de Gamma con la API CLOB o el Market WebSocket para datos de precio y order-book. Planifica la cadencia de polling alrededor de los límites de tasa documentados para evitar throttling.

Gamma es de solo lectura para datos públicos; no se requiere API key para los ejemplos anteriores. Para colocar órdenes y operar el libro usa la API CLOB en https://clob.polymarket.com, que requiere API key + HMAC.

Cierre

Este tutorial de la API Gamma de Polymarket cubrió los pasos prácticos para obtener markets y events, manejar paginación por cursor y evitar errores comunes. Usa estos patrones como base para bots y análisis confiables que respeten los límites de tasa y el modelo de paginación de Gamma.

Preguntas frecuentes

¿Necesito una API key para leer de la API Gamma?

No. Los endpoints públicos de lectura de Gamma no requieren autenticación. La URL base es https://gamma-api.polymarket.com. Solo el endpoint CLOB requiere API key + HMAC para trading.

¿Cómo hago paginación a través de listas grandes de markets?

Usa paginación basada en cursor. Cada listado devuelve next_cursor; pasa ese valor como after_cursor para obtener la siguiente página. Gamma rechaza la paginación basada en offset con HTTP 422.

¿Cuáles son los límites de tasa importantes a considerar?

/markets tiene un límite de 300 requests por 10 segundos. Las llamadas de listado combinadas /markets + /events cuentan para un límite combinado de 900 req / 10 s. El límite global de la API Gamma es 4000 req / 10 s. Escalona las peticiones e implementa backoff para evitar throttling.

¿Debo usar Gamma o el Market WebSocket para datos en tiempo real?

Usa Gamma para metadatos, listados y lecturas históricas. Usa el Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) para order-book en tiempo real y eventos de ticks; el WebSocket soporta hasta 500 instrumentos por conexión.

¿Puedo filtrar markets por tag o condition?

Sí. Gamma soporta filtros como tag_id, condition_ids, clob_token_ids, slug y otros. Pasar filtros específicos reduce el payload y ayuda a mantenerse dentro de los límites de tasa.