oracle3
Oracle3 MCP server lets agents research Kalshi and Polymarket prediction markets, calculate fee-aware relation and pricing outputs, and simulate paper trades locally.
Search open markets on Kalshi or Polymarket and fetch market details, resolution rules, quotes, and displayed order books.
Compute venue trading fees for fills, including Kalshi taker/maker and Polymarket taker schedules.
Check constraints for implication, exclusivity, complement, same_event, and event_sum using supplied quotes or live venue quotes, returning baskets, fees, gross/net edge, and assumptions.
List supported relation types and locally saved relations from the research CLI.
Convert market prices to Wang-transform implied probabilities and premiums via fair_value.
Get a calibrated ML model probability for a market alongside its price and features, if the ML extra is installed.
Simulate YES/NO paper buys against the live book with fees, inspect paper cash/positions/fills, and reset the local paper ledger.
Public market reads need no exchange credentials; paper tools never send real orders.
Integrates with Solana (via DFlow) as a trading venue for prediction market contracts, supporting live order execution with Jito bundle submission alongside Kalshi and Polymarket.
Oracle3
Build prediction-market agents that discover markets, analyze opportunities, and test strategies.
Connect AI agents to Kalshi and Polymarket through MCP. Give them reusable Skills for market research and strategy development, then build on a Python engine for paper and live execution.
14 MCP tools · 6 agent Skills · Kalshi & Polymarket data · Python 3.10+
Quickstart · MCP tools · Agent Skills · Project and contributions · Documentation
Why Oracle3
A connected research workflow. Discover contracts, inspect their rules and order books, compare related outcomes, and track simulated positions.
Calculations that include trading costs. Five relationship checks return candidate baskets, per-leg fees, and calculated net edge.
Tools and workflows for agents. Use MCP for structured access and Skills for repeatable research, strategy authoring, and operations.
An engine you can extend. Build strategies with Python interfaces, risk controls, and paper/live venue adapters.
A foundation for experiments. Reproducible software checks, automated tests, and installed-package validation make the implementation inspectable.
Public Kalshi and Polymarket market reads need no exchange credentials. MCP provides market data, calculations, and a local paper ledger; real-order execution uses the separate CLI/Python engine.
Related MCP server: pmxt-mcp
Quickstart
Install the current development checkout:
git clone https://github.com/YichengYang-Ethan/oracle3-prediction-market-agent.git
cd oracle3-prediction-market-agent
python -m venv .venv
.venv/bin/python -m pip install -e .Connect it to Claude Code from this directory:
claude mcp add oracle3 -- "$PWD/.venv/bin/oracle3-mcp"For other MCP clients, configure the absolute path to .venv/bin/oracle3-mcp as the command with an empty argument list. On Windows, use .venv\Scripts\python.exe and .venv\Scripts\oracle3-mcp.exe.
Client configuration and first tool call · Published-package installation
Give your agent a first task
Find Kalshi and Polymarket contracts about the next Fed rate decision. Compare their outcome definitions, resolution rules, and order-book quotes. Summarize the markets with their IDs, prices, and the assumptions needed to compare them.
For a calculation that works offline after installation:
Use Oracle3 to check an implication: A implies B. A has a YES bid of $0.60 and B has a YES ask of $0.55. Use the default Kalshi taker fee schedule and 100 contracts per leg. Show the basket, gross edge, fees, and net edge.
The synthetic example returns $5.00 gross edge − $3.4125 fees = $1.5875 calculated net edge, conditional on the supplied implication and quotes. See exact inputs and output.
What agents can do
Task | Tools | Result |
Discover markets |
| Contracts, metadata, and available resolution rules |
Inspect market conditions |
| Prices, fee information, and displayed depth |
Analyze related contracts |
| Baskets and net edge under a stated relationship |
Calculate fees and model values |
| Fee estimates and parameterized model outputs |
Get a calibrated probability |
| A machine-learning probability next to the market price, with the model's out-of-sample scores (how it was built and tested) |
Try a paper entry |
| Simulated fills and holdings in a local ledger |
Relationship checks cover implication, exclusivity, complement, same event, and event sum. They expose assumptions with their results, giving agents and researchers a common calculation layer.
All 14 MCP tools · Workflow examples
Reusable agent Skills
The repository includes six workflows that help agents move from individual tool calls to complete tasks:
Skill | Use it to |
Find markets and organize research inputs | |
Examine related contracts and calculate fee-aware baskets | |
Develop strategies with Oracle3's Python interfaces | |
Build agent-driven decision workflows | |
Run and inspect simulated trading sessions | |
Configure and operate the separate live engine |
Claude Code project copies are included in .claude/skills/. Open the checkout as your project, or use your client's supported Skill installation mechanism. Skill setup.
For AI agents: start with llms.txt for task routing, the MCP reference for tool schemas, and AGENTS.md for contributing code.
Build with Python and the CLI
Use the same project for research scripts, agent strategies, and engine operations:
.venv/bin/oracle3 market search --exchange kalshi --query "fed" --json
.venv/bin/oracle3 market search --exchange polymarket --query "fed decision" --jsonComponent | Build with it |
Structured market access and local paper operations for agents | |
Shared calculations for related-contract strategies | |
Logical-relation, statistical, and model-driven approaches | |
Paper/live adapters for Kalshi, Polymarket, and Solana via DFlow | |
Wang-transform models and estimators for research | |
Optional venue, data-provider, and wallet integrations |
CLI guide · Integration guide · Execution reference
Built for experimentation
Oracle3 combines a concrete decision environment with structured tools, observable state, and a software validation harness. This supports work on agent interfaces, workflow guidance, and reproducible evaluation.
CI runs automated tests and checks the built package through real MCP sessions on SDK 1.x and 2.x. The harness documentation explains the reproducible checks. Model-level agent evaluation is a next research direction.
Project overview and Yicheng Yang's contributions · Fee-frontier study · Companion pricing research
Contribute
Help build better agent workflows, labeled evaluation tasks, strategy examples, and client integrations. New venue, data-provider, and wallet integrations start in oracle3-extras.
Contributing guide · Open problems · Discussions
Origin and attribution
Oracle3 began as ulab-uiuc/oracle3, developed by Yicheng Yang and Haofei Yu at U Lab (University of Illinois Urbana-Champaign). It also bundles the lab's Coinjure package. Yicheng Yang continues to develop and maintain the extensions in this repository. Read the project story and contributions.
We acknowledge the foundational work of the Coinjure team at the University of Illinois Urbana-Champaign—Haofei Yu, Yicheng Yang, Yuxiang Liu, and Prof. Jiaxuan You—on which Oracle3 builds.
For software citation, use CITATION.cff and Zenodo. For the pricing model, see the working paper.
License
Apache 2.0; see LICENSE. Original U Lab and Coinjure portions retain their MIT license in NOTICE.
This software is for research and education. Trading involves financial risk.
Available Tools
14 toolscheck_constraintARead-onlyIdempotent
Calculate a price-bound violation and basket economics conditional on the relation you supply.
A pure calculation with no network calls: use it for hypothetical or
historical prices, and use check_constraint_live to fetch current quotes
instead. Returns violated, profitable_after_fees, the best basket (legs,
cost, conditional payoff bound, fees, gross and net edge), every candidate basket,
any missing quotes, and the assumptions behind the check (full fills at the
quoted prices, a correctly specified relation). The assessment object marks
relation_verified=false, execution_verified=false and conditional_on_relation=true:
this tool does not verify resolution rules, order-book depth or full fills.
Quote prices must be finite and in [0, 1]; prices used to calculate fees must
be strictly between 0 and 1. Each (venue, market_id) must be unique.
Inputs: quotes (required), relation (required), maker, contracts. Returns: object
check_constraint_liveARead-only
Fetch live quotes and fees, then calculate price bounds conditional on the supplied relation.
This is the main research call: find related contracts with search_markets,
confirm with get_market that their resolution rules really satisfy the
relation, then pass them here. Read-only: it calls the venues' public APIs
and places no orders. Returns the check_constraint result (violated,
profitable_after_fees, best basket with net edge) plus the quotes it used;
to simulate the trade, call paper_order for each leg of the best basket.
Live quotes do not verify resolution rules, order-book depth or full fills:
assessment.relation_verified and assessment.execution_verified remain false.
Inputs: markets (required), relation (required), maker, contracts. Returns: object
fair_valueARead-onlyIdempotent
Convert a market price into the probability it implies under the Wang transform, and report the premium.
Solves p_mkt = Phi(Phi^-1(p) + lam) for p; a pure calculation with no network
calls. Use it to strip the favourite-longshot premium from a quoted price
before comparing it with your own forecast. The default lam = 0.183 is the
pooled estimate in Yang (2026), SSRN 6468338; it pools real-money and
play-money venues, so treat it as illustrative. Returns market_price,
lambda, implied_probability and premium (price minus implied probability).
Inputs: market_price (required), lam. Returns: object
get_marketARead-only
Get one market's details: title, best bid and ask, volume and closing date.
Kalshi results include the resolution rules (rules_primary, rules_secondary);
Polymarket results include the outcomes, token ids, neg-risk flag and the
market's fee schedule. Read the rules of every leg here before trusting a
relation in check_constraint_live. For prices plus fee terms only, use
get_quote; for depth, use get_orderbook. Public data, no API key.
Inputs: venue (required), market_id (required). Returns: object
get_orderbookARead-only
Get the displayed order book for YES and NO as [price, size] levels, best first.
Prices are dollars per contract and sizes are contracts. Use it to see how
much of a basket can fill near the quoted price before paper_order; use
get_quote when only the top of book matters. Kalshi publishes bids only, so
each side's asks are derived from the other side's bids (a YES ask of p is a
NO bid of 1 - p). Public data, no API key.
Inputs: venue (required), market_id (required), depth. Returns: object
get_quoteARead-only
Get the best bid and ask on YES and NO, in dollars, plus the market's fee schedule.
Use it to collect prices for check_constraint, or to read the fee terms
(Kalshi multiplier and maker fees, Polymarket taker rate) that trading_fee
takes. check_constraint_live fetches quotes itself, so this is not needed
before calling it. A missing ask is derived from the opposite side's bid.
Returns {venue, market_id, title, yes_bid, yes_ask, no_bid, no_ask,
fee_schedule}. Public data, no API key.
Inputs: venue (required), market_id (required). Returns: object
list_relationsARead-only
List the market relations saved on this machine by the oracle3 research CLI, optionally filtered.
Reads ~/.oracle3/relations.json with no network calls. Use it to reuse pairs
already discovered or validated offline, then pass a pair to
check_constraint_live. For the abstract relation kinds and their bounds,
call list_relation_types instead. Returns the store path, a count and the
matching relations (markets, type, status and validation details); the list
is empty if the CLI has saved none.
Inputs: status, market_id, spread_type. Returns: object
list_relation_typesARead-onlyIdempotent
List the relation types the constraint checks support and the probability bound each enforces.
Static reference data with no network or file access, for example
implication: P(A) <= P(B). Use it to choose the relation argument of
check_constraint or check_constraint_live; to see concrete market pairs
saved on this machine, use list_relations instead. Returns
{relations: {name: bound}}.
Inputs: no named parameters. Returns: object
model_probabilityARead-only
Get oracle3's calibrated machine-learning probability for one open market, next to its market price.
The model was trained on resolved Kalshi and Polymarket contracts using only
information available at prediction time: the displayed price, time to the
scheduled end, recent price changes and volatility, spread and traded volume
(Kalshi), and category. It was tuned with event-grouped, purged walk-forward
cross-validation and recalibrated with isotonic regression on training folds.
The features are rebuilt from the venue's public API at call time, so no
account is needed. Returns model_probability, market_price, their difference,
the model's out-of-sample scores against market prices and the features used.
It is an estimate, not a trading signal; read the rules with get_market.
Requires the ML extra: pip install 'oracle3[ml]'.
Inputs: venue (required), market_id (required). Returns: object
paper_orderA
Simulate buying YES or NO contracts in the local paper ledger, filling against the live order book with venue fees. Never sends an order to a venue.
Walks the displayed asks from the best price up to limit_price and charges
the venue fee on each level. Use it to test the legs of a basket found by
check_constraint_live. Writes ~/.oracle3/mcp_paper_ledger.json (or the path
in ORACLE3_MCP_LEDGER); only buys are supported and positions are held at
cost. Returns status (filled, partially_filled, unfilled, or rejected when
paper cash is short), requested and filled contracts, average price, cost,
fees and the per-level fills. Supply request_id for safe retries: an identical
venue/market/side/quantity/limit returns the original result without another
fill, including unfilled or rejected results; changed intent is an error.
Without request_id, each call is a new order. Reset clears retry history.
Inputs: side (required), venue (required), contracts (required), market_id (required), +2 more. Returns: object
paper_portfolioARead-only
Show the local paper ledger: cash, open positions and the number of fills.
Reads ~/.oracle3/mcp_paper_ledger.json (or ORACLE3_MCP_LEDGER) with no
network calls. Use it after paper_order to confirm fills and remaining cash.
Starting cash is $10,000; positions are carried at cost, and the ledger does
not mark to market or track resolution. Returns the ledger path,
initial_cash, cash, positions and fills.
Inputs: no named parameters. Returns: object
paper_resetADestructive
Erase the local paper ledger and restore the $10,000 starting cash.
Deletes all paper positions, fill history and request_id retry history. No
venue is contacted and real accounts are never touched. Without confirm=true it returns status
not_reset and changes nothing. Use it to start a fresh paper-trading
session.
Inputs: confirm. Returns: object
search_marketsARead-only
Search open Kalshi or Polymarket markets and return candidates with their best prices.
Start here to find market ids, then call get_quote or get_orderbook for live
prices, or get_market for resolution details. Reads the venues' public APIs,
so no account or API key is needed; Kalshi keyword search scans up to 1,000
open events. Returns {venue, query, count, markets}; each market has
market_id, title, best bid and ask in dollars, volume and closing date.
Inputs: venue (required), limit, query, series_ticker. Returns: object
trading_feeARead-onlyIdempotent
Compute the venue fee for one fill at a given price and size; a pure calculation with no network calls.
Kalshi charges round_up(0.07 x M x C x P x (1 - P)) on taker fills, and
0.0175 x M x C x P x (1 - P) on maker fills where the series has maker fees;
Polymarket charges takers rate x C x p x (1 - p) and makers nothing. Use it
to price a single leg or a hypothetical fill; take a live market's fee terms
from get_quote, and use check_constraint to price a whole basket. Returns
fee, fee_per_contract, order_type and the schedule used.
Inputs: price (required), venue (required), contracts (required), maker, +3 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a clearly distinct part of the prediction-market research and paper-trading workflow. The closest pairs, such as check_constraint vs. check_constraint_live and get_quote vs. get_orderbook, are explicitly differentiated by whether they fetch live data and whether they return top-of-book or full depth.
All names use snake_case and are grouped predictably with prefixes such as get_, list_, paper_, and check_constraint. However, the naming is not uniformly verb_noun: several tools are noun phrases like fair_value, trading_fee, and model_probability.
Fourteen tools is well-scoped for a domain covering market search, quote inspection, relation checks, probability/fee calculations, and paper trading. Each tool has a clear role without obvious redundancy.
The surface covers the core research and paper-trading lifecycle: discovery, market details, order books, relation checks, calculations, fee modeling, simulated buys, and portfolio inspection. Minor gaps remain, such as no paper sell/close operation and no tool to save or delete relations, but these are partly workable through the external CLI or by holding positions at cost.
Maintenance
Related MCP Connectors
Hosted MCP for Kalshi prediction markets: search, odds, order books, settlement rules, and trading.
Polymarket & Kalshi live prediction market odds aggregator and cross-venue arbitrage scanner MCP.
Historical tick, order book and settlement data for Polymarket and Predict.fun crypto up/down markets, plus smart-money lists and backtest quotes, over a read-only MCP server.
Read-only prediction-market data across Kalshi, Polymarket, Limitless: venues, fees, lookups, stats.
Related MCP Servers
- AlicenseBqualityCmaintenanceA simple MCP server that grabs prediction market data from polymarket, PredictIt, & Kalshi.151 npm38MIT
- AlicenseCqualityDmaintenanceMCP server that provides a unified prediction market API for multiple venues like Polymarket and Kalshi, allowing AI agents to discover markets, fetch order books, and execute trades through a single interface.328MIT
- AlicenseAqualityCmaintenanceA read-only MCP server exposing Polymarket's public prediction-market data. Search markets, read live odds and order books, pull historical probability time-series, and inspect public wallet positions.1446 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceMCP server for querying and optionally trading across prediction markets (Polymarket, Kalshi, Limitless, Manifold) through a unified API.31MIT