oracle3

Servidor MCP de mercado de previsão para Kalshi e Polymarket: livros de ofertas ao vivo, tabelas de taxas das plataformas, verificações de não arbitragem cientes de taxas entre contratos relacionados e ordens simuladas.

GitHub

279

Experimente este MCPPatrocinado

Documentação

Oracle3

Oracle3 é um motor de negociação open-source e servidor MCP para mercados de previsão. Ele mapeia as relações lógicas entre contratos de eventos, encontra preços que violam os axiomas da probabilidade após as taxas de cada plataforma, e negocia essas oportunidades ao vivo na Kalshi, Polymarket e Solana, ou em modo simulado, sob limites de risco pré-negociação.

Negocia ao vivo na Kalshi, Polymarket e Solana. oracle3 live run executa com o mesmo motor usado na negociação simulada, atrás de limites de risco pré-negociação e um interruptor de emergência. Agentes de IA se conectam por meio de um servidor MCP com 13 ferramentas.

Resumo


Plataformas	Kalshi, Polymarket e Solana (DFlow)
Execução	Ao vivo e simulada em um único motor, com limites de risco pré-negociação, interruptor de emergência e envio de pacotes Jito na Solana
Relações verificadas	implicação, exclusividade, complemento, mesmo evento entre plataformas, soma de eventos
Custos	A tabela de taxas de cada mercado obtida da API da plataforma (Kalshi taker 0,07·M·C·P·(1−P); Polymarket taxa taker·C·p·(1−p))
Estratégias	6 baseadas em restrições, 2 de arbitragem estatística, 2 orientadas por modelos
Interfaces para agentes	Servidor MCP com 13 ferramentas, CLI JSON, 6 habilidades de agente, API Python
Testes	600+, com ruff, mypy e codespell na CI
Instalação	`pip install oracle3`
Licença	Apache-2.0; as partes originais do U Lab são MIT (veja NOTICE)

Qual problema ele resolve?

Contratos sobre resultados relacionados são ligados pela probabilidade. Se A implica B, então P(A) ≤ P(B). Se A e B não podem ocorrer simultaneamente, então P(A) + P(B) ≤ 1. Os resultados de um evento somam um. Os preços cotados violam esses limites, dentro de uma plataforma e entre plataformas, e uma cesta de contratos que paga um valor conhecido em todos os estados pode ser comprada por menos do que esse valor.

As lacunas são pequenas, e ambas as plataformas cobram taxas taker que escalam com p(1 − p). Se uma lacuna vale algo depende da taxa em cada perna da cesta. O Oracle3 faz três coisas com isso:

Relações. Ele registra quais mercados estão relacionados e como (implicação, exclusividade, complemento, mesmo evento, soma de eventos).
Verificações. Para cada relação, ele encontra a cesta mais barata a preços executáveis, precifica cada perna sob a tabela de taxas do próprio mercado e reporta a margem antes e depois das taxas.
Execução. Ele negocia as cestas que sobrevivem, ao vivo ou em modo simulado, sob limites de posição, drawdown e exposição, com um interruptor de emergência.

Como eu executo?

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

A partir do 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

Referência completa da CLI: documentação.

Como agentes de IA usam?

Servidor MCP

Adicione-o a qualquer cliente MCP. Para o Claude Code:

claude mcp add oracle3 -- uvx oracle3 mcp

Para Claude Desktop, Cursor e outros clientes que leem um bloco mcpServers:

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

Ferramenta	O que faz	Efeitos colaterais
`search_markets`	Busca por palavras-chave na Kalshi ou Polymarket; listagem de séries da Kalshi	somente leitura
`get_market`	Preços, volume, horário de fechamento e regras de resolução	somente leitura
`get_orderbook`	Ambos os lados do livro de ofertas, melhor nível primeiro	somente leitura
`get_quote`	Melhor oferta e melhor pedido em YES e NO, com a tabela de taxas do mercado	somente leitura
`check_constraint_live`	Busca cotações e tabelas de taxas, depois verifica uma relação	somente leitura
`check_constraint`	Verifica uma relação em cotações fornecidas por você	nenhum
`trading_fee`	Taxa para uma execução sob uma tabela de taxas da plataforma	nenhum
`fair_value`	Probabilidade implícita por um preço sob a transformação de Wang	nenhum
`list_relation_types`	As relações suportadas e seus limites	nenhum
`list_relations`	Relações salvas localmente pela CLI de pesquisa	lê um arquivo local
`paper_order`	Compra em um livro contábil simulado local, preenchendo contra o livro ao vivo com taxas	grava um arquivo local
`paper_portfolio`	Saldo, posições e execuções no livro contábil simulado	lê um arquivo local
`paper_reset`	Apaga o livro contábil simulado (requer `confirm=true`)	grava um arquivo local

A execução com dinheiro real permanece na CLI: agentes pesquisam e negociam em modo simulado via MCP, e um humano aprova as ordens ao vivo.

Se o seu cliente executou o oracle3 1.2.0, que falhava ao iniciar com mcp 2.x, atualize a cópia em cache do uv uma vez com uvx --refresh oracle3 mcp.

Habilidades de agente

skills/ (espelhado em .claude/skills/ para Claude Code) contém instruções passo a passo para agentes:

Habilidade	Use para
`pm-constraint-arbitrage`	Verificar mercados relacionados em busca de violação que sobreviva às taxas com as ferramentas MCP
`pm-data-discovery`	Encontrar mercados e salvar amostras de pesquisa
`pm-quant-strategy-authoring`	Escrever um `QuantStrategy` ajustável
`pm-agent-strategy-authoring`	Escrever um `AgentStrategy` orientado por LLM ou ferramentas
`pm-paper-trade-ops`	Executar, monitorar e arquivar negociação simulada
`pm-live-trade-ops`	Negociação ao vivo, somente com aprovação explícita do usuário

