Polymarket Gamma API: Guía práctica de integración y pipelines de datos

Qué es la API Gamma y dónde encaja

La API Gamma de Polymarket es una interfaz REST de solo lectura en https://gamma-api.polymarket.com que devuelve metadatos indexados sobre eventos y mercados en Polymarket. No requiere clave de API para sus endpoints públicos de lectura, lo que la convierte en la primera llamada natural en cualquier aplicación de mercados de predicción: usas Gamma para descubrir qué existe y luego pasas los identificadores de token resultantes a otros servicios para precios y ejecución.

El punto arquitectónico importante es la separación de responsabilidades. Gamma es un catálogo, no un lugar de negociación. Responde preguntas como «qué mercados están activos», «cuál es el slug de este evento» y «qué tokens de resultado pertenecen a este mercado». No responde «cuál es la mejor oferta actual» ni «coloca esta orden». Esas pertenecen a la API CLOB, mientras que las posiciones de usuario y el historial de operaciones pertenecen a la API Data. Tratar a Gamma como la capa de descubrimiento y a las otras API como capas de ejecución y analítica mantiene tu integración limpia y tus modos de fallo aislados.

Esta guía asume que tienes un cliente HTTP funcional, familiaridad básica con JSON y un lugar para persistir datos, como una base de datos o un almacén de objetos. Todos los ejemplos usan marcadores de posición y rutas públicas de lectura; no se requieren credenciales para las operaciones mostradas.

• Gamma: eventos, mercados, etiquetas, series, metadatos deportivos, búsqueda.
• CLOB: libros de órdenes, precios, colocación y cancelación de órdenes.
• API Data: operaciones, posiciones y actividad específica del usuario.
• Subgraph: consultas directas on-chain cuando necesitas el estado bruto de la cadena.

La jerarquía de eventos y mercados

Gamma organiza los datos jerárquicamente. Una serie agrupa eventos relacionados, como una liga deportiva recurrente o un conjunto estacional de preguntas. Un evento es un concepto a nivel de página que normalmente corresponde a una pregunta en el sitio de Polymarket y puede contener uno o más mercados. Un mercado es la unidad negociable y contiene los tokens de resultado, volumen, liquidez y campos de estado.

Cada mercado expone identificadores que necesitarás aguas abajo. El conditionId identifica el contrato del mercado, y clobTokenIds es un arreglo de identificadores de token para los resultados, típicamente Sí y No. Cuando pasas de Gamma a CLOB para precios, pasas esos identificadores de token en lugar de los slugs de mercado. Persistir la asignación entre slug, conditionId e IDs de token en el momento de la ingesta ahorra búsquedas repetidas más adelante.

Los eventos y mercados también tienen campos de estado como active y closed. Son independientes: un mercado puede estar activo pero no cerrado, cerrado e inactivo, o en estados transitorios alrededor de la resolución. Filtra por ambos cuando quieras inventario actualmente negociable, y registra los valores que observaste para poder razonar sobre cambios a lo largo del tiempo.

Listar eventos activos con curl

Comienza con una solicitud mínima que liste eventos activos y abiertos ordenados por volumen reciente. La respuesta incluye un indicador has_more y los objetos de evento en sí. Inspecciona una respuesta manualmente antes de escribir cualquier código de pipeline para que entiendas los nombres de campo que devuelve tu versión de la API.

El siguiente comando es seguro de ejecutar contra el endpoint público. No requiere autenticación y no modifica el estado.

curl -s "https://gamma-api.polymarket.com/events?active=true&closed=false&order=volume_24hr&ascending=false&limit=5" \
  | python -m json.tool | head -n 80

Paginar mercados sin perder filas

Gamma admite paginación basada en offset con limit y offset, y la respuesta incluye has_more. El patrón fiable es solicitar una página, procesarla y luego incrementar el offset por el número de registros realmente devueltos hasta que has_more sea falso. No asumas que el servidor devuelve exactamente limit registros; la página final suele ser más corta y los filtros pueden reducir el tamaño de página.

Un modo de fallo sutil es la deriva de offset. Si paginas a través de una lista activa ordenada por volumen mientras nuevos eventos entran en la parte superior del orden, las filas pueden desplazarse entre páginas y puedes ver duplicados o perder registros. Para una ingesta tipo snapshot, ordena por un campo estable como start_date o id cuando esté disponible, o acepta duplicados y deduplica aguas abajo por identificador de mercado. Gamma también expone endpoints de estilo keyset como markets/keyset y events/keyset; prefiérelos cuando necesites un recorrido estable de grandes conjuntos de resultados.

