A toolkit for building automated trading strategies on Kalshi prediction markets.
Signed Kalshi API client, market-data ingestion, position tracking, SQLite telemetry, a Streamlit dashboard, and a pluggable LLM client (any model on OpenRouter). Three example strategies ship with the repo as starting points — fork them, replace them, or write your own from scratch.
Quick Start · What's Included · Example Strategies · Configuration · Contributing · Kalshi API Docs
Read this before running with real money. No strategy in this repo is guaranteed to make money. The examples lose money on certain markets. Trading prediction markets is hard, the edges are small, and what worked last quarter may not work this quarter. This is a toolkit, not a turnkey bot. Read the code, understand what it does, and tune it for the markets you care about. The authors are not responsible for losses you incur using this software.
# 1. Clone and set up
git clone https://github.com/ryanfrigo/kalshi-ai-trading-bot.git
cd kalshi-ai-trading-bot
python setup.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 LLMOpen the dashboard in another terminal:
python cli.py dashboardNeed API keys?
- Kalshi key + private key → kalshi.com/account/settings
- OpenRouter key → openrouter.ai
This repo gives you the building blocks. The example strategies use them — your own strategies can too.
| Component | What it does | Where it lives |
|---|---|---|
| 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, persistent daily-cost tracker | src/clients/openrouter_client.py, src/clients/xai_client.py |
| SQLite telemetry | Every trade, AI decision, and cost metric logged locally | src/utils/database.py |
| Streamlit dashboard | Real-time portfolio, positions, P&L, decision logs | beast_mode_dashboard.py |
| Paper trading | Log signals against settled markets without sending orders | paper_trader.py |
| CLI | run, dashboard, status, health, scores, history, close-all |
cli.py |
| Risk helpers | Kelly sizing, stop-loss math, drawdown circuit breaker | src/utils/, src/strategies/ |
The repo also ships scaffolding for things that aren't fully wired — multi-agent debate runners in src/agents/, sentiment analyzer in src/data/, etc. Treat them as starting points if you want to extend them.
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.
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 and applies category/sector guardrails.
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 agents/ directory 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.pyand build it.
python cli.py run --paper # paper trading
python cli.py run --live # live trading (real money)Defaults: 15% max drawdown, 45% min confidence, 3% max position size, 30% max sector concentration, quarter-Kelly. All configurable in src/config/settings.py.
Pure edge-based math, no LLM required. Scans every active Kalshi market for NO-side asks above a price threshold with a positive expected-value edge, then places resting maker orders one cent below the ask.
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 300Rules: NO side only, YES last ≤ 20¢, NO ask > 80¢, edge > 5¢, max 10%/position, skips sports/entertainment/"mention" markets.
Aggressive settings with no category guardrails. Available for comparison and experimentation — not recommended for live trading. Running this with real money historically led to significant losses on this repo.
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:
# 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 statusclose-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.
- Python 3.12 or later
- A Kalshi account with API access (API docs)
- An OpenRouter API key (only needed for the AI directional strategy)
git clone https://github.com/ryanfrigo/kalshi-ai-trading-bot.git
cd kalshi-ai-trading-bot
python setup.pyCreates a virtual env, installs dependencies, and prints next steps.
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 -r requirements.txtcp 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) |
Place your Kalshi private key as kalshi_private_key (no extension) in the project root. Download it from Kalshi Settings → API. It's git-ignored.
Verify everything is wired:
python cli.py healthAll trading parameters live in src/config/settings.py. The most useful knobs:
# Position sizing
max_position_size_pct = 3.0 # Max 3% of balance per position
max_positions = 10 # Max concurrent positions
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 # Minimum AI confidence to enter
# LLM (OpenRouter)
primary_model = "anthropic/claude-sonnet-4.5"
ai_temperature = 0 # Deterministic
ai_max_tokens = 8000
# Risk management
max_daily_loss_pct = 10.0 # Daily loss circuit breaker
max_drawdown = 0.15 # Portfolio drawdown halt
daily_ai_cost_limit = 10.0 # Max daily LLM spend in USDSwapping models: change primary_model to any slug from 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.
kalshi-ai-trading-bot/
├── beast_mode_bot.py # Example AI directional bot — main loop orchestration
├── cli.py # Unified CLI: run, dashboard, status, health, close-all, scores, history
├── paper_trader.py # Paper-trading signal logger + static dashboard
├── setup.py # Bootstrap script
├── env.template # Environment variable template
│
├── src/
│ ├── agents/ # UNWIRED scaffolding for multi-agent debate (fork to use)
│ ├── clients/ # Kalshi, OpenRouter, WebSocket clients
│ ├── config/ # Settings and trading parameters
│ ├── data/ # News + sentiment helpers (optional)
│ ├── events/ # Async event bus
│ ├── jobs/ # ingest, decide, execute, track, evaluate
│ ├── strategies/ # Safe compounder, category scorer, portfolio enforcer
│ └── utils/ # Database, logging, prompts, risk helpers
│
├── scripts/ # Diagnostic and utility scripts
├── docs/ # Additional docs + paper-trading dashboard HTML
└── tests/ # Pytest suite
Simulate trades without sending real orders. Every signal is logged to SQLite and a static HTML dashboard renders cumulative P&L after markets settle.
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 statsOutput goes to docs/paper_dashboard.html.
The category scorer evaluates each Kalshi market category on a 0-100 scale based on historical ROI, win rate, recent trend, and sample size. Allocation per category is gated by score.
| Score | Max Position | Status |
|---|---|---|
| 80–100 | 20% | STRONG |
| 60–79 | 10% | GOOD |
| 40–59 | 5% | WEAK |
| 20–39 | 2% | POOR |
| 0–19 | 0 | BLOCKED |
python cli.py scoresThis is one heuristic for category-level risk control. If it doesn't fit your strategy, ignore it — it's only used by the AI directional path.
Every trade, AI decision, and cost metric is recorded to trading_system.db (local SQLite). Inspect via the dashboard or:
python cli.py history # Last 50 trades
python cli.py history --limit 100 # Last 100
python cli.py status # Live balance + open positions from Kalshipytest tests/ # full suite
pytest tests/ -v # verbose
pytest --cov=src # with coverageblack src/ tests/ cli.py beast_mode_bot.py
isort src/ tests/ cli.py beast_mode_bot.py
mypy src/- Create a module under
src/strategies/ - Wire it into a CLI flag in
cli.py(or invoke it directly) - Use the
KalshiClientfor orders/positions andDatabaseManagerfor state - Add tests under
tests/
Health check fails with HTTP 401
A 401 from Kalshi almost always means one of three things:
KALSHI_API_KEYin.envdoesn't match the API key ID shown in Kalshi- The private key file (
kalshi_private_key) is the wrong key for that API key, or its path is wrong - 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.
"Shutdown signal received" without pressing Ctrl-C
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 withnohup) - 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.
Bot ran for weeks but placed no positions
This is expected behavior, not a bug. The example strategies are conservative by design:
- AI Directional requires confidence ≥ 45%, category score ≥ 30, and is gated by drawdown / sector caps. On many days, no markets clear all four filters.
- Safe Compounder requires NO ask > 80¢ AND edge > 5¢. 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.
"no such table: positions" error on fresh install
The DB file isn't committed; it's created at runtime. The bot auto-initializes on startup, but you can do it manually:
python -m src.utils.databaseUse -m — running python src/utils/database.py directly fails with an import error.
AdGuard (macOS) blocks dependency downloads
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.
Bot not placing live trades despite --live
grep -i "live trading\|paper trading\|LIVE ORDER" logs/trading_system.log | tail -20If you see "Paper trading mode" the flag isn't taking effect. Verify the API key has trading permissions in Kalshi Settings.
Model not found / OpenRouter API errors
Model names on OpenRouter change. Update primary_model in src/config/settings.py with a current slug from openrouter.ai/models, or set PRIMARY_MODEL in .env.
Bot only seeing "KXMVE" tickers
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.
Python 3.14 PyO3 compatibility error
export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1
pip install -r requirements.txtOr use Python 3.13:
pyenv install 3.13.1 && pyenv local 3.13.1
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txtThese 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. Three-quarter Kelly compounds losses catastrophically on a 45% win-rate strategy. Quarter-Kelly is what the example strategies use.
3. A 50% drawdown limit isn't a limit. The default is 15% with the circuit breaker actually halting trades, not just logging.
4. Sector concentration creates correlated losses. When 90% of capital is in economic categories on a Fed day, everything moves together. The default cap is 30% per category.
5. More trades without edge is faster path to zero. The default scan interval is 60 seconds, not 30, and trades are gated by both confidence and category score.
Your edge is probably somewhere else. Use the toolkit to find it.
Contributions welcome. See CONTRIBUTING.md for full guidelines.
# 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 PRMIT. See LICENSE.
If this is useful to you, a star helps others find it.