Polymarket API rate limits — Gamma, Data & CLOB

Los límites de tasa de las API de Polymarket son las restricciones que debes tener en cuenta al diseñar bots, paneles o sistemas de analítica. Esta guía expone los límites documentados para cada superficie pública (Gamma, Data, CLOB y el WebSocket de mercado), explica las restricciones importantes de Gamma /markets (incluida la regla de 300 req / 10 s en /markets y la paginación basada en cursor) y ofrece estrategias concretas —agrupamiento, caché, paginación con cursor, backoff exponencial— para mantener tu cliente fiable bajo carga.

Puntos clave

• El endpoint /markets de Gamma: 300 solicitudes por 10 segundos; usa el parámetro limit y after_cursor para paginar (no uses offset).
• Límites combinados de listados: las llamadas de listado /markets + /events comparten un tope de 900 req / 10 s; Gamma en conjunto: 4000 req / 10 s.
• Usa las APIs CLOB y Data para lecturas especializadas; CLOB requiere API key + HMAC para llamadas de trading, las lecturas son públicas.
• WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) ofrece datos en tiempo real; prefiere WS para actualizaciones del libro en vivo en lugar de hacer polling.
• Patrones de mitigación: coalescencia de solicitudes, TTLs de caché, backoff exponencial con jitter, colas conscientes de la tasa y fetchings con paginación consciente.

Por qué importan los límites de tasa

Los límites de tasa protegen la infraestructura compartida de Polymarket e impiden que clientes ruidosos degraden la experiencia para otros. Para desarrolladores que construyen bots de arbitraje o sistemas de analítica, alcanzar un límite provoca el rechazo inmediato de solicitudes y puede romper flujos sensibles al tiempo. Planear los patrones de solicitud desde el principio reduce sorpresas y hace los sistemas más robustos.

Límites de tasa y endpoints documentados de Polymarket

Gamma (metadatos primarios de mercado)

• Base URL: https://gamma-api.polymarket.com
• Límites notables:
  • /markets: máximo 300 solicitudes por 10 segundos. Usa el parámetro limit (máx 1000) y la paginación basada en cursor vía after_cursor. La API rechaza offset con HTTP 422.
  • Límite combinado /markets + /events para listados: 900 solicitudes por 10 segundos.
  • Superficie global de la API Gamma: 4000 solicitudes por 10 segundos.

Notas prácticas:

• Siempre prefiere el after_cursor que devuelve la llamada anterior; no intentes emular keyset con offset.
• Ajusta limit para reducir viajes de ida y vuelta. Si necesitas listados completos de mercados, limit=1000 reduce las llamadas.

Data (posiciones, trades, holders)

• Base URL: https://data-api.polymarket.com
• Auth: Ninguna para lecturas públicas.
• El documento resume la superficie pero no lista números de tasa por endpoint para Data. Trata a Data como pública, pero aplica los mismos controles conservadores en el cliente que con Gamma (agrupar, cachear, backoff).

CLOB (libro de órdenes y trading)

• Base URL: https://clob.polymarket.com
• Las lecturas son públicas. El trading requiere API key + HMAC.
• La superficie de CLOB expone libro de órdenes, midpoint, historial de precios y colocación/cancelación de órdenes. La documentación no publica números explícitos de tasa por endpoint para lecturas de CLOB; trata las rutas de trading como sensibles a la tasa y usa el WebSocket de CLOB o el Market WS para datos del libro en vivo cuando sea posible.

Market WebSocket (actualizaciones de mercado en tiempo real)

• URL: wss://ws-subscriptions-clob.polymarket.com/ws/market
• No se requiere autenticación para datos de mercado.
• Feeds: libro en tiempo real, price_change, best_bid_ask (habilítalo con custom_feature_enabled: true), last_trade_price, tick_size_change.
• PING de latido cada 10 segundos. Máximo 500 instrumentos por conexión.

Detalles de Gamma /markets que debes seguir

• Paginación: solo after_cursor. La API devuelve next_cursor — pásalo sin cambios a la siguiente llamada.
• limit por defecto es 20, máx 1000. Usa limit mayor para sincronizaciones masivas.
• Parámetros de filtrado aceptan arrays para slug, id, condition_ids, clob_token_ids, question_ids, market_maker_address y otros como closed, active, archived, tag_id.
• Ordenación: order acepta listas separadas por comas de campos (p. ej. volume24hr,liquidity) y ascending es booleano con valor por defecto true.

Señales de error comunes y cómo reaccionar

• HTTP 429 (rate limited): deja de hacer polling inmediato, haz backoff y reintenta con backoff exponencial y jitter.
• HTTP 422 al usar offset: cambia a paginación con after_cursor.
• Respuestas parciales o páginas vacías: respeta los cursores; verifica tus filtros. Si crees que has alcanzado una cuota del lado del servidor, reduce la concurrencia de solicitudes del cliente.

Patrones de diseño para evitar throttling

1. Cachea agresivamente

