Guía de la API de Polymarket: conecta un bot en 5 pasos

Auth

Firma de wallet y luego una API key derivada de ella. Mantén la clave privada fuera del host del bot si puedes.

Lectura

Gamma API para mercados y metadatos, sin auth. CLOB API para el libro.

Trading

CLOB API, peticiones firmadas. Compras como órdenes a mercado, ventas como órdenes limitadas.

Comisión de taker

0.07 x p x (1-p) por acción en los mercados de cripto. Los makers no pagan nada.

Liquidación

Los mercados cortos de cripto liquidan sobre una media de 60 segundos del oráculo frente a la apertura de la ventana.

Geografía

Bloquea Estados Unidos, Reino Unido, Francia y varios países más.

Docs

docs.polymarket.com

Cinco pasos, simplificados a propósito. Los fragmentos muestran la forma de cada llamada, no código de producción: sin reintentos, sin manejo de errores, sin backoff ante límites de peticiones. La librería cliente oficial se encarga de firmar; los ejemplos la usan.

1. Instala el cliente y deriva las credenciales

   Polymarket pasó a CLOB v2 en 2026, así que usa el cliente v2. Las credenciales se derivan una vez de una firma de wallet y luego se reutilizan.

   pip install py-clob-client-v2
   
   from py_clob_client.client import ClobClient
   
   HOST = "https://clob.polymarket.com"
   client = ClobClient(HOST, key=PRIVATE_KEY, chain_id=137, signature_type=1)
   creds = client.create_or_derive_api_key()   # firma una vez, guarda el resultado
   client.set_api_creds(creds)

   Las cuentas creadas con email usan un tipo de firma distinto al de las cuentas con wallet. Varios tipos se autentican sin problema pero solo el correcto ve tu saldo, así que comprueba la llamada de saldo antes de operar.

2. Encuentra el mercado y sus token ids

   Gamma es el catálogo de solo lectura. Los slugs de los mercados cortos de cripto son deterministas, y un mercado cerrado desaparece de las consultas por slug pero sigue accesible por id numérico.

   import requests
   
   GAMMA = "https://gamma-api.polymarket.com"
   m = requests.get(f"{GAMMA}/markets", params={"slug": "btc-updown-5m-1757500800"}).json()[0]
   up_token, down_token = m["clobTokenIds"]     # un token por resultado
   market_id = m["id"]                           # guárdalo: sobrevive al cierre

3. Lee el libro

   book = client.get_order_book(up_token)
   best_ask = float(book.asks[0].price)    # lo que paga una compra ahora
   best_bid = float(book.bids[0].price)    # lo que recibe una venta ahora
   spread = best_ask - best_bid            # salta la ventana si esto es ancho

   Registra cada lectura con el reloj en que la hiciste. Una ventana sin una lectura fresca no es una operación que hubieras podido hacer.

4. Envía una orden

   Una compra fill-or-kill debe ser una orden a mercado por un importe en dólares con como máximo dos decimales. Las ventas funcionan como órdenes limitadas que toman lo que hay.

   from py_clob_client.clob_types import MarketOrderArgs, OrderArgs, OrderType
   
   buy = client.create_market_order(MarketOrderArgs(token_id=up_token, amount=25.00, side="BUY"))
   resp = client.post_order(buy, OrderType.FOK)
   assert resp.get("success"), resp          # lanza error ante cualquier otra cosa, nunca asumas una ejecución
   
   sell = client.create_order(OrderArgs(token_id=up_token, price=0.90, size=30, side="SELL"))
   client.post_order(sell, OrderType.FAK)

   Una orden puede dar error en la red y aun así ejecutarse. Consulta tus operaciones después de cualquier excepción y concilia antes de la siguiente ventana.

5. Lee las ejecuciones y cobra

   Las ganancias no se cobran solas. Tras la liquidación, las acciones quedan en la wallet hasta que redimes la condición, y un saldo sin cobrar acaba bloqueando nuevas órdenes.

   fills = client.get_trades()                # tus ejecuciones, con la comisión pagada en cada una
   # El cobro es una llamada on-chain por condition id. El cliente relayer la envuelve;
   # sin él, reclama en la interfaz web todos los días.

Qué comprobar antes de poner dinero real

• Confirma que la comisión de tu primera ejecución real coincide con 0.07 x p x (1-p). Coincidió en todas las ejecuciones registradas.
• El mínimo por orden es 5 acciones; las apuestas de porcentaje diminuto se redondean hacia arriba o se rechazan.
• Los límites de peticiones son generosos para un solo bot, pero agrupa las lecturas del libro donde la API lo permita.
• Hay recompensas para makers en algunos mercados y exigen un tamaño mínimo de orden, actualmente 50 acciones. Una cotización de 10 acciones no gana nada.