Kalshi Command Center

A complete command-line interface for Kalshi prediction market trading. Provides portfolio visibility, live market scanning, trade execution, and risk management through a unified command API.

Overview

The Kalshi Command Center bridges your OpenClaw AI assistant with Kalshi's API. Core capabilities:

• - Portfolio Management: Real-time P&L tracking with emoji-annotated positions
• Live Market Scanning: Heuristic edge scoring across 600+ open markets
• Market Queries: Fetch live bid/ask data before trading
• Trade Execution: Buy/sell with Kelly sizing, risk validation, and audit logging
• Risk Management: Hard caps on trade size, position count, and daily loss
• Research Cache: Store opportunity rankings for quick reference

Available Commands

All commands are exposed through kalshi_commands.py with argparse routing. Use the module directly or import individual handlers.

Portfolio & Positions

CODEBLOCK0

Output: Cash balance, open positions with P&L, cost basis, and current value. Positions sorted by absolute P&L. Emoji indicators: 🔥 (>20% gain), ✅ (>5% gain), 📉 (break-even), ⚠️ (>15% loss).

Example:
CODEBLOCK1

Live Market Scanning

CODEBLOCK2

Output: Top 8 markets ranked by heuristic edge score. Shows bid/ask, spread (%), volume, OI, days to expiration, and composite score.

Heuristic Scoring Algorithm:

• - Spread tightness (25% weight): Markets with tight spreads = better price discovery
• Distance from extremes (35% weight): Markets in 20-80 range = actionable
• Liquidity (25% weight): Volume + Open Interest, log-scaled
• Time value (15% weight): Sweet spot 14-60 days to close

See references/scoring.md for detailed algorithm.

Example:
CODEBLOCK3

Market Data Queries

CODEBLOCK4

Output: Live bid/ask for both YES and NO sides, last price, 24h volume, status, and actionable guidance.

Example:
CODEBLOCK5

Cached Opportunities

CODEBLOCK6

Output: Top 8 opportunities from research cache with live price refresh. Shows source, edge %, confidence, and reasoning.

Order Management

CODEBLOCK7

Trade Execution

Direct trade placement (low-level):

CODEBLOCK8

Intelligent execution from cache (high-level):

CODEBLOCK9

The execute handler:

1. 1. Looks up the pick from research cache
2. Fetches live market data
3. Calculates Kelly-sized position (if available)
4. Validates risk limits
5. Places the order with audit logging

Brier Score Calibration

CODEBLOCK10

Prerequisites

System Requirements

• - Python 3.10+

API SDK

CODEBLOCK11

Authentication & Configuration

Set environment variables OR edit your OpenClaw config:

Option 1: Environment Variables

CODEBLOCK12

Option 2: Config File (~/.openclaw/config.yaml)

CODEBLOCK13

Key Path Resolution:

1. 1. If private_key_file is set: expand as ~/.openclaw/keys/{value} if relative
2. Fallback to private_key_path (legacy, deprecated)
3. Try standard paths if neither set

Optional: Kelly Position Sizing & Risk Validation

If available, the execute handler will use:

• - proactive.triggers.kelly_size for position sizing
• INLINECODE8 for risk gate approval

If modules are unavailable, defaults to:

• - Quantity: 10 contracts (fallback)
• Risk validation: disabled (log-only)

Market Filtering

Blocked Categories

The scanner excludes these categories automatically:

• - Weather: KXTEMP, KXRAIN, KXSNOW, KXWIND, KXWEATH (irrational/unhedgeable)
• Entertainment: KXCELEB, KXMOVIE, KXYT, KXTIKTOK (low signal)
• Social Media: KXTWIT, KXSTREAM (low volume)
• Index Futures: INX, NASDAQ, FED-MR (not Kalshi core)

See references/blocklist.md for complete list.

Sports Filter

Sports markets are intentionally excluded from the production stack. Recent evaluation did not show durable model edge there, so the system does not route sports markets into scanning or execution.

