Kalshi Trading Bot CLI

AI-powered Kalshi trading CLI that finds edge and executes trades.

Runs deep fundamental research on every market — independent probability estimates, ranked price drivers, catalyst calendars — then computes edge as the spread between model price and the live order book. Signals are sized using half-Kelly and filtered through a 5-gate risk engine before a dollar is risked.

Integrates with the Octagon Research API for AI-generated probability estimates that power the edge detection engine.

Prerequisites

• Bun ≥ 1.1 (required — the bot uses bun:sqlite and runs .tsx directly; Node.js won't work) bash curl -fsSL https://bun.com/install | bash
• A Kalshi account with API access (API key + RSA private key)
• One LLM provider key (OpenAI / Anthropic / Google / xAI / OpenRouter / Ollama). The setup wizard collects these on first run.
• Optional: an Octagon key for AI edge analysis, and a Tavily key for web research.

Quick Start

bunx kalshi-trading-bot-cli@latest

That's it — no clone, no install. The setup wizard runs automatically on first launch and walks you through API keys.

Prefer a global install? bun add -g kalshi-trading-bot-cli then run kalshi.

Scripting and agent use — for parallel invocations, --json consumers, or anything that pipes our output: install globally and use the kalshi binary, not bunx. See Scripting & Parallel Use below for the gory details.

Or work from a clone:

git clone https://github.com/OctagonAI/kalshi-trading-bot-cli.git
cd kalshi-trading-bot-cli
bun install
bun start

Where things live

• Config, cache, SQLite DB: ~/.kalshi-bot/
• API keys (.env): ~/.kalshi-bot/.env — written by the setup wizard. A .env in the current directory takes precedence (handy for dev).
• First run with no keys configured triggers the setup wizard automatically.

Updating

Using @latest in the bunx command always pulls the newest published version — so bunx kalshi-trading-bot-cli@latest is the zero-friction path.

If you ran bunx kalshi-trading-bot-cli without @latest, Bun may serve a cached copy. Force a refresh:

bunx kalshi-trading-bot-cli@latest   # pin latest for this invocation
bun pm cache rm                      # or clear Bun's install cache

If you installed globally with bun add -g kalshi-trading-bot-cli:

bun update -g kalshi-trading-bot-cli         # update in place
bun add -g kalshi-trading-bot-cli@latest     # or reinstall pinned to latest

Check your installed version with kalshi --version (or bun pm ls -g | grep kalshi).

Example Session

$ bunx kalshi-trading-bot-cli@latest

Welcome to Kalshi Trading Bot CLI
Type help for commands, or just ask a question.

> search crypto

  Ticker                  Title                          Last    Volume
  KXBTC-26APR-B95000      Bitcoin above $95k by Apr 30   $0.58   12,841
  KXBTC-26APR-B100000     Bitcoin above $100k by Apr 30  $0.31    8,203
  KXETH-26APR-B2000       Ethereum above $2k by Apr 30   $0.72    5,419

3 markets found

> analyze KXBTC-26APR-B95000

  Octagon Research Report — KXBTC-26APR-B95000
  ─────────────────────────────────────────────
  Model Probability   72%
  Market Price        58%
  Edge               +14.0%  (very_high confidence)

  Top Drivers
  1. Bitcoin ETF inflows accelerating            impact: high
  2. Halving cycle momentum                      impact: high
  3. Macro risk-on sentiment                     impact: moderate

  Kelly Sizing
  Recommended: 3 contracts YES at $0.58
  Risk gates: ✓ Kelly  ✓ Liquidity  ✓ Correlation  ✓ Concentration  ✓ Drawdown

> buy KXBTC-26APR-B95000 3 58

  ✓ Order placed: BUY 3 YES @ $0.58
  Order ID: abc-123-def

> portfolio

  Ticker                  Side  Qty  Entry   Now    Edge    P&L
  KXBTC-26APR-B95000      YES    3   $0.58   $0.61  +11.0%  +$0.09

  Cash: $487.26 · Exposure: $1.74 · Positions: 1

Commands

Flags

Discovery & Portfolio (Octagon-powered)

The search, similar, clusters, peers, correlate, and basket commands turn the whole Kalshi universe into a queryable database. When OCTAGON_API_KEY is set the bot routes searches through Octagon's typed endpoints — semantic embedding lookups, nightly k-means clusters (thematic + behavioral), Pearson correlation matrices, and one-call diversified basket construction with cluster caps and pairwise-correlation gates. Without a key, search and search edge fall back to the local SQLite cache.

# Free-text + structured search (semantic full-text + filters)
kalshi search "bitcoin price" --category crypto --min-volume 10000 --limit 20

# Edge ranking from Octagon's latest run (server-side, no local pre-fetch)
kalshi search edge --min-edge 5 --limit 10 --sort-by total_volume

# Semantic neighbors — catches matches keyword search misses
kalshi similar KXBTCD-26DEC31-T100000 --top-k 25
kalshi similar -q "Will Bitcoin pierce six figures" --category crypto

# Browse the universe by theme
kalshi clusters --label fed                 # find Fed-decision clusters
kalshi clusters 42                          # markets in cluster 42
kalshi clusters --behavioral                # behavioral clusters (mean ret + vol)
kalshi clusters --ranked --timeframe 1y --min-return 0.20 --top-k 5

# Same-theme dedup
kalshi peers KXBTCD-26DEC31-T100000 --kind thematic --limit 50
kalshi peers KXBTCD-26DEC31-T100000 --show-cluster     # which cluster does this belong to?

# Pairwise correlation matrix — most-uncorrelated pairs first
kalshi correlate KXBTCD-... KXETHU-... KXSOL-... --window-days 90

# Build a diversified basket (one HTTP call — universe → cluster cap → corr cap → sizing)
kalshi basket build --category crypto --min-volume 10000 \
  -n 8 --max-per-cluster 2 --max-corr 0.6 \
  --bankroll 1000 --kelly 0.25 \
  --probs KXBTCD-...:0.62,KXETHU-...:0.58

# "Find me 5 uncorrelated bets on macro themes" — one HTTP call
kalshi basket build --label fed,cpi,fomc,gdp,jobs \
  -n 5 --max-per-cluster 1 --max-corr 0.4

# Backtest a basket and read total_return / Sharpe / max DD directly
kalshi basket backtest --tickers KX-A,KX-B,KX-C --weights 0.4,0.4,0.2 --timeframe 1y

# Kelly-size legs you've already picked
kalshi basket size --bankroll 1000 --kelly 0.25 --probs KX-A:0.62,KX-B:0.55

# Or let Octagon's model fill in the probabilities for you
kalshi basket size --auto-probs --tickers KX-A,KX-B,KX-C --bankroll 1000 --kelly 0.25
kalshi basket size --auto-probs --theme "AI Race Milestones" --bankroll 1000 --kelly 0.25

# Diversified basket builder over an explicit candidate pool
kalshi basket build --tickers KX-A,KX-B,KX-C,KX-D -n 3 --max-per-cluster 1 --max-corr 0.5
kalshi basket build --theme "Iran Escalation" -n 4 --max-per-cluster 1 --max-corr 0.5 --auto-probs --bankroll 1000

# Sanity-check a proposed basket before placing orders (one call, server-side)
kalshi basket validate --tickers KX-A,KX-B --bankroll 1000 --max-corr 0.5
kalshi basket validate --theme "Iran Escalation" --bankroll 1000
#   → cluster breakdown, pairwise correlations (top by |corr|), calendar
#     clashes (weeks where many legs resolve), duplicate underliers, warnings.

Editorial Theme Dashboard

themes is a local registry of editorial narrative buckets (e.g. "AI Race Milestones", "Iran Escalation") that maps to lists of Kalshi series with optional