OctagonAI/kalshi-trading-bot-cli

Kalshi Trading Bot CLI – What It Is

Kalshi Trading Bot CLI is a command‑line application that helps you trade on the Kalshi prediction‑market platform. It uses AI‑generated probability estimates (via Octagon Research) to spot edges between the model’s price and the live order‑book, then sizes trades with a half‑Kelly approach and a built‑in five‑gate risk engine.

Core Capabilities

Area	What the bot does
Market discovery	search, similar, clusters, peers – semantic and keyword search across all Kalshi markets, powered by Octagon embeddings when an API key is supplied.
Edge detection	analyze (or search edge) pulls Octagon’s model probability, compares it to the market price, and reports the edge with confidence levels.
Position sizing	Uses half‑Kelly sizing (kelly flag) and respects configurable risk caps (liquidity, concentration, draw‑down, etc.).
Basket building	basket build creates diversified multi‑leg baskets using cluster caps and correlation limits; basket backtest evaluates historic return, Sharpe, max draw‑down, win‑rate.
Risk & compliance	A five‑gate engine (Kelly, liquidity, correlation, concentration, draw‑down) blocks orders that exceed limits; mandate/kill/resume lets you set daily loss caps.
Learning loop	reflect turns settled trades into short lessons, hypothesis tracks falsifiable claims, and calibration reports Brier scores and skill per category.
Automation friendly	--json flag for machine‑readable output, --dry-run for scanning only, and a global binary (kalshi) for scripting or parallel invocations.
Paper‑trading	paper buy/sell lets you test strategies with real quotes but no real money at risk.
Reporting	report, trust, themes report, and events give markdown summaries, integrity scores, and calendar views.

How to Get Started

1. Install Bun (≥ 1.1) – the bot runs on Bun’s native TypeScript runtime and uses bun:sqlite.
2. Run the zero‑install command:

   bunx kalshi-trading-bot-cli@latest
   

   The first launch launches a wizard that asks for:
   • Kalshi API key + RSA private key
   • An LLM provider key (OpenAI, Anthropic, etc.)
   • Optional Octagon API key (for AI edge analysis) and Tavily key (web research).
3. Configuration files are stored in ~/.kalshi-bot/ (including a .env with your keys).
4. After setup you can type help inside the REPL or use any of the commands directly, e.g.:

   kalshi search crypto
   kalshi analyze KXBTC-26APR-B95000
   kalshi buy KXBTC-26APR-B95000 3 58
   

Typical Workflow

1. Discover – search or clusters to find markets of interest.
2. Analyze – analyze <ticker> shows model probability, market price, edge, top drivers, and Kelly‑sized order size.
3. Validate – basket validate or backtest to ensure the proposed trade meets risk limits and has historic performance.
4. Execute – buy / sell (or paper buy for simulation). The bot checks the five‑gate risk engine before sending the order to Kalshi.
5. Monitor – portfolio shows live P&L; watch streams live price and order‑book.
6. Learn – After settlement, run calibration to see skill scores, reflect to capture lessons, and hypothesis to manage claim‑tracking.

Extensibility & Scripting

• JSON output (--json) makes the tool easy to embed in bots or automated pipelines.
• Global binary (kalshi) enables parallel runs and integration with other agents.
• Custom themes – you can create, import, or edit narrative buckets (themes) to organise markets around your own research ideas.
• Daemon mode (daemon) keeps caches warm, syncs settlements, and runs background reflection without blocking interactive use.

Who Might Use It

• Quantitative traders who want AI‑augmented edge detection on prediction markets.
• Researchers experimenting with LLM‑driven probability forecasts.
• Hobbyists looking for a scriptable, terminal‑based interface to Kalshi with built‑in risk controls.

---

Bottom line: the Kalshi Trading Bot CLI is a full‑featured, AI‑enhanced command‑line trading assistant for Kalshi, offering market discovery, edge analysis, risk‑aware sizing, basket construction, backtesting, and a feedback loop for continuous improvement—all runnable with a single bunx command after installing Bun.