Kalshi MCP Trading Server

A complete Model Context Protocol (MCP) server and standalone CLI for the Kalshi prediction market trading platform. This skill provides full access to Kalshi's trading API, including market data, portfolio management, order placement, and advanced trading features.

Features

🏆 Complete API Coverage

•Market Data: Events, markets, orderbooks, trade history, series information
•Portfolio Management: Balance, positions, trade fills, portfolio history
•Trading Operations: Place/cancel orders, batch operations, advanced order types
•Search & Discovery: Find events by keywords, filter by categories, NBA game finder

🔒 Secure Authentication

•RSA-PSS signature authentication (industry standard)
•Environment variable configuration (no hardcoded secrets)
•Support for both production and demo environments

🚀 Dual Interface

•MCP Server: Integrates with Claude and other AI systems via Model Context Protocol
•Standalone CLI: Direct command-line access without requiring MCP

📊 Enhanced Data

•Automatic American odds conversion for sports markets
•Dollar/cent conversions for easy reading
•Rich market information display

Setup

1. Get API Credentials

•Log into your Kalshi account
•Navigate to "API Keys" section
•Click "Create New API Key"
•IMPORTANT: Save both the API Key ID and Private Key file immediately
•The private key cannot be retrieved again once you close the page

2. Configure Environment Variables

bash

export KALSHI_API_KEY="your-api-key-id-here"
export KALSHI_PRIVATE_KEY_PATH="/path/to/your/private-key.pem"

# Optional: Use demo environment for testing
export KALSHI_BASE_URL="https://demo-api.kalshi.co/trade-api/v2"

3. Install Dependencies

bash

cd scripts/
pip install -r requirements.txt

Usage

MCP Server

Start the MCP server for integration with Claude or other AI systems:

bash

python3 scripts/kalshi_mcp_server.py

The server exposes 20+ tools covering all Kalshi API functionality:

Market Data Tools:

•list_events - List events with filters
•get_event - Get single event details
•list_markets - List markets with filters
•get_market - Get single market details
•get_market_orderbook - Get live orderbook
•get_market_history - Get price/volume history
•get_series - Get series information
•list_trades - Get recent trades

Portfolio Tools:

•get_balance - Account balance and portfolio value
•get_positions - All open positions
•get_portfolio_history - Portfolio value over time
•get_fills - Trade execution history

Trading Tools:

•place_order - Place YES/NO orders (market/limit)
•cancel_order - Cancel specific order
•get_orders - List open orders
•batch_create_orders - Place multiple orders
•batch_cancel_orders - Cancel multiple orders

Search Tools:

•search_events - Search events by keyword
•search_markets - Search markets by keyword
•get_events_by_category - Filter by Sports/Politics/etc
•get_nba_games - NBA games for specific date

Standalone CLI

Use the CLI directly without MCP for quick operations:

Account Information

bash

# Check account balance
python3 scripts/kalshi_client.py balance

# View all positions
python3 scripts/kalshi_client.py positions

# View open orders
python3 scripts/kalshi_client.py orders

Market Discovery

bash

# Search for NBA events
python3 scripts/kalshi_client.py search "NBA"

# List NBA game events today
python3 scripts/kalshi_client.py nba-today

# Get specific series events
python3 scripts/kalshi_client.py events --series KXNBAGAME --status open

# Get markets for an event
python3 scripts/kalshi_client.py markets --event KXNBAGAME-26FEB09CLEDEN

Market Analysis

bash

# Get detailed market info with odds
python3 scripts/kalshi_client.py market KXNBAGAME-26FEB09CLEDEN-CLE

# Get live orderbook
python3 scripts/kalshi_client.py orderbook KXNBAGAME-26FEB09CLEDEN-CLE

Trading Operations

bash

# Place a limit order (buy 10 YES contracts at 55 cents)
python3 scripts/kalshi_client.py order --ticker KXNBAGAME-26FEB09CLEDEN-CLE --side yes --count 10 --price 55

# Place a market order
python3 scripts/kalshi_client.py order --ticker KXNBAGAME-26FEB09CLEDEN-CLE --side no --count 5 --type market

