Stop Trading Blind: This AI CLI Finds Kalshi Edge for You

What if every trade you placed was backed by deep fundamental research, independent probability models, and institutional-grade risk management? Most prediction market traders are flying blind—staring at order books, guessing at catalysts, and sizing positions with gut instinct. The result? Predictable losses, emotional decisions, and portfolios that bleed out slowly.

But what if you could compress a team of quantitative researchers, fundamental analysts, and risk officers into a single command-line tool? Enter the Kalshi Trading Bot CLI—an AI-native trading system that doesn't just execute trades, but thinks before it risks a single dollar. Built by OctagonAI, this open-source powerhouse runs deep fundamental research on every Kalshi market, generates independent probability estimates, computes real edge against live order books, and executes with half-Kelly sizing filtered through a brutal 5-gate risk engine.

This isn't another crypto bot clone or overhyped trading "algo." This is a fundamentally different approach to prediction market trading—one that treats every contract as a research problem to solve, not a gamble to take. Whether you're a quant developer seeking systematic edge, a data scientist exploring alternative markets, or a trader tired of losing to better-informed participants, this tool demands your attention. Let's pull back the curtain on how it works—and why the smartest Kalshi traders are already integrating it into their workflow.

What Is the Kalshi Trading Bot CLI?

The Kalshi Trading Bot CLI is an open-source, AI-powered command-line interface for trading Kalshi prediction markets—the first regulated U.S. exchange for event contracts. Created by OctagonAI, it represents a paradigm shift from traditional trading bots that rely on technical indicators or momentum signals. Instead, this tool operates on fundamental research and probabilistic edge detection.

At its core, the CLI integrates three powerful systems: the Octagon Research API for AI-generated probability estimates and price driver analysis, the Kalshi exchange API for live market data and order execution, and a local SQLite cache for performance optimization and cost control. The result is a research-first trading system that mimics how sophisticated hedge funds approach event-driven strategies—just compressed into commands you can run in your terminal.

The tool is trending now because prediction markets are exploding in popularity. From political forecasting to crypto price predictions, traders are flocking to Kalshi for legally regulated exposure to real-world events. But here's the problem: most participants have no systematic way to estimate true probabilities. They're trading against the crowd, not against inefficiency. The Kalshi Trading Bot CLI changes that equation by generating independent probability estimates and quantifying edge—defined as the spread between the model's fair value and the market's current price.

Built with Bun and TypeScript (.tsx files run directly), the CLI leverages modern JavaScript^{↗ Bright Coding Blog} runtime performance while maintaining type safety. It requires Bun ≥ 1.1 specifically for its bun:sqlite native module—Node.js won't work, a deliberate technical choice that optimizes for speed and simplicity over compatibility.

Key Features That Separate Winners from Losers

The Kalshi Trading Bot CLI isn't a toy. It's a production-grade system with features that rival institutional trading infrastructure:

Deep Fundamental Research Engine: Every market analysis triggers comprehensive AI research—probability estimates, ranked price drivers, catalyst calendars, and confidence scoring. This isn't surface-level sentiment analysis; it's structured fundamental work that identifies why a market should be priced differently.
Independent Probability Modeling: The Octagon Research API generates model probabilities detached from market prices. This independence is crucial—if your model simply echoes the market, you have zero edge. The system explicitly calculates edge as modelProb - marketProb, giving you quantifiable, comparable signals across any market.
Half-Kelly Position Sizing: The bot uses Kelly criterion mathematics—specifically half-Kelly for conservatism—to determine optimal contract counts. This maximizes long-term geometric growth while controlling volatility. The default kelly_multiplier of 0.5 can be adjusted via configuration, but the philosophy is clear: size according to edge and bankroll, not confidence or fear.
5-Gate Risk Engine: Before any capital is deployed, trades must pass five sequential filters: Kelly sizing validation, liquidity verification, correlation checks (preventing concentrated exposure), concentration limits (max positions per category), and drawdown circuit breakers. Miss any gate, and the trade dies—no exceptions, no overrides.
Real-Time Market Monitoring: The watch command provides live price feeds and continuous theme scanning with configurable intervals. Use --live for aggressive 15-minute scans or customize with --interval for your preferred cadence.
Comprehensive Backtesting: The backtest command validates model accuracy with Brier scores, hit rates, flat-bet P&L, and skill scores against market benchmarks. It supports resolved and unresolved market analysis, edge bucket segmentation, and CSV export for external analysis.
Agent-Ready Architecture: Every command supports --json output with a consistent envelope format, enabling seamless integration with scripts, CI/CD pipelines, and AI agents. The watch --theme command outputs NDJSON for streaming data pipelines.

