La API de Polymarket en palabras llanas

Polymarket tiene tres APIs HTTP públicas. Gamma, en gamma-api.polymarket.com, lista eventos y mercados. CLOB, en clob.polymarket.com, sirve libros de órdenes, precios e histórico de precios. Data, en data-api.polymarket.com, sirve operaciones y posiciones. Todos los endpoints de lectura de las tres funcionan sin autenticación. Solo operar necesita credenciales y una wallet con fondos.

¿Qué API de Polymarket necesito?

Elige según la pregunta que estés haciendo. Si la pregunta es "qué mercados existen y de qué van", eso es Gamma. Si es "cuánto cuesta este resultado ahora mismo, y cuánto costaba la semana pasada", eso es CLOB. Si es "quién operó qué", eso es Data. Casi todo el trabajo de solo lectura usa Gamma para descubrir y CLOB para una llamada de precio por token.

La tabla siguiente sale de la referencia agent-skills de Polymarket y de la página oficial de límites, ambas comprobadas el 4 de septiembre de 2026.

API	URL base	Autenticación para leer	Rutas principales	Límite de lectura
Gamma	https://gamma-api.polymarket.com	No	/events, /markets, /tags, /sports, /public-search	4.000 peticiones por 10 s en general, 500 en /events, 300 en /markets
CLOB	https://clob.polymarket.com	No	/book, /price, /midpoint, /spreads, /prices-history	9.000 peticiones por 10 s en general, 1.500 en /book, /price y /midpoint
Data	https://data-api.polymarket.com	No	/trades, /positions, /closed-positions	1.000 peticiones por 10 s en general, 200 en /trades, 150 en /positions

Fuentes: agent-skills de Polymarket, market-data.md y límites de peticiones de Polymarket, consultados los dos el 4 de septiembre de 2026.

¿Cómo se leen mercados sin autenticación?

Manda un GET normal a Gamma. Sin clave, sin cabecera, sin cuenta. GET https://gamma-api.polymarket.com/events?active=true&closed=false&limit=100 devuelve los eventos abiertos. GET https://gamma-api.polymarket.com/events?slug=which-party-will-win-the-house-in-2026 devuelve un evento por su slug, la misma cadena que aparece en la URL de Polymarket. Los mercados funcionan igual en /markets?slug=....

Tres parámetros hacen casi todo el trabajo. limit acepta de 1 a 500 y vale 20 por defecto. offset pagina los resultados. order ordena por volume_24hr, volume, liquidity, start_date, end_date, competitive o closed_time, y ascending invierte la dirección. Para navegar por una categoría, llama primero a GET /tags y luego filtra con tag_id.

Un evento es un contenedor. Un mercado es una pregunta de sí o no dentro de él. "¿Qué partido ganará la Cámara en 2026?" es un evento; "¿Controlará el Partido Demócrata la Cámara tras las midterms de 2026?" es un mercado dentro de él. El código que trata a los dos como si fueran lo mismo se rompe con el primer evento de varios resultados que se encuentra.

¿Qué significan los precios?

Un precio de Polymarket es un número entre 0 y 1 que se lee directamente como una probabilidad. Un mercado a 0,895 es la multitud diciendo 89,5%. Gamma devuelve outcomePrices como un array alineado con outcomes, más lastTradePrice, bestBid y bestAsk en cada mercado.

Esta es una respuesta real, del evento de Gamma which-party-will-win-the-house-in-2026, consultada el 4 de septiembre de 2026:

{
  "question": "Will the Democratic Party control the House after the 2026 Midterm elections?",
  "outcomes": ["Yes", "No"],
  "outcomePrices": ["0.895", "0.105"],
  "lastTradePrice": 0.9,
  "bestBid": 0.89,
  "bestAsk": 0.9,
  "volume": 5723307.96
}

Para cualquier cosa sensible al tiempo, ve a CLOB en lugar de Gamma. GET /price?token_id=TOKEN_ID&side=BUY devuelve la mejor oferta de venta, GET /midpoint?token_id=TOKEN_ID devuelve el punto medio entre la mejor compra y la mejor venta, y GET /book?token_id=TOKEN_ID devuelve el libro completo. Existen versiones por lotes como peticiones POST en /prices, /midpoints, /spreads y /books, que aceptan hasta 500 tokens por llamada.

El identificador que importa aquí es el tokenID, el token ERC1155 del resultado. Cada mercado tiene un token por resultado. El conditionID identifica el mercado en la cadena, y questionID es el hash de los datos auxiliares de UMA que deciden el resultado. Una marca neg_risk señala los mercados que pertenecen a un grupo de varios resultados mutuamente excluyentes.

¿Cómo se obtienen precios históricos?

Usa el endpoint de histórico de CLOB, /prices-history, indexado por id de token. Acepta un intervalo (1h, 6h, 1d, 1w, 1m, max) o un rango absoluto con marcas de tiempo de inicio y fin, y devuelve entradas con la forma {t: marca de tiempo, p: precio}. Su límite de lectura es de 1.000 peticiones por 10 segundos, lo bastante generoso como para que rellenar unos cientos de mercados sea cuestión de minutos y no de días.

Dos notas prácticas. El histórico de precios es por token y no por mercado, así que un mercado de sí o no necesita dos llamadas si quieres las dos patas, y la segunda es casi exactamente uno menos la primera. Y la serie es un precio muestreado, no una cinta de operaciones. Si necesitas las ejecuciones reales, eso está en la API Data en /trades.

¿Cómo funciona la resolución?

