oracle3

Oracle3

Oracle3 es un motor de trading de código abierto y servidor MCP para mercados de predicción. Mapea las relaciones lógicas entre contratos de eventos, encuentra precios que rompen los axiomas de probabilidad después de las tarifas de cada plataforma, y los negocia en vivo en Kalshi, Polymarket y Solana, o en papel, bajo límites de riesgo previos a la operación.

Opera en vivo en Kalshi, Polymarket y Solana. oracle3 live run ejecuta con el mismo motor que utiliza el trading en papel, detrás de límites de riesgo previos a la operación y un interruptor de apagado. Los agentes de IA se conectan a través de un servidor MCP con 13 herramientas.

De un vistazo

Plataformas	Kalshi, Polymarket y Solana (DFlow)
Ejecución	En vivo y en papel en un solo motor, con límites de riesgo previos a la operación, interruptor de apagado y envío de paquetes Jito en Solana
Relaciones verificadas	implicación, exclusividad, complemento, mismo evento entre plataformas, suma de eventos
Costos	El programa de tarifas propio de cada mercado desde la API de la plataforma (Kalshi taker 0.07·M·C·P·(1−P); Polymarket taker rate·C·p·(1−p))
Estrategias	6 basadas en restricciones, 2 de arbitraje estadístico, 2 impulsadas por modelos
Interfaces de agente	Servidor MCP con 13 herramientas, CLI JSON, 6 habilidades de agente, API de Python
Pruebas	Más de 600, con ruff, mypy y codespell en CI
Instalación	pip install oracle3
Licencia	Apache-2.0; las porciones originales de U Lab son MIT (ver NOTICE)

¿Qué problema resuelve?

Los contratos sobre resultados relacionados están vinculados por la probabilidad. Si A implica B, entonces P(A) ≤ P(B). Si A y B no pueden ocurrir ambos, P(A) + P(B) ≤ 1. Los resultados de un evento suman uno. Los precios cotizados rompen estos límites, dentro de una plataforma y entre plataformas, y una cesta de contratos que paga una cantidad conocida en cada estado puede entonces comprarse por menos de esa cantidad.

Las brechas son pequeñas, y ambas plataformas cobran tarifas de taker que escalan con p(1 − p). Si una brecha vale algo depende de la tarifa en cada pata de la cesta. Oracle3 hace tres cosas con esto:

1. Relaciones. Registra qué mercados están relacionados y cómo (implicación, exclusividad, complemento, mismo evento, suma de eventos).
2. Verificaciones. Para cada relación encuentra la cesta más barata a precios ejecutables, valora cada pata bajo el programa de tarifas propio de ese mercado, e informa el margen antes y después de tarifas.
3. Ejecución. Opera las cestas que sobreviven, en vivo o en papel, bajo límites de posición, drawdown y exposición, con un interruptor de apagado.

¿Cómo lo ejecuto?

pip install oracle3

# Find markets (JSON output for scripts and agents)
oracle3 market search --exchange kalshi --query "fed" --json
oracle3 market search --exchange polymarket --query "fed decision" --json

# Start the MCP server over stdio
oracle3 mcp

# Trade live on Kalshi (key via KALSHI_API_KEY_ID and KALSHI_PRIVATE_KEY_PATH)
oracle3 live run --exchange kalshi --monitor \
  --strategy-ref oracle3.strategy.contrib.implication_arb_strategy:ImplicationArbStrategy

Desde Python:

from oracle3.arbitrage import Quote, check_constraint
from oracle3.fees import KalshiSchedule

# A implies B, but A is bid at 0.60 while B is offered at 0.55.
result = check_constraint(
    "implication",
    [Quote("A", yes_bid=0.60, schedule=KalshiSchedule()),
     Quote("B", yes_ask=0.55, schedule=KalshiSchedule())],
)
best = result.best
print(best.description, best.gross_edge, best.fees, best.net_edge)
# NO on A + YES on B 0.05 0.0342 0.0158

Referencia completa de CLI: documentación.

¿Cómo lo usan los agentes de IA?

Servidor MCP

Añádelo a cualquier cliente MCP. Para Claude Code:

claude mcp add oracle3 -- uvx oracle3 mcp

Para Claude Desktop, Cursor y otros clientes que leen un bloque mcpServers:

{
  "mcpServers": {
    "oracle3": { "command": "uvx", "args": ["oracle3", "mcp"] }
  }
}

