BT — Kalshi Edge Bot (public engineering docs)

This repo contains the public documentation for BT, a Python trading bot I run against Kalshi prediction markets. The source is kept in a private repo to protect the edge. The goal here is to describe the engineering — architecture, math, safety, stack — with enough detail that it's verifiable as a real system, without giving away the strategy itself.

BT identifies systematically mispriced contracts on Kalshi and places automated orders on them. Two market families currently:

1. Weather markets (KXHIGH* — daily high-temperature at US airports). Compares 31-member GFS ensemble forecasts from Open-Meteo against live Kalshi contract prices.
2. Sports markets (KX* — NBA/NFL moneylines, spreads, totals). Compares sharp consensus odds (de-vigged, from multiple books via a public aggregator) against Kalshi pricing.

In both cases the pipeline is the same shape: predict → compare → threshold → size → place → settle → measure.

Prediction markets have structural features that reward engineering discipline over information asymmetry:

• Objective settlement. Weather settles off the NWS Daily Climate Report; sports settles off the final score. There's nothing to argue about — calibration either works or it doesn't.
• Retail-dominated flow. Pricing inefficiencies persist longer than in equities/FX.
• Public data sources. GFS ensemble forecasts and consensus sports odds are free and high-quality. No data moat required — the edge is in the pipeline, not the data.
• Quadratic fee structure (0.07 * P * (1−P) per-fill on Kalshi taker orders) makes edge math sharp and easy to reason about.

Kalshi's taker fee is quadratic in contract price:

fee = 0.07 * P * (1 - P)

This peaks at 0ドル.0175/contract at P=0.50 and falls to zero at the boundaries. Every edge calculation deducts fees per-fill before deciding to trade — a net edge below the fee curve is not an edge. Maker (limit) orders avoid the fee entirely when filled passively.

edge = p_model - p_market - fee(p_market)

Trade only when |edge| exceeds a calibrated threshold.

Full Kelly maximizes long-run log-wealth but drawdowns are brutal and miscalibration destroys the strategy. Fractional Kelly (start small, ramp only after calibration proves out) trades expected growth for survivability:

kelly_fraction = f * (edge / (price * (1 - price)))
position_usd = bankroll * min(kelly_fraction, max_position_pct)

Both f and max_position_pct are hard-capped in config and can't be raised without tripping the risk gate.

A model that says "70%" and wins 55% of the time is broken, not edge. BT ships a calibration pipeline (kwx calibrate) that buckets historical signals by predicted probability and checks realized hit rate against predicted hit rate via reliability curves + Brier score. Live trading is gated on the system passing calibration — not on any backtest P&L number.

┌──────────────────────────────────────────────────────────────────┐
│ scheduled scans │
│ (systemd timers — Linux/macOS) │
└─────────────────────────────────┬────────────────────────────────┘
 │
 ▼
 ┌─────────────────────┐ ┌──────────────────────┐ ┌─────────────────────┐
 │ forecast adapters │ │ market adapters │ │ odds adapter │
 │ │ │ │ │ │
 │ Open-Meteo (GFS/ │ │ Kalshi — REST + │ │ sharp consensus │
 │ HRRR/NBM), METAR │ │ WebSocket auth via │ │ (de-vigged) │
 │ │ │ RSA-PSS signing │ │ │
 └──────────┬──────────┘ └──────────┬───────────┘ └──────────┬──────────┘
 │ │ │
 └───────────────┬───────────┴────────────────┬───────────┘
 │ │
 ▼ ▼
 ┌──────────────────┐ ┌──────────────────┐
 │ signal engine │ │ odds engine │
 │ │ │ │
 │ bracket parsing, │ │ de-vig, average, │
 │ prob distribution│ │ consensus line │
 └────────┬─────────┘ └────────┬─────────┘
 │ │
 └─────────────┬─────────────┘
 ▼
 ┌──────────────────────────┐
 │ edge detector │
 │ edge = p_model − p_mkt │
 │ − fee(p_mkt) │
 └────────────┬─────────────┘
 ▼
 ┌───────────────────────────┐
 │ risk gate + kill switch │
 │ • hard caps (pos, day) │
 │ • calibration pass check │
 │ • .kill file check │
 └────────────┬──────────────┘
 ▼
 ┌────────────────────────────┐
 │ execution (maker first) │
 │ order lifecycle + fills │
 └────────────┬───────────────┘
 ▼
 ┌────────────────────────────┐
 │ SQLite + JSONL journal │
 │ (ACID state + audit log) │
 └────────────┬───────────────┘
 ▼
 ┌────────────────────────────┐
 │ settlement + calibration │
 │ (NWS / final score) │
 └────────────────────────────┘