Un mercado de Polymarket paga según el resultado que decide el oráculo optimista de UMA, no según lo que elija el personal de Polymarket. El questionID de cada mercado es el hash de los datos auxiliares que lee el oráculo, y por eso importa tantísimo el texto exacto de resolución. Dos mercados con títulos casi idénticos pueden resolverse de forma distinta porque su reglamento escrito difiere en una fecha o en una fuente.

Para un bot, la consecuencia práctica es simple. Lee la descripción del mercado, no el título. Un mercado cuyo título dice "La Fed baja tipos en octubre" puede resolverse por un comunicado concreto del FOMC publicado en una fecha concreta, y un titular que parece una bajada puede no serlo según ese reglamento.

¿Cuáles son los límites de peticiones?

Polymarket publica límites por endpoint y los aplica ralentizando. Las peticiones que pasan de la línea se retrasan y se encolan en vez de rechazarse al momento, lo que significa que un bucle mal escrito degenera en lentitud en lugar de en un 429 limpio. A 4 de septiembre de 2026 los límites publicados incluyen un techo general de 15.000 peticiones por 10 segundos, 4.000 por 10 segundos en Gamma, 9.000 por 10 segundos en CLOB y 1.000 por 10 segundos en la API Data (límites de peticiones de Polymarket).

Los endpoints de negociación tienen un límite de pico y otro sostenido. POST /order figura con 5.000 peticiones por 10 segundos de pico y 120.000 por 10 minutos de forma sostenida. Una integración de solo lectura no se acercará nunca a ninguno de estos números.

¿Qué biblioteca cliente conviene usar?

Usa los SDK unificados. A 4 de septiembre de 2026, los repositorios py-clob-client y clob-client están archivados en GitHub, ambos con su último push el 25 de mayo de 2026, y el README de Python indica que el cliente ya no funciona y que no debe usarse ni para integraciones nuevas ni existentes (Polymarket/py-clob-client). Los sustitutos son py-sdk, que se instala con pip install polymarket-client, y ts-sdk (Polymarket/py-sdk).

Si solo necesitas leer, no necesitas ninguna biblioteca. Tres peticiones GET con requests o fetch cubren descubrimiento, precio e histórico. Una dependencia que no añades es una dependencia que no te pueden archivar por debajo.

Un ejemplo de solo lectura en Python

import requests

GAMMA = "https://gamma-api.polymarket.com"
CLOB = "https://clob.polymarket.com"

# 1. Veinte eventos abiertos, primero los de más movimiento.
events = requests.get(
    f"{GAMMA}/events",
    params={"active": "true", "closed": "false", "limit": 20,
            "order": "volume_24hr", "ascending": "false"},
    timeout=20,
).json()

for event in events:
    print(event["title"])
    for market in event.get("markets", []):
        # outcomePrices y clobTokenIds llegan como cadenas con JSON dentro.
        prices = market.get("outcomePrices")
        print("   ", market["question"], prices)

# 2. Punto medio en vivo para un token de resultado.
token_id = "REPLACE_WITH_A_CLOB_TOKEN_ID"
mid = requests.get(f"{CLOB}/midpoint", params={"token_id": token_id}, timeout=20).json()
print("midpoint:", mid)

La salida esperada es una línea por evento, luego una línea sangrada por mercado con sus precios de resultado como cadenas, y después un único diccionario del tipo {'mid': '0.895'}. Fíjate en la codificación como cadena: Gamma devuelve outcomePrices y clobTokenIds como cadenas con JSON dentro del JSON, así que necesitan un segundo parseo antes de usarse.

Fallos que conviene manejar antes de programar esto en un cron: un evento con cero mercados, un mercado cuyo outcomePrices no está porque no ha habido operaciones, un slug que ya no existe después de que Polymarket renombre un evento, y la limitación de peticiones, que aparece como respuesta lenta y no como error.

Dónde se rompe esto

Los bloqueos por país son el primer muro. Polymarket está bloqueado en Italia desde el 27 de julio de 2026 por orden de la Agenzia delle Dogane e dei Monopoli, aplicado por los proveedores de internet a nivel de DNS (Key4biz, 28 de julio de 2026). Ese bloqueo resuelve también los nombres de host de la API hacia la página de aviso de la agencia, así que una petición a gamma-api.polymarket.com desde una conexión italiana falla con un error de certificado en vez de devolver datos.

En España pasa algo equivalente y es anterior. El 26 de mayo de 2026 la Dirección General de Ordenación del Juego abrió expediente sancionador a Polymarket y Kalshi por operar sin licencia y ordenó el bloqueo cautelar de sus webs mientras se resuelve el expediente. Brasil bloqueó plataformas de mercados de predicción en mayo de 2026 con otra base legal. Si tu bot corre en un servidor de un país bloqueado, el problema no es la API, es la red: alójalo fuera o cambia de fuente de datos.

El segundo muro es que leer precios no es lo mismo que tener un historial. La API de Polymarket te dice qué piensa el mercado. No te dice qué pensabas tú, cuándo lo pensaste, ni si acertaste. Esa es otra capa, y es la que convierte una tubería de datos en un historial.

Eso es lo que hace la API de insiderz. Lista los mismos eventos, acepta una call bloqueada con la hora y el precio de mercado de ese instante, y puntúa la call contra el mercado cuando el evento se resuelve. No se mueve dinero. Los bots usan los mismos endpoints, las mismas reglas y la misma clasificación que las personas. Si estás construyendo el lado de pronosticar y no el de operar, lee después cómo construir un bot de predicción, o ve directo a la versión en 100 líneas de Python.