Octagon CLI

The Octagon CLI, distributed as the Kalshi Trading Bot CLI, is an AI-native research and trading interface for Kalshi prediction markets. It pairs live Kalshi market data with the Octagon Research API so you can discover markets, investigate events, generate independent probability estimates, find pricing discrepancies, build diversified baskets, validate portfolio risk, and execute trades — all from the terminal.

Instead of stitching together market discovery, research, probability modeling, position sizing, and order execution by hand, the CLI brings those workflows behind one interface that works two ways at once:

• an interactive terminal application for traders and researchers
• a structured JSON command-line API for scripts, automations, and AI agents

Repository: Kalshi Trading Bot CLI on GitHub

How you use it

Issue direct commands:

kalshi search edge --min-edge 5
kalshi analyze KXBTC-26APR-B95000
kalshi basket validate --theme "Iran Escalation"

Or ask natural-language questions inside the interactive terminal:

Find the most liquid Bitcoin markets with at least five points of model edge.
Compare the leading Federal Reserve outcome markets.
Build a diversified basket of five macroeconomic trades.
What catalysts could move this market before settlement?

The agent runs up to 10 tool-use iterations across Kalshi and Octagon — gathering market data, inspecting related contracts, retrieving research, and comparing prices — before it answers. Bring your own LLM key (OpenAI, Anthropic, Google, xAI, OpenRouter, or local Ollama).

What the CLI unlocks

Discover across the full Kalshi universe

Search by keyword, category, ticker prefix, theme, liquidity constraint, or semantic similarity to reduce thousands of contracts into a researchable opportunity set.

# Keyword + structured filters
kalshi search "bitcoin price" --category crypto --min-volume 10000 --limit 20

# Rank live opportunities by model edge
kalshi search edge --min-edge 5 --sort-by total_volume --limit 10

Edge results sort by model edge, expected return, trading volume, or model probability. Beyond flat search, the CLI gives you a market map:

• similar — semantic neighbors that keyword search misses, from a ticker or a free-text thesis (-q "Will Bitcoin move above six figures?").
• clusters — thematic clusters (--label fed), behavioral clusters by historical return pattern (--behavioral), or clusters ranked by basket performance (--ranked --timeframe 1y).
• peers — the markets that share a ticker's cluster.
• series / events — move beyond single contracts to series rollups and full event outcome ladders (kalshi events KXFEDCHAIRNOM-29).
• catalysts upcoming --days 14 — markets approaching resolution, grouped by date.

Research a market

analyze fuses live market state with Octagon research into an independent assessment — model probability, market-implied probability, edge, confidence, ranked price drivers, catalysts, suggested size, and risk-gate results.

kalshi analyze KXBTC-26APR-B95000

For longer-form due diligence, report pulls the full Octagon markdown report for a market, event, series, or Kalshi URL, with --refresh to force a fresh run:

kalshi report KXBTC-26APR-B95000 --refresh

trust adds a Trader Trust scorecard so you can judge whether a contract is clearly defined and interpretable before relying on its displayed probability:

kalshi trust KXFEDCHAIRNOM-29

Edge, sizing, and the five-gate risk engine

The CLI defines edge as the gap between Octagon's independent probability estimate and the probability implied by the live order book:

Model probability: 72%
Market price:      58%
Edge:             +14 percentage points

This separates the research question (what is the probability?) from the trading question (is the price attractive relative to that probability?). No estimate becomes a trade automatically — signals pass through fractional-Kelly sizing and a five-gate risk engine first:

1. Kelly — is the position size justified by the estimated edge?
2. Liquidity — is there enough activity to enter and exit responsibly?
3. Correlation — does the trade duplicate exposure already in the book?
4. Concentration — would it over-weight one market, event, or category?
5. Drawdown — has the account crossed a configured drawdown or daily-loss limit?

Sizing and limits are configurable. The runtime default is half-Kelly; basket commands also accept an explicit multiplier:

kalshi basket size --bankroll 1000 --kelly 0.25 --probs KX-A:0.62,KX-B:0.55

kalshi config risk.kelly_multiplier 0.25
kalshi config risk.max_drawdown 0.20
kalshi config risk.max_positions 10
kalshi config risk.daily_loss_limit 200

Build and validate diversified baskets

