# 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. **13 MCP tools · 6 agent Skills · Kalshi & Polymarket data · Python 3.10+** [](https://github.com/YichengYang-Ethan/oracle3-prediction-market-agent/actions/workflows/pytest.yml) [](https://github.com/YichengYang-Ethan/oracle3-prediction-market-agent/stargazers) [](https://pypi.org/project/oracle3/) [](LICENSE) [](https://doi.org/10.5281/zenodo.20062548) [Quickstart](#quickstart) · [MCP tools](docs/mcp.md) · [Agent Skills](#reusable-agent-skills) · [Project and contributions](docs/research-review.md) · [Documentation](https://yichengyang-ethan.github.io/oracle3-prediction-market-agent/) ## 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. ## Quickstart Install the current development checkout: ```bash 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: ```bash 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](docs/agent-quickstart.md) · [Published-package installation](docs/mcp.md) ### 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](docs/agent-quickstart.md#first-call-a-deterministic-fee-check). ## 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 | | 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 13 MCP tools](docs/mcp.md) · [Workflow examples](docs/agent-quickstart.md) ## 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](skills/pm-data-discovery/SKILL.md) | Find markets and organize research inputs | | [Constraint arbitrage](skills/pm-constraint-arbitrage/SKILL.md) | Examine related contracts and calculate fee-aware baskets | | [Quant strategy authoring](skills/pm-quant-strategy-authoring/SKILL.md) | Develop strategies with Oracle3's Python interfaces | | [Agent strategy authoring](skills/pm-agent-strategy-authoring/SKILL.md) | Build agent-driven decision workflows | | [Paper operations](skills/pm-paper-trade-ops/SKILL.md) | Run and inspect simulated trading sessions | | [Live operations](skills/pm-live-trade-ops/SKILL.md) | Configure and operate the separate live engine | Claude Code project copies are included in [`.claude/skills/`](.claude/skills/). Open the checkout as your project, or use your client's supported Skill installation mechanism. [Skill setup](docs/agent-quickstart.md#agent-skills). **For AI agents:** start with [`llms.txt`](llms.txt) for task routing, the [MCP reference](docs/mcp.md) for tool schemas, and [`AGENTS.md`](AGENTS.md) for contributing code. ## Build with Python and the CLI Use the same project for research scripts, agent strategies, and engine operations: ```bash .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](oracle3/mcp_server/) | Structured market access and local paper operations for agents | | [Relations and fees](oracle3/arbitrage.py) | Shared calculations for related-contract strategies | | [Strategies](oracle3/strategy/) | Logical-relation, statistical, and model-driven approaches | | [Trading engine](oracle3/trader/) | Paper/live adapters for Kalshi, Polymarket, and Solana via DFlow | | [Pricing](oracle3/pricing/) | Wang-transform models and estimators for research | | [oracle3-extras](https://github.com/YichengYang-Ethan/oracle3-extras) | Optional venue, data-provider, and wallet integrations | [CLI guide](docs/CLI_MONITORING.md) · [Integration guide](docs/extras.md) · [Execution reference](docs/runtime-integrity.md) ## 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](https://github.com/YichengYang-Ethan/oracle3-prediction-market-agent/actions/workflows/pytest.yml) runs automated tests and checks the built package through real MCP sessions on SDK 1.x and 2.x. The [harness documentation](docs/agent-harness.md) explains the reproducible checks. Model-level agent evaluation is a next research direction. [Project overview and Yicheng Yang's contributions](docs/research-review.md) · [Fee-frontier study](docs/research/fee-frontier.md) · [Companion pricing research](https://github.com/YichengYang-Ethan/prediction-market-pricing) ## 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](https://github.com/YichengYang-Ethan/oracle3-extras). [Contributing guide](.github/CONTRIBUTING.md) · [Open problems](https://github.com/YichengYang-Ethan/oracle3-prediction-market-agent/issues?q=is%3Aissue+label%3Aopen-problem) · [Discussions](https://github.com/YichengYang-Ethan/oracle3-prediction-market-agent/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](https://github.com/ulab-uiuc/coinjure) package. Yicheng Yang continues to develop and maintain the extensions in this repository. [Read the project story and contributions](docs/research-review.md). 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](CITATION.cff) and [Zenodo](https://doi.org/10.5281/zenodo.20062548). For the pricing model, see the [working paper](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6468338). ## License Apache 2.0; see [LICENSE](LICENSE). Original U Lab and Coinjure portions retain their MIT license in [NOTICE](NOTICE). *This software is for research and education. Trading involves financial risk.*