Herramienta	Qué hace	Efectos secundarios
search_markets	Búsqueda por palabras clave en Kalshi o Polymarket; listado de series de Kalshi	solo lectura
get_market	Precios, volumen, hora de cierre y reglas de resolución	solo lectura
get_orderbook	Ambos lados del libro, mejor nivel primero	solo lectura
get_quote	Mejor oferta y demanda en YES y NO, con el programa de tarifas del mercado	solo lectura
check_constraint_live	Obtener cotizaciones y programas de tarifas, luego verificar una relación	solo lectura
check_constraint	Verificar una relación en cotizaciones que tú proporcionas	ninguno
trading_fee	Tarifa por una ejecución bajo un programa de plataforma	ninguno
fair_value	Probabilidad implícita en un precio bajo la transformación de Wang	ninguno
list_relation_types	Las relaciones soportadas y sus límites	ninguno
list_relations	Relaciones guardadas localmente por la CLI de investigación	lee un archivo local
paper_order	Comprar en un libro de papel local, ejecutando contra el libro en vivo con tarifas	escribe un archivo local
paper_portfolio	Efectivo, posiciones y ejecuciones en el libro de papel	lee un archivo local
paper_reset	Borrar el libro de papel (requiere confirm=true)	escribe un archivo local

La ejecución con dinero real permanece en la CLI: los agentes investigan y operan en papel a través de MCP, y un humano aprueba las órdenes en vivo.

Si tu cliente ejecutó oracle3 1.2.0, que fallaba al iniciar con mcp 2.x, actualiza la copia en caché de uv una vez con uvx --refresh oracle3 mcp.

Habilidades de agente

skills/ (reflejado en .claude/skills/ para Claude Code) contiene instrucciones paso a paso para agentes:

Habilidad	Úsala para
pm-constraint-arbitrage	Verificar mercados relacionados en busca de una violación que sobreviva a las tarifas con las herramientas MCP
pm-data-discovery	Encontrar mercados y guardar muestras de investigación
pm-quant-strategy-authoring	Escribir un QuantStrategy ajustable
pm-agent-strategy-authoring	Escribir un AgentStrategy impulsado por LLM o herramientas
pm-paper-trade-ops	Ejecutar, monitorear y archivar trading en papel
pm-live-trade-ops	Trading en vivo, solo con aprobación explícita del usuario

CLI JSON

Cada comando market, paper y trade, y cada comando research excepto research memory, acepta --json. Un motor en ejecución puede pausarse, reanudarse, inspeccionarse y detenerse desde otro proceso con oracle3 trade pause|resume|state|stop --json. Consulta AGENTS.md para saber qué comandos son de solo lectura.

¿Qué hacen las tarifas al margen?

Ambas plataformas cobran tarifas de taker proporcionales a p(1 − p). Una cesta de taker de dos patas con ambas patas cerca de 0.50 tiene que superar estas violaciones por contrato antes de que quede cualquier margen:

Plataformas	Violación de equilibrio
Kalshi + Kalshi	3.50¢
Kalshi + Polymarket (tasa 0.05)	3.00¢
Kalshi + Polymarket (tasa 0.04)	2.75¢
Polymarket + Polymarket (tasa 0.04)	2.00¢

Comprar cada resultado de un evento de n vías cuesta k(1 − Σp²) por contrato, que se acerca a 7¢ en Kalshi a medida que los resultados se multiplican. La derivación, las tablas y las fuentes están en ¿Sobreviven los márgenes de arbitraje en mercados de predicción a las tarifas?; python scripts/fee_frontier.py reproduce cada número.

¿Cómo se prueba?

• oracle3.fees reproduce la tabla de tarifas publicada de Kalshi y el ejemplo de tarifa documentado de Polymarket.
• oracle3.arbitrage está probado por unidades para cada relación, incluyendo cestas de plataformas mixtas y cotizaciones faltantes.
• El servidor MCP se prueba contra APIs de plataforma simuladas, se ejecuta contra las APIs públicas en vivo, y se verifica en CI en ambas versiones principales del SDK de MCP.
• El motor de precios utiliza los coeficientes del documento de trabajo complementario (SSRN 6468338), verificado contra su paquete de replicación.

Hoja de ruta

