Oracle3

Oracle3 is an open-source paper-trading engine and MCP server for prediction markets. It maps logical relations between event contracts on Kalshi and Polymarket, checks whether quoted prices break the axioms of probability after each venue's fees, and paper-trades the baskets that survive under pre-trade risk limits.

Status: paper-traded research software with no live track record. The MCP server cannot place real orders. See What is verified, and what is not?

At a glance

What problem does it solve?

Contracts on related outcomes are tied together by probability. If A implies B, then P(A) ≤ P(B). If A and B cannot both happen, P(A) + P(B) ≤ 1. The outcomes of one event sum to one. Quoted prices break these bounds, within a venue and across venues, and a basket of contracts that pays a known amount in every state can then be bought for less than that amount.

The gaps are small, and both venues charge taker fees that scale with p(1 − p). Whether a gap is worth anything depends on the fee on every leg of the basket. Oracle3 does three things with that:

1. Relations. It records which markets are related and how (implication, exclusivity, complement, same event, event sum).
2. Checks. For each relation it finds the cheapest basket at executable prices, prices every leg under that market's own fee schedule, and reports the edge before and after fees.
3. Paper trading. It trades the baskets that survive in a paper account, under position, drawdown and exposure limits, with a kill switch.

How do I run it?

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

From 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

Full CLI reference: documentation.

How do AI agents use it?

MCP server

Add it to any MCP client. For Claude Code:

claude mcp add oracle3 -- uvx oracle3 mcp

For Claude Desktop, Cursor and other clients that read an mcpServers block:

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

No tool can place a real order. The server imports no authenticated trader.

If your client ran oracle3 1.2.0, which failed to start with mcp 2.x, refresh uv's cached copy once with uvx --refresh oracle3 mcp.

Agent skills

skills/ (mirrored in .claude/skills/ and .agent/skills/) holds step-by-step instructions for agents:

JSON CLI

Every market, paper and trade command, and every research command except research memory, accepts --json. A running engine can be paused, resumed, inspected and stopped from another process with oracle3 trade pause|resume|state|stop --json. See AGENTS.md for which commands are read-only.

What do fees do to the edge?

Both venues charge taker fees proportional to p(1 − p). A two-leg taker basket with both legs near 0.50 has to clear these violations per contract before any edge is left:

Buying every outcome of an n-way event costs k(1 − Σp²) per contract, which approaches 7¢ on Kalshi as outcomes multiply. The derivation, the tables and the sources are in Do prediction-market arbitrage edges survive fees?; python scripts/fee_frontier.py reproduces every number.

What is verified, and what is not?

Verified

• oracle3.fees reproduces Kalshi's published fee table and Polymarket's documented fee example (unit-tested).
• The static checks in oracle3.arbitrage are unit-tested for every relation, including mixed-venue baskets and missing quotes.
• The MCP server is tested with mocked venue APIs and was run against the live public APIs on 2026-09-28.
• The pricing engine uses the coefficients from the companion working paper (SSRN 6468338), checked against its replication package.

Not demonstrated

• No live track record. Performance figures are deliberately not published. The committed replay episodes are short smoke tests, not statistically powered backtests.
• How often violations exceed the fee hurdle. The fee note gives the thresholds; it does not measure how often, for how long or at what depth prices cross them.
• Execution. The checks assume every leg fills at the quoted price. SpreadExecutor (multi-leg execution with LIFO unwind on partial fills) is unit-tested but not yet wired into the multi-leg strategies. The strategies subtract a flat 0.005 per side per contract instead of the venue schedules in oracle3.fees, which understates taker fees at mid prices (a Kalshi leg bought at 0.50 pays 1.75¢).
• Experimental modules. oracle3/experimental/ (flash-loan arbitrage), the multi-agent pipeline and the on-chain reputation module are prototypes and are not on the trading path.

Roadmap

1. Wire oracle3.fees into the strategies so every signal is priced net of the venue schedule.
2. Measure how often and how deeply live violations exceed the fee hurdle, per relation and venue pair.
3. A pre-registered forward paper-trading record with timestamped daily snapshots.

How is it built?

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

Relations and venue quotes feed the constraint checker, which prices every basket under each market's fee schedule. Strategies consume those checks and the pricing engine's fair values and send orders through a trading engine that enforces risk limits. The MCP server exposes the data, the checker and a separate paper ledger to agents; live traders are reachable only from the CLI.