Kalshi AI Trading Bot

<div align="center">

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

</div>

---

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.

---

Quick Start

# 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
• OpenRouter key → openrouter.ai

---

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 | |---|---|---| | 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.

---

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 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.py and 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.

2. Safe Compounder — python cli.py run --safe-compounder

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 300

Rules: NO side only, YES last ≤ 20¢, NO ask > 80¢, edge > 5¢, max 10%/position, skips sports/entertainment/"mention" markets.

3. Beast Mode — python cli.py run --beast

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.

---

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:

# 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 account with API access (API docs)
• An OpenRouter API key (only needed for the AI directional strategy)

Automated Setup

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.

Manual Setup

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

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) |

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 health

---

Configuration

All 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 USD

Swapping 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.

---

Project Structure

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-tradi