oddsrail

El carril que los agentes de IA utilizan para operar en mercados de predicción.

Un servidor MCP que da a cualquier agente (Claude Code, Claude Desktop o cualquier cosa compatible con MCP) acceso a los mercados de predicción de Polymarket y Kalshi: búsqueda de mercados, libros de órdenes, historial de precios, posiciones y enrutamiento de órdenes — con atribución de código de builder en cadena en Polymarket — además de dos herramientas de señal premium (detección de sobresalto/fade en directo, riesgo de disputa de resolución).

Modelo de negocio: el flujo de órdenes enrutado genera comisiones de builder; las herramientas de señal son la capa de datos de pago (x402 de pago por llamada planificado).

Por qué esto y no Parsec

El competidor más cercano (parsecapi.com) es un servicio alojado de código cerrado: guarda tus claves del exchange (o mantiene una wallet administrada que firma por ti), y su Builder Program se queda con el 55–85% de las comisiones que recogen los builders. oddsrail es lo contrario en todos los ejes: autoalojado, no custodial (las claves nunca salen de tu máquina), open source y con el 85% de tus comisiones de builder de PolymarketShare because atribución usa el mecanismo nativo, no un middleman. Parsec tampoco ha diseñado ni herramientas de señalización/análisis ni nada sobre riesgo de resolución — esa es nuestra capa de pago.

Inicio rápido

Se requiere Python 3.11 o superior. Crea el venv, instala y consuélalo en Claude Code:

GXP1 GXP2

Luego pídele al agente: "busca mercados sobre la final del Mundial y ejecuta la señal de overshoot en el favorito".

Cómo funciona la atribución (CLOB V2, verificado en agosto de 2026)

1. Obtén tu código de builder (un bytes32) en polymarket.com → Settings → Builders. Establece allí tus tarifas: taker de hasta 100 bps, maker de hasta 50 bps — adicionales a las tarifas de la plataforma y saldadas a tu wallet de builder.

2. export ODDSRAIL_BUILDER_CODE=0x... donde se ejecute el servidor.

3. Cada orden que cualquier agente enruta a través de place_order lleva el código en el campo builder de la estructura de la orden V2 antes de la firma — la atribución es on-chain, visible en cada evento OrderFilled de CTF Exchange V2, CTF Exchange V2.

4. Verifícalos con la herramienta builder_stats (endpoint público de trades del builder + leaderboard).

Variables de entorno

Estado — verificado en vivo el 2026-08-23

Las 10 herramientas invocables se probaron de extremo a extremo en una sesión real de cliente MCP contra Polymarket en vivo, desde el VPS de Finlandia (/opt/oddsrail). Verificado que funcionan: búsqueda, consulta de mercado, libro de órdenes (9 de 65 niveles), historial de precios (361 puntos), señal de overshoot, riesgo de disputa, leaderboard de builders, dry-run de órdenes, órdenes abiertas e información del servidor.

Durante esa ejecución se corrigieron los mapeos de campos contra la API real: las formas derivadas de la documentación eran incorrectas en tres lugares (sans es un dict indexado por yes/no, search() anida los mercados dentro de eventos, y los datos de libro/volumen/resolución viven en los subobjetos prices/metrics/state/resolution).

⚠️ Nota sobre la red

Los dominios de la API de Polymarket están bloqueados en las redes turcas (BTK): las pruebas locales fallan en TLS con una página de bloqueo. Ejecuta el servidor en un lugar donde Polymarket sea accesible (el VPS de Finlandia en /opt/oddsrail, una VPN o cualquier otra red no bloqueada). La lógica de señales y la capa MCP son totalmente probables sin conexión.

Kalshi (segunda plataforma)

Kalshi es by design bring-your-own-key y de un solo inquilino: el operador aporta su propia clave de API, opera su propia cuenta y este servidor no guarda ningún tipo de datos en caché. Es una decisión deliberada: el Kalshi Developer Agreement limita el uso de la API a las operaciones propias de un miembro (§3), prohíbe facilitar las operaciones de otros miembros (§3.2) y la sublicencia de la API (§3.7), y restringe el almacenamiento/intercambio de datos de la API (§3.1). Un servicio Kalshi alojado y multitenant no sería compatible; un servicio autoalojado sí lo es.

Aquí no existe la atribución. Los Kalshi Builder Codes son una integración de Solana/DFlow/Jupiter — no hay ningún campo de builder o afiliado en la API REST, así que el flujo de órdenes de Kalshi no puede atribuirse ni monetizarse como el de Polymarket. Kalshi está en oddsrail para la cobertura y el alcance de las señales, no para obtener ingresos por enrutamiento.

Hay dos formas en esta API que son fáciles de hacer mal, así que oddsrail normaliza ambas:

• Los preciorios son cadenas de dólares, no céntimos ("0.5600"), y los tamaños son cadenas de punto fijo ("10.00"); el campo heredado de céntimos enteros se removió en marzo de 2026. Toda la aritmetitera usa Decimal.

• El libro de órdenes es solo de bids en ambos lados. yes_dollars y no_dollars son ambas escaleras de bids ascendientes — así que la mejor bid es el último elemento, y una bid de NO a $0.99 es designada/as a YES a $0.01. kalshi_get_orderbook devuelve una vista convencional de bid/ask (mejor oferta primero) del libro de YES junto con las escaleras brutas.