kwx/ # main package (~12.6K LOC Python)
 auth/ # Kalshi RSA-PSS auth signing
 forecast/ # Open-Meteo GFS/HRRR adapters, METAR pull
 markets/ # Kalshi REST + WS market data
 sports_markets/ # Kalshi KX* sports adapters (at-format, spread, total)
 odds/ # sharp consensus odds client, de-vig engine
 signals/ # bracket parsing + probability distribution
 sports_edge/ # sports-specific edge compute
 matching/ # signal ↔ market matching
 risk/ # hard caps, kill switch, gates
 exec/ # order placement, lifecycle, cancel
 settle/ # settlement fetch + resolution
 calib/ # reliability curves, Brier, auto-calibration
 backtest/ # historical replay harness
 storage/ # SQLite schema + migrations + JSONL journal
 ops/ # ops scripts, daily summary, heartbeat
 scan.py # top-level scan orchestrator
 cli.py, __main__.py # operator CLI
scripts/ # ops scripts (sports-scan, heartbeat, daily summary, CI gate)
deploy/ # systemd units (Linux) / launchd plists (macOS)
tests/ # 88 test files — pytest + respx (httpx mocks)
docs/ # runbook, key rotation, operator handbook

This is the part I spent the most time getting right.

• No live trading until paper-trading calibration passes. The code ships gated. env = "demo" by default; flipping to prod requires the calibration report to show realized hit rate within tolerance of predicted hit rate, across a minimum sample window.
• Hard caps (per-position USD, per-position % of bankroll, per-day loss) enforced at the risk gate — not as soft checks inside the strategy. The gate is a separate module; the strategy cannot bypass it.
• Kill switch. A .kill file in the runtime directory halts all order placement immediately. Heartbeat checks the file every scan. Operator can flip this in <2 seconds.
• Fee-aware everywhere. The quadratic fee is deducted in every edge calculation — a signal that doesn't pay for itself after fees is not a signal.
• No real-money trading in automated tests. Test suites hit a recorded-response fixture layer (respx); they cannot reach the real Kalshi API.
• Settlement is authoritative. PnL comes from resolved contracts, not from end-of-day marks. Settlement source (NWS / final score) is the only source of truth.

A few things that weren't obvious at the start:

• Time zones are the #1 bug source. NWS reports on LST (no DST). Kalshi tickers bracket dates in the market's nominal TZ. Every settlement bug I've hit came from a silent TZ assumption. The codebase eventually converged on "store UTC, render local, settle off LST, assert at every boundary."
• The RSA-PSS signing is exact. salt_length = digest_length (SHA-256 = 32 bytes). Getting this wrong fails silently for hours until you look at response codes. Now tested explicitly.
• "Data quality" as a first-class concept. The system writes a snapshot per scan with provenance. If a forecast adapter changes its response shape, the signal generator doesn't silently produce nonsense — it raises.
• Backoff and rate-limit pacing. Open-Meteo free tier is 10K req/day. Kalshi has tiered limits. The OddsPapi client in particular needed proactive pacing between requests (tested with pytest) to avoid 429s.

• 17 phases shipped
• 88 test files
• Weather pipeline operational (demo env, running on a Pi via systemd timers)
• Sports pipeline operational (v2.0), NBA + NFL at-format, spreads, totals
• Calibration reporting integrated into daily summary
• Running demo-env only — not live with real capital

Full source (12.6K LOC Python), strategy-specific parameters, calibrated thresholds, the backtest harness, market-specific adapters, and the complete .planning/ trail (17 phases of discuss → plan → execute → verify).

Happy to walk through it on request.

Author: Luke Hanna · lllukehanna@gmail.com · Los Angeles