1. Valorar cada señal de estrategia con los programas de tarifas de la plataforma en oracle3.fees.
2. Medir con qué frecuencia y profundidad las violaciones en vivo superan el umbral de tarifas, por relación y par de plataformas.
3. Conectar SpreadExecutor, ejecución de múltiples patas con liquidación LIFO en ejecuciones parciales, a las estrategias de múltiples patas.
4. Publicar un historial prospectivo pre-registrado con instantáneas diarias con marca de tiempo.

¿Cómo está construido?

graph TD
    R[Relation store<br/>implication · exclusivity · complement · same event · event sum] --> C[Constraint checker<br/>oracle3.arbitrage + oracle3.fees]
    Q[Venue data<br/>Kalshi · Polymarket public APIs] --> C
    C --> S[Strategy layer<br/>6 constraint-based · 2 statistical · 2 model-driven · LLM agents]
    P[Pricing engine<br/>Wang transform, calibrated in Yang 2026] --> S
    S --> E[Trading engine<br/>risk manager · position tracker · kill switch]
    E --> T[Paper trader]
    E --> L[Live traders<br/>CLI only]
    C --> M[MCP server<br/>read-only tools + paper ledger]
    Q --> M

Las relaciones y las cotizaciones de la plataforma alimentan el verificador de restricciones, que valora cada cesta bajo el programa de tarifas de cada mercado. Las estrategias consumen esas verificaciones y los valores justos del motor de precios y envían órdenes a través de un motor de trading que aplica límites de riesgo. El servidor MCP expone los datos, el verificador y un libro de papel separado a los agentes; los operadores en vivo solo son accesibles desde la CLI.

Estrategias basadas en restricciones, cada una aplicando un límite de probabilidad:

Estrategia	Límite
Entre mercados	Mismo evento, mismo precio entre plataformas
Exclusividad	P(A) + P(B) ≤ 1 para eventos mutuamente excluyentes
Implicación	P(A) ≤ P(B) cuando A implica B
Condicional	P(A | B) dentro de límites derivados
Suma de eventos	Σ P(resultado) = 1 dentro de un evento
Estructural	P(A) = β·P(B) + α de una relación ajustada

Arbitraje estadístico: spread de cointegración, lead-lag. Impulsadas por modelos: divergencia de valor justo y decaimiento de prima, utilizando el modelo de precios a continuación.

Modelo de precios. Los valores justos provienen de la transformación de Wang p_mkt = Φ(Φ⁻¹(p) + λ), con λ estimado en 291,309 contratos resueltos en el documento de trabajo complementario, Yang (2026), Pricing Prediction Markets: Incomplete Markets, Selection Rules, and Calibration Wedges (SSRN 6468338). El modelo y sus estimaciones están documentados allí.

Proyectos relacionados

• ulab-uiuc/prediction-market-cli (Coinjure): sistema de trading nativo para agentes en mercados de predicción; Oracle3 incluye su paquete coinjure.
• pmxt-dev/pmxt: API unificada entre plataformas de mercados de predicción.
• Jon-Becker/prediction-market-analysis: marco de recopilación y análisis de datos con un gran conjunto de datos público.
• YichengYang-Ethan/prediction-market-pricing: paquete de replicación para el modelo de precios.

¿Cómo puedo colaborar?

• Problemas abiertos se rastrean como issues etiquetados open-problem: medir violaciones contra el umbral de tarifas, evaluar el descubrimiento de relaciones y comparar la calibración de LLM y mercado.
• Discusiones están abiertas para preguntas e ideas: GitHub Discussions.
• Contribuciones: consulta CONTRIBUTING.md.

¿Cómo lo cito?

Los metadatos de citación están en CITATION.cff, y cada versión está archivada en Zenodo (DOI 10.5281/zenodo.20062548). Para el modelo de precios, cita el documento de trabajo (SSRN 6468338).

Origen y atribución

Oracle3 comenzó como ulab-uiuc/oracle3, desarrollado por Yicheng Yang y Haofei Yu en U Lab (University of Illinois Urbana-Champaign) bajo la Licencia MIT, e incluye el paquete coinjure del mismo laboratorio. Las capas de estrategia, precios, riesgo, panel y pruebas en este repositorio se añadieron sobre esa base; consulta NOTICE para el texto de licencia retenido.

Licencia

Apache 2.0; consulta LICENSE. Las porciones del código original de U Lab permanecen bajo la Licencia MIT reproducida en NOTICE.

Este software es para investigación y educación. El trading implica riesgo financiero.