Build a Polymarket bot: scanner, sizing, execution, monitoring

Esta guía muestra cómo construir un bot para Polymarket que escanee mercados de manera continua, dimensione oportunidades, ejecute a través del CLOB y monitorice el rendimiento. Se centra en la arquitectura y en patrones de desarrollo que puedes implementar usando las APIs públicas de Polymarket y el modelo del Relayer.

Puntos clave

• Arquitectura el bot como cuatro servicios independientes: scanner, sizer, executor y monitor.
• Usa las APIs Gamma y CLOB de Polymarket para listados y colocación de órdenes; el WebSocket para actualizaciones en tiempo real del libro.
• Prefiere órdenes de mercado FAK para ejecución a alta velocidad, pero siempre considera deslizamiento y comisiones.
• Instrumenta monitorización y switches de apagado rápidos para disputas del oráculo, retrasos en la liquidación o fills inesperados.

Por qué esta estructura

Los sistemas de trading son más fáciles de razonar cuando las responsabilidades están separadas. Un scanner encuentra edges candidatos, un sizer convierte el edge en una posición, un executor envía órdenes vía el CLOB y un monitor garantiza corrección y seguridad. Esta separación te permite escalar, testear y analizar latencia y riesgo de forma independiente.

H2: Fuentes de datos y APIs

Empieza conectando estos endpoints de Polymarket a tus servicios:

• Gamma (metadatos de mercado): https://gamma-api.polymarket.com — markets, events, tags, series. Usa paginación con after_cursor; evita offset.
• CLOB (libro de órdenes y trading): https://clob.polymarket.com — las lecturas del orderbook son públicas; el trading requiere API key + HMAC. Los SDKs de CLOB manejan la colocación de órdenes.
• Market WebSocket (libro en tiempo real): wss://ws-subscriptions-clob.polymarket.com/ws/market — suscríbete para book, price_change, best_bid_ask y tick_size_change. PING cada 10s.
• Data API (posiciones, open interest): https://data-api.polymarket.com para análisis post-trade.

Nota de diseño: combina los listados de Gamma con el feed WebSocket para un escaneo en vivo eficiente. Respeta los límites de tasa de Gamma (por ejemplo, /markets) y los requisitos de clave del CLOB para colocar órdenes.

H2: Scanner — encontrar oportunidades candidatas

Función

El scanner descubre oportunidades que coincidan con tu estrategia: spreads intra-market en binarias, sumas en multi-outcome o patrones de endgame. Debe ser stateless, escalable horizontalmente y centrado en calcular edges brutos.

Entradas y cadencia

• Suscríbete al Market WebSocket con custom_feature_enabled: true para recibir best_bid_ask y cambios de tick.
• Rellena con Gamma /markets cuando encuentres por primera vez un instrumento para obtener metadatos y outcomes.
• Mantén una vista en memoria pequeña de best asks/bids para cada outcome.

Cálculo del edge

• Binaria intra-market: calcula edge = 1.00 - (bestAsk(YES) + bestAsk(NO)). Un edge positivo es candidato.
• Multi-outcome: edge = 1.00 - sum(bestAsk(outcomes)).

Umbrales y filtros

• Umbral mínimo de edge (por ejemplo, > X centavos configurados) para cubrir comisiones de taker y riesgo de ejecución.
• Comprobaciones mínimas de liquidez: la profundidad en el best ask debe satisfacer el tamaño mínimo de fill.
• Consciencia del tick-size: ten en cuenta los eventos tick_size_change — la granularidad de precio puede cambiar a $0.001 cerca de extremos.

H2: Sizing — riesgo y asignación de capital

Objetivos

El sizing convierte un edge bruto en un plan de órdenes: cuántas acciones comprar por outcome y cómo fragmentar órdenes para limitar el deslizamiento.

Componentes

• Límites de exposición: topes de exposición en pUSD por mercado y globales.
• Dimensionado limitado por profundidad: calcula el volumen acumulado disponible en niveles sucesivos de precio en el lado ask; dimensiona solo hasta el volumen que mantenga el deslizamiento esperado dentro de la tolerancia.
• Margen para comisiones: resta la comisión esperada de taker (variable, hasta 1.8% en algunas categorías) del edge bruto antes de decidir operar.

Patrón práctico

• Empieza con fills conservadores: prefiere múltiples órdenes FAK pequeñas en lugar de una orden grande a menos que controles el libro.
• Si compras un complete set vía los flujos de CTF split/merge, incluye el coste de split/merge (gestionado por el Relayer) y el posible redondeo debido al tick size.

H2: Executor — colocar órdenes y manejar fills

Tipos de órdenes y restricciones

• Usa el endpoint de trading del CLOB para la colocación de órdenes: https://clob.polymarket.com. El SDK de CLOB y el Relayer gestionan el despliegue de wallet, approvals y firma de órdenes.
• Para velocidad, usa FAK (Fill-And-Kill) market orders cuando sea apropiado. Los FAKs ejecutan inmediatamente o se cancelan; ayudan a evitar exposición persistente pero pueden fill parcial.

Flujo de ejecución

