API de Polymarket: consultar eventos públicos

Descubrir eventos públicos no requiere clave de trading

Los endpoints públicos de descubrimiento de Polymarket son de solo lectura y no piden autenticación. Puedes pedir eventos con active=true y closed=false desde la ruta events/keyset, controlando el tamaño de la página con limit y avanzando con after_cursor. Un evento es la entidad de nivel superior que agrupa uno o varios mercados, y mercado es la unidad que tiene pregunta, resultados y precios. Enviar órdenes es un flujo autenticado distinto que aquí no se toca: lo que devuelve este endpoint es una observación puntual de metadatos, no un permiso para operar ni una señal de compra.

Como es solo lectura, no hay SDK que instalar ni secreto que guardar: basta la biblioteca estándar de Python y una cabecera User-Agent que identifique tu script. Cuando pases de listar títulos a comparar mercados, el dato que importa vive en la ruta de detalles. Si esta es tu primera vez con el tema, conviene partir de una vista general de los mercados de Polymarket; si lo que quieres es automatizar decisiones, mira primero los bots de trading.

Un ejemplo ejecutado con la biblioteca estándar

El ejemplo de código se ejecutó el 2026-10-10. Capturó 2 registros de metadatos de eventos públicos, sin órdenes ni cuenta, y anotó la hora de observación en UTC. Es una instantánea de solo lectura, no un estudio empírico ni una prueba de rendimiento. La respuesta devolvió 2 eventos y dejó next_cursor con valor, lo que indica que existían más páginas por recorrer.

ID de evento, ID de mercado y el cursor de paginación

En la respuesta, cada elemento de events trae su propio id junto a slug y title. Ese id de evento no es el id de mercado, ni el condition ID, ni el token ID de un resultado. Para ver question, outcomes, outcomePrices, clobTokenIds, activity, closure, aceptación de órdenes, liquidez y volumen tienes que consultar la ruta de detalles de mercado. Algunos de esos campos llegan como arrays serializados y hay que parsearlos. Volumen y liquidez no son lo mismo, y un valor ausente o viejo no significa cero: si vas a comparar, conserva la fecha en que observaste el precio.

La paginación se controla con next_cursor. Si viene con valor, pasas ese mismo cursor como after_cursor en la siguiente solicitud y repites hasta que el cursor se agote. En el ejemplo, has_next_page era true: con solo 2 eventos ya sabías que faltaba recorrer el resto. Si ignoras el cursor, tu lista queda truncada sin ningún aviso.

Antes de usar un evento: closed y aceptación de órdenes

Pedir active=true y closed=false filtra a nivel de evento, pero un mismo evento puede contener mercados en estados distintos. Los campos closure y aceptación de órdenes de los detalles te dicen si un mercado concreto admite órdenes en ese momento. Un evento activo no implica que todos sus mercados estén operables, y el endpoint de descubrimiento no te da profundidad ni volumen por sí solo. Si tu script va a filtrar oportunidades, la decisión debería depender de los detalles del mercado y de su fecha de observación, no de la lista de eventos.

Cuando la duda es si hay contrapartida suficiente, la liquidez en Polymarket se mide en los detalles del mercado y cambia con el tiempo; aquí basta recordar que el listado público devuelve metadatos, no un libro de órdenes completo.

El código, y qué mirar en su salida

El código de abajo no instala nada y no usa secretos. Arma la URL con los 3 parámetros, envía la petición con un tiempo de espera de 20 segundos, registra observed_at en UTC y resume solo id, slug y title de cada evento, más una bandera has_next_page calculada a partir de next_cursor. Copiarlo tal cual te da un punto de partida verificable.

import json
from datetime import datetime, timezone
from urllib.request import Request, urlopen

url = "https://gamma-api.polymarket.com/events/keyset?active=true&closed=false&limit=2"
request = Request(url, headers={"User-Agent": "PolyZenoResearch/1.0"})
with urlopen(request, timeout=20) as response:
    data = json.load(response)
print(json.dumps({
    "observed_at": datetime.now(timezone.utc).isoformat(),
    "events": [{"id": e["id"], "slug": e["slug"], "title": e["title"]}
               for e in data["events"]],
    "has_next_page": bool(data.get("next_cursor"))
}, ensure_ascii=False, indent=2))

La salida observada el 2026-10-10

Con limit=2, la ejecución observada devolvió 2 eventos públicos: el id 16183, slug kraken-ipo-in-2025, y el id 16263, slug macron-out-in-2025. No son recomendaciones ni mercados vigentes hoy: son los registros que aparecieron en esa instantánea concreta, y el listado puede cambiar entre ejecuciones. has_next_page quedó en true, así que para una lista completa habría que seguir el cursor. Esta captura no verifica precios, no mide liquidez y no envía ninguna orden.

Limitaciones: qué no cubre esta guía

El alcance es descubrimiento de solo lectura. No se cubre la API autenticada de trading, ni la firma de órdenes, ni la gestión de claves, ni el control de errores de un sistema real. La muestra es de 2 eventos en una sola observación, así que no sirve para estimar cobertura, latencia ni calidad de datos. Las respuestas pueden cambiar y un evento que hoy está activo puede cerrar o dejar de aceptar órdenes mañana. El error típico aquí es construir un filtro sobre una lista truncada o sobre campos viejos: si no recorres el cursor y no relees los detalles con su fecha, decidirás con información incompleta.

Qué endpoint usar según lo que necesites

Esta tabla resume la elección entre las 2 rutas tratadas, sin ordenar ninguna como mejor en abstracto.

La regla práctica: si solo vas a mostrar una lista de eventos activos, quédate en events/keyset y recorre el cursor. Si vas a decidir sobre un mercado concreto, salta a los detalles y comprueba cierre, aceptación de órdenes, precios y liquidez con su fecha. Y si el siguiente paso es enviar órdenes, eso ya es otro flujo autenticado que este ejemplo no demuestra.