Time Window

• - Default scan: 7-180 days to expiration (interactive trading sweet spot)
• Includes volume floor (>10 contracts traded)
• Markets with tight spreads and high OI ranked first

Risk Limits

Hard caps enforced on all trades:

Limit	Value	Enforced By
Max single trade cost	$25.00 USD	INLINECODE9
Max position size

100 contracts | _check_risk() |
| Max daily loss | $50.00 USD | Kelly sizing + risk validator (if available) |

Trade Audit Log: All trades (accepted/blocked/failed) logged to ~/.openclaw/logs/trades.jsonl.

Example audit entry:
CODEBLOCK14

See references/risk-limits.md for full risk framework.

Heuristic Edge Scoring

The scan command ranks markets by a 4-factor composite score:

1. Spread Tightness (25% weight)

CODEBLOCK15

• - Score 1.0 at 0% spread (mid = bid = ask)
• Score 0.5 at 10% spread
• Score 0.0 at 20%+ spread

Rationale: Tight spreads = more efficient price discovery, easier entry/exit.

2. Distance from Extremes (35% weight)

CODEBLOCK16

• - Score 1.0 at exactly 50¢ (maximum uncertainty)
• Score 0.5 at 25¢ or 75¢ (moderate certainty)
• Score 0.0 at 0¢ or 100¢ (resolved)
• Heavy penalty (<30% of base score) for near-settled markets

Rationale: Markets in the 20-80 range offer actionable edge. Extremes are near-certain and illiquid.

3. Liquidity (25% weight)

CODEBLOCK17

Log-scaled to avoid mega-markets dominating. Weights recent volume (60%) over open interest (40%).

4. Time Value (15% weight)

CODEBLOCK18

• - Sweet spot: 14-60 days to close (score 1.0)
• Below 14d: linear ramp (less time = lower score)
• Above 60d: logarithmic decay (floor 0.3)

Rationale: Too-short markets have liquidity spikes; too-long markets lack catalysts. 14-60d is where directional bets play out.

Composite Score

CODEBLOCK19

Weighted sum of 0-100 scale. Top 8 markets by score displayed.

See references/scoring.md for worked examples.

Output Formatting

All output strips Markdown for iMessage compatibility. Emoji indicators:

Emoji	Meaning
📈	Positive P&L or bullish signal
📉

Negative P&L or bearish signal |
| 🔥 | High gains (>20%) or strong edge |
| ✅ | Moderate gains (>5%) or approved |
| ⚠️ | Warning (>15% loss) or risk issue |
| 🔻 | Moderate loss (>0%) |
| ➖ | Break-even |
| 🎯 | Live scan results |
| 🏀 | Sports excluded / blocked |
| 💵 | Cash/financial data |
| 📊 | Market data |
| 📎 | Ticker link |
| 💰 | Proceeds/proceeds |

Error Handling & Retry Logic

The _get_client() function retries on transient failures:

CODEBLOCK20

Failure Classification:

• - network: Timeout, connection reset → retry with 2s backoff
• INLINECODE15: 401/403, invalid key → fail immediately
• INLINECODE16: 429 → retry with backoff
• INLINECODE17: Other errors → fail immediately

User-Facing Messages:

• - Network: "Can't reach Kalshi API — network timeout or connection reset."
• Auth: "Kalshi auth failed — API key may be expired or invalid."
• Rate limit: "Kalshi rate limited — too many requests. Try again in a minute."

Usage Examples

Daily Portfolio Check

CODEBLOCK21

Returns cash, positions, total P&L with emoji-coded performance.

Find New Edge Right Now

CODEBLOCK22

Scans 600 markets, ranks by heuristic score, shows top 8 with bid/ask and days to close.

Check Before Buying

CODEBLOCK23

Live bid/ask, spread, volume, and guidance on limit price strategy.

Execute from Research Cache

CODEBLOCK24