Real-World Use Cases Where This Tool Dominates

1. Political Event Arbitrage

Election contracts, policy predictions, and geopolitical events on Kalshi are notoriously inefficient. The crowd overweights recent polling, underweights base rates, and ignores structural factors. The CLI's research engine analyzes historical precedents, demographic trends, and institutional constraints to generate probabilities that systematically exploit these biases. Backtest results showing 12.5% skill scores over market prices aren't luck—they're structural edge.

2. Crypto Prediction Markets

Bitcoin and Ethereum price-level contracts are among Kalshi's most traded markets. The CLI integrates ETF flow analysis, halving cycle dynamics, and macro sentiment to model probabilities that often diverge significantly from technical-trader-dominated prices. The example session shows a +14% edge on BTC $95k contracts—edge that compounds with disciplined execution.

3. Systematic Portfolio Management

For traders running multiple positions, the risk engine is transformative. The portfolio command shows real-time P&L, exposure metrics, and risk snapshots. With max_positions: 10, max_per_category: 3, and daily_loss_limit: $200, the system enforces discipline that prevents the catastrophic drawdowns that destroy most prediction market traders.

4. Quantitative Research & Model Validation

Data scientists can use the backtesting infrastructure to validate proprietary models against Kalshi settlement prices. The --export flag generates per-market CSVs for external statistical analysis. Compare your model's Brier score against Octagon's 0.168 benchmark—if you can't beat it, you know where to allocate research resources.

5. AI Agent & Automation Workflows

The JSON API enables sophisticated automation. Build a system that scans for edge overnight, queues orders for market open, monitors positions with trailing stops, and generates performance reports—all without human intervention. The consistent response envelope with ok, data, and meta fields makes parsing trivial.

Step-by-Step Installation & Setup Guide

Getting started is deliberately frictionless. The maintainers optimized for zero-configuration first runs.

Prerequisites

