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.
Badge for your README
Markdown
[](/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
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.
- # Kalshi AI Trading Bot
- <div align="center">
- [](https://github.com/ryanfrigo/kalshi-ai-trading-bot/actions/workflows/ci.yml)
- [](https://www.python.org/downloads/)
- [](LICENSE)
- [](https://github.com/ryanfrigo/kalshi-ai-trading-bot/stargazers)
- [](https://github.com/ryanfrigo/kalshi-ai-trading-bot/network)
- [](https://github.com/ryanfrigo/kalshi-ai-trading-bot/issues)
- **The honest edge layer for prediction-market trading.**
- 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.
- 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.
- [**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)
- </div>
- ---
- > **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.
- ---
- ## Prove Your Edge (the headline)
- 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.**
- 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.
- ```bash
- python cli.py edge # the honest verdict
- ```
- `cli edge` pulls Kalshi's authoritative settlements, reconciles them against your decision journal *in memory* (it writes nothing), and scores your settled trades:
- | Metric | What it answers |
- |---|---|
- | **Brier score** | When you say 70%, are you calibrated? (proper scoring rule; lower = better) |
- | **Log-loss** | Same, but punishes confident wrongness harder |
- | **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 |
- | **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 |
- 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.
- The honest answer is often "no edge yet, keep a track record." That is the feature, not a bug.
- **This is not hypothetical — it runs on a real account, and it has already ruled against us.** The
- most recent published verdict on the operator's live account (2026-10-02, n=55
- forward-settled trades; the page is regenerated by `cli report` and may be out of date):
- > **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).
- > The Edge Policy auto-derives from exactly this record — the losing
- > categories are blocked on the next `cli trade`, and the overconfidence haircuts shrink the
- > estimates that produced them.
- 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.
- We ship the "no edge" verdict on our own account because a measurement harness that only ever
- prints flattering numbers is marketing, not measurement. See [docs/TRACK_RECORD.md](docs/TRACK_RECORD.md)
- — losses included.
- ---
- ## The Self-Improvement Loop
- 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.
- ```bash
- python cli.py policy # the gate your OWN settled record earns
- python cli.py improve # settle → learn → re-derive the gate → persist
- ```
- `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:
- | Rule | Derived from | Effect on the next trade |
- |---|---|---|
- | **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) |
- | **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 |
- | **Haircut** | an `est_prob` band where you're ≥10pp overconfident | shrinks the *journaled* estimate to your calibrated win-rate, so future calibration self-corrects |
- 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.
- 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.
- > 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.
- ---
- ## Quick Start
- ```bash
- # 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 (asks y/n on stdin)
- # 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 (needs the `[dashboard]` extra: `pip install -e ".[dashboard]"`):
- ```bash
- 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/)
- ---
- ## Data-Fed Families (priced from the resolution source)
- Some families resolve on a published number. For those, pricing means reading
- the source — and the repo ships the source-readers plus the forward-scoring
- loop that grades the model against the book:
- | Family | Source | Tools | Docs |
- |---|---|---|---|
- | 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) |
- | Monthly GPU compute price (KXA100MS...) | Ornn OCPI public daily index | `scripts/ornn_data.py fetch|strike|ladder` | [docs/ORNN.md](docs/ORNN.md) |
- | 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 |
- | Truth Social weekly post buckets | Roll Call count (Mon 10am ET) | `scripts/ts_posts.py` | notes kept locally, not in the repo |
- | Any priced snapshot | realized outcomes | `scripts/jev_score.py`, `scripts/aaa_pricer.py score` | `data/runtime/jev_scores.jsonl` |
- The discipline these encode: **every pricing event is snapshotted with the
- model's fair, the book's quote, and fee-aware edges — then scored against the
- realized value once it settles.** Standing verdicts per alert family live in
- `data/aaa/alerts/ADJUDICATIONS.md`. A scheduled morning job (4:05am PT) refreshes
- all sources, reprices every ladder, and drops gap alerts for the agent loop;
- it never places orders.
- ---
- ## Agent-Native Surface
- 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.
- **Atomic CLI tools** (`cli.py`):
- | Tool | Kind | What it does |
- |---|---|---|
- | `brief` | read-only | One-shot situational awareness: governor verdict, equity, positions, resting orders (JSON) |
- | `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. |
- | `trade` | mutating | Place ONE guarded, journaled order through the full risk stack. Dry-run unless `--live` |
- | `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` |
- | `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 |
- | `settle` | read-only* | Pull Kalshi's authoritative settlements; report realized win-rate / P&L (*writes the local settlements log) |
- | `learnings` | writes | Reconcile outcomes → calibration + per-category/side edge → append genuinely new candidate learnings. `--dry` for read-only |
- | `edge` | read-only | **The headline** — Brier / log-loss / edge-vs-book + the gated, forward-only verdict |
- | `report` | writes | Render the public **[Live Track Record](docs/TRACK_RECORD.md)** from the persisted settlements / journal / policy — losses included. Offline-capable |
- | `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 |
- | `improve` | writes | **The self-improvement loop** — settle → reconcile → re-derive the policy → diff what changed → persist the gate. `--dry` for read-only |
- | `scores` · `history` · `status` | read-only | Category scores, closed-trade history, live balance/positions |
- 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.
- **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.
- **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)**.
- > `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.
- ---
- ## What's Included
- This repo gives you the building blocks. The example strategies use them — your own strategies can too.
- | Component | What it does | Where it lives |
- |---|---|---|
- | **Edge harness** | Brier / log-loss / edge-vs-book + forward-only honesty verdict (pure, deterministic) | `src/agent/edge.py` |
- | **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` |
- | **Learnings system** | Joins settlements back into the decision journal; calibration table + realized edge → evolving learnings | `src/agent/learnings.py` |
- | **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` |
- | **Kalshi client** | Authenticated REST + WebSocket client (RSA signing, retries, rate-limit handling) | `src/clients/kalshi_client.py` |
- | **Market ingestion** | Pulls the full tradeable universe via the Events API, persists to SQLite | `src/jobs/ingest.py` |
- | **Position tracking** | Stop-loss, take-profit, time-based, and resolution-based exits with real Kalshi sell orders | `src/jobs/track.py` |
- | **LLM client** | Single OpenRouter API key, swap models with one config line, fallback chain on errors, daily-cost tracker | `src/clients/openrouter_client.py` |
- | **SQLite telemetry** | Every trade, AI decision, and cost metric logged locally | `src/utils/database.py` |
- | **MCP server** | First-mover MCP layer over the governor-gated tools | `src/mcp_server.py` |
- | **Streamlit dashboard** | Real-time portfolio, positions, P&L, decision logs | `scripts/trading_dashboard.py` (`python cli.py dashboard`) |
- | **Risk helpers** | Quarter-Kelly sizing, stop-loss math, and the drawdown circuit breaker | `src/risk/`, `src/strategies/` |
- 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).
- ---
- ## Example Strategies
- 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.
- ### 1. AI Directional — `python cli.py run`
- 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.
- > **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.
- ```bash
- python cli.py run --paper # paper trading
- python cli.py run --live # live trading (real money)
- ```
- 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`.
- ### 2. Safe Compounder — `python cli.py run --safe-compounder`
- 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.
- ```bash
- python cli.py run --safe-compounder # dry-run preview
- python cli.py run --safe-compounder --live # live execution
- # Run continuously instead of one cycle and exit:
- python cli.py run --safe-compounder --live --loop --interval 300
- ```
- Rules: NO side only, YES last ≤ 20¢, NO ask > 80¢, edge > 3¢, max 10%/position, skips sports/entertainment/"mention" markets.
- ### 3. Beast Mode — `python cli.py run --beast`
- 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.
- ---
- ## Stopping Cleanly
- 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.
- If you want to **liquidate everything** before stepping away:
- ```bash
- # 1. Stop the bot
- Ctrl-C
- # 2. Place limit sells at the current best bid for every open position
- python cli.py close-all # dry-run preview
- python cli.py close-all --live # actually send orders
- # 3. Verify
- python cli.py status
- ```
- `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.
- ---
- ## Installation
- ### Prerequisites
- - Python 3.12 or later
- - A [Kalshi](https://kalshi.com) account with API access ([API docs](https://trading-api.readme.io/reference/getting-started))
- - An [OpenRouter](https://openrouter.ai/) API key (only needed for the AI directional strategy)
- ### Automated Setup
- ```bash
- git clone https://github.com/ryanfrigo/kalshi-ai-trading-bot.git
- cd kalshi-ai-trading-bot
- python setup_env.py
- ```
- 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.
- ### Manual Setup
- ```bash
- git clone https://github.com/ryanfrigo/kalshi-ai-trading-bot.git
- cd kalshi-ai-trading-bot
- python -m venv .venv
- source .venv/bin/activate # macOS / Linux
- # .venv\Scripts\activate # Windows
- pip install -e .
- ```
- ### Configuration
- ```bash
- cp env.template .env
- # then edit .env with your keys
- ```
- | Variable | Description |
- |---|---|
- | `KALSHI_API_KEY` | Your Kalshi API key ID |
- | `OPENROUTER_API_KEY` | OpenRouter key (only for AI directional strategy) |
- 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.
- Verify everything is wired:
- ```bash
- python cli.py health
- ```
- ---
- ## Configuration
- All trading parameters live in `src/config/settings.py`. The most useful knobs:
- ```python
- # Position sizing
- max_position_size_pct = 10.0 # Max 10% of balance per position
- # max_positions is also in settings.py but nothing reads it; the enforced cap is 15 (position_limits.py)
- kelly_fraction = 0.25 # Quarter-Kelly (conservative)
- # Market filtering
- min_volume = 500 # Minimum contract volume
- max_time_to_expiry_days = 14 # How far out to trade
- min_confidence_to_trade = 0.45 # Legacy per-market path only (src/jobs/decide.py); the unified path hard-codes 0.60
- # LLM (OpenRouter)
- primary_model = "anthropic/claude-sonnet-4.5"
- ai_temperature = 0 # Deterministic
- ai_max_tokens = 8000
- # Risk management
- max_daily_loss_pct = 5.0 # Daily loss circuit breaker
- max_drawdown = 0.20 # Portfolio drawdown halt
- daily_ai_cost_limit = 10.0 # Max daily LLM spend in USD
- ```
- **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.
- **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.
- ---
- ## Project Structure
- 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).
- ```
- kalshi-ai-trading-bot/
- ├── cli.py # Unified CLI: brief/trade/close/settle/learnings/edge + run/daily/status/...
- ├── beast_mode_bot.py # Example AI directional bot — main loop orchestration
- ├── setup_env.py # Bootstrap script (interactive env setup)
- ├── env.template # Environment variable template
- │
- ├── src/ # ── clean core ──
- │ ├── agent/ # Agent brain: edge.py (harness), learnings.py, journal, settle, toolbelt
- │ ├── mcp_server.py # First-mover MCP server over the governor-gated tools
- │ ├── risk/ # risk_governor.py — daily-loss + drawdown kill switch
- │ ├── clients/ # Kalshi, OpenRouter, WebSocket clients
- │ ├── config/ # Settings and trading parameters
- │ ├── strategies/ # Safe compounder, category scorer, portfolio enforcer, market making
- │ ├── jobs/ # ingest, decide, execute, track, evaluate
- │ └── utils/ # Database, logging, prompts
- │
- ├── experimental/ # ── quarantine: UNWIRED scaffolding, not supported ──
- │ ├── agents/ # Multi-agent debate runners (may become adversarial-verify roles)
- │ ├── clients/ # Dead/experimental clients
- │ └── strategies/ # Experimental strategies
- │
- ├── .claude/skills/ # kalshi-trade — the disciplined live-trading process
- ├── scripts/ # Diagnostic + utility scripts (incl. hunt_candidates.py)
- ├── docs/ # MCP.md and additional docs
- └── tests/ # Pytest suite
- ```
- ---
- ## Paper Trading
- Simulate trades without sending real orders. Every signal is logged to SQLite and a static HTML dashboard renders cumulative P&L after markets settle.
- ```bash
- python paper_trader.py # one scan
- python paper_trader.py --loop --interval 900 # continuous, every 15m
- python paper_trader.py --settle # update outcomes for resolved markets
- python paper_trader.py --dashboard # regenerate HTML
- python paper_trader.py --stats # print stats
- ```
- Output goes to `docs/paper_dashboard.html` (a blank template until you run it).
- ---
- ## Category Scoring (display only)
- 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.
- | Score | Intended max position | Status |
- |---|---|---|
- | 80–100 | 20% | STRONG |
- | 60–79 | 10% | GOOD |
- | 40–59 | 5% | WEAK |
- | 30–39 | 2% | POOR |
- | 0–29 | 0 | BLOCKED |
- ```bash
- python cli.py scores
- ```
- This is a reporting heuristic. Nothing in the order path reads it.
- ---
- ## Performance Tracking
- Every trade, AI decision, and cost metric is recorded to `trading_system.db` (local SQLite). Inspect via the dashboard or:
- ```bash
- python cli.py history # Last 50 trades
- python cli.py history --limit 100 # Last 100
- python cli.py status # Live balance + open positions from Kalshi
- ```
- ---
- ## Development
- ### Running Tests
- Install the dev extra first (`pip install -e ".[dev]"`); the MCP server needs `pip install -e ".[mcp]"`.
- ```bash
- pytest # safe suite (no credentials needed; never touches the live API)
- pytest -v # verbose
- pytest --cov=src # with coverage
- ```
- Tests marked `live` hit the real Kalshi API — some **place real orders** — and
- are skipped by default. To run them (against an account whose losses you accept):
- ```bash
- RUN_LIVE_TESTS=1 pytest -m live
- ```
- ### Code Quality
- ```bash
- black src/ tests/ cli.py beast_mode_bot.py
- isort src/ tests/ cli.py beast_mode_bot.py
- mypy src/
- ```
- ### Adding a New Strategy
- 1. Create a module under `src/strategies/`
- 2. Wire it into a CLI flag in `cli.py` (or invoke it directly)
- 3. Use the `KalshiClient` for orders/positions and `DatabaseManager` for state
- 4. Add tests under `tests/`
- ---
- ## Troubleshooting
- <details>
- <summary><strong>Health check fails with HTTP 401</strong></summary>
- A 401 from Kalshi almost always means one of three things:
- 1. `KALSHI_API_KEY` in `.env` doesn't match the API key ID shown in Kalshi
- 2. The private key file (`kalshi_private_key.pem`) is the wrong key for that API key, or its path is wrong
- 3. The key was created on Kalshi's demo environment but you're pointing at production (or vice versa)
- 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.
- </details>
- <details>
- <summary><strong>"Shutdown signal received" without pressing Ctrl-C</strong></summary>
- The bot now logs which signal arrived (SIGINT, SIGTERM, or SIGHUP). If you see SIGTERM or SIGHUP without sending it yourself, common causes:
- - Parent shell closed (run inside `tmux`, `screen`, or with `nohup`)
- - A cloud platform / systemd / launchd timeout
- - Another shell sent `kill <pid>`
- - An OOM killer warning before SIGKILL
- The bot did not kill itself — something external ended the process.
- </details>
- <details>
- <summary><strong>Bot ran for weeks but placed no positions</strong></summary>
- This is expected behavior, not a bug. The example strategies are conservative by design:
- - **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.
- - **Safe Compounder** requires NO ask > 80¢ AND edge > 3¢. Most NO-side markets don't meet both.
- 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.
- </details>
- <details>
- <summary><strong>"no such table: positions" error on fresh install</strong></summary>
- The DB file isn't committed; it's created at runtime. The bot auto-initializes on startup, but you can do it manually:
- ```bash
- python -m src.utils.database
- ```
- Use `-m` — running `python src/utils/database.py` directly fails with an import error.
- </details>
- <details>
- <summary><strong>AdGuard (macOS) blocks dependency downloads</strong></summary>
- 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.
- </details>
- <details>
- <summary><strong>Bot not placing live trades despite --live</strong></summary>
- ```bash
- grep -i "live trading\|paper trading\|LIVE ORDER" logs/trading_system.log | tail -20
- ```
- 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).
- </details>
- <details>
- <summary><strong>Model not found / OpenRouter API errors</strong></summary>
- 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).
- </details>
- <details>
- <summary><strong>Bot only seeing "KXMVE" tickers</strong></summary>
- 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`.
- </details>
- <details>
- <summary><strong>Python 3.14 PyO3 compatibility error</strong></summary>
- ```bash
- export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1
- pip install -e .
- ```
- Or use Python 3.13:
- ```bash
- pyenv install 3.13.1 && pyenv local 3.13.1
- python -m venv .venv && source .venv/bin/activate
- pip install -e .
- ```
- </details>
- ---
- ## Lessons From Live Trading
- 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.
- **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.
- **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.
- **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.
- **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.
- **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.
- Your edge is probably somewhere else. Use the toolkit to find it.
- ---
- ## Contributing
- Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
- ```bash
- # 1. Fork
- # 2. Create a feature branch
- git checkout -b feature/your-feature
- # 3. Make changes, add tests, run pytest and black
- # 4. Commit using conventional commits (feat:, fix:, refactor:)
- # 5. Open a PR
- ```
- ---
- ## Resources
- - [Kalshi Trading API](https://trading-api.readme.io/reference/getting-started)
- - [Kalshi API Authentication](https://trading-api.readme.io/reference/authentication)
- - [Kalshi Markets](https://kalshi.com/markets)
- - [OpenRouter Model Catalog](https://openrouter.ai/models)
- ---
- ## License
- MIT. See [LICENSE](LICENSE).
- ---
- <div align="center">
- **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)
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.