La colocación de órdenes habla en términos naturales: outcome (yes/no), action (buy/sell), price = probabilidad de ese resultado — y traduce internamente al bid/ask del libro de YES de Kalshi (comprar NO @ 0.25 se convierte en ask a 0.75). Esta traducción está cubierta por pruebas unitarias, porque es el lugar obvio para instalar un bug de posición invertida.

Credenciales: KALSHI_KEY_ID junto con KALSHI_PRIVATE_KEY_PATH (PKCS#8 PEM) o KALSHI_PRIVATE_KEY. Define KALSHI_DEMO=1 para usar el entorno de demo. Las herramientas de lectura no necesitan ninguna clave.

Herramientas (21)

• search_markets, get_market, get_orderbook, price_history, get_positions — de solo lectura, sin clave ni.

• overshoot_signal — premium: detección de saltos de pánico recientes + tendencia de reversiónhistórica de este mercado (portado del analizador polymarket-wc)

• dispute_risk — premium: heurística transparente de 0–0 para resolución de disputas (resoluciones propensas a disputas UMA)

• place_order, cancel_order, open_orders — trading, dry-run por defecto

• builder_stats — verificación de atribución + leaderboard público de builders

• server_info — estado de configuración, por plataforma

Kalshi: kalshi_search_markets, kalshi_get_market, kalshi_get_orderbook, kalshi_get_trades, kalshi_balance, kalshi_positions, kalshi_open_orders, kalshi_place_order, kalshi_cancel_order.

Notas sobre la pica

• El SDK unificado oficial polymarket-client (0.6.x): AsyncPublicClient para datos y AsyncSecureClient.place_limit_order(..., builder_code=...) para órdenes atribuidas. El antiguo py-clob-client está archivado pero no puede adjuntar códigos de builder — no lo uses.

• MCP SDK 2.0: utiliza MCPServer de mcp.server.mcpserver (el import antiguo mcp.server.fastmcp.FastMCP no está en 2.x).

• Kalshi está sobre httpx y cryptography, no el SDK oficial: kalshi-python-sync requiere Python >=3.13 y se reversiona cada semana en bloqueo con la versión del spec. La autenticación es RSA-PSS(SHA256, salt=longitud del digest) sobre str(unix_ms) + METHOD + path, donde el path incluye /trade-api/v2 y excluye los query. La URL base es ahora external-api.kalshi.com.

• x402 (planificado): el paquete oficial x402 de PyPI (v2.x) puede envolver las herramientas MCP directamente (x402.mcp, el pago viaja en el _meta de la llamada), pero sus helpers MCP actualmente apuntan a mcp 1.x — integrarlo requiere fijar mcp>=1.28,<2 o esperar a la versión compatible con 2.x. La liquidación en mainnet necesita un facilitator (Coinbase CDP: 1,000 liquidaciones gratuitas al mes y luego $0,001). Mantén los niveles gratuitos de ambas señales para que los registries puedan indexar el servidor.

Cómo es la economía de los builders Cómo se ve la economía de los builders (en vivo, 2026-08-23)

Extraído del leaderboard público mediante builder_stats:

Las filas más instructivas son las de usuarios pequeños: MagicMarkets enruta $354K/semana con 1 usuario activo, Gate $1.11M/semana con 2, PolymarketScan $277K con 3. Esos son operadores de bots que enrutan su propio flujo — exactamente el cliente objetivo de oddsrail — y muestran que un solo trader agente serio es suficiente para mover volumen de verdad. Las wallets (MetaMask, 37K usuarios) dominan en número de usuarios, no en volumen por usuario.

Roadmap

1. Prueba de humo en vivo desde una red no bloqueado — hecho el 2026-08-23, todas las herramientas pasan

2. Registrar el código de builder (polymarket.com → Settings → Builders), fija las dicho comisiones a 0 bps en el lanzamiento, export ODDSRAIL_BUILDER_CODE; primera orden atribuailable en un tamaño pequeño

3. Registrar Kalshi como plataforma #2 — terminada el 2026-08-23, 9 herramientas, verificada en vivo

4. Envolver con x402 de pago las dos señales una vez que se resuelva el conflicto de mcp-2

5. Listados en registros: registro oficial de MCP (mcp-publisher, marcador mcp-name: en PyPI), Smithery (necesita un HTTP público streamable + una herramienta gratuita para su scanner), Glama (glama.json)

Publicación / distribución

• GitHub: https://github.com/donde (público, MIT)

• Glama: rastrea automáticamente GitHub; glama.json en la raíz del repo declara el mantenimiento.

• Registro oficial de MCP: server.json está listo. Publicar primero requiere el paquete en PyPI (el registro verifica la propiedad con un marcador mcp-project: io.github. repositorio io.github en el README de PyPI) y luego mcp-publisher login github && mcp-publisher publish`.

• Smithery: requiere un endpoint público HTTPS de streamable-HTTP — disponible cuando oddsrail se aloje en lugar de ejecutarse localmente a través de stdio.