• Cachea listas de mercados y metadatos con TTLs cortos (30s–2m) según el uso. Los mercados y las listas de eventos raramente cambian cada segundo.
• Cachea por clave de consulta (filtros + orden). Invalidar la caché solo cuando recibas eventos de cambio (p. ej. desde WebSocket) o tras la expiración del TTL.

2. Agrupa y aumenta limit

• Para sincronizaciones completas, usa limit=1000 para reducir viajes de ida y vuelta contra /markets.
• Extrae páginas grandes en ventanas fuera de pico y usa actualizaciones incrementales desde el WebSocket.

3. Usa WebSocket para datos en tiempo real

• Para actualizaciones del libro en vivo o movimientos de precio, suscríbete al Market WS en lugar de hacer polling a Gamma o lecturas de CLOB. El WS soporta hasta 500 instrumentos por conexión; shardea clientes si necesitas >500.

4. Colas conscientes de la tasa y backoff

• Implementa un limitador cliente estilo leaky-bucket o token-bucket que coincida con los picos documentados (por ejemplo, 300/10s para /markets).
• Cuando recibas 429, aplica backoff exponencial con jitter e incrementa progresivamente la ventana de reintento.

5. Coalesce solicitudes concurrentes idénticas

• Si varias partes de tu app solicitan la misma consulta /markets simultáneamente, coalescénlas a una única solicitud en vuelo y distribuye la respuesta.

6. Sincronización basada en cursor

• Sigue siempre la paginación basada en cursor. Para sincronizaciones en vivo, solicita la primera página y luego suscríbete a deltas si están disponibles. No intentes fetches concurrentes ingenuos con cursores que puedan exceder el límite por endpoint de Gamma.

Estrategias de fetch de ejemplo

• Job de indexación masiva (no en tiempo real): obtén /markets?limit=1000 y sigue next_cursor hasta agotarlo. Duerme brevemente entre páginas y respeta el límite de 300/10s del endpoint.
• UI casi en tiempo real: obtiene el set base una vez (cache 30s), luego abre WebSocket para deltas y actualizaciones de best_bid_ask.
• Micro-cliente de watchlist: shardea watchlists entre múltiples conexiones WS si hay más de 500 instrumentos.

Guía operativa para bots y clientes de alto rendimiento

• Usa el WebSocket de CLOB o las lecturas de CLOB para datos a nivel de libro y Gamma para metadatos más lentos.
• Mantén seguras las credenciales de trading (CLOB API key + HMAC); los endpoints de trading están autenticados.
• Monitoriza tus 429 y métricas de latencia por endpoint e instrumento. Si regularmente te acercas a los topes documentados, solicita acceso o contacta por los canales oficiales de Polymarket (el Builder Program es la vía para integraciones de mayor volumen y atribución).

Cómo afecta esto a tu desarrollo y despliegue

Si construyes un bot de trading o un servicio de analítica, planifica flujos de datos en capas: una extracción inicial masiva desde Gamma con limit grande, seguida de suscripciones WebSocket para actualizaciones en vivo y un pequeño conjunto de polls periódicos a Gamma (cacheados) para metadatos no presentes en el feed WS. Implementa limitación del lado cliente, coalescencia y paginación consciente de cursores para evitar alcanzar el tope documentado de 300 req / 10 s en /markets y los topes combinados y globales de Gamma.

Resumen de cierre

Los límites de tasa de las API de Polymarket son explícitos para las superficies de listado de Gamma y el Market WS ofrece una alternativa escalable para feeds en vivo. Diseña en torno a la paginación basada en cursor (after_cursor), usa limit estratégicamente y prefiere WebSockets para datos de alta frecuencia. Seguir estos patrones reducirá el throttling y hará tus integraciones más fiables.

Frequently asked questions

What is the /markets rate limit on Gamma?

El endpoint /markets de Gamma está limitado a 300 solicitudes por 10 segundos. Usa limit (máx 1000) y paginación basada en cursor vía after_cursor. No uses offset: la API lo rechaza con HTTP 422.

Are there combined limits for Gamma endpoints?

Sí. Las llamadas de listado a /markets y /events comparten un tope combinado de 900 solicitudes por 10 segundos. Además, la superficie global de la API Gamma está limitada a 4000 solicitudes por 10 segundos.

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

Prefiere el Market WebSocket (wss://ws-subscriptions-clob.polymarket.com/ws/market) para actualizaciones en vivo del libro y de precios: es más eficiente y evita el polling repetido. Usa Gamma para metadatos que cambian más lentamente y para sincronizaciones iniciales masivas.

What should my client do on HTTP 429 responses?

Trata el 429 como una señal para detener el polling agresivo. Implementa backoff exponencial con jitter, reduce la concurrencia y coalesce solicitudes idénticas. Registra los 429 para ajustar dinámicamente tu limitador de tasa.

Does the CLOB API require authentication?

Las lecturas de CLOB son públicas. Las operaciones de trading en CLOB requieren API key más autenticación HMAC. Respeta los límites de trading y prefiere los feeds WS para actualizaciones del libro.