Guía de la API de Polymarket - Crea tu primer bot de trading en 2026

Capítulo 27 de 33

La versión corta

Polymarket expone tres APIs públicas: CLOB (trading), Gamma (descubrimiento de mercados) y Data (analítica). El SDK oficial de Python es py-clob-client 0.34.6. La autenticación usa una clave de API + firma ECDSA, con las órdenes firmadas mediante EIP-712 a través de una billetera proxy en Polygon. Los límites de tasa te restringen a unas 60 órdenes/minuto por clave. El mayor escollo para los desarrolladores nuevos es el problema de mapeo entre condition_id → token_id entre Gamma y CLOB: resuélvelo primero y todo lo demás encaja. Cada mes se ganan en Polymarket unos 40 millones $ en recompensas de liquidez y spread capturado por bots, casi en su totalidad por usuarios de la API.

Parte 1: Las tres APIs

Polymarket separa limpiamente las responsabilidades en tres servicios distintos. Usar la API correcta para cada tarea mantiene tu bot rápido, sencillo y dentro de los límites de tasa.

Un bucle de bot típico usa Gamma para encontrar mercados, CLOB para obtener libros de órdenes y enviar operaciones, y Data para hacer back-test del rendimiento de la estrategia sin conexión. Piensa en Gamma como el "catálogo", en CLOB como el "exchange" y en Data como el "almacén".

Parte 2: Autenticación y el modelo de billetera proxy

Polymarket no firma las operaciones con la clave privada de tu billetera principal. En su lugar, usa una billetera proxy estilo Gnosis Safe: tu billetera principal autoriza un proxy, y el proxy ejecuta todas las operaciones en Polygon. Tu bot de API habla con ese proxy.

Lo que necesitas

• Clave de API - genérala en Settings → Developer de Polymarket
• Clave privada - la clave de tu billetera de trading (NO la frase semilla de tu MetaMask principal)
• Dirección funder - la dirección de tu billetera proxy (se muestra en Settings → Wallet)
• Chain ID - 137 (Polygon mainnet)
• Tipo de firma - 1 (POLY_PROXY, estándar para usuarios minoristas)

Parte 3: Instalar py-clob-client

El SDK oficial de Python es la forma más rápida de pasar de cero a tu primera orden. Usaremos la versión 0.34.6, que es la actual a fecha de abril de 2026.

# Create a virtual environment first
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# Install the SDK
pip install py-clob-client==0.34.6 requests websocket-client python-dotenv

Configuración básica del cliente

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON

load_dotenv()

client = ClobClient(
 host="https://clob.polymarket.com",
 key=os.environ["POLY_PRIVATE_KEY"],
 chain_id=POLYGON, # 137
 signature_type=1, # POLY_PROXY
 funder=os.environ["POLY_FUNDER"],
)

# One-time: derive and cache API credentials
client.set_api_creds(client.create_or_derive_api_creds())

La llamada a create_or_derive_api_creds() firma un mensaje con tu clave privada y lo intercambia por una clave de API, un secret y una passphrase. Guárdalos en tu .env tras la primera ejecución para no llamar al endpoint de derivación en cada arranque.

Parte 4: Descubrir mercados vía Gamma

Antes de poder operar, necesitas encontrar mercados que merezcan la pena. Gamma devuelve JSON con todo lo que muestra la interfaz de Polymarket: pregunta, resultados, precios, volumen 24h, vencimiento, etiquetas e imágenes.

import requests

resp = requests.get(
 "https://gamma-api.polymarket.com/markets",
 params={
 "active": "true",
 "closed": "false",
 "tag_slug": "politics",
 "limit": 20,
 "order": "volume24hr",
 "ascending": "false",
 },
 timeout=10,
)
resp.raise_for_status()
markets = resp.json()

for m in markets:
 print(f"{m['slug']:50} Yes ${float(m['outcomePrices'][0]):.3f} Vol24h ${m.get('volume24hr', 0):,.0f}")

Parámetros útiles de consulta de Gamma

Parte 5: El mapeo de condition_id → token_id

Este es el punto de dolor número 1 en el desarrollo de bots de Polymarket. Gamma devuelve un condition_id (uno por mercado). Las operaciones de CLOB usan un token_id (uno por resultado). Siempre necesitas ambos.

# Each Gamma market object contains 'clobTokenIds' - a JSON string array
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # First outcome
no_token = token_ids[1] # Second outcome

# Alternative: ask CLOB directly using condition_id
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

El escollo del orden de los resultados

El array outcomes y el array clobTokenIds de Gamma están indexados entre sí. Siempre lee la etiqueta del resultado en lugar de asumir que el índice 0 es "Yes". En mercados de múltiples resultados (NegRisk, Óscar, elecciones), el índice 0 podría ser "Kamala Harris" o "Taylor Swift": el orden es determinista pero específico de cada mercado.

Parte 6: Leer libros de órdenes

book = client.get_order_book(token_id=yes_token)

best_bid = float(book.bids[0].price) if book.bids else None
best_ask = float(book.asks[0].price) if book.asks else None
mid = (best_bid + best_ask) / 2 if best_bid and best_ask else None
spread = best_ask - best_bid if best_bid and best_ask else None

print(f"Bid {best_bid} Ask {best_ask} Mid {mid:.4f} Spread {spread:.4f}")

Los libros de órdenes se devuelven como arrays ordenados (bids descendentes, asks ascendentes). Cada nivel tiene price y size. Para estimar el slippage de una orden mayor, recorre el libro y acumula nocional hasta consumir tu tamaño objetivo.

Parte 7: Enviar órdenes

