La API de Polymarket, mapeada: Gamma vs CLOB vs Data API
Quien empieza pierde un día con el mismo problema: Polymarket no tiene una API, tiene cuatro, y el endpoint que buscas rara vez está en la que probaste primero. Este es el mapa completo.
Lo primero que hay que entender sobre la API de Polymarket es que no existe como tal. Hay cuatro APIs REST y cuatro streams WebSocket, cada una al servicio de una parte distinta de la integración, cada una en su propio hostname, con sus propios límites de tasa y sus propios requisitos de autenticación.
Casi todas las preguntas del tipo “la API de Polymarket no tiene X” acaban siendo “X está en otro host”. Aquí tienes toda la superficie en un solo lugar.
Las cuatro APIs REST
| API | URL base | Para qué sirve | Autenticación |
|---|---|---|---|
| Gamma | gamma-api.polymarket.com | Descubrir eventos y mercados; metadatos | Ninguna |
| CLOB | clob.polymarket.com | Precios, libros de órdenes, colocar y gestionar órdenes | Ninguna para leer, L1/L2 para operar |
| Data | data-api.polymarket.com | Posiciones, actividad, participación en mercados | Ninguna |
| Relayer | relayer-v2.polymarket.com | Enviar transacciones de wallet sin tener POL para el gas | Firmada |
La regla de enrutamiento de 30 segundos
¿Qué mercados existen? → Gamma. ¿Cuál es el precio? / quiero operar → CLOB. ¿Qué tiene esta wallet? → Data API. Necesito mover fondos sin gas → Relayer. Si estás buscando un endpoint de eventos en el CLOB, o un libro de órdenes en Gamma, ahí está el error.
API Gamma: descubrimiento y metadatos
Gamma es por donde se empieza. Responde a qué existe: eventos, los mercados que contienen, etiquetas, búsqueda y los metadatos que necesitas para trabajar con todo lo demás; sobre todo, los IDs de token que exige cada endpoint del CLOB.
/events: lista eventos, con paginación por keyset disponible/markets: lista mercados; tambiénby id,by slug,by token/public-search: búsqueda en eventos y mercados/tags,/comments: taxonomía y discusión- Interés abierto, volumen en vivo, principales tenedores
/markets tiene el límite más estricto de la plataforma
300 req / 10s, 13× más estricto que el límite general de Gamma, de 4,000 req / 10s. Si paginas la lista completa de mercados en un bucle, esto es lo primero que se rompe. Guarda en caché los metadatos de los mercados; apenas cambian durante la vida de un mercado. Todas las cifras en la referencia de límites de tasa.
API CLOB: precios, libros y órdenes
El libro de órdenes en sí, y el único lugar donde puedes operar. La lectura es pública; para operar hacen falta credenciales.
| Grupo | Endpoints | Autenticación |
|---|---|---|
| Libro de órdenes | /book, /books, /midpoint, /midpoints, /spread, /spreads | Pública |
| Precios | /price, /prices, /prices-history, precio de la última operación, /tick-size, tasa de comisión | Pública |
| Órdenes | POST /order, POST /orders, DELETE /order, /orders, /cancel-all, /cancel-market-orders | L2 + firma de la wallet |
| Registro | /trades, /data/orders, /data/trades, /notifications | L2 |
| Autenticación | /auth/api-key, /auth/api-keys, /auth/derive-api-key | L1 |
| Cuenta | balance allowance (consultar / actualizar) | L2 |
Singular frente a plural es una distinción real
Casi todos los endpoints de datos de mercado del CLOB tienen un gemelo por lotes: /book y /books, /price y /prices. Los singulares tienen 1,500 req / 10s y los plurales 500 req / 10s, pero una llamada plural cubre muchos tokens, así que agrupar te da muchos más datos por unidad de presupuesto de límite de tasa. Prefiere /books a un bucle de /book prácticamente siempre.
Data API: posiciones y actividad
Preguntas del tipo cartera: /positions, /closed-positions, /trades, más la API de PNL del usuario. Ten en cuenta que es la más estricta de las tres APIs principales: un límite general de 1,000 req / 10s, con /positions y /closed-positions en solo 150 req / 10s cada uno. Está pensada para paneles, no para bucles de polling.
Los cuatro streams WebSocket
Si estás haciendo polling de /book con un temporizador, para: para eso están los streams. El polling es la forma más común de quemar presupuesto de límite de tasa sin ningún beneficio.
| Stream | URL | Transmite |
|---|---|---|
| CLOB Market | wss://ws-subscriptions-clob.polymarket.com/ws/market | Actualizaciones públicas del libro de órdenes, de precios y del ciclo de vida de los mercados |
| CLOB User | wss://ws-subscriptions-clob.polymarket.com/ws/user | Actualizaciones autenticadas de órdenes y operaciones de tu cuenta |
| RTDS | wss://ws-live-data.polymarket.com | Precios de referencia públicos, comentarios, actividad de operaciones |
| Sports | wss://sports-api.polymarket.com/ws | Estado de los partidos en vivo y marcadores |
El canal User es el que la gente pasa por alto. Si tu bot hace polling de /data/orders para saber si su orden se ejecutó, estás pagando presupuesto de límite de tasa por información que el canal User te habría enviado en el momento en que ocurrió, y con menos latencia.
Autenticación: L1 y L2
Los datos de mercado públicos no necesitan ninguna credencial: puedes llamar a Gamma, a los endpoints de lectura del CLOB y a la Data API con un simple curl. Para operar hacen falta dos capas, y entender cuál es cuál resuelve la mayoría de los errores de autenticación.
| Capa | Cómo funciona | Propósito |
|---|---|---|
| L1 | La wallet firma un mensaje EIP-712 | Demostrar el control de la wallet; crear o derivar credenciales de API |
| L2 | Solicitudes firmadas con credenciales de API usando HMAC-SHA256 | Autenticar las solicitudes privadas al CLOB |
La colocación de órdenes usa ambas: L2 autentica la solicitud y una firma de la wallet autoriza la orden. Los datos tipados de L1 son un payload ClobAuth en chainId: 137 (Polygon), con la dirección de tu firmante, una marca de tiempo Unix en segundos, un nonce (usa 0 salvo que gestiones varios conjuntos de credenciales) y el string de mensaje fijo.
Obtener una clave de API
- Firma el payload EIP-712
ClobAuthcon tu clave privada de Polygon. - Llama a
POST /auth/api-keycon las cabeceras L1 para crear credenciales. Recibes una key, un secret y una passphrase: las tres son necesarias para L2. - En ejecuciones posteriores, llama a
GET /auth/derive-api-keypara recuperar las credenciales existentes en lugar de crear otras nuevas.
Los dos fallos de autenticación que explican la mayoría de las consultas de soporte
Credenciales incompletas: L2 necesita la key, el secret y la passphrase; con dos de las tres se produce una solicitud bien formada con una firma que no se puede verificar. Desfase del reloj: la firma incluye una marca de tiempo, así que un contenedor cuyo reloj va unos segundos desfasado produce firmas que el servidor rechaza como no válidas. Ambos aparecen como Unauthorized/Invalid api key, por eso ese mensaje se busca tanto. Consulta la referencia de errores.
SDK
Polymarket mantiene SDK unificados para TypeScript y Python que encapsulan todo lo anterior con una interfaz tipada y se encargan de la paginación, las formas de error y la configuración de la wallet. Si empiezas de cero en cualquiera de los dos lenguajes, úsalos: implementar a mano la firma EIP-712 y la firma HMAC de solicitudes es una forma muy propensa a errores de pasar un fin de semana.
Ve directamente a REST cuando tu runtime no tenga SDK, cuando necesites control exacto sobre la firma, las cabeceras, los reintentos o el transporte, o cuando necesites un endpoint que el SDK aún no expone. Ten en cuenta que estos son los SDK unificados: si usas un cliente antiguo, hay una ruta de migración documentada, y los clientes antiguos son el origen de muchos bugs de credenciales obsoletas.
¿Cuánto cuesta la API de Polymarket?
Nada. No hay plan de pago, ni página de precios de la API, ni suscripción: las APIs de Polymarket son de uso gratuito, y el acceso se regula con límites de tasa, no con facturación. Los datos de mercado públicos ni siquiera requieren una clave.
Lo único que escala con el dinero son los límites de trading por firmante, escalonados según el volumen de 30 días de tu wallet maker, desde Standard con 40 tokens de órdenes/s hasta Elite con 600; pero eso es una asignación de rendimiento, no una comisión.
Lo único que ninguna de estas APIs te dará
Una vez mapeada toda la superficie, lo útil es saber lo que no está en ella: la profundidad histórica del libro de órdenes.
Todos los endpoints de arriba sirven el estado actual. /book devuelve el libro ahora. /prices-history te da precios pero no profundidad, así que no puede decirte cuál habría sido tu ejecución. Y cuando un mercado se resuelve, /book devuelve 404. Lo que sobrevive es una serie de precios escasa, de aproximadamente un punto por minuto, que puedes obtener con un inicio y un fin explícitos. Ningún plan ni nivel de límite de tasa cambia esto.
| Pregunta | ¿Se puede responder con la API de Polymarket? |
|---|---|
| ¿Cómo está el libro ahora mismo? | Sí: /book |
| ¿Cuál era el precio ayer? | Sí, aproximadamente un punto por minuto, con /prices-history y un inicio y un fin |
| ¿Cuál era la profundidad ayer a las 14:03:17? | No |
| ¿A qué precio se habría ejecutado mi orden de 500 acciones? | No |
| Muéstrame un mercado que se resolvió la semana pasada | Su registro y su resultado, sí (closed=true). Su libro, no. |
Ese hueco es la razón por la que hacer backtesting de una estrategia de Polymarket requiere una fuente de datos aparte que haya grabado el libro mientras los mercados estaban activos. PolyTest hace exactamente eso para los mercados cripto Up/Down: 240M+ snapshots puntuales con 8 niveles de profundidad por lado, marcas de tiempo por debajo del segundo y mercados resueltos conservados en lugar de descartados. Una cabecera, JSON limpio y una prueba gratuita de 3 días:
curl -H "X-API-Key: $POLYTEST_KEY" \
"https://api.polytest.io/api/v1/markets?coin=btc&market_type=5m&limit=20"Referencia completa de endpoints en la documentación de PolyTest, o empieza una prueba gratuita.
Preguntas frecuentes
- ¿Cuáles son los endpoints de la API de Polymarket?
- Polymarket tiene cuatro APIs REST: Gamma (gamma-api.polymarket.com) para eventos, mercados y metadatos; CLOB (clob.polymarket.com) para precios, libros de órdenes y trading; Data API (data-api.polymarket.com) para posiciones y actividad; y Relayer (relayer-v2.polymarket.com) para transacciones sin gas. También hay cuatro streams WebSocket que cubren el canal público de mercado, el canal autenticado de usuario, los datos en tiempo real y los deportes.
- ¿La API de Polymarket es gratuita?
- Sí. No hay plan de pago, suscripción ni página de precios de la API: el acceso se regula con límites de tasa, no con facturación, y los datos de mercado públicos no requieren ninguna clave de API. Lo único que escala es el nivel de rendimiento de trading por firmante, que se basa en el volumen de trading de 30 días de tu wallet, no en un pago.
- ¿Cómo obtengo una clave de API de Polymarket?
- Firma el payload de datos tipados EIP-712 ClobAuth con tu clave privada de Polygon y luego llama a POST /auth/api-key con las cabeceras L1 para crear credenciales. Recibes una key, un secret y una passphrase: las tres son necesarias para firmar las solicitudes L2. En ejecuciones posteriores usa GET /auth/derive-api-key para recuperar las credenciales existentes en lugar de crear otras nuevas. Los datos de mercado públicos no necesitan clave.
- ¿Cuál es la diferencia entre la API Gamma y la API CLOB?
- Gamma sirve para descubrir: qué eventos y mercados existen, sus metadatos y los IDs de token que necesitan otros endpoints. CLOB sirve para el libro de órdenes: precios actuales, profundidad del libro y colocar o cancelar órdenes. Si necesitas encontrar un mercado, usa Gamma; si necesitas ponerle precio u operar en él, usa CLOB.
- ¿Polymarket tiene un SDK de Python?
- Sí. Polymarket mantiene SDK unificados para TypeScript y Python que cubren las cuatro APIs REST con una interfaz tipada y se encargan de la paginación, las formas de error y la configuración de la wallet. Hay una ruta de migración documentada desde los clientes antiguos. Ir directamente a REST tiene sentido cuando tu runtime no está soportado, necesitas control exacto sobre la firma y los reintentos o necesitas un endpoint que el SDK aún no expone.
- ¿Puedo obtener la profundidad histórica del libro de órdenes desde la API de Polymarket?
- No. Todos los endpoints de Polymarket sirven el estado actual. El endpoint /prices-history devuelve una serie de precios de aproximadamente un punto por minuto sin la profundidad que hay detrás, así que no puede decirte a qué precio se habría ejecutado un tamaño de orden dado, y el libro de órdenes de un mercado resuelto devuelve 404. El backtesting requiere snapshots puntuales grabados mientras los mercados estaban activos, como el archivo de 240M+ snapshots de mercados cripto Up/Down de PolyTest.
Obtén los datos históricos que Polymarket no guarda
PolyTest registra los mercados cripto Up/Down de Polymarket mientras están activos: 240M+ snapshots con 8 niveles de profundidad del libro de órdenes, marcas de tiempo por debajo del segundo y mercados resueltos conservados. Empieza con una prueba gratuita de 3 días.
Sigue leyendo
El SDK de Python de Polymarket en 2026 (y cómo dejar py-clob-client)
Si tu código todavía importa ClobClient desde py_clob_client, está construido sobre un paquete sustituido, igual que la mayor parte del código de Polymarket que te escribirá un asistente de IA. Este es el SDK actual y cómo pasarte a él.
WebSockets de Polymarket: datos en tiempo real que no se caen
Hacer polling del libro de órdenes es la forma más común de quemar presupuesto de límite de tasa sin ningún beneficio. Aquí están los cuatro streams, las opciones de suscripción que nadie documenta y el modo de fallo en el que tu bot recibe silencio y lo interpreta como calma.
Límites de tasa de la API de Polymarket: la referencia completa
Polymarket publica sus límites de tasa en varias páginas, en dos sistemas completamente distintos y con una ventana de 10 segundos que casi nadie espera. Aquí lo tienes todo en un conjunto de tablas, más lo que pasa realmente cuando superas un límite.