basket build pushes candidate-universe selection, edge filtering, thematic-cluster caps, pairwise-correlation limits, and Kelly sizing into a single server-side request — useful when several attractive trades are really the same underlying event.

# From a category
kalshi basket build --category crypto --min-volume 10000 \
  -n 8 --max-per-cluster 2 --max-corr 0.6 --bankroll 1000 --kelly 0.25

# From an editorial theme, with model-filled probabilities
kalshi basket build --theme "Iran Escalation" \
  -n 4 --max-per-cluster 1 --max-corr 0.5 --auto-probs --bankroll 1000

basket validate inspects a portfolio before any order — surfacing cluster concentration, strong pairwise correlations, duplicate underliers, resolution-date clashes, and portfolio-level warnings. correlate measures pairwise Pearson correlations directly (with per-contract --sides) to expose hidden overlap.

kalshi basket validate --theme "Iran Escalation" --bankroll 1000
kalshi correlate KX-A KX-B KX-C --window-days 90

This is where the CLI shines for agents: generate a candidate basket, validate it, revise it, and only then move toward execution.

Organize markets with editorial themes

Editorial themes are curated narrative collections — AI Race Milestones, Iran Escalation, Fed Cuts Aggressively — managed locally and mapped to Kalshi series. They are distinct from machine-generated clusters: themes are the human narratives you curate.

kalshi themes import          # seed the included registry
kalshi themes report          # narrative dashboard with SEO + liquidity
kalshi themes audit           # high public interest, little/no tradable inventory
kalshi themes overlap         # series assigned to multiple themes
kalshi themes create "My Macro Hedge" --tickers KXRECSSNBER,KXCPIYOY

Themes unlock narrative-based discovery, editorial dashboards, theme-level backtesting, basket construction by macro thesis, and detection of gaps between public interest and tradable inventory.

Trade, monitor, and validate

With Kalshi credentials configured, the CLI places and manages orders and tracks the portfolio:

kalshi buy  KXBTC-26APR-B95000 3 58             # 3 contracts, limit 58c, defaults to the YES side
kalshi sell KXBTC-26APR-B95000 3 62 --side no   # set the side explicitly with --side yes|no
kalshi cancel <order_id>
kalshi portfolio            # positions, entry/current prices, remaining edge, P&L, exposure
kalshi watch KXBTC-26APR-B95000   # live price + order-book feed

Set KALSHI_USE_DEMO=true to trade against Kalshi's demo environment with no real capital at risk.

backtest answers the question that matters most — does the model find real edge? It compares historical Octagon predictions against final settlement (resolved markets) or current pricing (unresolved), reporting Brier score, market Brier, skill score with confidence intervals, hit rate, and capital-weighted flat-bet P&L.

kalshi backtest --days 30 --min-volume 10 --min-price 5 --max-price 95
kalshi backtest --export results.csv

Installation

The fastest path needs no clone or install:

bunx kalshi-trading-bot-cli@latest

The CLI requires Bun 1.1 or newer (it uses bun:sqlite and runs TypeScript directly):

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

On first launch the setup wizard collects provider and API credentials and writes them to ~/.kalshi-bot/.env. Configuration, cache, and the SQLite database live under ~/.kalshi-bot/.

Recommended install for agents and scripts

For repeated, parallel, or automated use, install globally and call the kalshi binary directly:

bun add -g kalshi-trading-bot-cli
kalshi search crypto --json

This is preferable to repeated bunx calls because it keeps Bun install messages out of JSON output, prevents concurrent processes racing on the temporary package cache, lowers startup overhead, and gives agents and scheduled jobs a stable executable.

Connect the Octagon Research API

Set OCTAGON_API_KEY to enable Octagon-powered functionality:

export OCTAGON_API_KEY=your_octagon_api_key

An Octagon key unlocks deep research, independent probability estimates, edge scanning, semantic search, thematic and behavioral clusters, peer discovery, correlation analysis, basket construction and validation, model-driven Kelly sizing, and full market reports. Get a key from the Octagon application. Without it, basic search falls back to the local SQLite cache, but research, edge, and advanced portfolio workflows require Octagon access.

LLM provider configuration

The natural-language agent needs at least one model provider. Supported providers: OpenAI, Anthropic, Google, xAI, OpenRouter, and Ollama.

