Skip to content
Back to search

kalshi-ai-trading-bot

The honest edge layer for Kalshi prediction markets - an agent-native toolkit (CLI, MCP server, Claude skill) that measures whether you actually beat the book instead of claiming it.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ryanfrigo--kalshi-ai-trading-bot/badge.svg)](/listings/ryanfrigo--kalshi-ai-trading-bot)

HTML

<a href="/listings/ryanfrigo--kalshi-ai-trading-bot"><img src="/api/listings/ryanfrigo--kalshi-ai-trading-bot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 1. Clone and set up
git clone https://github.com/ryanfrigo/kalshi-ai-trading-bot.git
cd kalshi-ai-trading-bot
python setup_env.py    # creates .venv, installs deps

# 2. Add your API keys
cp env.template .env
# then open .env and fill in KALSHI_API_KEY and OPENROUTER_API_KEY

# 3. Verify connectivity
python cli.py health

# 4. Run an example strategy in paper mode
python cli.py run --paper                  # AI directional (LLM-driven)
python cli.py run --safe-compounder        # Edge-based NO-side, no LLM

Open the dashboard in another terminal:

python cli.py dashboard

> **Need API keys?** > - Kalshi key + private key → [kalshi.com/account/settings](https://kalshi.com/account/settings) > - OpenRouter key → [openrouter.ai](https://openrouter.ai/)

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 622 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Kalshi AI Trading Bot
  2. <div align="center">
  3. [![CI](https://github.com/ryanfrigo/kalshi-ai-trading-bot/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanfrigo/kalshi-ai-trading-bot/actions/workflows/ci.yml)
  4. [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  6. [![GitHub Stars](https://img.shields.io/github/stars/ryanfrigo/kalshi-ai-trading-bot?style=flat&color=yellow)](https://github.com/ryanfrigo/kalshi-ai-trading-bot/stargazers)
  7. [![GitHub Forks](https://img.shields.io/github/forks/ryanfrigo/kalshi-ai-trading-bot?style=flat&color=blue)](https://github.com/ryanfrigo/kalshi-ai-trading-bot/network)
  8. [![GitHub Issues](https://img.shields.io/github/issues/ryanfrigo/kalshi-ai-trading-bot)](https://github.com/ryanfrigo/kalshi-ai-trading-bot/issues)
  9. **The honest edge layer for prediction-market trading.**
  10. An agent-native toolkit for [Kalshi](https://kalshi.com) whose flagship isn't "an LLM that picks trades" — it's a rigorous, settlement-grounded way to **measure whether you actually have edge against the sharp Kalshi book.** Many bots in this niche publish returns without settlement-level evidence. This one does the opposite: it ships the tooling to test your own track record honestly, and it refuses to assert edge on thin or leaky data.
  11. Under the hood: a signed Kalshi API client, market-data ingestion, position tracking, SQLite telemetry, a Streamlit dashboard, a pluggable LLM client (any model on OpenRouter), atomic agent CLI tools, a Claude skill, and a first-mover MCP server. Example strategies ship as starting points — fork them, replace them, or write your own.
  12. [**Live Track Record**](docs/TRACK_RECORD.md) · [**Jev on Kalshi: measured**](docs/JEV.md) · [Quick Start](#quick-start) · [Prove Your Edge](#prove-your-edge-the-headline) · [Agent-Native Surface](#agent-native-surface) · [What's Included](#whats-included) · [Example Strategies](#example-strategies) · [Configuration](#configuration) · [Contributing](CONTRIBUTING.md)
  13. </div>
  14. ---
  15. > **Read this before running with real money.** Nothing here is guaranteed to make money, and this README makes no such promise. The whole point of the toolkit is to let you *measure* whether you have edge — not to hand you one. The liquid Kalshi book is usually the sharp price; real edge is rare and must be proven on settled reality, out-of-sample. The example strategies lose money on certain markets. This is a toolkit you fork, not a turnkey bot. Read the code, understand it, tune it for the markets you care about. The authors are not responsible for losses you incur using this software.
  16. ---
  17. ## Prove Your Edge (the headline)
  18. The thing this repo does that the rest of the niche doesn't: it lets you **prove — or disprove — that you beat the price the sharp book charged you.**
  19. There is no offline backtest command yet. `cli backtest` is a placeholder. The only committed measured result is the live track record in [docs/TRACK_RECORD.md](docs/TRACK_RECORD.md), and it comes from one account, not a backtest.
  20. ```bash
  21. python cli.py edge # the honest verdict
  22. ```
  23. `cli edge` pulls Kalshi's authoritative settlements, reconciles them against your decision journal *in memory* (it writes nothing), and scores your settled trades:
  24. | Metric | What it answers |
  25. |---|---|
  26. | **Brier score** | When you say 70%, are you calibrated? (proper scoring rule; lower = better) |
  27. | **Log-loss** | Same, but punishes confident wrongness harder |
  28. | **Edge vs. book** | The price you paid for your side *is* the book's implied probability for it. `edge_vs_book` = realized win-rate − mean implied price. Positive = you beat the book; ~0 = the book was right |
  29. | **Forward-only guard** | Out-of-sample honesty: counts only trades where the event resolved strictly *after* you traded. Leakage and thin samples are quarantined, never silently counted |
  30. The verdict is **gated**: with fewer than 10 forward-settled trades, or on non-forward data, it **refuses to claim edge** — the niche's central failure is asserting skill from a handful of lucky settlements, and this harness will not do that. The measurement code (`src/agent/edge.py`) is pure and deterministic; all IO lives in the CLI.
  31. The honest answer is often "no edge yet, keep a track record." That is the feature, not a bug.
  32. **This is not hypothetical — it runs on a real account, and it has already ruled against us.** The
  33. most recent published verdict on the operator's live account (2026-10-02, n=55
  34. forward-settled trades; the page is regenerated by `cli report` and may be out of date):
  35. > **NO MEASURED EDGE** — won 58% vs. 60% implied by the book (edge −1.9 pts). Brier 0.2356 (n=43 trades with a recorded estimate).
  36. > The Edge Policy auto-derives from exactly this record — the losing
  37. > categories are blocked on the next `cli trade`, and the overconfidence haircuts shrink the
  38. > estimates that produced them.
  39. This verdict is from my live account. I haven't committed the settlements, so you can't re-run this exact number; `cli policy --demo` runs the same code on a demo fixture.
  40. We ship the "no edge" verdict on our own account because a measurement harness that only ever
  41. prints flattering numbers is marketing, not measurement. See [docs/TRACK_RECORD.md](docs/TRACK_RECORD.md)
  42. — losses included.
  43. ---
  44. ## The Self-Improvement Loop
  45. Measuring edge is half the story. The other half is **letting what you measured constrain what you trade next** — automatically. Most bots decide and measure in separate silos; here the two are wired together.
  46. ```bash
  47. python cli.py policy # the gate your OWN settled record earns
  48. python cli.py improve # settle → learn → re-derive the gate → persist
  49. ```
  50. `cli improve` pulls Kalshi's authoritative settlements, reconciles them into your decision journal, and re-derives a machine-readable **Edge Policy** from your whole settled record:
  51. | Rule | Derived from | Effect on the next trade |
  52. |---|---|---|
  53. | **Block** | a category/method with ≥5 settled trades and negative realized P&L | `cli trade` **refuses** it (override with `--override-policy`, and the override is recorded) |
  54. | **Side warning** | a net-negative *side* | advisory only — a losing side never disables your whole strategy, because losses usually concentrate in a few categories, not a side |
  55. | **Haircut** | an `est_prob` band where you're ≥10pp overconfident | shrinks the *journaled* estimate to your calibrated win-rate, so future calibration self-corrects |
  56. The same honesty rule as `edge` applies everywhere: **a group with fewer than 5 settled trades earns no opinion** — the policy never invents a constraint the data can't support. It re-derives from the whole settled record each time: a group is blocked while its record is net-negative over at least 5 trades, and the block lifts if later settlements bring it back to break-even. `cli improve` prints what was added or removed.
  57. This is the loop, closed: **decide → trade → settle → measure → re-derive the policy → the policy gates the next `cli trade`.** Your outcomes feed forward. The policy is checked by `cli trade` and the MCP `trade` tool; the example strategies (`run`, `daily`) don't read it. Run it against a shipped example with `cli policy --demo` (no keys needed), then point it at your own record.
  58. > Not a backtest. A backtest needs a captured price/outcome corpus this repo doesn't ship yet (`cli backtest` explains why). The self-improvement loop needs no corpus — it learns from the settlements you already have.
  59. ---
  60. ## Quick Start
  61. ```bash
  62. # 1. Clone and set up
  63. git clone https://github.com/ryanfrigo/kalshi-ai-trading-bot.git
  64. cd kalshi-ai-trading-bot
  65. python setup_env.py # creates .venv, installs deps (asks y/n on stdin)
  66. # 2. Add your API keys
  67. cp env.template .env
  68. # then open .env and fill in KALSHI_API_KEY and OPENROUTER_API_KEY
  69. # 3. Verify connectivity
  70. python cli.py health
  71. # 4. Run an example strategy in paper mode
  72. python cli.py run --paper # AI directional (LLM-driven)
  73. python cli.py run --safe-compounder # Edge-based NO-side, no LLM
  74. ```
  75. Open the dashboard in another terminal (needs the `[dashboard]` extra: `pip install -e ".[dashboard]"`):
  76. ```bash
  77. python cli.py dashboard
  78. ```
  79. > **Need API keys?**
  80. > - Kalshi key + private key → [kalshi.com/account/settings](https://kalshi.com/account/settings)
  81. > - OpenRouter key → [openrouter.ai](https://openrouter.ai/)
  82. ---
  83. ## Data-Fed Families (priced from the resolution source)
  84. Some families resolve on a published number. For those, pricing means reading
  85. the source — and the repo ships the source-readers plus the forward-scoring
  86. loop that grades the model against the book:
  87. | Family | Source | Tools | Docs |
  88. |---|---|---|---|
  89. | AAA gas/diesel daily + weekly/monthly ladders | AAA Fuel Gauge prints (national + 21 states) + wholesale futures | `scripts/aaa_data.py`, `scripts/aaa_futures.py`, `scripts/aaa_pricer.py price|path|score` | [docs/AAA.md](docs/AAA.md) |
  90. | Monthly GPU compute price (KXA100MS...) | Ornn OCPI public daily index | `scripts/ornn_data.py fetch|strike|ladder` | [docs/ORNN.md](docs/ORNN.md) |
  91. | OpenRouter weekly author text-share (KX*SHARE) | the rankings "Market Share" chart (Mon 10am ET) | `scripts/orshare_data.py snapshot|day|week` | notes kept locally, not in the repo |
  92. | Truth Social weekly post buckets | Roll Call count (Mon 10am ET) | `scripts/ts_posts.py` | notes kept locally, not in the repo |
  93. | Any priced snapshot | realized outcomes | `scripts/jev_score.py`, `scripts/aaa_pricer.py score` | `data/runtime/jev_scores.jsonl` |
  94. The discipline these encode: **every pricing event is snapshotted with the
  95. model's fair, the book's quote, and fee-aware edges — then scored against the
  96. realized value once it settles.** Standing verdicts per alert family live in
  97. `data/aaa/alerts/ADJUDICATIONS.md`. A scheduled morning job (4:05am PT) refreshes
  98. all sources, reprices every ladder, and drops gap alerts for the agent loop;
  99. it never places orders.
  100. ---
  101. ## Agent-Native Surface
  102. The toolkit is built to be driven by an agent (Claude, or anything else) through small, composable tools — each does one thing and reports honestly. You can call them yourself, wire them into a loop, or hand the keys to an MCP client.
  103. **Atomic CLI tools** (`cli.py`):
  104. | Tool | Kind | What it does |
  105. |---|---|---|
  106. | `brief` | read-only | One-shot situational awareness: governor verdict, equity, positions, resting orders (JSON) |
  107. | `verify` | no orders | The **adversarial-verify gate** before any live buy: research the catalyst → a SKEPTIC tries to refute the fade → a deterministic gate recomputes the edge off the live book and rules `BUY_NO`/`PASS`. Works with no API key via `--research-file`. It never places an order or writes the journal; it does log AI spend to the local DB. |
  108. | `trade` | mutating | Place ONE guarded, journaled order through the full risk stack. Dry-run unless `--live` |
  109. | `close` | mutating | Sell ONE held position at the current bid (allowed under a daily-loss or drawdown halt: reduce-only, up to the held size; blocked by a manual halt or a state error). Dry-run unless `--live` |
  110. | `fills` | writes | Reconcile the journal against actual order fills — void records whose orders never filled, shrink partial fills — so calibration and the policy only learn from trades that executed. `--dry` for read-only |
  111. | `settle` | read-only* | Pull Kalshi's authoritative settlements; report realized win-rate / P&L (*writes the local settlements log) |
  112. | `learnings` | writes | Reconcile outcomes → calibration + per-category/side edge → append genuinely new candidate learnings. `--dry` for read-only |
  113. | `edge` | read-only | **The headline** — Brier / log-loss / edge-vs-book + the gated, forward-only verdict |
  114. | `report` | writes | Render the public **[Live Track Record](docs/TRACK_RECORD.md)** from the persisted settlements / journal / policy — losses included. Offline-capable |
  115. | `policy` | read-only | The data-driven **Edge Policy** your settled record earns: block losing categories, warn on losing sides, haircut overconfident bands. `--demo` runs on a shipped fixture |
  116. | `improve` | writes | **The self-improvement loop** — settle → reconcile → re-derive the policy → diff what changed → persist the gate. `--dry` for read-only |
  117. | `scores` · `history` · `status` | read-only | Category scores, closed-trade history, live balance/positions |
  118. Plus `run` / `daily` (strategy loops), `health` (connectivity check), and `scripts/capture_corpus.py` (daily price-snapshot capture that feeds a future backtest). `trade` and `close` both default to a dry-run preview and route through the risk governor + per-position cap — the same guard stack everything else uses.
  119. **The `kalshi-trade` skill** (`.claude/skills/kalshi-trade/SKILL.md`) encodes the disciplined process for managing the live account on each loop tick: assess state, surface edge, research true probabilities, decide under strict risk rules, execute guarded orders, journal the prediction, and measure realized edge.
  120. **MCP server** (`src/mcp_server.py`) — a first-mover [Model Context Protocol](https://modelcontextprotocol.io) server. No official Kalshi MCP exists; this thin wrapper exposes the same governor-gated tools (`brief`, `settle`, `learnings`, `edge`, `policy`, `scores`, `history`, `hunt`, `status`, plus the mutating `trade`/`close`) so you can **drive the toolkit from Claude Desktop or Claude Code — running on your own keys, your key never leaving your machine.** Read-only by default; the two mutating tools require an explicit `confirm=true`. See **[docs/MCP.md](docs/MCP.md)**.
  121. > `hunt` (a broad live-book scan for edge candidates, backed by `scripts/hunt_candidates.py`) is surfaced through the MCP server today. Its output is research material to investigate — not a buy list.
  122. ---
  123. ## What's Included
  124. This repo gives you the building blocks. The example strategies use them — your own strategies can too.
  125. | Component | What it does | Where it lives |
  126. |---|---|---|
  127. | **Edge harness** | Brier / log-loss / edge-vs-book + forward-only honesty verdict (pure, deterministic) | `src/agent/edge.py` |
  128. | **Edge Policy** | Turns the settled record into a pre-trade gate for `cli trade` and MCP `trade` (block losing categories, warn on losing sides, haircut overconfident bands) | `src/agent/policy.py` |
  129. | **Learnings system** | Joins settlements back into the decision journal; calibration table + realized edge → evolving learnings | `src/agent/learnings.py` |
  130. | **Risk governor** | Daily-loss + drawdown kill switch + manual halt, authoritative for every live order; under a daily-loss/drawdown halt only a held-size reduce-only sell passes, as IOC + `reduce_only` (it will not rest) | `src/risk/risk_governor.py` |
  131. | **Kalshi client** | Authenticated REST + WebSocket client (RSA signing, retries, rate-limit handling) | `src/clients/kalshi_client.py` |
  132. | **Market ingestion** | Pulls the full tradeable universe via the Events API, persists to SQLite | `src/jobs/ingest.py` |
  133. | **Position tracking** | Stop-loss, take-profit, time-based, and resolution-based exits with real Kalshi sell orders | `src/jobs/track.py` |
  134. | **LLM client** | Single OpenRouter API key, swap models with one config line, fallback chain on errors, daily-cost tracker | `src/clients/openrouter_client.py` |
  135. | **SQLite telemetry** | Every trade, AI decision, and cost metric logged locally | `src/utils/database.py` |
  136. | **MCP server** | First-mover MCP layer over the governor-gated tools | `src/mcp_server.py` |
  137. | **Streamlit dashboard** | Real-time portfolio, positions, P&L, decision logs | `scripts/trading_dashboard.py` (`python cli.py dashboard`) |
  138. | **Risk helpers** | Quarter-Kelly sizing, stop-loss math, and the drawdown circuit breaker | `src/risk/`, `src/strategies/` |
  139. The governor's state file, the `TRADING_HALTED` kill-switch flag and `governor_audit.jsonl` live in `data/runtime/` under the repo root; set `KALSHI_RUNTIME_DIR` (an absolute path; `~` is expanded, a relative path is rejected) to move all three to another directory (wheel installs should set it, since there is no repo root to anchor to).
  140. ---
  141. ## Example Strategies
  142. Three strategies ship with the repo. **None of them is "the right answer."** They exist so you can run something end-to-end and see how the pieces connect, then fork the one closest to what you want to build.
  143. ### 1. AI Directional — `python cli.py run`
  144. The default. For each candidate market, it calls a single LLM via OpenRouter (with a fallback chain on errors) to score directional confidence, then sizes positions with fractional Kelly. The risk governor and a per-position cap apply to every order; there are no category or sector limits.
  145. > **It is not a "5-model ensemble"** despite earlier README claims. One model is called per decision. The fallback chain only triggers on errors. The `experimental/agents/` quarantine contains scaffolding for real parallel multi-model voting, but it's not wired into the live trading path. If you want a real ensemble, fork `src/jobs/decide.py` and build it.
  146. ```bash
  147. python cli.py run --paper # paper trading
  148. python cli.py run --live # live trading (real money)
  149. ```
  150. Defaults: 20% max drawdown, 45% min confidence (legacy path), 10% max position size, quarter-Kelly. `cli.py run` tightens these to 15% max drawdown and 3% max position. There is no sector-concentration limit. All configurable in `src/config/settings.py`.
  151. ### 2. Safe Compounder — `python cli.py run --safe-compounder`
  152. Pure edge-based math, no LLM required. Scans active markets with a YES last price of 20¢ or less, checks the orderbooks of up to 200 of them, and buys NO only when its estimate beats the ask by more than 3¢. It places resting maker orders one cent below the ask.
  153. ```bash
  154. python cli.py run --safe-compounder # dry-run preview
  155. python cli.py run --safe-compounder --live # live execution
  156. # Run continuously instead of one cycle and exit:
  157. python cli.py run --safe-compounder --live --loop --interval 300
  158. ```
  159. Rules: NO side only, YES last ≤ 20¢, NO ask > 80¢, edge > 3¢, max 10%/position, skips sports/entertainment/"mention" markets.
  160. ### 3. Beast Mode — `python cli.py run --beast`
  161. Looser settings. The risk governor still applies. Available for comparison and experimentation — **not recommended for live trading**. Running this with real money historically led to significant losses on this repo.
  162. ---
  163. ## Stopping Cleanly
  164. Ctrl-C sends SIGINT and triggers graceful shutdown — the bot finishes the in-flight cycle, logs, and exits. Open positions remain on Kalshi until they resolve.
  165. If you want to **liquidate everything** before stepping away:
  166. ```bash
  167. # 1. Stop the bot
  168. Ctrl-C
  169. # 2. Place limit sells at the current best bid for every open position
  170. python cli.py close-all # dry-run preview
  171. python cli.py close-all --live # actually send orders
  172. # 3. Verify
  173. python cli.py status
  174. ```
  175. `close-all` queries Kalshi directly (not the local DB), so it works even when local state is stale. Sells are limit-priced, so they may rest unfilled on thin books — check Kalshi or `cli.py status` after a minute.
  176. ---
  177. ## Installation
  178. ### Prerequisites
  179. - Python 3.12 or later
  180. - A [Kalshi](https://kalshi.com) account with API access ([API docs](https://trading-api.readme.io/reference/getting-started))
  181. - An [OpenRouter](https://openrouter.ai/) API key (only needed for the AI directional strategy)
  182. ### Automated Setup
  183. ```bash
  184. git clone https://github.com/ryanfrigo/kalshi-ai-trading-bot.git
  185. cd kalshi-ai-trading-bot
  186. python setup_env.py
  187. ```
  188. Creates a virtual env, installs dependencies, and prints next steps. It asks y/n questions on stdin (create the venv? install missing dependencies?), so run it in an interactive terminal.
  189. ### Manual Setup
  190. ```bash
  191. git clone https://github.com/ryanfrigo/kalshi-ai-trading-bot.git
  192. cd kalshi-ai-trading-bot
  193. python -m venv .venv
  194. source .venv/bin/activate # macOS / Linux
  195. # .venv\Scripts\activate # Windows
  196. pip install -e .
  197. ```
  198. ### Configuration
  199. ```bash
  200. cp env.template .env
  201. # then edit .env with your keys
  202. ```
  203. | Variable | Description |
  204. |---|---|
  205. | `KALSHI_API_KEY` | Your Kalshi API key ID |
  206. | `OPENROUTER_API_KEY` | OpenRouter key (only for AI directional strategy) |
  207. Save your Kalshi private key as `kalshi_private_key.pem` in the project root, or set `KALSHI_PRIVATE_KEY_PATH` in `.env`. Download it from [Kalshi Settings → API](https://kalshi.com/account/settings). It's git-ignored.
  208. Verify everything is wired:
  209. ```bash
  210. python cli.py health
  211. ```
  212. ---
  213. ## Configuration
  214. All trading parameters live in `src/config/settings.py`. The most useful knobs:
  215. ```python
  216. # Position sizing
  217. max_position_size_pct = 10.0 # Max 10% of balance per position
  218. # max_positions is also in settings.py but nothing reads it; the enforced cap is 15 (position_limits.py)
  219. kelly_fraction = 0.25 # Quarter-Kelly (conservative)
  220. # Market filtering
  221. min_volume = 500 # Minimum contract volume
  222. max_time_to_expiry_days = 14 # How far out to trade
  223. min_confidence_to_trade = 0.45 # Legacy per-market path only (src/jobs/decide.py); the unified path hard-codes 0.60
  224. # LLM (OpenRouter)
  225. primary_model = "anthropic/claude-sonnet-4.5"
  226. ai_temperature = 0 # Deterministic
  227. ai_max_tokens = 8000
  228. # Risk management
  229. max_daily_loss_pct = 5.0 # Daily loss circuit breaker
  230. max_drawdown = 0.20 # Portfolio drawdown halt
  231. daily_ai_cost_limit = 10.0 # Max daily LLM spend in USD
  232. ```
  233. **Swapping models:** change `primary_model` to any slug from [openrouter.ai/models](https://openrouter.ai/models). The fallback chain in `src/clients/openrouter_client.py` controls what happens when the primary errors.
  234. **Controlling LLM spend:** the bot checks the daily limit before every API call and skips trading until the next calendar day once exhausted. Set `DAILY_AI_COST_LIMIT` in `.env` to override.
  235. ---
  236. ## Project Structure
  237. The repo is split into a **clean core** (the supported toolkit) and an **`experimental/` quarantine** (unwired scaffolding kept for reference, not part of the supported surface).
  238. ```
  239. kalshi-ai-trading-bot/
  240. ├── cli.py # Unified CLI: brief/trade/close/settle/learnings/edge + run/daily/status/...
  241. ├── beast_mode_bot.py # Example AI directional bot — main loop orchestration
  242. ├── setup_env.py # Bootstrap script (interactive env setup)
  243. ├── env.template # Environment variable template
  244. │
  245. ├── src/ # ── clean core ──
  246. │ ├── agent/ # Agent brain: edge.py (harness), learnings.py, journal, settle, toolbelt
  247. │ ├── mcp_server.py # First-mover MCP server over the governor-gated tools
  248. │ ├── risk/ # risk_governor.py — daily-loss + drawdown kill switch
  249. │ ├── clients/ # Kalshi, OpenRouter, WebSocket clients
  250. │ ├── config/ # Settings and trading parameters
  251. │ ├── strategies/ # Safe compounder, category scorer, portfolio enforcer, market making
  252. │ ├── jobs/ # ingest, decide, execute, track, evaluate
  253. │ └── utils/ # Database, logging, prompts
  254. │
  255. ├── experimental/ # ── quarantine: UNWIRED scaffolding, not supported ──
  256. │ ├── agents/ # Multi-agent debate runners (may become adversarial-verify roles)
  257. │ ├── clients/ # Dead/experimental clients
  258. │ └── strategies/ # Experimental strategies
  259. │
  260. ├── .claude/skills/ # kalshi-trade — the disciplined live-trading process
  261. ├── scripts/ # Diagnostic + utility scripts (incl. hunt_candidates.py)
  262. ├── docs/ # MCP.md and additional docs
  263. └── tests/ # Pytest suite
  264. ```
  265. ---
  266. ## Paper Trading
  267. Simulate trades without sending real orders. Every signal is logged to SQLite and a static HTML dashboard renders cumulative P&L after markets settle.
  268. ```bash
  269. python paper_trader.py # one scan
  270. python paper_trader.py --loop --interval 900 # continuous, every 15m
  271. python paper_trader.py --settle # update outcomes for resolved markets
  272. python paper_trader.py --dashboard # regenerate HTML
  273. python paper_trader.py --stats # print stats
  274. ```
  275. Output goes to `docs/paper_dashboard.html` (a blank template until you run it).
  276. ---
  277. ## Category Scoring (display only)
  278. The category scorer rates each Kalshi market category 0-100 from historical ROI, win rate, recent trend, and sample size. `cli.py scores` shows it. It does not gate orders today. The table below lists intended caps, which are not enforced.
  279. | Score | Intended max position | Status |
  280. |---|---|---|
  281. | 80–100 | 20% | STRONG |
  282. | 60–79 | 10% | GOOD |
  283. | 40–59 | 5% | WEAK |
  284. | 30–39 | 2% | POOR |
  285. | 0–29 | 0 | BLOCKED |
  286. ```bash
  287. python cli.py scores
  288. ```
  289. This is a reporting heuristic. Nothing in the order path reads it.
  290. ---
  291. ## Performance Tracking
  292. Every trade, AI decision, and cost metric is recorded to `trading_system.db` (local SQLite). Inspect via the dashboard or:
  293. ```bash
  294. python cli.py history # Last 50 trades
  295. python cli.py history --limit 100 # Last 100
  296. python cli.py status # Live balance + open positions from Kalshi
  297. ```
  298. ---
  299. ## Development
  300. ### Running Tests
  301. Install the dev extra first (`pip install -e ".[dev]"`); the MCP server needs `pip install -e ".[mcp]"`.
  302. ```bash
  303. pytest # safe suite (no credentials needed; never touches the live API)
  304. pytest -v # verbose
  305. pytest --cov=src # with coverage
  306. ```
  307. Tests marked `live` hit the real Kalshi API — some **place real orders** — and
  308. are skipped by default. To run them (against an account whose losses you accept):
  309. ```bash
  310. RUN_LIVE_TESTS=1 pytest -m live
  311. ```
  312. ### Code Quality
  313. ```bash
  314. black src/ tests/ cli.py beast_mode_bot.py
  315. isort src/ tests/ cli.py beast_mode_bot.py
  316. mypy src/
  317. ```
  318. ### Adding a New Strategy
  319. 1. Create a module under `src/strategies/`
  320. 2. Wire it into a CLI flag in `cli.py` (or invoke it directly)
  321. 3. Use the `KalshiClient` for orders/positions and `DatabaseManager` for state
  322. 4. Add tests under `tests/`
  323. ---
  324. ## Troubleshooting
  325. <details>
  326. <summary><strong>Health check fails with HTTP 401</strong></summary>
  327. A 401 from Kalshi almost always means one of three things:
  328. 1. `KALSHI_API_KEY` in `.env` doesn't match the API key ID shown in Kalshi
  329. 2. The private key file (`kalshi_private_key.pem`) is the wrong key for that API key, or its path is wrong
  330. 3. The key was created on Kalshi's demo environment but you're pointing at production (or vice versa)
  331. Re-download the key pair from Kalshi and verify both values point to the matching pair. The health check will print this hint when it detects a 401.
  332. </details>
  333. <details>
  334. <summary><strong>"Shutdown signal received" without pressing Ctrl-C</strong></summary>
  335. The bot now logs which signal arrived (SIGINT, SIGTERM, or SIGHUP). If you see SIGTERM or SIGHUP without sending it yourself, common causes:
  336. - Parent shell closed (run inside `tmux`, `screen`, or with `nohup`)
  337. - A cloud platform / systemd / launchd timeout
  338. - Another shell sent `kill <pid>`
  339. - An OOM killer warning before SIGKILL
  340. The bot did not kill itself — something external ended the process.
  341. </details>
  342. <details>
  343. <summary><strong>Bot ran for weeks but placed no positions</strong></summary>
  344. This is expected behavior, not a bug. The example strategies are conservative by design:
  345. - **AI Directional** requires confidence ≥ 45% on the legacy path (≥ 60% on the unified path) and passes the risk governor. On many days, no market qualifies.
  346. - **Safe Compounder** requires NO ask > 80¢ AND edge > 3¢. Most NO-side markets don't meet both.
  347. If you want more activity, lower the thresholds in `src/config/settings.py` (or the relevant strategy file) — but that means taking lower-edge bets. Or write your own strategy that targets the markets you actually have an edge on. This repo is a toolkit; the example thresholds are starting points.
  348. </details>
  349. <details>
  350. <summary><strong>"no such table: positions" error on fresh install</strong></summary>
  351. The DB file isn't committed; it's created at runtime. The bot auto-initializes on startup, but you can do it manually:
  352. ```bash
  353. python -m src.utils.database
  354. ```
  355. Use `-m` — running `python src/utils/database.py` directly fails with an import error.
  356. </details>
  357. <details>
  358. <summary><strong>AdGuard (macOS) blocks dependency downloads</strong></summary>
  359. If AdGuard is running as a system-level proxy, `pip install` may time out during setup. Disable AdGuard at the system level for the install, then re-enable it. AdGuard as a browser extension is fine.
  360. </details>
  361. <details>
  362. <summary><strong>Bot not placing live trades despite --live</strong></summary>
  363. ```bash
  364. grep -i "live trading\|paper trading\|LIVE ORDER" logs/trading_system.log | tail -20
  365. ```
  366. If you see "Paper trading mode" the flag isn't taking effect. Verify the API key has trading permissions in [Kalshi Settings](https://kalshi.com/account/settings).
  367. </details>
  368. <details>
  369. <summary><strong>Model not found / OpenRouter API errors</strong></summary>
  370. Model names on OpenRouter change. Update `primary_model` in `src/config/settings.py` with a current slug from [openrouter.ai/models](https://openrouter.ai/models).
  371. </details>
  372. <details>
  373. <summary><strong>Bot only seeing "KXMVE" tickers</strong></summary>
  374. The Kalshi `/markets` endpoint returns parlay tickers; real markets live under the Events API. The ingestion pipeline already uses Events with nested markets. If you see only `KXMVE*`, check API permissions and run `python cli.py health`.
  375. </details>
  376. <details>
  377. <summary><strong>Python 3.14 PyO3 compatibility error</strong></summary>
  378. ```bash
  379. export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1
  380. pip install -e .
  381. ```
  382. Or use Python 3.13:
  383. ```bash
  384. pyenv install 3.13.1 && pyenv local 3.13.1
  385. python -m venv .venv && source .venv/bin/activate
  386. pip install -e .
  387. ```
  388. </details>
  389. ---
  390. ## Lessons From Live Trading
  391. These are observations from running the example strategies with real money on Kalshi. They informed the defaults shipped here. They are **not** universal trading wisdom — they're notes from one set of experiments.
  392. **1. Category discipline mattered more than AI confidence.** The LLM could be 80% confident on a CPI trade and still be wrong. Market-implied probabilities on highly-watched economic releases are already efficient.
  393. **2. Kelly fraction matters enormously.** For example, at a 45% win rate, three-quarter Kelly compounds losses catastrophically. Quarter-Kelly is what the example strategies use.
  394. **3. A 50% drawdown limit isn't a limit.** The default is 20% with the circuit breaker enforced in the order path (15% under `cli.py run`), so it halts trades instead of just logging. The governor peak was re-baselined on 2026-09-25 after withdrawals and manual bets; see docs/TRACK_RECORD.md.
  395. **4. Concentration creates correlated losses.** When 90% of capital is in economic categories on a Fed day, everything moves together. There is no per-category cap in the code; size by hand.
  396. **5. More trades without edge is faster path to zero.** The default scan interval is 60 seconds, not 30, and trades are gated by confidence and the risk governor.
  397. Your edge is probably somewhere else. Use the toolkit to find it.
  398. ---
  399. ## Contributing
  400. Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
  401. ```bash
  402. # 1. Fork
  403. # 2. Create a feature branch
  404. git checkout -b feature/your-feature
  405. # 3. Make changes, add tests, run pytest and black
  406. # 4. Commit using conventional commits (feat:, fix:, refactor:)
  407. # 5. Open a PR
  408. ```
  409. ---
  410. ## Resources
  411. - [Kalshi Trading API](https://trading-api.readme.io/reference/getting-started)
  412. - [Kalshi API Authentication](https://trading-api.readme.io/reference/authentication)
  413. - [Kalshi Markets](https://kalshi.com/markets)
  414. - [OpenRouter Model Catalog](https://openrouter.ai/models)
  415. ---
  416. ## License
  417. MIT. See [LICENSE](LICENSE).
  418. ---
  419. <div align="center">
  420. **Found this useful?** ⭐ [Star the repo](https://github.com/ryanfrigo/kalshi-ai-trading-bot) so others can find it · 💬 [Ask or share in Discussions](https://github.com/ryanfrigo/kalshi-ai-trading-bot/discussions) · ❤️ [Sponsor the work](https://github.com/sponsors/ryanfrigo)
  421. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.