# Cancel an order
python3 scripts/kalshi_client.py cancel ORDER_ID_HERE

Understanding Kalshi Markets

Market Structure

•Event: A real-world outcome (e.g., "Cavaliers vs Nuggets game on Feb 9")
•Market: A specific binary question within an event (e.g., "Will Cavaliers win?")
•Ticker Format: SERIES-EVENT-MARKET (e.g., KXNBAGAME-26FEB09CLEDEN-CLE)

Pricing

•All prices are in cents (1-99¢)
•55¢ = 55% implied probability
•
American Odds: Automatically calculated and displayed
- •55¢ → -122 (slight favorite)
- •30¢ → +233 (underdog)

Order Types

•Limit Order: Specific price, may not fill immediately
•Market Order: Fill at best available price immediately
•YES Position: Wins $1 if outcome happens
•NO Position: Wins $1 if outcome doesn't happen

Example Trading Workflow

bash

# 1. Check account balance
python3 scripts/kalshi_client.py balance
# Balance: $89.52

# 2. Find Cleveland vs Denver game
python3 scripts/kalshi_client.py search "Cleveland Denver"

# 3. Get markets for that game  
python3 scripts/kalshi_client.py markets --event KXNBAGAME-26FEB09CLEDEN

# 4. Analyze specific market
python3 scripts/kalshi_client.py market KXNBAGAME-26FEB09CLEDEN-CLE
# Ticker: KXNBAGAME-26FEB09CLEDEN-CLE
# Title: Will the Cavaliers win vs. the Nuggets on February 9?
# YES: 45¢ ($0.45) - +122
# NO: 55¢ ($0.55) - -122

# 5. Place order (buy 10 YES at 50¢ - think Cavs are undervalued)
python3 scripts/kalshi_client.py order --ticker KXNBAGAME-26FEB09CLEDEN-CLE --side yes --count 10 --price 50

# 6. Monitor positions
python3 scripts/kalshi_client.py positions

API Reference

Core Endpoints

Endpoint	Description	Example
`/events`	List events	`list_events(series_ticker="KXNBAGAME")`
`/markets`	List markets	`list_markets(event_ticker="KXNBAGAME-26FEB09CLEDEN")`
`/portfolio/balance`	Get balance	`get_balance()`
`/portfolio/orders`	Create/list orders	`place_order(ticker="...", side="yes", count=10)`

Authentication Headers

All authenticated requests require these headers:

•KALSHI-ACCESS-KEY: Your API key ID
•KALSHI-ACCESS-TIMESTAMP: Current timestamp (milliseconds)
•KALSHI-ACCESS-SIGNATURE: RSA-PSS signature of timestamp + method + path

Rate Limits

•Market Data: 100 requests/minute
•Trading: 60 requests/minute
•Portfolio: 60 requests/minute

Troubleshooting

Common Issues

Authentication Errors (401)

code

Error: 401 - {"error": "invalid signature"}

•Check that KALSHI_API_KEY and KALSHI_PRIVATE_KEY_PATH are set correctly
•Verify the private key file exists and is readable
•Ensure system clock is synchronized (signatures are time-sensitive)

Invalid Order (400)

code

Error: 400 - {"error": "invalid price"}

•Prices must be between 1-99 cents for limit orders
•Cannot place orders on closed/settled markets
•Check market is still active with get_market

Market Not Found (404)

code

Error: 404 - {"error": "market not found"}

•Verify ticker format: SERIES-EVENT-MARKET
•Use search tools to find correct tickers
•Market may have closed or settled

Debug Mode

Add verbose output to CLI commands:

bash

export KALSHI_DEBUG=1
python3 scripts/kalshi_client.py balance

Demo Environment

Practice with fake money on demo environment:

bash

export KALSHI_BASE_URL="https://demo-api.kalshi.co/trade-api/v2"

Security Notes

•Never commit API keys or private keys to version control
•Store private keys securely with restricted file permissions (chmod 600)
•Use environment variables for all credentials
•Consider using demo environment for testing and development

References

Built for the OpenClaw community. Trade responsibly and never risk more than you can afford to lose.