1. Prepara la intención de trade: lista de outcome token ids y cantidades objetivo devueltas por el sizer.
2. Si ejecutas un complete-set multi-outcome, podrías en su lugar realizar un CTF split (mintear un complete set) y luego vender las piernas — el Relayer y el SDK abstraen las operaciones CTF.
3. Envía órdenes vía la API de trading del CLOB con los encabezados de atribución correctos si formas parte del Builder Program.
4. Observa los fills desde el WebSocket (last_trade_price y actualizaciones de best_bid_ask) o desde las respuestas de trade del CLOB.

Seguridad y reconciliación

• Rastrea fills parciales y cancela el resto o re-precia inmediatamente.
• Reconciliación de balances on-chain CTF (vía Data API) tras los fills para asegurar que realmente posees los outcome tokens esperados.
• Implementa claves de idempotencia y manejo de nonce para reintentos de órdenes.

H2: Monitorización y seguridad operativa

Qué monitorizar

• Tasa de fills, slippage promedio versus esperado, edge realizado después de comisiones.
• Latencia entre actualizaciones del WebSocket y envío de órdenes.
• Eventos inusuales: disputas UMA, tick_size_change, outages en la marketplace.

Alertas y kill-switches

• Soft kill automatizado: pausa la colocación de nuevas órdenes cuando el P&L neto realizado cae por debajo de un umbral o cuando el deslizamiento de fills excede límites.
• Hard kill: detén inmediatamente todo el tráfico si UMA reporta una disputa para un mercado en el que tengas posiciones, o si el Relayer señala problemas de liquidación.

Logs de auditoría y observabilidad

• Almacena todas las intenciones de orden, snapshots crudos de mercado y fills ejecutados. Usa estos logs para post-mortems y backtesting.
• Etiqueta logs con market id, condition_ids y request ids para emparejar registros de Gamma y CLOB.

H2: Builder Program, credenciales y límites de tasa

Si planeas enrutar órdenes con atribución, únete al Builder Program y gestiona las claves desde Polymarket settings. Los tiers de Builder controlan límites diarios del Relayer y recompensas. Para tradear vía el CLOB necesitarás API key + HMAC y debes respetar límites de tasa y cuotas del Relayer.

H2: Riesgos comunes y mitigaciones

Nunca supongas que el edge matemático está garantizado. Riesgos a considerar:

• Riesgo de resolución: las disputas en UMA pueden pausar o alterar los pagos.
• Deslizamiento y fills parciales: los FAKs pueden fill parcial; planifica exposición residual.
• Comisiones: las comisiones de taker varían por categoría y pueden erosionar edges pequeños (Geopolitics no tiene comisiones).
• Tiempo de settlement: tiempos de redeem/merge y retrasos del oráculo pueden retener capital.
• Fallos en smart-contracts o en el Relayer: instrumenta fallback y alertas humanas.

Cómo afecta a tu trading

Diseña tu bot para que cada unidad de trade sea pequeña, observable y reversible dentro de tus límites de riesgo. Dimensionado conservador, monitorización rápida y condiciones claras de kill reducen el riesgo de cola. Usa los endpoints Gamma y CLOB para estado de mercado determinista y prefiere órdenes FAK para ejecución rápida, pero siempre mide el slippage realizado frente a lo esperado.

Cierre

La arquitectura anterior ofrece un plano pragmático para construir un bot de trading para Polymarket: un scanner de alto rendimiento, un sizer conservador, un executor robusto usando el CLOB y el Relayer, y monitorización por capas. Empieza pequeño, instrumenta agresivamente e itera en sizing y filtros a medida que acumulas datos en vivo.

Preguntas frecuentes

¿Qué APIs debería usar para obtener listados de mercado y datos del libro en vivo?

Usa https://gamma-api.polymarket.com para metadatos de mercado (/markets) y wss://ws-subscriptions-clob.polymarket.com/ws/market para el order book en tiempo real y eventos best_bid_ask. Usa https://clob.polymarket.com para lecturas del order-book y trading; las lecturas son públicas pero el trading requiere API key + HMAC.

¿Debería usar órdenes limit o órdenes de mercado (FAK) para arbitraje?

Los FAK (Fill-And-Kill) market orders se usan comúnmente por velocidad y para evitar exposición persistente. Pueden fill parcial, así que diseña el dimensionado y la reconciliación en consecuencia. El SDK de CLOB expone helpers para crear FAK market orders.

¿Cómo tengo en cuenta las comisiones al dimensionar operaciones?

Resta las comisiones de taker esperadas de tu edge bruto antes de tradear. Las comisiones de taker varían por categoría (0% a 1.8% actualmente). Usa un umbral de net-edge que cubra comisiones más el deslizamiento esperado y márgenes de monitorización.

¿Qué monitorización es esencial para un bot en vivo?

Monitoriza tasas de fills, slippage realizado, latencia, avisos de disputa UMA, eventos tick_size_change y salud del Relayer. Implementa soft y hard kill-switches para deslizamientos grandes, drawdowns de P&L o disputas del oráculo.

¿Puedo enrutar órdenes a través del Builder Program?

Sí. El Builder Program permite a terceros enrutar órdenes con atribución y ganar builder fees. Los tiers controlan límites diarios del Relayer y recompensas; las credenciales se obtienen en polymarket.com/settings.