oracle3 1.2.1__tar.gz → 1.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (146) hide show
  1. {oracle3-1.2.1 → oracle3-1.2.2}/PKG-INFO +23 -26
  2. {oracle3-1.2.1 → oracle3-1.2.2}/README.md +21 -24
  3. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/__init__.py +1 -1
  4. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/cli/cli.py +275 -3
  5. oracle3-1.2.2/oracle3/mcp_server/server.py +683 -0
  6. {oracle3-1.2.1 → oracle3-1.2.2}/pyproject.toml +3 -3
  7. oracle3-1.2.1/oracle3/mcp_server/server.py +0 -392
  8. {oracle3-1.2.1 → oracle3-1.2.2}/LICENSE +0 -0
  9. {oracle3-1.2.1 → oracle3-1.2.2}/NOTICE +0 -0
  10. {oracle3-1.2.1 → oracle3-1.2.2}/coinjure/__init__.py +0 -0
  11. {oracle3-1.2.1 → oracle3-1.2.2}/coinjure/matching/__init__.py +0 -0
  12. {oracle3-1.2.1 → oracle3-1.2.2}/coinjure/matching/_cache.py +0 -0
  13. {oracle3-1.2.1 → oracle3-1.2.2}/coinjure/matching/_category.py +0 -0
  14. {oracle3-1.2.1 → oracle3-1.2.2}/coinjure/matching/_date.py +0 -0
  15. {oracle3-1.2.1 → oracle3-1.2.2}/coinjure/matching/_fetchers.py +0 -0
  16. {oracle3-1.2.1 → oracle3-1.2.2}/coinjure/matching/_pipeline.py +0 -0
  17. {oracle3-1.2.1 → oracle3-1.2.2}/coinjure/matching/_resolution.py +0 -0
  18. {oracle3-1.2.1 → oracle3-1.2.2}/coinjure/matching/_template.py +0 -0
  19. {oracle3-1.2.1 → oracle3-1.2.2}/coinjure/matching/_text.py +0 -0
  20. {oracle3-1.2.1 → oracle3-1.2.2}/coinjure/matching/_types.py +0 -0
  21. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/agent/__init__.py +0 -0
  22. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/agent/coordinator.py +0 -0
  23. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/alerts/__init__.py +0 -0
  24. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/alerts/alerter.py +0 -0
  25. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/alerts/telegram_alerter.py +0 -0
  26. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/analytics/performance_analyzer.py +0 -0
  27. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/arbitrage.py +0 -0
  28. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/backtest/backtester.py +0 -0
  29. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/blinks/__init__.py +0 -0
  30. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/blinks/generator.py +0 -0
  31. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/blinks/server.py +0 -0
  32. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/cli/__init__.py +0 -0
  33. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/cli/agent_commands.py +0 -0
  34. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/cli/control.py +0 -0
  35. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/cli/data_commands.py +0 -0
  36. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/cli/market_commands.py +0 -0
  37. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/cli/monitor.py +0 -0
  38. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/cli/news_commands.py +0 -0
  39. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/cli/research_commands.py +0 -0
  40. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/cli/textual_monitor.py +0 -0
  41. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/cli/trade_commands.py +0 -0
  42. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/cli/utils.py +0 -0
  43. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/config/__init__.py +0 -0
  44. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/config/config.py +0 -0
  45. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/core/trading_engine.py +0 -0
  46. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/dashboard/__init__.py +0 -0
  47. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/dashboard/server.py +0 -0
  48. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/dashboard/static/demo.html +0 -0
  49. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/dashboard/static/index.html +0 -0
  50. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/dashboard/static/live.html +0 -0
  51. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/backtest/dflow_recorder.py +0 -0
  52. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/backtest/historical_data_source.py +0 -0
  53. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/backtest/history_reader.py +0 -0
  54. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/backtest/kalshi_replay_data_source.py +0 -0
  55. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/base_fetcher.py +0 -0
  56. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/composite_data_source.py +0 -0
  57. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/data_source.py +0 -0
  58. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/live/coingecko_x402_data_source.py +0 -0
  59. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/live/dflow_data_source.py +0 -0
  60. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/live/dflow_ws_data_source.py +0 -0
  61. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/live/google_news_data_source.py +0 -0
  62. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/live/kalshi_data_source.py +0 -0
  63. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/live/live_data_source.py +0 -0
  64. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/live/onchain_signal_source.py +0 -0
  65. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/live/polymarket_orderflow.py +0 -0
  66. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/live/twitter_fetcher.py +0 -0
  67. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/market_data_manager.py +0 -0
  68. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/preprocessing/__init__.py +0 -0
  69. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/data/preprocessing/news_processor.py +0 -0
  70. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/engine/__init__.py +0 -0
  71. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/engine/control.py +0 -0
  72. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/engine/registry.py +0 -0
  73. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/events/events.py +0 -0
  74. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/experimental/__init__.py +0 -0
  75. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/experimental/flash_loan.py +0 -0
  76. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/fees.py +0 -0
  77. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/live/live_trader.py +0 -0
  78. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/market/__init__.py +0 -0
  79. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/market/relations.py +0 -0
  80. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/market/validation.py +0 -0
  81. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/mcp_server/__init__.py +0 -0
  82. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/mcp_server/__main__.py +0 -0
  83. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/mcp_server/paper.py +0 -0
  84. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/mcp_server/venues.py +0 -0
  85. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/mock/__init__.py +0 -0
  86. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/mock/mock_mode.py +0 -0
  87. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/onchain/__init__.py +0 -0
  88. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/onchain/logger.py +0 -0
  89. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/onchain/reputation.py +0 -0
  90. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/order/order_book.py +0 -0
  91. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/position/position_manager.py +0 -0
  92. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/pricing/__init__.py +0 -0
  93. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/pricing/calibrator.py +0 -0
  94. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/pricing/contract_scorer.py +0 -0
  95. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/pricing/distortion.py +0 -0
  96. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/pricing/fair_value.py +0 -0
  97. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/pricing/greeks.py +0 -0
  98. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/pricing/premium_tracker.py +0 -0
  99. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/pricing/wang_mle.py +0 -0
  100. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/risk/correlation_risk_manager.py +0 -0
  101. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/risk/onchain_risk_manager.py +0 -0
  102. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/risk/risk_manager.py +0 -0
  103. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/storage/__init__.py +0 -0
  104. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/storage/serializers.py +0 -0
  105. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/storage/state_store.py +0 -0
  106. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/__init__.py +0 -0
  107. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/agent_strategy.py +0 -0
  108. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/__init__.py +0 -0
  109. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/adaptive_onchain_strategy.py +0 -0
  110. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/allocation_strategy.py +0 -0
  111. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/coint_spread_strategy.py +0 -0
  112. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/conditional_arb_strategy.py +0 -0
  113. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/cross_market_arbitrage_strategy.py +0 -0
  114. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/debate_strategy.py +0 -0
  115. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/event_sum_arb_strategy.py +0 -0
  116. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/exclusivity_arb_strategy.py +0 -0
  117. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/fair_value_strategy.py +0 -0
  118. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/implication_arb_strategy.py +0 -0
  119. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/lead_lag_strategy.py +0 -0
  120. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/llm_news_strategy.py +0 -0
  121. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/multi_agent_strategy.py +0 -0
  122. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/premium_decay_strategy.py +0 -0
  123. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/prompts.py +0 -0
  124. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/solana_agent_strategy.py +0 -0
  125. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/contrib/structural_arb_strategy.py +0 -0
  126. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/loader.py +0 -0
  127. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/market_making_strategy.py +0 -0
  128. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/momentum_mean_reversion_strategy.py +0 -0
  129. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/orderbook_imbalance_strategy.py +0 -0
  130. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/quant_strategy.py +0 -0
  131. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/simple_strategy.py +0 -0
  132. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/strategy.py +0 -0
  133. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/strategy/test_strategy.py +0 -0
  134. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/ticker/ticker.py +0 -0
  135. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/trader/atomic_trader.py +0 -0
  136. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/trader/jito_submitter.py +0 -0
  137. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/trader/kalshi_trader.py +0 -0
  138. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/trader/paper_trader.py +0 -0
  139. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/trader/polymarket_trader.py +0 -0
  140. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/trader/solana_trader.py +0 -0
  141. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/trader/spread_executor.py +0 -0
  142. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/trader/trader.py +0 -0
  143. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/trader/types.py +0 -0
  144. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/trading/__init__.py +0 -0
  145. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/trading/allocator.py +0 -0
  146. {oracle3-1.2.1 → oracle3-1.2.2}/oracle3/trading/sizing.py +0 -0