CLI JSON

Todo comando market, paper e trade, e todo comando research exceto research memory, aceita --json. Um motor em execução pode ser pausado, retomado, inspecionado e interrompido de outro processo com oracle3 trade pause|resume|state|stop --json. Veja AGENTS.md para saber quais comandos são somente leitura.

O que as taxas fazem com a margem?

Ambas as plataformas cobram taxas taker proporcionais a p(1 − p). Uma cesta taker de duas pernas com ambas as pernas próximas de 0,50 precisa superar essas violações por contrato antes de sobrar qualquer margem:

Plataformas	Violação de equilíbrio
Kalshi + Kalshi	3,50¢
Kalshi + Polymarket (taxa 0,05)	3,00¢
Kalshi + Polymarket (taxa 0,04)	2,75¢
Polymarket + Polymarket (taxa 0,04)	2,00¢

Comprar todos os resultados de um evento com n resultados custa k(1 − Σp²) por contrato, o que se aproxima de 7¢ na Kalshi à medida que os resultados se multiplicam. A derivação, as tabelas e as fontes estão em As margens de arbitragem em mercados de previsão sobrevivem às taxas?; python scripts/fee_frontier.py reproduz todos os números.

Como é testado?

oracle3.fees reproduz a tabela de taxas publicada da Kalshi e o exemplo documentado de taxas da Polymarket.
oracle3.arbitrage é testado por unidade para cada relação, incluindo cestas de plataformas mistas e cotações ausentes.
O servidor MCP é testado contra APIs de plataformas simuladas, executado contra as APIs públicas ao vivo e verificado na CI em ambas as versões principais do SDK MCP.
O motor de precificação usa os coeficientes do working paper complementar (SSRN 6468338), verificado contra seu pacote de replicação.

Roadmap

Precificar cada sinal de estratégia com as tabelas de taxas das plataformas em oracle3.fees.
Medir com que frequência e profundidade as violações ao vivo superam o obstáculo das taxas, por relação e par de plataformas.
Integrar SpreadExecutor, execução multi-perna com unwind LIFO em preenchimentos parciais, nas estratégias multi-perna.
Publicar um histórico prospectivo pré-registrado com snapshots diários com carimbo de data/hora.

Como é construído?

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

Relações e cotações das plataformas alimentam o verificador de restrições, que precifica cada cesta sob a tabela de taxas de cada mercado. As estratégias consomem essas verificações e os valores justos do motor de precificação e enviam ordens por meio de um motor de negociação que impõe limites de risco. O servidor MCP expõe os dados, o verificador e um livro contábil simulado separado aos agentes; os traders ao vivo são acessíveis apenas pela CLI.

Estratégias baseadas em restrições, cada uma aplicando um limite de probabilidade:

Estratégia	Limite
Entre mercados	Mesmo evento, mesmo preço entre plataformas
Exclusividade	P(A) + P(B) ≤ 1 para eventos mutuamente exclusivos
Implicação	P(A) ≤ P(B) quando A implica B
Condicional	P(A \| B) dentro de limites derivados
Soma de eventos	Σ P(resultado) = 1 dentro de um evento
Estrutural	P(A) = β·P(B) + α a partir de uma relação ajustada

Arbitragem estatística: spread de cointegração, lead-lag. Orientadas por modelos: divergência de valor justo e decaimento de prêmio, usando o modelo de precificação abaixo.

Modelo de precificação. Os valores justos vêm da transformação de Wang p_mkt = Φ(Φ⁻¹(p) + λ), com λ estimado em 291.309 contratos resolvidos no working paper complementar, Yang (2026), Pricing Prediction Markets: Incomplete Markets, Selection Rules, and Calibration Wedges (SSRN 6468338). O modelo e suas estimativas estão documentados lá.

Projetos relacionados

ulab-uiuc/prediction-market-cli (Coinjure): sistema de negociação nativo para agentes em mercados de previsão; o Oracle3 inclui seu pacote coinjure.
pmxt-dev/pmxt: API unificada entre plataformas de mercados de previsão.
Jon-Becker/prediction-market-analysis: framework de coleta e análise de dados com um grande conjunto de dados público.
YichengYang-Ethan/prediction-market-pricing: pacote de replicação para o modelo de precificação.

Como posso colaborar?

Problemas em aberto são rastreados como issues rotuladas open-problem: medir violações contra o obstáculo das taxas, avaliar descoberta de relações e comparar calibração de LLM e de mercado.
Discussões estão abertas para perguntas e ideias: GitHub Discussions.
Contribuições: veja CONTRIBUTING.md.

Como citar?

Os metadados de citação estão em CITATION.cff, e cada versão é arquivada no Zenodo (DOI 10.5281/zenodo.20062548). Para o modelo de precificação, cite o working paper (SSRN 6468338).

Origem e atribuição

O Oracle3 começou como ulab-uiuc/oracle3, desenvolvido por Yicheng Yang e Haofei Yu no U Lab (University of Illinois Urbana-Champaign) sob a Licença MIT, e inclui o pacote coinjure do mesmo laboratório. As camadas de estratégia, precificação, risco, painel e testes neste repositório foram adicionadas sobre essa base; veja NOTICE para o texto da licença mantido.

Licença

Apache 2.0; veja LICENSE. Partes do código original do U Lab permanecem sob a Licença MIT reproduzida em NOTICE.

Este software é para pesquisa e educação. Negociação envolve risco financeiro.