El SDK de Python de Polymarket en 2026 (y cómo dejar py-clob-client)

Esto importa más que un cambio de versión normal por una razón: casi todos los ejemplos de código de Polymarket de internet son anteriores. Artículos de blog, respuestas de Stack Overflow, ejemplos de GitHub y (como se entrenaron con ese material) el código que escribe tu asistente de IA cuando le pides un bot de Polymarket. Si te has visto depurando imports que no existen, este es el motivo.

Qué cambió realmente

El enfoque anterior te daba un cliente por cada servicio de Polymarket. Importabas un cliente CLOB para el libro de órdenes, llamabas a Gamma por HTTP sin más para descubrir mercados, consultabas aparte la Data API para las posiciones y añadías un paquete de builder-signing si necesitabas transacciones del relayer. Cuatro modelos mentales, cuatro formas de error, cuatro estilos de paginación.

El SDK unificado lo reduce todo a un único cliente que cubre todas las superficies.

Instalación

pip install polymarket-client
# uv add polymarket-client
# poetry add polymarket-client

Cuatro clientes: elige con criterio

import asyncio
from polymarket import AsyncPublicClient


async def main() -> None:
    async with AsyncPublicClient() as client:
        pages = client.list_markets(closed=False)
        first = await pages.first_page()
        for market in first.items:
            print(market.slug)


asyncio.run(main())

Los datos públicos no requieren credenciales, así que construye y prueba todo lo que puedas contra AsyncPublicClient antes de introducir una clave. El descubrimiento, el parsing, la paginación, la generación de señales y el backoff se pueden ejercitar sin nada en riesgo.

Paginación

Una sola interfaz de paginador para todos los métodos de listado. Tres formas de consumirlo, según te importen o no los límites de página:

pages = client.list_markets(closed=False, page_size=10)

# 1. Page at a time — use this when you need to control pacing
#    against the tight /markets rate limit (300 req / 10s).
async for page in pages:
    for market in page.items:
        ...

# 2. Item at a time, boundaries ignored.
async for market in pages.iter_items():
    ...

# 3. Manual, resumable.
page = await pages.first_page()
if page.next_cursor:
    nxt = await pages.from_cursor(page.next_cursor).first_page()

Modelos tipados

Los métodos devuelven tipos reales en lugar de diccionarios, exportados desde el paquete de nivel superior:

from polymarket import Event, Market, OrderBook, PriceHistoryPoint

Es la mejora menos vistosa y probablemente la más valiosa. Con los clientes antiguos, un campo renombrado o ausente aparecía como un KeyError en lo más profundo del bucle de tu estrategia en tiempo de ejecución, a menudo en producción y a menudo con una posición abierta. Los modelos tipados llevan ese fallo a donde le corresponde.

Suscripciones en tiempo real

subscribe() combina varios feeds en un único stream de eventos tipados, una mejora real frente a gestionar a mano varias conexiones WebSocket.

from polymarket.streams import MarketSpec, SportsSpec

async with await client.subscribe(
    [MarketSpec(token_ids=[token_id]), SportsSpec()],
) as stream:
    async for event in stream:
        # MarketBookEvent | MarketPriceChangeEvent
        # | MarketLastTradePriceEvent | MarketTickSizeChangeEvent
        # | MarketBestBidAskEvent | NewMarketEvent
        # | MarketResolvedEvent | SportsEvent
        handle(event)

El SDK se encarga del heartbeat, el framing y las reconexiones que de otro modo implementarías tú, incluido el requisito de enviar PING cada 10 segundos en una conexión directa. Detalles en la guía de WebSocket.

Colocar una orden

market = await client.get_market(slug="<market-slug>")
token_id = market.outcomes.yes.token_id
assert token_id is not None

response = await client.place_market_order(
    token_id=token_id,
    side="BUY",
    amount="10",     # pUSD to spend, not shares to buy
)

if not response.ok:
    raise RuntimeError(response.message)

# Settlement is on-chain and asynchronous.
hashes = await client.wait_for_order_fill_settlement(response)

# Reconcile rather than assuming.
page = await client.list_positions(market=[market.condition_id]).first_page()
position = next((p for p in page.items if p.token_id == token_id), None)

Migrar desde py-clob-client

1. Haz inventario de todas las llamadas a Polymarket, incluidas las llamadas requests directas a Gamma y a la Data API. También entran en el alcance: el SDK unificado las cubre, e integrarlas es la mayor parte del beneficio.
2. Instala polymarket-client y elimina los paquetes antiguos. Mantener ambos instalados para migrar poco a poco invita a importar el símbolo client equivocado.
3. Sustituye la construcción del cliente. Un único AsyncSecureClient.create(...) reemplaza los antiguos clientes por servicio y su gestión separada de credenciales.
4. Sustituye el acceso por diccionario por acceso a atributos. market["condition_id"] pasa a ser market.condition_id. Es tedioso, y es donde el type checker empieza a amortizarse.
5. Reescribe la paginación con la interfaz del paginador en lugar de bucles manuales con offset o cursor.
6. Sustituye el código WebSocket hecho a mano por subscribe() y elimina tu lógica de heartbeat y reconexión.
7. Vuelve a ejecutar primero tus rutas de solo lectura, contra el cliente público, antes de dejar que nada coloque una orden.

Por qué tu asistente de IA se equivoca con esto

Vale la pena abordarlo directamente, porque así llega aquí mucha gente. Pide a un LLM código de Polymarket en Python y muy a menudo obtendrás imports de py_clob_client, construcción de ClobClient(...) y objetos OrderArgs. El modelo no está fallando: está reproduciendo la inmensa mayoría del código de Polymarket que ha visto, que es anterior a los SDK unificados.

• Mira primero la línea del import. from polymarket import ... es lo actual; from py_clob_client... no.
• Pega la documentación actual en el contexto. Polymarket publica Markdown legible por máquinas en docs.polymarket.com/llms.txt, y cada página tiene una variante .md. Darle al modelo lo auténtico funciona mejor que discutir con él.
• Desconfía del código seguro de sí mismo que no se ejecuta. El código generado mezcla con frecuencia APIs antiguas y nuevas en algo que nunca ha existido.

El mismo problema se aplica a los proveedores de datos. Publicamos llms.txt, llms-full.txt y una especificación OpenAPI, y permitimos los crawlers de IA, precisamente para que los asistentes puedan escribir integraciones correctas con PolyTest sin adivinar. Algunos proveedores bloquean esos crawlers, lo cual es una decisión legítima, pero significa que tu asistente improvisará su API.

Lo que el SDK sigue sin poder hacer

El SDK unificado es una interfaz mucho mejor para las APIs de Polymarket. No cambia lo que contienen esas APIs, y lo que más suelen querer quienes crean bots no está en ellas.

No hay libro de órdenes histórico. client.get_market() devolverá los metadatos de un mercado resuelto, pero su libro ya no existe: /book devuelve 404 y prices-history solo conserva aproximadamente un punto por minuto. Ningún método del SDK, plan o credencial recupera el libro.

Para hacer backtesting necesitas snapshots grabados mientras los mercados estaban activos. PolyTest los ofrece para los mercados cripto Up/Down: 240M+ snapshots puntuales, 8 niveles de profundidad por lado, marcas de tiempo por debajo del segundo y mercados resueltos conservados. Es una API REST normal con una cabecera X-API-Key, así que encaja en el mismo código asíncrono junto al SDK. Empieza gratis o lee cómo crear un bot para ver el recorrido completo.