Orden límite (GTC - la opción por defecto)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # Shares, not dollars. 100 shares @ $0.45 = $45 max cost.
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

La llamada a create_order firma un mensaje estructurado EIP-712 con tu clave privada. post_order lo envía a CLOB. Nunca envías claves privadas en bruto por la red, solo órdenes firmadas.

Tipos de orden

Cancelar

# Single order
client.cancel(order_id="0xabc...")

# Cancel all orders on a specific market
client.cancel_market_orders(market=market['conditionId'])

# Nuclear option: cancel everything
client.cancel_all()

Parte 8: Streaming por WebSocket

Sondear Gamma cada segundo es un desperdicio y alcanzarás los límites de tasa rápido. El feed de WebSocket transmite actualizaciones de libro de órdenes y operaciones en tiempo real, con latencia inferior al segundo.

import json, websocket

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

def on_open(ws):
 ws.send(json.dumps({
 "type": "market",
 "assets_ids": [yes_token, no_token],
 }))

def on_message(ws, message):
 event = json.loads(message)
 if event.get("event_type") == "price_change":
 print(f"{event['market']} {event['side']} {event['price']} size={event['size']}")

ws = websocket.WebSocketApp(
 WS_URL,
 on_open=on_open,
 on_message=on_message,
)
ws.run_forever(ping_interval=20)

Existen dos feeds: el de /market (libro de órdenes y operaciones públicos) y el de /user (tus propios eventos de orden y ejecución, autenticado). Los bots de producción suelen conectarse a ambos, reconectan automáticamente al desconectarse y tratan el WebSocket como la fuente de verdad del estado actual del libro.

Parte 9: Límites de tasa y backoff

Cuando recibas un HTTP 429, el servidor devuelve una cabecera Retry-After. Implementa un backoff exponencial con jitter:

import random, time

def post_with_backoff(fn, *args, max_retries=6):
 for attempt in range(max_retries):
 try:
 return fn(*args)
 except Exception as e:
 if "429" in str(e):
 sleep = (2 ** attempt) + random.random()
 time.sleep(min(sleep, 30))
 continue
 raise
 raise RuntimeError("Too many retries")

Parte 10: Una arquitectura de bot de referencia

Todo bot de Polymarket robusto tiene los mismos seis componentes. Construye cada uno como su propio módulo; mantenlos débilmente acoplados.

Parte 11: Modos de fallo comunes

• Datos de WebSocket obsoletos - Registra la hora del último mensaje por activo; si no hay actualizaciones durante >30s en un mercado activo, fuerza un refresco por REST.
• Colisiones de nonce - py-clob-client gestiona los nonce de las órdenes por ti, pero si escribes tu propio firmante, incrementa el nonce en cada orden.
• Saldo insuficiente - Comprueba siempre el saldo de pUSD antes de enviar; el libro podría mostrar tu orden pero el emparejamiento la rechazará.
• Mercado en pausa o resolviéndose - Comprueba market.active && !market.closed antes de operar. Las actualizaciones de Gamma van por detrás de CLOB unos segundos alrededor de la resolución.
• Desajuste del adaptador NegRisk - Los mercados de múltiples resultados se enrutan por un adaptador NegRisk separado. El SDK lo gestiona, pero confirma que tu orden fue al venue correcto.

Parte 12: Recompensas de liquidez vía API

Polymarket reparte unos 5 millones $/mes en recompensas de liquidez generales más 5 millones $+/mes en recompensas específicas de deportes (ver Recompensas de liquidez). La gran mayoría fluye hacia market makers basados en API que pueden mantener cotizaciones ajustadas de dos lados a través de miles de mercados.

La fórmula de recompensas premia las órdenes cercanas al punto medio, el tamaño y el tiempo en el libro. Un bucle de market making mínimo:

1. Lee el libro de órdenes del mercado objetivo
2. Calcula un punto medio justo (p. ej., VWAP de los 3 niveles superiores de cada lado)
3. Publica un bid en mid − spread_target/2 y un ask en mid + spread_target/2
4. En cada actualización de WebSocket, reajusta el precio si tu cotización se desvía más de un tick del objetivo
5. Cancela y sal si el libro se adelgaza o saltan noticias

Parte 13: Pasar a producción

• Alojamiento: un VPS de 6 $/mes (Hetzner, DigitalOcean) en Europa o US-East basta para la mayoría de los bots. Colócalo junto a un Polygon RPC si necesitas latencia inferior a 10ms.
• RPC: usa Alchemy, Infura o QuickNode para un Polygon RPC fiable. Los planes gratuitos sirven hasta que envíes cientos de órdenes por minuto.
• Monitorización: Prometheus + Grafana para métricas; un bot de Telegram para alertas. Registra cada ID de orden que envías y cada ejecución que recibes.
• Copias de seguridad: persiste el estado cada minuto. Si el VPS muere a mitad de una ejecución, querrás reanudar en segundos, no reconciliar a mano.
• Impuestos: tu registrador es también tu rastro de auditoría; ver Guía fiscal.

Parte 14 - Consejos profesionales validados para la API de Polymarket

Hoja de referencia: situación → acción

¿Qué sigue?

• Herramientas y recursos - paneles, analítica y feeds de datos de terceros que complementan la API
• Estrategias avanzadas - arbitraje de múltiples patas y construcciones tipo opciones adecuadas para bots
• Recompensas de liquidez - fórmulas exactas para ganar rebates de market-making
• Guía del libro de órdenes - intuición más profunda para leer el libro antes de programar contra él
• Glosario - definiciones en lenguaje sencillo de cada término de esta guía