Looks up pick #1, fetches live market data, places buy order with 15 contracts (manual override skips Kelly).

Monitor Orders

CODEBLOCK25

Lists all open/resting limit orders with price and remaining count.

Exit a Position

CODEBLOCK26

Sell 10 contracts at bid (35¢).

File Structure

CODEBLOCK27

Implementation Reference

Source: kalshi_commands.py (standalone implementation)

• - Env var support for API credentials
• CLI routing via argparse
• Full retry logic and error classification
• Trade audit logging
• Kelly sizing integration (optional)
• Risk validation gates (optional)

Key Functions (all available in kalshi_commands.py):

• - portfolio_command() — cash + positions + P&L
• INLINECODE21 — live scan with heuristic scoring
• INLINECODE22 — cached research results
• INLINECODE23 — live bid/ask for single market
• INLINECODE24, sell_command() — direct order placement
• INLINECODE26 — intelligent execution from cache
• INLINECODE27 — list resting orders
• INLINECODE28 — cancel by order ID
• INLINECODE29 — API client with retry logic
• INLINECODE30 — user-friendly error messages

Troubleshooting

"Kalshi is not enabled"

Set kalshi.enabled: true in ~/.openclaw/config.yaml.

"Kalshi key_id not configured"

Set KALSHI_KEY_ID env var OR kalshi.api_key_id in config file.

"Kalshi private key not found"

Set KALSHI_KEY_PATH env var (absolute path) OR kalshi.private_key_file in config.

"Auth failed — API key may be expired"

Verify key and private key file exist and are readable. Check Kalshi account for key status.

"Can't reach Kalshi API — network timeout"

Transient network issue or Kalshi infrastructure down. Retry in 30s.

"Kalshi rate limited — too many requests"

Back off for 1 minute. The scanner makes ~50-100 API calls per scan.

No markets after filtering

All 600 open markets filtered out by spread/volume/timeframe. This stack intentionally excludes sports; try widening your non-sports filters instead.

Advanced Usage

Custom Ticker Names

Edit ~/.openclaw/config.yaml:

CODEBLOCK28

All commands will use friendly names in output.

Audit Log Inspection

Trade execution is fully logged to ~/.openclaw/logs/trades.jsonl:

CODEBLOCK29

Parse to monitor trade velocity, P&L, and blocked trades.

Dry-Run Scanning

To scan without placing orders:

CODEBLOCK30

OpenClaw Ecosystem Integration

The Kalshi Command Center is your execution layer in the Prediction Market Trading Stack.

Connected Skill	How It Connects
Kalshalyst	Feeds edge opportunities → execute trades via execute command
Market Morning Brief

Reads your portfolio for the daily P&L digest |
| Portfolio Drift Monitor | Monitors positions you open through this command center |
| Prediction Market Arbiter | Flags cross-platform divergences → trade on the Kalshi side here |

Install the complete stack:
CODEBLOCK31

Agent Bug-Fix Protocol

CRITICAL: When you (the agent) discover and fix a bug in any script during a conversation, you MUST write the fix to the source file on disk using file editing tools. Showing the fix in chat is NOT sufficient — the next scheduled run starts a fresh session and will not have your conversational fix.

Checklist after finding a bug:

1. 1. Edit the actual .py file on disk (e.g., ~/skills/kalshi-command-center/scripts/kalshi_commands.py)
2. Also update the installed copy at INLINECODE42
3. Confirm both files are written before telling the user the fix is done
4. If the fix is significant, stage a git commit in INLINECODE43

Never say "fixed" if you only demonstrated the fix in conversation output.

Attribution

Author: KingMadeLLC
Version: 1.0.0

---

Feedback & Issues

Found a bug? Have a feature request? Want to share results?

• - GitHub Issues: github.com/kingmadellc/openclaw-prediction-stack/issues
• X/Twitter: @KingMadeLLC

Part of the OpenClaw Prediction Stack — the first prediction market skill suite on ClawHub.