Skip to main content
Glama

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+

Tests GitHub stars PyPI License DOI

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

search_markets, get_market

Contracts, metadata, and available resolution rules

Inspect market conditions

get_quote, get_orderbook

Prices, fee information, and displayed depth

Analyze related contracts

check_constraint, check_constraint_live

Baskets and net edge under a stated relationship

Calculate fees and model values

trading_fee, fair_value

Fee estimates and parameterized model outputs

Get a calibrated probability

model_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

paper_order, paper_portfolio

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

Data discovery

Find markets and organize research inputs

Constraint arbitrage

Examine related contracts and calculate fee-aware baskets

Quant strategy authoring

Develop strategies with Oracle3's Python interfaces

Agent strategy authoring

Build agent-driven decision workflows

Paper operations

Run and inspect simulated trading sessions

Live operations

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" --json

Component

Build with it

MCP server

Structured market access and local paper operations for agents

Relations and fees

Shared calculations for related-contract strategies

Strategies

Logical-relation, statistical, and model-driven approaches

Trading engine

Paper/live adapters for Kalshi, Polymarket, and Solana via DFlow

Pricing

Wang-transform models and estimators for research

oracle3-extras

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 tools
check_constraintA
Read-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_liveA
Read-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_valueA
Read-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_marketA
Read-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_orderbookA
Read-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_quoteA
Read-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_relationsA
Read-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_typesA
Read-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_probabilityA
Read-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_portfolioA
Read-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_resetA
Destructive

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_marketsA
Read-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_feeA
Read-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

    A4.3/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      MCP 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.
      32
      8
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A 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.
      14
      46 PyPI
      MIT