First, install Bun (required—Node.js won't work):

curl -fsSL https://bun.com/install | bash

You'll also need:

A Kalshi account with API access (API key + RSA private key)
One LLM provider key (OpenAI, Anthropic, Google, xAI, OpenRouter, or Ollama)
Optional: Octagon API key for AI edge analysis, Tavily key for web research

Installation Options

Zero-install (recommended for trying):

bunx kalshi-trading-bot-cli@latest

This runs the latest version directly—no clone, no install. The setup wizard launches automatically on first run.

Global install (for regular use):

bun add -g kalshi-trading-bot-cli
kalshi  # now available everywhere

Clone for development:

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

Configuration Structure

The bot stores everything in ~/.kalshi-bot/:

Path	Purpose
`~/.kalshi-bot/.env`	API keys (auto-written by setup wizard)
`~/.kalshi-bot/`	SQLite cache, configuration, database

A .env in your current directory takes precedence—useful for development environments with different credentials.

Updating

Always use @latest for newest features:

bunx kalshi-trading-bot-cli@latest  # pin latest
bun pm cache rm                      # force refresh if cached

For global installs:

bun update -g kalshi-trading-bot-cli
# or
bun add -g kalshi-trading-bot-cli@latest

Verify version with kalshi --version.

First Run Setup

Launch and let the wizard handle configuration:

kalshi init  # explicit setup wizard
# or just run any command—wizard triggers automatically

The wizard collects: Kalshi API credentials, LLM provider keys, optional Octagon/Tavily keys, and basic risk preferences.

REAL Code Examples: From the Repository

These examples are extracted directly from the Kalshi Trading Bot CLI repository and demonstrate practical implementation patterns.

Example 1: Interactive Trading Session

This captures the complete workflow—search, analyze, size, execute, monitor:

$ 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

What's happening here? The trader searches crypto-themed markets, analyzes the BTC $95k contract, and receives a complete research package: 72% model probability vs. 58% market price = 14 percentage points of edge. The Kelly sizing recommends 3 contracts, all five risk gates pass, and the order executes. The portfolio view shows immediate mark-to-market P&L. This entire workflow—from discovery to execution—takes under 60 seconds.

Example 2: Backtesting for Model Validation

Verify your edge before risking capital:

# Default 15-day lookback with full statistics
kalshi backtest

# Extended analysis with filtering
kalshi backtest --days 30                    # 30-day window
kalshi backtest --resolved                   # settled markets only
kalshi backtest --unresolved --min-edge 10   # open markets, 10pp threshold
kalshi backtest --category crypto            # sector focus
kalshi backtest --export results.csv         # data export for analysis

The output reveals critical performance metrics:

Octagon Backtest — 15-day lookback (04/02 – 04/17)
══════════════════════════════════════════════════════════

  Events         83
  Markets        247   (142 resolved, 105 unresolved)
  Brier (Octagon)   0.168
  Brier (Market)    0.192
  Skill Score       +12.5%  [95% CI: +4.1% to +20.8%]
  Hit rate          61.4%  [95% CI: 54.2% to 68.1%]
  Flat-bet P&L      +$14.38 (ROI: +7.8%)

Key insight: The Brier score (lower is better) shows Octagon's 0.168 beating the market's 0.192—a 12.5% skill score with statistical significance. The 61.4% hit rate on resolved markets, combined with positive flat-bet ROI, demonstrates genuine predictive edge, not random variance.

Example 3: Agent Automation with JSON API

Build systematic workflows with structured output:

# 1. Find markets
MARKETS=$(kalshi search crypto --json | jq '.data')

# 2. Analyze top pick
ANALYSIS=$(kalshi analyze KXBTC-26APR-B95000 --json)
EDGE=$(echo "$ANALYSIS" | jq '.data.edge')

# 3. Trade if edge exceeds threshold
if (( $(echo "$EDGE > 0.05" | bc -l) )); then
  kalshi buy KXBTC-26APR-B95000 3 58 --json
fi

# 4. Monitor portfolio
kalshi portfolio --json

The JSON response follows a strict envelope:

{
  "ok": true,
  "command": "analyze",
  "data": {
    "ticker": "KXBTC-26APR-B95000",
    "modelProb": 0.72,
    "marketProb": 0.58,
    "edge": 0.14,
    "confidence": "very_high",
    "drivers": [
      { "claim": "Bitcoin ETF inflows accelerating", "impact": "high" }
    ]
  },
  "meta": {
    "octagon_credits_used": 3,
    "octagon_cache_hits": 0
  },
  "timestamp": "2026-03-30T10:00:00.000Z"
}

Why this matters: The consistent ok/data/meta structure enables error handling, cost tracking (credit usage), and pipeline integration. The meta.octagon_credits_used field is essential for budget management—each report costs 3 credits, and with daily_credit_ceiling configurable, you control research spend precisely.

Example 4: Risk Configuration

Tune the engine to your risk tolerance:

# View all settings
kalshi config

# Adjust Kelly fraction (more conservative)
kalshi config risk.kelly_multiplier 0.3

# Tighten drawdown circuit breaker
kalshi config risk.max_drawdown 0.15

# Reduce position concentration
kalshi config risk.max_per_category 2

# Set daily loss limit
kalshi config risk.daily_loss_limit 100

Default configuration values:

Setting	Default	Purpose
`risk.kelly_multiplier`	`0.5`	Half-Kelly for conservative growth
`risk.max_drawdown`	`0.20`	20% drawdown triggers halt
`risk.max_positions`	`10`	Portfolio concentration limit
`risk.max_per_category`	`3`	Sector diversification
`risk.daily_loss_limit`	`200`	Daily pain threshold in USD

Advanced Usage & Best Practices

Cache Management for Cost Control: Octagon reports are cached with tiered TTLs—markets closing soon get shorter windows. Use --refresh sparingly for fresh analysis. Monitor meta.octagon_cache_hits to verify cache efficiency.

Demo Mode for Strategy Development: Set KALSHI_USE_DEMO=true to trade simulated markets. Test strategies, validate backtest assumptions, and build confidence before live deployment.

Thematic Scanning with NDJSON: The watch --theme <theme> command outputs NDJSON for streaming pipelines. Build real-time dashboards, alert systems, or automated position managers.

Performance Flags for Deep Analysis: Add --performance to portfolio commands for Sharpe ratios and Brier scores. Use --verbose for debugging execution issues.

Credit Ceiling Discipline: Set octagon.daily_credit_ceiling to prevent runaway research costs. At 3 credits per report, a 100-credit ceiling allows ~33 full analyses daily—sufficient for systematic scanning.

LLM Provider Flexibility: The config command switches models instantly. Default GPT-5.4 works well, but Claude or Gemini may perform better for specific market types. Local Ollama support enables fully offline operation.

Comparison with Alternatives

Feature	Kalshi Trading Bot CLI	Manual Trading	Generic Crypto Bots	Institutional Platforms
AI Research Engine	✅ Deep fundamental analysis	❌ None	❌ Technical indicators only	⚠️ Expensive, slow
Independent Probabilities	✅ Octagon API, model vs. market	❌ Subjective bias	❌ Price-following	✅ Proprietary, opaque
Kelly Sizing	✅ Half-Kelly, configurable	❌ Gut-based	❌ Fixed amounts	✅ Often proprietary
Risk Engine	✅ 5-gate systematic	❌ Emotional discipline	❌ Basic stop-losses	✅ Complex, expensive
Backtesting	✅ Brier scores, skill metrics	❌ Hindsight only	⚠️ Limited historical	✅ Available
Cost	Free, open-source	Trading losses	Subscription fees	$10K+/month
Setup Complexity	Medium (one-time wizard)	Low	Low	High
Agent Integration	✅ Full JSON API	❌ None	⚠️ Limited	⚠️ Custom development

The verdict: The Kalshi Trading Bot CLI occupies a unique position—institutional-grade research and risk management at zero cost, with the flexibility of open-source code and modern API design. It outperforms manual trading through systematic discipline, beats generic bots with fundamental analysis, and democratizes access to tools previously reserved for hedge funds.

FAQ: What Developers Ask

Q: Why Bun instead of Node.js? A: The CLI requires bun:sqlite for native SQLite performance and runs .tsx files directly without compilation. Bun's speed and built-in TypeScript support reduce complexity. Node.js compatibility is explicitly not a goal.

Q: Is my API key data secure? A: Keys store locally in ~/.kalshi-bot/.env. The telemetry system explicitly never collects API keys, trade details, or natural language inputs—only anonymous command usage metrics.

Q: Can I run this completely free? A: The CLI is MIT-licensed and free. However, Octagon API calls cost credits (3 per report). Tavily web search requires its own key. Kalshi trading itself requires capital. Use demo mode for zero-cost testing.

Q: How does the 5-gate risk engine work? A: Sequential validation: (1) Kelly sizing produces non-zero position, (2) sufficient liquidity exists, (3) correlation with existing positions acceptable, (4) category concentration below limit, (5) current drawdown below circuit breaker. Fail any gate, trade aborts.

Q: What's the difference between --json and regular output? A: Regular output is human-readable tables and formatted text. --json returns machine-parseable structured data with consistent envelope format—essential for automation, logging, and integration.

Q: Can I use my own probability models instead of Octagon? A: The architecture supports this. While Octagon integration is the default, the JSON API and local database structure allow injecting proprietary estimates. Fork and modify the research pipeline for custom implementations.

Q: What markets work best with this tool? A: Any Kalshi market where fundamental analysis generates edge—political events, crypto prices, economic indicators, sports outcomes. The backtesting command validates which categories show strongest model performance for your specific strategy.

Conclusion: The Edge You've Been Missing

The Kalshi Trading Bot CLI isn't just another trading tool—it's a fundamental reimagining of how prediction markets should be traded. By combining deep AI research, independent probability modeling, mathematical position sizing, and ruthless risk discipline, it transforms trading from gambling into a systematic, research-driven process.

The 12.5% skill scores, positive flat-bet ROI, and five-gate risk architecture aren't marketing claims—they're measurable, backtested, and transparently documented. This is what institutional-grade prediction market trading looks like when democratized through open-source software.

My take? If you're trading Kalshi without systematic edge calculation, you're donating to those who have it. This tool levels the playing field. The question isn't whether you can afford to use it—it's whether you can afford not to.

Ready to stop trading blind? Star the repository, run bunx kalshi-trading-bot-cli@latest, and let the research engine show you what real edge looks like. Your future self—and your P&L—will thank you.

Found this valuable? Share it with fellow developers and traders exploring prediction markets. The best tools deserve the smartest users.