export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...
export GOOGLE_API_KEY=...
export XAI_API_KEY=...
export OPENROUTER_API_KEY=...

The CLI defaults to an OpenAI model (GPT-5.4). When using another provider, switch the configured model accordingly.

Command overview

# Discovery
kalshi search [query]
kalshi search edge
kalshi similar <ticker>
kalshi clusters
kalshi peers <ticker>

# Research
kalshi analyze <ticker>
kalshi report <ticker>
kalshi trust <event_ticker>
kalshi catalysts upcoming

# Events & series
kalshi events
kalshi series
kalshi series candles

# Portfolio construction
kalshi correlate <ticker...>
kalshi basket build
kalshi basket validate
kalshi basket size
kalshi basket backtest
kalshi basket candles

# Editorial themes
kalshi themes list | show | report | audit | overlap | create | add-series

# Trading & account
kalshi buy | sell | cancel | portfolio | watch

# Evaluation
kalshi backtest

The full reference covers 40+ commands and every flag — see the User Guide.

Agent and JSON usage

Every command supports --json and returns a consistent envelope:

kalshi analyze KXBTC-26APR-B95000 --json

{
  "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"
}

Successful commands exit 0. Failures exit 1 with "ok": false and an error object (code, message). This stable contract makes the CLI a clean tool layer for shell scripts, scheduled jobs, AI-agent tool calls, monitoring, and data pipelines.

Example orchestration

MARKETS=$(kalshi search crypto --json | jq '.data')
ANALYSIS=$(kalshi analyze KXBTC-26APR-B95000 --json)
EDGE=$(echo "$ANALYSIS" | jq '.data.edge')

# Trade only when the edge clears five percentage points
if (( $(echo "$EDGE > 0.05" | bc -l) )); then
  kalshi buy KXBTC-26APR-B95000 3 58 --json
fi

kalshi portfolio --json

A more advanced agent can search the universe, rank by edge and liquidity, pull reports, find correlated positions, build and validate a diversified basket, Kelly-size each leg, place orders, and re-evaluate edge as prices move.

Parallel research and streaming

After a global install, fan out analyses concurrently:

parallel -j 30 'kalshi analyze {} --json > {}.json' ::: KXBTC-26APR-B95000 KXETH-26APR-B2000 KX-A KX-B

watch --theme emits newline-delimited JSON (one object per scan cycle), suitable for log processors, alerting services, message queues, and serverless workflows:

kalshi watch --theme "Bitcoin Breakout" --json

Octagon credit controls

Octagon reports consume credits and are cached with market-aware expiration — markets closer to settlement get shorter cache lifetimes. Force a fresh report with --refresh, and cap daily usage to balance freshness against spend:

kalshi analyze KXBTC-26APR-B95000 --refresh
kalshi config octagon.daily_credit_ceiling 100

Common use cases

• Individual trader — discover markets, generate research, compare model probability with live price, size trades, and monitor portfolio risk.
• Quantitative researcher — use JSON output, backtests, correlations, clusters, and basket analytics to test whether signals persist across time and category.
• AI trading agent — expose commands as tools to research, validate, size, and execute strategies through one structured interface.
• Portfolio manager — manage aggregate risk with basket validation, correlation analysis, cluster caps, resolution calendars, and loss limits.
• News and event analyst — use reports, outcome ladders, catalysts, semantic discovery, and themes to see how events are being priced.
• Developer — treat the JSON envelope as a local integration layer for discovery, research, probability comparison, portfolio analysis, and execution.
• Scheduled monitor — run recurring searches or watch to detect new markets, edge changes, upcoming catalysts, concentration, and correlation spikes.

Telemetry

The CLI collects anonymous operational telemetry — command names, tool usage, timing, and success/failure status — to improve reliability. It never collects API keys, trade details, natural-language prompts, or personal information. Disable it any time:

export TELEMETRY_ENABLED=false

Get started

# Interactive
bunx kalshi-trading-bot-cli@latest

# Agents, scripts, and parallel workflows
bun add -g kalshi-trading-bot-cli
kalshi search edge --min-edge 5 --json

Connect OCTAGON_API_KEY to unlock deep research, model probabilities, edge scanning, semantic discovery, clustering, correlation analysis, and server-side basket construction.

Next steps

• MCP Server
• Claude Plugin