@@ -1,7 +1,7 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: oracle3
3
- Version: 1.2.1
4
- Summary: Paper-trading engine and MCP server for prediction markets (Kalshi, Polymarket): no-arbitrage checks across related event contracts, net of venue fees, under pre-trade risk limits.
3
+ Version: 1.2.2
4
+ Summary: Trading engine and MCP server for prediction markets: fee-aware no-arbitrage trading across related event contracts, live on Kalshi, Polymarket and Solana or on paper, under pre-trade risk limits.
5
5
  License: Apache-2.0
6
6
  License-File: LICENSE
7
7
  License-File: NOTICE
@@ -61,20 +61,21 @@ Description-Content-Type: text/markdown
61
61
 
62
62
  # Oracle3
63
63
 
64
- **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.
64
+ **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.
65
65
 
66
66
  [![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)
67
67
  [![PyPI](https://img.shields.io/pypi/v/oracle3)](https://pypi.org/project/oracle3/)
68
68
  [![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
69
69
  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20062548.svg)](https://doi.org/10.5281/zenodo.20062548)
70
70
 
71
- > **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)
71
+ > **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.
72
72
 
73
73
  ## At a glance
74
74
 
75
75
  | | |
76
76
  |---|---|
77
- | Venues | Kalshi and Polymarket; a Solana/DFlow execution layer is experimental |
77
+ | Venues | Kalshi, Polymarket and Solana (DFlow) |
78
+ | Execution | Live and paper on one engine, with pre-trade risk limits, a kill switch and Jito bundle submission on Solana |
78
79
  | Relations checked | implication, exclusivity, complement, same event across venues, event sum |
79
80
  | 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)) |
80
81
  | Strategies | 6 constraint-based, 2 statistical-arbitrage, 2 model-driven |
@@ -91,7 +92,7 @@ The gaps are small, and both venues charge taker fees that scale with p(1 − p)
91
92
 
92
93
  1. **Relations.** It records which markets are related and how (implication, exclusivity, complement, same event, event sum).
93
94
  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.
94
- 3. **Paper trading.** It trades the baskets that survive in a paper account, under position, drawdown and exposure limits, with a kill switch.
95
+ 3. **Execution.** It trades the baskets that survive, live or on paper, under position, drawdown and exposure limits, with a kill switch.
95
96
 
96
97
  ## How do I run it?
97
98
 
@@ -104,6 +105,10 @@ oracle3 market search --exchange polymarket --query "fed decision" --json
104
105
 
105
106
  # Start the MCP server over stdio
106
107
  oracle3 mcp
108
+
109
+ # Trade live on Kalshi (key via KALSHI_API_KEY_ID and KALSHI_PRIVATE_KEY_PATH)
110
+ oracle3 live run --exchange kalshi --monitor \
111
+ --strategy-ref oracle3.strategy.contrib.implication_arb_strategy:ImplicationArbStrategy
107
112
  ```
108
113
 
109
114
  From Python:
@@ -161,13 +166,13 @@ For Claude Desktop, Cursor and other clients that read an `mcpServers` block:
161
166
  | `paper_portfolio` | Cash, positions and fills in the paper ledger | reads a local file |
162
167
  | `paper_reset` | Erase the paper ledger (requires `confirm=true`) | writes a local file |
163
168
 
164
- No tool can place a real order. The server imports no authenticated trader.
169
+ Real-money execution stays in the CLI: agents research and paper-trade through MCP, and a human signs off on live orders.
165
170
 
166
171
  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`.
167
172
 
168
173
  ### Agent skills
169
174
 
170
- [`skills/`](skills/) (mirrored in `.claude/skills/` and `.agent/skills/`) holds step-by-step instructions for agents:
175
+ [`skills/`](skills/) (mirrored in `.claude/skills/` for Claude Code) holds step-by-step instructions for agents:
171
176
 
172
177
  | Skill | Use it to |
173
178
  |---|---|
@@ -195,27 +200,19 @@ Both venues charge taker fees proportional to p(1 − p). A two-leg taker basket
195
200
 
196
201
  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.
197
202
 
198
- ## What is verified, and what is not?
199
-
200
- **Verified**
203
+ ## How is it tested?
201
204
 
202
- - `oracle3.fees` reproduces Kalshi's published fee table and Polymarket's documented fee example (unit-tested).
203
- - The static checks in `oracle3.arbitrage` are unit-tested for every relation, including mixed-venue baskets and missing quotes.
204
- - The MCP server is tested with mocked venue APIs and was run against the live public APIs on 2026-09-28.
205
+ - `oracle3.fees` reproduces Kalshi's published fee table and Polymarket's documented fee example.
206
+ - `oracle3.arbitrage` is unit-tested for every relation, including mixed-venue baskets and missing quotes.
207
+ - 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.
205
208
  - 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).
