Kalshi Dutch Agent

The bot operates on a simple but effective two-phase cycle: discover markets that might be profitable, then monitor them in real time so we can act the instant conditions are right. Here's how each piece works.

Phase 1 — Market Discovery (REST API Scan)

Every ~2 minutes, the bot calls Kalshi's REST API to fetch the full catalog of open events and their markets. This is the only way to discover new markets — you can't subscribe to something you don't know exists yet.

For each event, the scanner pulls every market's current ask prices, volume, and open interest. It then runs through your profile filters — checking category (e.g., sports, weather, economics), minimum liquidity, number of outcomes, and the coverage probability threshold.

Markets that pass all filters become candidates. Markets that are close but don't quite qualify get logged as near misses so you can see what's just outside the threshold.

Phase 2 — Real-Time Price Updates (WebSocket)

While REST scans happen every couple of minutes, prices change every second. That's where the WebSocket comes in. The bot maintains a persistent connection to Kalshi's WebSocket API (wss://api.elections.kalshi.com), which pushes live price and volume updates for every market on the platform.

These updates stream in sub-second and are stored in an in-memory cache. Between REST scans, the strategy engine reads from this cache instead of making API calls — which means zero additional rate-limit usage and prices that are always fresh.

The WebSocket also delivers market lifecycle events (new markets opening, markets settling) and fill confirmations when our orders execute — so the bot knows immediately when a trade goes through.

Phase 3 — Continuous Evaluation (Strategy Engine)

Every bot cycle (typically every few seconds), the strategy engine re-evaluates all candidate markets using the latest WS-cached prices. For dutching, it calculates:

• Coverage probability — what percentage of outcomes can we cover?
• Total cost — how much does it cost to buy all legs (including Kalshi's taker fee)?
• Guaranteed payout — the minimum we receive no matter which outcome wins
• Net profit margin — payout minus cost, accounting for fees

When the numbers cross your profile's threshold — meaning the cost to cover all outcomes is low enough to guarantee a profit — the engine issues a trade decision.

Phase 4 — Execution & Position Management

Once a trade decision is made, the executor places limit orders for each leg of the dutch bet. Each order is sized proportionally so the payout is balanced regardless of which outcome wins.

After entry, the triage agent monitors open positions. It can check external data sources (like weather forecasts for weather markets) to detect if conditions have changed and recommend early exits before resolution.

Positions are tracked per-profile, with independent risk limits, capital allocation, and trade modes (sim vs. live) for each.

Data Flow Diagram

💡 Key Design Choices

• REST for discovery, WS for speed — You need the full catalog to find new opportunities, but you need real-time prices to act on them. Using both gives you the best of each.
• Cycle-based evaluation, event-driven data — The bot evaluates on a regular cadence, but the data feeding those evaluations is always current thanks to the WebSocket stream.
• Near misses matter — Markets just outside the profitability threshold today might cross it tomorrow. Tracking them means you're ready when they do.
• Fees are first-class citizens — Every calculation includes Kalshi's taker fee model (7% × price × (1−price), clamped). A market that looks profitable before fees might not be after them.
• Profile isolation — Each profile has its own filters, risk limits, and capital. One conservative profile can run alongside an aggressive one without interference.

Profile-Level Controls

Each profile has independent settings: max capital, max positions, allowed categories, position sizing rules, and sim/live mode. A conservative profile might cap at $50 with 3 max positions, while an aggressive one uses $200 with 10 positions. They never interfere with each other.

Position Sizing & Capital Allocation

The risk manager checks available capital before every trade. It enforces per-position maximums and ensures no single trade uses too large a share of the profile's total capital. If a trade would exceed limits, it's blocked.

The Triage Agent

After entry, the triage agent periodically checks open positions against external data. For weather markets, it fetches NWS forecasts. If conditions shift against a position, it can recommend or execute an early exit — limiting losses before the market resolves.

Sim Mode Safety Net

Every profile defaults to sim mode, which tracks positions virtually without placing real orders. You can validate the strategy's performance with real market data before risking actual capital. Switching to live requires an explicit password-protected action.

Click an endpoint to see the raw API response.

Monitoring Architecture

Scan Loop Phases

The bot tracks which phase it's in. When a hang is detected, the phase tells you exactly where it's stuck.

Troubleshooting Guide

Common symptoms, what they mean, and how to fix them. Check journalctl -u kalshi-bot for log details.

SSH Quick Commands