Oracle3 Prediction Market Agent logo

Oracle3 Prediction Market Agent

Community
YichengYang-Ethan

Oracle3: open-source trading engine and MCP server for prediction markets. Finds fee-adjusted no-arbitrage violations across related event contracts and trades them live on Kalshi, Polymarket and Solana, or on paper, under pre-trade risk limits. 13 MCP tools, JSON CLI, agent skills, 600+ tests.

PublisherYichengYang-Ethan
Repositoryoracle3-prediction-market-agent
LanguagePython
Forks
36
Stars
258
Available tools
0
Transport typestdio
Categories
LicenseApache-2.0
Links
  • Connect tools to AI workflows

    Oracle3 Prediction Market Agent exposes MCP capabilities that can be used by compatible AI clients and agents.

  • 0 available tools

    Browse the callable actions below, including names and descriptions when provided by the server.

  • Ready-to-copy setup

    Use the installation snippets to configure this server in your preferred MCP client.

  • Open source signals

    258 stars and 36 forks from the linked repository.

Oracle3

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

Tests PyPI License DOI

Trades live on Kalshi, Polymarket and Solana. oracle3 live run executes with the same engine that runs paper trading, behind pre-trade risk limits and a kill switch. AI agents plug in through a 13-tool MCP server.

At a glance

VenuesKalshi, Polymarket and Solana (DFlow)
ExecutionLive and paper on one engine, with pre-trade risk limits, a kill switch and Jito bundle submission on Solana
Relations checkedimplication, exclusivity, complement, same event across venues, event sum
CostsEach 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))
Strategies6 constraint-based, 2 statistical-arbitrage, 2 model-driven
Agent interfacesMCP server with 13 tools, JSON CLI, 6 agent skills, Python API
Tests600+, with ruff, mypy and codespell in CI
Installpip install oracle3
LicenseApache-2.0; the original U Lab portions are MIT (see 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. Execution. It trades the baskets that survive, live or on paper, 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

# 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

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.

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"] }
  }
}
ToolWhat it doesSide effects
search_marketsKeyword search on Kalshi or Polymarket; Kalshi series listingread-only
get_marketPrices, volume, close time and resolution rulesread-only
get_orderbookBoth sides of the book, best level firstread-only
get_quoteBest bid and ask on YES and NO, with the market's fee scheduleread-only
check_constraint_liveFetch quotes and fee schedules, then check a relationread-only
check_constraintCheck a relation on quotes you supplynone
trading_feeFee for one fill under a venue schedulenone
fair_valueProbability implied by a price under the Wang transformnone
list_relation_typesThe supported relations and their boundsnone
list_relationsRelations saved locally by the research CLIreads a local file
paper_orderBuy in a local paper ledger, filling against the live book with feeswrites a local file
paper_portfolioCash, positions and fills in the paper ledgerreads a local file
paper_resetErase the paper ledger (requires confirm=true)writes a local file

Real-money execution stays in the CLI: agents research and paper-trade through MCP, and a human signs off on live orders.

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/ for Claude Code) holds step-by-step instructions for agents:

SkillUse it to
pm-constraint-arbitrageCheck related markets for a fee-surviving violation with the MCP tools
pm-data-discoveryFind markets and save research samples
pm-quant-strategy-authoringWrite a tunable QuantStrategy
pm-agent-strategy-authoringWrite an LLM- or tool-driven AgentStrategy
pm-paper-trade-opsRun, monitor and archive paper trading
pm-live-trade-opsLive 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 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:

VenuesBreak-even violation
Kalshi + Kalshi3.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?; python scripts/fee_frontier.py reproduces every number.

How is it tested?

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

Roadmap

  1. Price every strategy signal with the venue fee schedules in oracle3.fees.
  2. Measure how often and how deeply live violations clear the fee hurdle, per relation and venue pair.
  3. Wire SpreadExecutor, multi-leg execution with LIFO unwind on partial fills, into the multi-leg strategies.
  4. Publish a pre-registered forward track record with timestamped daily snapshots.

How is it built?

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.

Constraint-based strategies, each enforcing one probability bound:

StrategyBound
Cross-marketSame event, same price across venues
ExclusivityP(A) + P(B) ≤ 1 for mutually exclusive events
ImplicationP(A) ≤ P(B) when A implies B
ConditionalP(A | B) within derived bounds
Event sumΣ P(outcome) = 1 within an event
StructuralP(A) = β·P(B) + α from a fitted relation

Statistical arbitrage: cointegration spread, lead-lag. Model-driven: fair-value divergence and premium decay, using the pricing model below.

Pricing model. Fair values come from the Wang transform p_mkt = Φ(Φ⁻¹(p) + λ), with λ estimated on 291,309 resolved contracts in the companion working paper, Yang (2026), Pricing Prediction Markets: Incomplete Markets, Selection Rules, and Calibration Wedges (SSRN 6468338). The model and its estimates are documented there.

Related projects

How can I collaborate?

How do I cite it?

Citation metadata is in CITATION.cff, and every release is archived on Zenodo (DOI 10.5281/zenodo.20062548). For the pricing model, cite the working paper (SSRN 6468338).

Origin and attribution

