MercadoDice

API de Polymarket: guía para leer mercados y precios sin clave

La Gamma API de Polymarket es pública y no pide clave. Endpoints, parámetros, cómo leer outcomePrices y el histórico de precios, con curl y JavaScript.

Por Matías MardonesActualizado el 25 de octubre de 20266 min de lectura

La respuesta corta

La API de Polymarket para leer datos es pública: la Gamma API (https://gamma-api.polymarket.com) no pide clave ni registro. Con ella puedes listar eventos y mercados, ordenarlos por volumen y leer sus precios. El histórico de precios sale de otra API, la CLOB API (https://clob.polymarket.com). Operar por API es otra historia: exige firma con la wallet y claves propias. La referencia completa está en docs.polymarket.com.

Qué APIs tiene Polymarket

API URL base Para qué la usas ¿Pide clave?
Gamma https://gamma-api.polymarket.com Eventos, mercados, búsqueda, etiquetas No
CLOB https://clob.polymarket.com Histórico de precios; órdenes y operaciones Para leer el histórico, no. Para operar, sí

Si todavía no tienes claro qué es un evento, un mercado o un contrato, lee primero qué es Polymarket.

Endpoints de la Gamma API

Endpoint Qué devuelve
GET /events Lista de eventos
GET /events/{id} Un evento concreto
GET /markets Lista de mercados
GET /markets/{id} Un mercado concreto
GET /public-search Búsqueda por texto
GET /tags Etiquetas o categorías
GET /series Series de eventos recurrentes
GET /sports Deportes
GET /teams Equipos

Parámetros habituales

Parámetro Uso
active true para mercados activos
closed false para excluir los ya cerrados
archived Incluir o excluir archivados
order Campo para ordenar, por ejemplo volume24hr
ascending false para ordenar de mayor a menor
limit Cuántos resultados por página
offset Desde qué resultado empezar (paginación)

Cómo listar eventos por volumen

Con curl, los diez eventos activos con más volumen en las últimas 24 horas:

curl "https://gamma-api.polymarket.com/events?active=true&closed=false&order=volume24hr&ascending=false&limit=10"

Antes de construir nada sobre un campo, imprime una respuesta completa y comprueba qué trae.

API de Polymarket con Python

Con la librería requests (pip install requests), este ejemplo mínimo pide los cinco mercados activos con más volumen del día y muestra la probabilidad de cada resultado:

import json
import requests

BASE = "https://gamma-api.polymarket.com"
params = {"active": "true", "closed": "false",
          "order": "volume24hr", "ascending": "false", "limit": 5}

r = requests.get(f"{BASE}/markets", params=params, timeout=10)
r.raise_for_status()

for m in r.json():
    outcomes = json.loads(m["outcomes"])
    prices = [float(p) for p in json.loads(m["outcomePrices"])]
    print(m["question"])
    for o, p in zip(outcomes, prices):
        print(f"  {o}: {p * 100:.1f} %")

json.loads hace falta por lo que se explica en la sección siguiente: esos campos llegan como texto.

Cómo leer outcomes, outcomePrices y clobTokenIds

Cada mercado de la Gamma API trae, entre otros, estos campos:

Campo Qué contiene
outcomes Los resultados posibles, por ejemplo “Yes” y “No”
outcomePrices El precio de cada resultado, entre 0 y 1
clobTokenIds Los identificadores de token que usa la CLOB API
volumeNum Volumen del mercado como número
oneDayPriceChange Cambio de precio en el último día
groupItemTitle Nombre corto del mercado dentro de su evento
image Imagen del mercado

El detalle que confunde a casi todos: outcomes y outcomePrices llegan como arrays en JSON guardados como texto. Es decir, recibes la cadena "[\"Yes\", \"No\"]", no un array. Hay que parsearla:

const parse = (v) => (typeof v === 'string' ? JSON.parse(v) : v);

const res = await fetch(
  'https://gamma-api.polymarket.com/markets?active=true&closed=false&order=volume24hr&ascending=false&limit=5'
);
const markets = await res.json();

for (const m of markets) {
  const outcomes = parse(m.outcomes);
  const prices = parse(m.outcomePrices).map(Number);
  const tokens = parse(m.clobTokenIds);
  outcomes.forEach((o, i) => {
    console.log(`${o}: ${(prices[i] * 100).toFixed(1)} %  token=${tokens?.[i]}`);
  });
}

El precio de un resultado es la probabilidad que le asigna el mercado: 0,62 equivale a un 62 %. Empareja cada resultado con su precio y su token por posición, y comprueba en una respuesta real que el orden coincide antes de confiar en él. La función parse sirve tanto si el campo llega como texto como si llega ya como array.

Histórico de precios con la CLOB API

El histórico se pide por token, no por mercado. Usa uno de los valores de clobTokenIds:

curl "https://clob.polymarket.com/prices-history?market=TOKEN_ID&interval=1w&fidelity=60"
  • market: el id del token.
  • interval: 1d, 1w o 1m.
  • fidelity: resolución de la serie, en minutos.

En JavaScript:

async function historico(tokenId, interval = '1w', fidelity = 60) {
  const url = new URL('https://clob.polymarket.com/prices-history');
  url.search = new URLSearchParams({ market: tokenId, interval, fidelity: String(fidelity) });
  const res = await fetch(url);
  if (!res.ok) throw new Error(`CLOB API respondió ${res.status}`);
  return res.json();
}

const data = await historico('TOKEN_ID');
console.log(JSON.stringify(data, null, 2));

Como con la Gamma API, imprime la respuesta y revisa su forma antes de graficarla.

Límites de uso (rate limits) de la API

La documentación oficial publica límites por IP en ventanas de 10 segundos (Rate Limits). Para la Gamma API, al 25 de octubre de 2026:

Endpoint Límite
General 4.000 peticiones / 10 s
/events 500 / 10 s
/markets 300 / 10 s
/public-search 350 / 10 s

Si te pasas, las peticiones se frenan (se retrasan o se ponen en cola) en lugar de rechazarse de inmediato. Las cifras cambian: revísalas en esa página.

Buenas prácticas

  • Cachea. Para casi cualquier uso de lectura basta guardar la respuesta unos minutos y servirla desde tu caché.
  • No martilles la API. Nada de bucles sin pausa ni cientos de peticiones en paralelo.
  • Pagina con limit y offset en lugar de pedir todo de una vez.
  • Maneja errores. Comprueba res.ok, reintenta con espera creciente y no rompas la página si la API tarda.
  • Muestra el contexto. Un precio en un mercado con poco volumeNum dice poco. Si publicas probabilidades, muestra también el volumen y la hora de la consulta. Los precios en vivo los puedes ver en el tablero de mercados.

Una nota sobre operar por API

La CLOB API también permite crear y cancelar órdenes, pero eso requiere firmar con tu wallet y usar claves de API. No lo detallamos aquí. Ten en cuenta dos cosas: los países en modo “solo cierre” lo están tanto en la web como en la API, y automatizar una estrategia no la vuelve rentable. Antes de pensar en un bot, lee la guía de estrategias y riesgos y la de comisiones: cada operación como taker paga según la categoría.

Preguntas frecuentes

¿Necesito una clave para usar la API de Polymarket?

Para leer eventos, mercados y precios con la Gamma API, no. Tampoco para pedir el histórico de precios a la CLOB API. Las claves solo hacen falta para operar.

¿Qué id uso para pedir el histórico de un mercado?

El id del token del resultado que te interesa, que sacas de clobTokenIds. Cada resultado tiene su propio token y su propia serie de precios.

¿Cuál es el límite de peticiones de la API de Polymarket?

Según la documentación oficial, la Gamma API admite 4.000 peticiones cada 10 segundos por IP en general, con límites menores por endpoint (300 para /markets). Al pasarte, las peticiones se frenan.

¿Puedo hacer un bot con la API de Polymarket?

Técnicamente sí, pero operar exige firma con wallet y claves, y las restricciones por país también aplican a la API. Un bot no garantiza resultados.

Sigue leyendo