El ejemplo de Python a continuación demuestra un paginador acotado y deduplicador. Limita el total de páginas para que un bucle descontrolado no pueda saturar el endpoint, y registra los identificadores que ya ha visto.

import time
import requests

BASE = "https://gamma-api.polymarket.com"

def iter_markets(limit=100, max_pages=20, pause=0.5):
    seen = set()
    offset = 0
    for _ in range(max_pages):
        resp = requests.get(
            f"{BASE}/markets",
            params={"active": "true", "closed": "false", "limit": limit, "offset": offset},
            timeout=15,
        )
        resp.raise_for_status()
        batch = resp.json()
        if not batch:
            break
        for market in batch:
            key = market.get("conditionId") or market.get("slug")
            if key and key not in seen:
                seen.add(key)
                yield market
        offset += len(batch)
        time.sleep(pause)

for m in iter_markets():
    print(m.get("slug"), m.get("conditionId"))

Resolver un solo mercado por slug

Cuando ya conoces el slug de un mercado, obtenlo directamente en lugar de escanear listas. El endpoint de slug devuelve el objeto del mercado, que luego puedes unir a tus metadatos almacenados. Este es el patrón a usar en un manejador de webhooks o en una página de detalles orientada al usuario, donde la latencia importa y un listado completo sería un desperdicio.

El mismo principio se aplica a los eventos: el endpoint de eventos acepta un parámetro slug y devuelve el evento coincidente con sus mercados anidados. Usa estas búsquedas específicas para rutas de lectura y reserva los endpoints de listado para la ingesta programada.

curl -s "https://gamma-api.polymarket.com/markets?slug=fed-decision-in-october" \
  | python -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d[0] if d else {}, indent=2)[:1200])"

Diseñar un pipeline de ingesta reproducible

Un pipeline de producción en torno a la API Gamma debe ser aburrido y observable. Estructúralo en cuatro etapas: obtener, normalizar, persistir y verificar. En la etapa de obtención, aplica filtros explícitos y un número acotado de páginas. En la normalización, mapea los campos de Gamma a tu propio esquema y extrae clobTokenIds a una tabla separada. En la persistencia, haz upsert por conditionId para que las ejecuciones repetidas sean idempotentes. En la verificación, compara recuentos de filas y sumas de comprobación con la ejecución anterior.

Registra los parámetros de la solicitud, el estado de la respuesta y el recuento de registros de cada página en un log de ejecución. Cuando algo parezca incorrecto más adelante, ese log es la diferencia entre un diagnóstico de cinco minutos y una tarde de conjeturas. Almacena el JSON sin procesar junto a las filas normalizadas durante al menos unas pocas ejecuciones para que puedas reproducir sin volver a obtener los datos.

Trata los límites de tasa como desconocidos hasta que los midas. La API pública es infraestructura compartida, así que incorpora una pausa conservadora entre páginas, respeta las respuestas 429 con retroceso exponencial y nunca paralelices agresivamente contra un endpoint compartido. Si tu carga de trabajo crece más allá de lo que permite un uso público respetuoso, considera una capa de datos dedicada o tu propio nivel de caché en lugar de aumentar la presión de solicitudes.

• Upsert por conditionId; mantén slug como clave secundaria.
• Persiste las cargas útiles sin procesar para reproducción y detección de deriva de esquema.
• Registra parámetros de página, códigos de estado y recuentos de filas por ejecución.
• Retrocede ante 429 y 5xx; limita los reintentos y alerta al agotarlos.

Verificar una ejecución y leer la tabla de resultados

Después de cada ejecución de ingesta, genera una pequeña tabla de resultados para que puedas comparar ejecuciones de un vistazo. La tabla siguiente es una plantilla: complétala con tus propios valores observados. No copies números de documentación ni de otros artículos; el objetivo es establecer una línea base para tu entorno y tus filtros.

Una ejecución saludable muestra registros vistos mayores o iguales que los registros insertados/actualizados, duplicados omitidos cercanos a cero en una primera ejecución y más altos en ejecuciones incrementales, y cero errores. Un salto repentino en duplicados generalmente significa deriva de offset en una lista ordenada. Una caída en registros vistos con los mismos filtros generalmente significa que un valor de filtro cambió o que el endpoint devolvió una página de error que tu cliente no detectó.

Para la latencia, mide el tiempo de solicitud de extremo a extremo en tu cliente y registra el percentil 95 por ejecución. Compáralo entre ejecuciones en lugar de contra un objetivo fijo; tanto la ruta de red como la carga del servidor varían. Si necesitas una ruta estable y de baja latencia para lecturas on-chain adyacentes, un endpoint gestionado de un proveedor como el servicio RPC de OnFinality puede eliminar una fuente de varianza, pero Gamma en sí sigue siendo un servicio operado por Polymarket.