Oracle3 began as ulab-uiuc/oracle3, developed by Yicheng Yang and Haofei Yu at U Lab (University of Illinois Urbana-Champaign) under the MIT License, and it bundles the coinjure package from the same lab. The strategy, pricing, risk, dashboard, and test layers in this repository were added on top of that base; see NOTICE for the retained license text.

License

Apache 2.0; see LICENSE. Portions from the original U Lab code remain under the MIT License reproduced in NOTICE.

This software is for research and education. Trading involves financial risk.

Installation

TypingMind
{
  "mcpServers": {
    "oracle3-prediction-market-agent": {
      "command": "oracle3",
      "args": [
        "mcp"
      ]
    }
  }
}

Use Oracle3 Prediction Market Agent MCP with multiple AI models

TypingMind connects MCP tools at the workspace level, so once Oracle3 Prediction Market Agent is connected, you can use it with different AI models in TypingMind instead of setting it up separately for each model. This MCP runs locally through the TypingMind MCP connector on your device.

Setup guide to use the local connector

Use this when the MCP server needs access to local files, apps, or private resources on your computer.

1

Open the MCP settings

In TypingMind, go to Settings, Advanced Settings, then Model Context Protocol and choose Setup Connector.

  1. Open TypingMind in your browser.
  2. Click the Settings icon.
  3. Go to Advanced Settings.
  4. Open the Model Context Protocol section.
  5. Click Setup Connector and choose This Device.
TypingMind MCP connector setup screen with This Device selected
2

Run the connector command

Choose This Device, copy the command from TypingMind, and run it in Terminal. Keep the process running while you use MCP.

  1. Copy the setup command shown by TypingMind.
  2. Open Terminal on macOS or Windows Terminal on Windows.
  3. Paste and run the command.
  4. Approve the package install if Terminal asks you to proceed.
  5. Keep the Terminal window running while using MCP tools.
3

Add Oracle3 Prediction Market Agent as a server

When the connector status is Ready, click Edit Servers and paste the MCP server configuration.

  1. Wait until the connector status shows Ready.
  2. Click Edit Servers.
  3. Paste the Oracle3 Prediction Market Agent MCP server configuration.
  4. Save the server list.
  5. Refresh if you want to confirm the connector is still ready.
TypingMind MCP settings showing active server and Edit Servers button
{
  "mcpServers": {
    "oracle3-prediction-market-agent": {
      "command": "npx",
      "args": [
        "-y",
        "<mcp-server-package>"
      ]
    }
  }
}
4

Use it across models

Save the server list, open Plugins, enable the Oracle3 Prediction Market Agent MCP tools, then select any supported AI model in TypingMind and use the tools in chat or assign them to an AI agent.

  1. Open the Plugins page in TypingMind.
  2. Enable the Oracle3 Prediction Market Agent MCP tools.
  3. Start a chat and choose the AI model you want to use.
  4. Use the MCP tools in chat or assign them to an AI agent.
  5. Switch to another AI model whenever needed without reconnecting MCP.
TypingMind chat using enabled MCP tools with a selected AI model
Can you use Oracle3 Prediction Market Agent to help me with this task?
Oracle3 Prediction Market Agent
Sure. I read it.
Here is what I found using Oracle3 Prediction Market Agent.

Frequently asked questions

What is the Oracle3 Prediction Market Agent MCP server used for?

Oracle3 Prediction Market Agent is an MCP server that lets compatible AI clients connect to external tools and context. In TypingMind, you can add this MCP server once and make its tools available in your AI workspace.

Can I use Oracle3 Prediction Market Agent MCP with multiple AI models in TypingMind?

Yes. TypingMind connects MCP tools at the workspace level, so you can use Oracle3 Prediction Market Agent with different AI models such as Claude, ChatGPT, Gemini, or other models you have configured in TypingMind without setting up the MCP server separately for each model.

Why use Oracle3 Prediction Market Agent MCP with TypingMind?

TypingMind is one of the best frontends for LLM chat because it brings multiple AI models, prompts, plugins, AI agents, API keys, and MCP tools into one workspace. With Oracle3 Prediction Market Agent connected, you can use its MCP tools across your preferred models while keeping your chat workflow organized in TypingMind.

How do I connect Oracle3 Prediction Market Agent MCP to TypingMind?

Oracle3 Prediction Market Agent runs through the TypingMind local MCP connector. This is best when the MCP server needs access to local files, desktop apps, command-line tools, or private resources on your computer.

What tools does Oracle3 Prediction Market Agent MCP provide in TypingMind?

Oracle3 Prediction Market Agent exposes MCP capabilities that can be enabled from the TypingMind Plugins page and used in chat or assigned to AI agents.

Do I need to share my API keys with TypingMind to use Oracle3 Prediction Market Agent MCP?

No. TypingMind is local-first and lets you keep your model providers, API keys, prompts, and MCP configuration under your control. If Oracle3 Prediction Market Agent requires authentication, add the required headers, OAuth settings, or local configuration for that MCP server when you create the connection.

Related MCP Servers

View all

Set up your own AI workspace now

Get notified about new features and future giveaways by subscribing to our newsletter 👇