oracle3-prediction-market-agent

<!-- mcp-name: io.github.YichengYang-Ethan/oracle3 -->

# 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.

[![Tests](https://github.com/YichengYang-Ethan/oracle3-prediction-market-agent/actions/workflows/pytest.yml/badge.svg)](https://github.com/YichengYang-Ethan/oracle3-prediction-market-agent/actions/workflows/pytest.yml)
[![PyPI](https://img.shields.io/pypi/v/oracle3)](https://pypi.org/project/oracle3/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20062548.svg)](https://doi.org/10.5281/zenodo.20062548)

> **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?](#what-is-verified-and-what-is-not)

## At a glance

| | |
|---|---|
| Venues | Kalshi and Polymarket; a Solana/DFlow execution layer is experimental |
| Relations checked | implication, exclusivity, complement, same event across venues, event sum |
| Costs | Each market's own fee schedule from the venue API (Kalshi taker 0.07·M·C·P·(1−P); Polymarket taker rate·C·p·(1−p)) |
| Strategies | 6 constraint-based, 2 statistical-arbitrage, 2 model-driven |
| Agent interfaces | MCP server with 13 tools, JSON CLI, 6 agent skills, Python API |
| Tests | 600+, with ruff, mypy and codespell in CI |
| Install | `pip install oracle3` |
| License | Apache-2.0; the original U Lab portions are MIT (see [NOTICE](NOTICE)) |

## 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?

```bash
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:

```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](https://yichengyang-ethan.github.io/oracle3-prediction-market-agent/).

## How do AI agents use it?

### MCP server

Add it to any MCP client. For Claude Code:

```bash
claude mcp add oracle3 -- uvx oracle3 mcp
```

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

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

| Tool | What it does | Side effects |
|---|---|---|
| `search_markets` | Keyword search on Kalshi or Polymarket; Kalshi series listing | read-only |
| `get_market` | Prices, volume, close time and resolution rules | read-only |
| `get_orderbook` | Both sides of the book, best level first | read-only |
| `get_quote` | Best bid and ask on YES and NO, with the market's fee schedule | read-only |
| `check_constraint_live` | Fetch quotes and fee schedules, then check a relation | read-only |
| `check_constraint` | Check a relation on quotes you supply | none |
| `trading_fee` | Fee for one fill under a venue schedule | none |
| `fair_value` | Probability implied by a price under the Wang transform | none |
| `list_relation_types` | The supported relations and their bounds | none |
| `list_relations` | Relations saved locally by the research CLI | reads a local file |
| `paper_order` | Buy in a local paper ledger, filling against the live book with fees | writes a local file |
| `paper_portfolio` | Cash, positions and fills in the paper ledger | reads a local file |
| `paper_reset` | Erase the paper ledger (requires `confirm=true`) | writes a local file |

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/`](skills/) (mirrored in `.claude/skills/` and `.agent/skills/`) holds step-by-step instructions for agents:

| Skill | Use it to |
|---|---|
| `pm-constraint-arbitrage` | Check related markets for a fee-surviving violation with the MCP tools |
| `pm-data-discovery` | Find markets and save research samples |
| `pm-quant-strategy-authoring` | Write a tunable `QuantStrategy` |
| `pm-agent-strategy-authoring` | Write an LLM- or tool-driven `AgentStrategy` |
| `pm-paper-trade-ops` | Run, monitor and archive paper trading |
| `pm-live-trade-ops` | Live trading, only with explicit user approval |

### 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](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:

| Venues | Break-even violation |
|---|---:|
| Kalshi + Kalshi | 3.50¢ |
| Kalshi + Polymarket (rate 0.05) | 3.00¢ |
| Kalshi + Polymarket (rate 0.04) | 2.75¢ |
| Polymarket + Polymarket (rate 0.04) | 2.00¢ |

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?](docs/research/fee-frontier.md); `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](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6468338)), checked against its [replication package](https://github.com/YichengYang-Ethan/prediction-market-pricing).

**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?

```mermaid
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.