Kalshi-Claw: Trade Prediction Markets with Natural Language via OpenClaw

Want your AI assistant to trade prediction markets directly? Most platforms either lack APIs or make integration painful, forcing you to handle order signing and position tracking yourself. Kalshi-Claw solves this by giving OpenClaw full Kalshi trading capability through natural language commands.

The architecture uses a Rust + TypeScript dual-runtime design: Rust core handles RSA-2048 signing, orderbook parsing, Kelly criterion position sizing, and hedge scoring — all CPU-intensive tasks. TypeScript manages Kalshi REST API integration, LLM orchestration, and terminal UI.

The standout feature is the LLM-powered hedge discovery pipeline. The Rust engine batch-scores market pairs first, then sends top candidates to an LLM for contrapositive logic validation — only logically necessary implications are accepted, correlations and "likely" relationships are rejected. Results are tiered by coverage: T1 (≥95%), T2 (90-95%), T3 (85-90%), helping traders build risk-controlled hedged portfolios.

All position data stays local in `~/.kalshi-claw/positions.json` — no third-party servers involved. Supports paper trading (DRY_RUN) and Kalshi's demo environment for zero-risk testing. macOS offers a one-command installer that handles Rust, Node.js, and all dependencies automatically.

Overview

Want your AI assistant to trade prediction markets directly? Most platforms either lack APIs or make integration painful. Kalshi-Claw gives OpenClaw full Kalshi prediction market trading capability through natural language commands. Inspired by Chainstack's PolyClaw (Polymarket equivalent), but Kalshi as a regulated centralized exchange offers a cleaner trading flow.

Core Features

Market Browsing & Search

  • `markets trending`: Top markets by 24h volume
  • `markets search "query"`: Keyword search
  • `market <ticker>`: Market details with live YES/NO orderbook depth

Trade Execution

  • `buy YES/NO <ticker> <amount>`: Buy positions
  • `sell YES/NO <ticker>`: Sell at current bid
  • Rust core auto-computes contract count: `floor(budget / ask_price)`
  • RSA-2048 PKCS#1 v1.5 signed orders
  • Kelly Criterion optimal position sizing

Example: Buy $50 YES at $0.65 ask → 76 contracts × $0.65 = $49.40 cost, payout $76.00 if correct, net P&L +$26.60.

Position Tracking

  • `positions`: List holdings with entry price, current mid-price, unrealized P&L
  • Local storage only: `~/.kalshi-claw/positions.json`

LLM Hedge Discovery (Key Innovation)

  • `hedge scan`: Scan trending markets for hedging opportunities
  • `hedge scan --query "topic"`: Topic-specific hedge search
  • `hedge analyze <ticker1> <ticker2>`: Analyze specific market pairs

Pipeline:

1. Rust engine batch pre-scores: coverage = 1 − (1−pA)(1−pB)

2. Top candidates sent to LLM (via OpenRouter) for contrapositive logic validation

3. Only logically necessary implications accepted — correlations rejected

4. Tiered display: T1 (≥95%), T2 (90-95%), T3 (85-90%)

5. Below 85% filtered by default (`--include-weak` to show)

Full scan takes ~60-120 seconds due to per-pair LLM validation.

Technical Architecture

Rust + TypeScript dual-runtime via napi-rs native Node.js addon:

Rust layer (src/) — CPU-intensive computation:

  • auth.rs: RSA-2048 PKCS#1 v1.5 request signing
  • orderbook.rs: Orderbook parsing, best bid/ask, contract count
  • hedge.rs: Batch hedge scoring, coverage tiers, pair ranking
  • sizing.rs: Kelly criterion, dollar sizing, max P&L calc

TypeScript layer (lib/ + scripts/) — async API and UI:

  • kalshiClient.ts: Full Kalshi REST API wrapper
  • llmClient.ts: OpenRouter LLM integration
  • positionStorage.ts: Local JSON position store
  • display.ts: ANSI terminal UI with P&L coloring

Installation

macOS One-Command Install

curl -fsSLk https://github.com/Kirubel125/Kalshi-Claw/archive/refs/heads/main.zip -o /tmp/cw.zip && \
unzip -qo /tmp/cw.zip -d /tmp && cd /tmp/Kalshi-Claw-main && bash install.sh

Configuration

Required: KALSHI_API_KEY, KALSHI_PRIVATE_KEY (PKCS#1 PEM), OPENROUTER_API_KEY (free tier available). Optional: KALSHI_USE_DEMO (default true), MAX_BET (default $25), DRY_RUN, KALSHI_LLM_MODEL (default nemotron-nano free).

Natural Language Usage (with OpenClaw)

  • "What's trending on Kalshi?" → Market overview
  • "Run Kalshi hedge scan limit 15" → LLM hedge analysis (~60s)
  • "Buy $50 YES on market KXFED-25DEC-T525" → Execute trade
  • "Show my Kalshi-Claw positions" → View holdings and P&L

Privacy & Security

All position data stored locally only. Supports Demo environment and DRY_RUN mode for zero-risk testing. RSA private key used for local signing only.

License: MIT | Author: Kirubel125