206
209
 
207
- **Not demonstrated**
208
-
209
- - **No live track record.** Performance figures are deliberately not published. The committed replay episodes are short smoke tests, not statistically powered backtests.
210
- - **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.
211
- - **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¢).
212
- - **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.
213
-
214
- **Roadmap**
210
+ ## Roadmap
215
211
 
216
- 1. Wire `oracle3.fees` into the strategies so every signal is priced net of the venue schedule.
217
- 2. Measure how often and how deeply live violations exceed the fee hurdle, per relation and venue pair.
218
- 3. A pre-registered forward paper-trading record with timestamped daily snapshots.
212
+ 1. Price every strategy signal with the venue fee schedules in `oracle3.fees`.
213
+ 2. Measure how often and how deeply live violations clear the fee hurdle, per relation and venue pair.
214
+ 3. Wire `SpreadExecutor`, multi-leg execution with LIFO unwind on partial fills, into the multi-leg strategies.
215
+ 4. Publish a pre-registered forward track record with timestamped daily snapshots.
219
216
 
220
217
  ## How is it built?
221
218
 
@@ -260,7 +257,7 @@ Relations and venue quotes feed the constraint checker, which prices every baske
260
257
 
261
258
  - **Open problems** are tracked as [issues labeled `open-problem`](https://github.com/YichengYang-Ethan/oracle3-prediction-market-agent/issues?q=is%3Aissue+label%3Aopen-problem): measuring violations against the fee hurdle, evaluating relation discovery, and comparing LLM and market calibration.
262
259
  - **Discussions** are open for questions and ideas: [GitHub Discussions](https://github.com/YichengYang-Ethan/oracle3-prediction-market-agent/discussions).
263
- - **Contributions:** see [CONTRIBUTING.md](CONTRIBUTING.md).
260
+ - **Contributions:** see [CONTRIBUTING.md](.github/CONTRIBUTING.md).
264
261
 
265
262
  ## How do I cite it?
266
263
 
@@ -2,20 +2,21 @@
2
2
 
3
3
  # Oracle3
4
4
 
5
- **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.
5
+ **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.
6
6
 
7
7
  [![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)
8
8
  [![PyPI](https://img.shields.io/pypi/v/oracle3)](https://pypi.org/project/oracle3/)
9
9
  [![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
10
10
  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20062548.svg)](https://doi.org/10.5281/zenodo.20062548)
11
11
 
12
- > **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)
12
+ > **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.
13
13
 
14
14
  ## At a glance
15
15
 
16
16
  | | |
17
17
  |---|---|
18
- | Venues | Kalshi and Polymarket; a Solana/DFlow execution layer is experimental |
18
+ | Venues | Kalshi, Polymarket and Solana (DFlow) |
19
+ | Execution | Live and paper on one engine, with pre-trade risk limits, a kill switch and Jito bundle submission on Solana |
19
20
  | Relations checked | implication, exclusivity, complement, same event across venues, event sum |
20
21
  | 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)) |
21
22
  | Strategies | 6 constraint-based, 2 statistical-arbitrage, 2 model-driven |
@@ -32,7 +33,7 @@ The gaps are small, and both venues charge taker fees that scale with p(1 − p)
32
33
 
33
34
  1. **Relations.** It records which markets are related and how (implication, exclusivity, complement, same event, event sum).
34
35
  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.
35
- 3. **Paper trading.** It trades the baskets that survive in a paper account, under position, drawdown and exposure limits, with a kill switch.
36
+ 3. **Execution.** It trades the baskets that survive, live or on paper, under position, drawdown and exposure limits, with a kill switch.
36
37
 
37
38
  ## How do I run it?
38
39
 
@@ -45,6 +46,10 @@ oracle3 market search --exchange polymarket --query "fed decision" --json
45
46
 
46
47
  # Start the MCP server over stdio
47
48
  oracle3 mcp
49
+
50
+ # Trade live on Kalshi (key via KALSHI_API_KEY_ID and KALSHI_PRIVATE_KEY_PATH)
51
+ oracle3 live run --exchange kalshi --monitor \
52
+ --strategy-ref oracle3.strategy.contrib.implication_arb_strategy:ImplicationArbStrategy
48
53
  ```
49
54
 
50
55
  From Python:
@@ -102,13 +107,13 @@ For Claude Desktop, Cursor and other clients that read an `mcpServers` block:
102
107
  | `paper_portfolio` | Cash, positions and fills in the paper ledger | reads a local file |
103
108
  | `paper_reset` | Erase the paper ledger (requires `confirm=true`) | writes a local file |
104
109
 
105
- No tool can place a real order. The server imports no authenticated trader.
110
+ Real-money execution stays in the CLI: agents research and paper-trade through MCP, and a human signs off on live orders.
106
111
 
107
112
  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`.
108
113
 
109
114
  ### Agent skills
110
115
 
111
- [`skills/`](skills/) (mirrored in `.claude/skills/` and `.agent/skills/`) holds step-by-step instructions for agents:
116
+ [`skills/`](skills/) (mirrored in `.claude/skills/` for Claude Code) holds step-by-step instructions for agents:
112
117
 
113
118
  | Skill | Use it to |
114
119
  |---|---|
@@ -136,27 +141,19 @@ Both venues charge taker fees proportional to p(1 − p). A two-leg taker basket
136
141
 
137
142
  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.
138
143
 
139
- ## What is verified, and what is not?
140
-
141
- **Verified**
144
+ ## How is it tested?
142
145
 
143
- - `oracle3.fees` reproduces Kalshi's published fee table and Polymarket's documented fee example (unit-tested).
144
- - The static checks in `oracle3.arbitrage` are unit-tested for every relation, including mixed-venue baskets and missing quotes.
145
- - The MCP server is tested with mocked venue APIs and was run against the live public APIs on 2026-09-28.
146
+ - `oracle3.fees` reproduces Kalshi's published fee table and Polymarket's documented fee example.
147
+ - `oracle3.arbitrage` is unit-tested for every relation, including mixed-venue baskets and missing quotes.
148
+ - 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.
146
149
  - 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).
147
150
 
148
- **Not demonstrated**
149
-
150
- - **No live track record.** Performance figures are deliberately not published. The committed replay episodes are short smoke tests, not statistically powered backtests.
151
- - **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.
152
- - **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¢).
153
- - **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.
154
-
155
- **Roadmap**
151
+ ## Roadmap
156
152
 
157
- 1. Wire `oracle3.fees` into the strategies so every signal is priced net of the venue schedule.
158
- 2. Measure how often and how deeply live violations exceed the fee hurdle, per relation and venue pair.
159
- 3. A pre-registered forward paper-trading record with timestamped daily snapshots.
153
+ 1. Price every strategy signal with the venue fee schedules in `oracle3.fees`.
154
+ 2. Measure how often and how deeply live violations clear the fee hurdle, per relation and venue pair.
155
+ 3. Wire `SpreadExecutor`, multi-leg execution with LIFO unwind on partial fills, into the multi-leg strategies.
156
+ 4. Publish a pre-registered forward track record with timestamped daily snapshots.
160
157
 
161
158
  ## How is it built?
162
159
 
@@ -201,7 +198,7 @@ Relations and venue quotes feed the constraint checker, which prices every baske
201
198
 
202
199
  - **Open problems** are tracked as [issues labeled `open-problem`](https://github.com/YichengYang-Ethan/oracle3-prediction-market-agent/issues?q=is%3Aissue+label%3Aopen-problem): measuring violations against the fee hurdle, evaluating relation discovery, and comparing LLM and market calibration.
203
200
  - **Discussions** are open for questions and ideas: [GitHub Discussions](https://github.com/YichengYang-Ethan/oracle3-prediction-market-agent/discussions).
204
- - **Contributions:** see [CONTRIBUTING.md](CONTRIBUTING.md).
201
+ - **Contributions:** see [CONTRIBUTING.md](.github/CONTRIBUTING.md).
205
202
 
206
203
  ## How do I cite it?
207
204
 
@@ -1,3 +1,3 @@
1
1
  """oracle3 package."""
2
2
 
3
- __version__ = '1.2.1'
3
+ __version__ = '1.2.2'
@@ -65,6 +65,14 @@ def blinks(host: str, port: int) -> None:
65
65
  @click.option(
66
66
  '--max-events', default=None, type=int, help='Limit events for episode replay.'
67
67
  )
68
+ @click.option('--snapshot-json', default=None, type=str, help='Write periodic JSON state snapshot to PATH')
69
+ @click.option(
70
+ '--snapshot-interval',
71
+ default=5,
72
+ type=click.IntRange(min=1),
73
+ show_default=True,
74
+ help='Seconds between snapshot writes',
75
+ )
68
76
  def dashboard( # noqa: C901
69
77
  port: int,
70
78
  exchange: str,
@@ -74,10 +82,13 @@ def dashboard( # noqa: C901
74
82
  strategy_kwargs_json: str | None,
75
83
  episode_dir: str | None,
76
84
  max_events: int | None,
85
+ snapshot_json: str | None,
86
+ snapshot_interval: int,
77
87
  ) -> None:
78
88
  """Launch the web dashboard with paper trading (open browser to http://localhost:PORT)."""
79
89
  import asyncio
80
90
  import json as json_lib
91
+ import os
81
92
  from decimal import Decimal
82
93
  from pathlib import Path
83
94
 
@@ -307,13 +318,77 @@ def dashboard( # noqa: C901
307
318
  dash = DashboardServer(engine, port=port)
308
319
  dash.start()
309
320
 
310
- # Start control server
321
+ # Start control server (Unix socket; gracefully skipped on Windows)
311
322
  ctrl = ControlServer(engine)
312
- await ctrl.start()
323
+ try:
324
+ await ctrl.start()
325
+ except AttributeError:
326
+ click.echo(' [–] Control server skipped (Windows — no Unix socket support)')
313
327
 
314
328
  if coordinator is not None:
315
329
  await coordinator.start()
316
330
 
331
+ # --- Snapshot writer (background) ---
332
+ snapshot_task: asyncio.Task[None] | None = None
333
+ if snapshot_json:
334
+ from datetime import datetime, timezone
335
+
336
+ async def _write_snapshot() -> None:
337
+ """Periodically write a JSON state snapshot to PATH (atomically)."""
338
+ while True:
339
+ await asyncio.sleep(snapshot_interval)
340
+
341
+ # Build non-cash positions list
342
+ positions_list = [
343
+ {
344
+ 'ticker': pos.ticker.symbol,
345
+ 'quantity': pos.quantity,
346
+ 'average_cost': pos.average_cost,
347
+ 'realized_pnl': pos.realized_pnl,
348
+ }
349
+ for pos in position_manager.positions.values()
350
+ if not isinstance(pos.ticker, CashTicker)
351
+ ]
352
+
353
+ # Cash balance
354
+ cash_positions = position_manager.get_cash_positions()
355
+ cash = cash_positions[0].quantity if cash_positions else Decimal('0')
356
+
357
+ # Last prices (mid-price from order books, YES-side only)
358
+ last_prices: dict[str, Decimal] = {}
359
+ for ticker in sorted(market_data.order_books, key=lambda t: t.symbol):
360
+ if isinstance(ticker, CashTicker):
361
+ continue
362
+ if getattr(ticker, 'is_no_side', False):
363
+ continue
364
+ best_bid = market_data.get_best_bid(ticker)
365
+ best_ask = market_data.get_best_ask(ticker)
366
+ if best_bid is not None and best_ask is not None:
367
+ last_prices[ticker.symbol] = (
368
+ best_bid.price + best_ask.price
369
+ ) / Decimal('2')
370
+ elif best_bid is not None:
371
+ last_prices[ticker.symbol] = best_bid.price
372
+ elif best_ask is not None:
373
+ last_prices[ticker.symbol] = best_ask.price
374
+
375
+ snapshot = {
376
+ 'timestamp': datetime.now(timezone.utc).isoformat(),
377
+ 'exchange': exchange,
378
+ 'positions': positions_list,
379
+ 'cash': cash,
380
+ 'last_prices': last_prices,
381
+ }
382
+
383
+ # Atomic write: tmp → replace
384
+ tmp_path = f'{snapshot_json}.tmp'
385
+ with open(tmp_path, 'w') as f:
386
+ json_lib.dump(snapshot, f, default=str, indent=2)
387
+ os.replace(tmp_path, snapshot_json)
388
+
389
+ snapshot_task = asyncio.create_task(_write_snapshot())
390
+ click.echo(f' [✓] JSON snapshots every {snapshot_interval}s → {snapshot_json}')
391
+
317
392
  mode_label = 'Solana Backtest' if is_backtest else 'Paper Trading'
318
393
  click.echo(f'{mode_label} Dashboard running at http://localhost:{port}')
319
394
  click.echo('Press Ctrl+C to stop.\n')
@@ -334,10 +409,15 @@ def dashboard( # noqa: C901
334
409
  except asyncio.CancelledError:
335
410
  pass
336
411
  finally:
412
+ if snapshot_task is not None:
413
+ snapshot_task.cancel()
337
414
  if coordinator is not None:
338
415
  await coordinator.stop()
339
416
  await engine.stop()
340
- await ctrl.stop()
417
+ try:
418
+ await ctrl.stop()
419
+ except Exception:
420
+ pass
341
421
  dash.stop()
342
422
 
343
423
  try:
@@ -402,6 +482,198 @@ def trade_log(
402
482
  click.echo()
403
483
 
404
484
 
485
+ def _empty_calibration_rows() -> dict[str, list[float]]:
486
+ return {
487
+ 'price': [],
488
+ 'outcome': [],
489
+ 'volume': [],
490
+ 'duration_hours': [],
491
+ 'spread': [],
492
+ }
493
+
494
+
495
+ def _parse_calibration_row(row: dict[str, str], row_number: int) -> dict[str, float]:
496
+ try:
497
+ price = float(row['price'])
498
+ outcome = float(row['outcome'])
499
+ except (TypeError, ValueError) as exc:
500
+ raise click.ClickException(
501
+ f'Invalid price/outcome at CSV row {row_number}'
502
+ ) from exc
503
+
504
+ if not 0 < price < 1:
505
+ raise click.ClickException(
506
+ f'Invalid price at CSV row {row_number}: expected value in (0, 1)'
507
+ )
508
+ if outcome not in (0.0, 1.0):
509
+ raise click.ClickException(
510
+ f'Invalid outcome at CSV row {row_number}: expected 0 or 1'
511
+ )
512
+
513
+ parsed = {'price': price, 'outcome': float(outcome)}
514
+ for optional in ('volume', 'duration_hours', 'spread'):
515
+ value = row.get(optional)
516
+ if value:
517
+ try:
518
+ parsed[optional] = float(value)
519
+ except ValueError as exc:
520
+ raise click.ClickException(
521
+ f'Invalid {optional} at CSV row {row_number}'
522
+ ) from exc
523
+ return parsed
524
+
525
+
526
+ def _load_calibration_csv(csv_path: str) -> dict[str, list[float]]:
527
+ import csv
528
+
529
+ rows = _empty_calibration_rows()
530
+
531
+ with open(csv_path, newline='', encoding='utf-8') as handle:
532
+ reader = csv.DictReader(handle)
533
+ if reader.fieldnames is None:
534
+ raise click.ClickException('CSV file has no header row')
535
+
536
+ fieldnames = set(reader.fieldnames)
537
+ required = {'price', 'outcome'}
538
+ missing = sorted(required - fieldnames)
539
+ if missing:
540
+ raise click.ClickException(
541
+ f'CSV is missing required column(s): {", ".join(missing)}'
542
+ )
543
+
544
+ for row_number, row in enumerate(reader, start=2):
545
+ parsed = _parse_calibration_row(row, row_number)
546
+ rows['price'].append(parsed['price'])
547
+ rows['outcome'].append(parsed['outcome'])
548
+ for optional in ('volume', 'duration_hours', 'spread'):
549
+ if optional in parsed:
550
+ rows[optional].append(parsed[optional])
551
+
552
+ if not rows['price']:
553
+ raise click.ClickException('CSV file has no data rows')
554
+
555
+ return rows
556
+
557
+
558
+ def _mle_result_to_json_dict(result: Any) -> dict[str, Any]:
559
+ return {
560
+ 'beta': result.beta,
561
+ 'lambda_hat': result.lambda_hat,
562
+ 'se_fisher': result.se_fisher,
563
+ 'se_robust': result.se_robust,
564
+ 'se_cluster': result.se_cluster,
565
+ 'log_likelihood': result.log_likelihood,
566
+ 'n_obs': result.n_obs,
567
+ 'n_params': result.n_params,
568
+ 'converged': result.converged,
569
+ 'aic': result.aic,
570
+ 'bic': result.bic,
571
+ 'pseudo_r2': result.pseudo_r2,
572
+ 'covariate_names': result.covariate_names,
573
+ }
574
+
575
+
576
+ @cli.command()
577
+ @click.option(
578
+ '--csv',
579
+ 'csv_path',
580
+ required=True,
581
+ type=click.Path(exists=True, dir_okay=False),
582
+ help='Resolved-contract CSV with price and outcome columns.',
583
+ )
584
+ @click.option(
585
+ '--platform',
586
+ type=click.Choice(['polymarket', 'kalshi', 'metaculus', 'manifold', 'default']),
587
+ default='default',
588
+ show_default=True,
589
+ help='Platform prior used as the optimizer warm start.',
590
+ )
591
+ @click.option(
592
+ '--hierarchical',
593
+ is_flag=True,
594
+ default=False,
595
+ help='Fit a covariate model using volume, duration_hours, and spread columns.',
596
+ )
597
+ @click.option('--json', 'as_json', is_flag=True, default=False, help='Output as JSON')
598
+ def calibrate(
599
+ csv_path: str,
600
+ platform: str,
601
+ hierarchical: bool,
602
+ as_json: bool,
603
+ ) -> None:
604
+ """Estimate Wang Transform lambda from a resolved-contract CSV."""
605
+ import json as json_lib
606
+
607
+ from oracle3.pricing.wang_mle import (
608
+ LAMBDA_KALSHI,
609
+ LAMBDA_MANIFOLD,
610
+ LAMBDA_METACULUS,
611
+ LAMBDA_POLYMARKET,
612
+ LAMBDA_POOLED,
613
+ WangMLE,
614
+ )
615
+
616
+ platform_priors = {
617
+ 'polymarket': LAMBDA_POLYMARKET,
618
+ 'kalshi': LAMBDA_KALSHI,
619
+ 'metaculus': LAMBDA_METACULUS,
620
+ 'manifold': LAMBDA_MANIFOLD,
621
+ 'default': LAMBDA_POOLED,
622
+ }
623
+ import importlib.util
624
+
625
+ missing = [m for m in ('numpy', 'scipy') if importlib.util.find_spec(m) is None]
626
+ if missing:
627
+ raise click.ClickException(
628
+ f'oracle3 calibrate needs {" and ".join(missing)}: '
629
+ f'pip install {" ".join(missing)}'
630
+ )
631
+
632
+ rows = _load_calibration_csv(csv_path)
633
+ mle = WangMLE()
634
+
635
+ covariates = None
636
+ covariate_names = None
637
+ initial_beta: list[float] = [platform_priors[platform]]
638
+ if hierarchical:
639
+ optional_columns = ('volume', 'duration_hours', 'spread')
640
+ missing = [
641
+ name for name in optional_columns if len(rows[name]) != len(rows['price'])
642
+ ]
643
+ if missing:
644
+ raise click.ClickException(
645
+ '--hierarchical requires complete CSV column(s): ' + ', '.join(missing)
646
+ )
647
+ covariates = mle.build_design_matrix(
648
+ volumes=rows['volume'],
649
+ durations_hours=rows['duration_hours'],
650
+ prices=rows['price'],
651
+ spreads=rows['spread'],
652
+ )
653
+ covariate_names = [
654
+ 'constant',
655
+ 'ln(1+volume)',
656
+ 'ln(1+duration)',
657
+ '|p-0.5|',
658
+ 'spread',
659
+ ]
660
+ initial_beta.extend([0.0] * (len(covariate_names) - 1))
661
+
662
+ result = mle.fit(
663
+ prices=rows['price'],
664
+ outcomes=rows['outcome'],
665
+ covariates=covariates,
666
+ covariate_names=covariate_names,
667
+ initial_beta=initial_beta,
668
+ )
669
+
670
+ if as_json:
671
+ click.echo(json_lib.dumps(_mle_result_to_json_dict(result)))
672
+ return
673
+
674
+ click.echo(result.summary_table())
675
+
676
+
405
677
  @cli.command()
406
678
  @click.option(
407
679
  '--keypair-path',