Solución de problemas comunes de integración con Gamma

La mayoría de los problemas con Gamma caen en unas pocas categorías. Las respuestas vacías generalmente significan una combinación de filtros demasiado restrictiva, como active=true con closed=true y una etiqueta estrecha. Verifica cada filtro de forma independiente antes de combinarlos. Los 404 inesperados en búsquedas por slug generalmente significan que el slug cambió o que el mercado fue renombrado; recurre a una búsqueda por conditionId si almacenaste uno.

Las sorpresas de esquema son comunes cuando se agregan campos o los objetos anidados cambian de forma. El análisis defensivo, donde lees campos opcionales con valores predeterminados y registras claves desconocidas, evita que un solo campo nuevo rompa un pipeline. Si tu cliente deserializa a tipos estrictos, versiona tus modelos y tolera propiedades desconocidas.

La limitación de tasa aparece como respuestas 429, a veces sin un encabezado Retry-After. Implementa retroceso exponencial con jitter, limita la concurrencia a una solicitud a la vez para la ingesta y alerta si el retroceso supera un umbral. Los errores 5xx persistentes deben tratarse como una interrupción: pausa la ejecución, conserva la última instantánea buena y reanuda desde el último offset confirmado en lugar de reiniciar desde cero.

• Resultado vacío: relaja los filtros uno a la vez.
• 404 en slug: vuelve a resolver por conditionId o búsqueda.
• Error de análisis: registra la carga útil sin procesar y las claves desconocidas.
• 429: retrocede con jitter; reduce la concurrencia.
• 5xx: pausa, conserva la instantánea, reanuda desde el punto de control.

Límites, compensaciones y cuándo agregar otra capa

Gamma está optimizada para el descubrimiento, no para lecturas de alta frecuencia ni analítica histórica. Te da metadatos y estado actuales, pero no es un almacén de series temporales. Si necesitas series de precios históricas, profundidad del libro de órdenes o comparaciones entre venues, necesitarás la API CLOB, la API Data o una capa de analítica separada. Construir esas uniones tú mismo es razonable para un producto enfocado y costoso para uno amplio.

También hay una compensación de frescura. Almacenar en caché las respuestas de Gamma reduce la carga y la latencia, pero significa que tu catálogo puede retrasarse respecto a la realidad. Elige una duración de caché basada en la rapidez con la que tus usuarios necesitan ver nuevos mercados; para la mayoría de las interfaces de descubrimiento, una caché corta con actualización en segundo plano es suficiente. Para interfaces de negociación, siempre confirma el precio y la disponibilidad contra el CLOB antes de presentar una cotización accionable.

Finalmente, considera tu límite de infraestructura. Gamma es un servicio de Polymarket, pero el resto de tu stack puede leer el estado de la cadena directamente. Si consultas Polygon para datos de liquidación o saldos, un endpoint RPC fiable importa tanto como un catálogo fiable. Puedes revisar las redes disponibles y las opciones de endpoint a través del directorio de redes de OnFinality y comparar planes en la página de precios de RPC antes de comprometerte con un proveedor.

Próximos pasos para una integración en producción

Una vez que tu ingesta de Gamma sea estable, extiéndela en tres direcciones. Primero, agrega una ruta de lectura CLOB para que tu aplicación pueda mostrar precios en vivo junto a los metadatos del catálogo. Segundo, agrega una ruta de la API Data para posiciones de usuario e historial de operaciones si estás construyendo una vista de cartera. Tercero, agrega monitoreo que alerte sobre fallos de ingesta, deriva de esquema y regresiones de latencia en lugar de esperar a que los usuarios reporten mercados faltantes.

Si tu aplicación también necesita acceso directo a la cadena para verificaciones de liquidación o saldos de billeteras, evalúa un nodo dedicado o un servicio RPC gestionado para que las lecturas del catálogo y las lecturas de la cadena fallen de forma independiente. Puedes explorar opciones de nodos dedicados y la oferta más amplia de servicios de API para decidir si la infraestructura gestionada se ajusta a tus objetivos de fiabilidad.

Para equipos que quieren una recomendación concreta de endpoint en lugar de una metodología, el Asistente RPC es el lugar adecuado para preguntar; esta guía se mantiene deliberadamente en el nivel de integración y medición para que tus elecciones se basen en tu propio comportamiento observado.

• Agrega precios CLOB junto a los metadatos de Gamma.
• Agrega lecturas de la API Data para posiciones y actividad.
• Instrumenta la ingesta con alertas sobre deriva y fallos.
• Separa los dominios de fallo de la infraestructura del catálogo y de la cadena.