# Kalshi MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
[![Kalshi API v2](https://img.shields.io/badge/Kalshi-API%20v2-orange.svg)](https://trading-api.readme.io/reference/getmarkets)

**Give Claude access to Kalshi prediction markets — browse live odds, analyze price history, and trade YES/NO contracts.**

Built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), this server connects Claude (and any MCP-compatible AI) directly to the [Kalshi Trade API v2](https://trading-api.readme.io/reference/getmarkets).

> **First MCP server for Kalshi.** Ask Claude "What are the current odds on the Fed rate decision?" and get a live answer.

---

## Features

| Tool | Description | Tier |
|------|-------------|------|
| `get_markets` | Browse open/settled markets with filters | 🆓 Free |
| `get_market_details` | Live odds, volume, order book for a market | 🆓 Free |
| `get_market_price_history` | OHLC candlestick data (1-min, hourly, daily) | 🆓 Free |
| `get_portfolio` | Account balance and open positions | 🔑 Pro |
| `place_order` | Buy YES/NO contracts (dry-run confirmation) | 🔑 Pro |
| `get_order_history` | Fills, settlements, open orders | 🔑 Pro |

---

## Quick Start

### 1. Install

```bash
git clone https://github.com/shadowfax-mitch/kalshi-mcp-server
cd kalshi-mcp-server
pip install -r requirements.txt
```

Or install as a package:

```bash
pip install kalshi-mcp-server
```

### 2. Configure Claude Desktop

Add to your `claude_desktop_config.json`:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

#### Free Tier (read-only, no credentials needed)

```json
{
  "mcpServers": {
    "kalshi": {
      "command": "python",
      "args": ["-m", "kalshi_mcp.server"],
      "cwd": "/path/to/kalshi-mcp-server"
    }
  }
}
```

#### Pro Tier (full trading access)

```json
{
  "mcpServers": {
    "kalshi": {
      "command": "python",
      "args": ["-m", "kalshi_mcp.server"],
      "cwd": "/path/to/kalshi-mcp-server",
      "env": {
        "KALSHI_API_KEY": "your-api-key-uuid",
        "KALSHI_PRIVATE_KEY_PATH": "/absolute/path/to/private_key.pem"
      }
    }
  }
}
```

#### Pro Tier (with package install / pipx)

```json
{
  "mcpServers": {
    "kalshi": {
      "command": "kalshi-mcp",
      "env": {
        "KALSHI_API_KEY": "your-api-key-uuid",
        "KALSHI_PRIVATE_KEY_PATH": "/absolute/path/to/private_key.pem"
      }
    }
  }
}
```

### 3. Restart Claude Desktop

After saving the config, restart Claude Desktop. You'll see a 🔨 tools icon — click it to verify Kalshi tools are loaded.

---

## Getting Kalshi API Credentials (Pro Tier)

1. Go to [https://kalshi.com/account/settings](https://kalshi.com/account/settings)
2. Navigate to **API** → **Create API Key**
3. Download your RSA private key PEM file
4. Copy your API key UUID
5. Set both as environment variables (see config above)

> **Security:** Never commit your private key or API key to version control.  
> Store them securely — they provide full trading access to your account.

---

## Usage Examples

Once configured, talk to Claude naturally:

### Browse Markets

```
"Show me open BTC prediction markets"
→ get_markets(series_ticker="KXBTC15M")

"What are the most liquid markets right now?"
→ get_markets(status="open", limit=20)

"Show me recently settled markets"
→ get_markets(status="settled", limit=10)
```

### Market Research

```
"Get the full details for KXBTC15M-24NOV1913-T10000 including the order book"
→ get_market_details("KXBTC15M-24NOV1913-T10000")

"Show me the hourly price chart for this market over the last 48 hours"
→ get_market_price_history("KXBTC15M-...", period_interval=60, lookback_hours=48)

"Get 1-minute candles for the last hour"
→ get_market_price_history("...", period_interval=1, lookback_hours=1)
```

### Portfolio (Pro)

```
"What's my current balance and positions?"
→ get_portfolio()

"Show me my recent trades and P&L"
→ get_order_history(include_fills=True, include_settlements=True)
```

### Trading (Pro)

Claude automatically uses a dry-run confirmation flow:

```
"Buy 10 YES contracts on KXBTC15M-... at 65 cents"

Claude:
1. Calls place_order(..., dry_run=True)  ← preview
2. Shows you:
   📋 ORDER PREVIEW (not submitted):
     Ticker:         KXBTC15M-24NOV1913-T10000
     Side:           YES
     Contracts:      10
     Limit price:    65¢ ($0.65)
     Estimated cost: $6.50
     Max payout:     $10.00
     Max profit:     $3.50

3. Asks: "Shall I submit this order?"
4. On confirmation: calls place_order(..., dry_run=False)
```

---

## Tool Reference

### `get_markets`

List Kalshi prediction markets.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `status` | str | `"open"` | `"open"`, `"closed"`, or `"settled"` |
| `series_ticker` | str | | Filter by series (e.g. `"KXBTC15M"`, `"NASDAQ100D"`) |
| `event_ticker` | str | | Filter by event |
| `limit` | int | `20` | Results per page (max 200) |
| `cursor` | str | | Pagination cursor |

---

### `get_market_details`

Full detail for a single market including live order book.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ticker` | str | required | Market ticker |
| `include_orderbook` | bool | `true` | Fetch live order book |

---

### `get_market_price_history`

OHLC candlestick price history.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ticker` | str | required | Market ticker |
| `period_interval` | int | `60` | Candle size in minutes: `1`, `60`, or `1440` |
| `lookback_hours` | int | `24` | Hours of history (1–168) |

---

### `get_portfolio` _(Pro)_

Account balance and open positions. No parameters.

---

### `place_order` _(Pro)_

Place a limit buy order.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ticker` | str | required | Market ticker |
| `side` | str | required | `"yes"` or `"no"` |
| `count` | int | required | Number of contracts |
| `price_cents` | int | required | Limit price in cents (1–99) |
| `dry_run` | bool | `true` | Preview without submitting (**always start here**) |

**Pricing guide:**
- Each contract pays **$1.00** if you're correct, **$0.00** if wrong
- `price_cents=65` means you pay **65¢** and profit **35¢** if correct
- `price_cents` reflects the market's implied probability (65¢ ≈ 65% chance)

---

### `get_order_history` _(Pro)_

Recent trading activity.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `include_fills` | bool | `true` | Recent executed trades |
| `include_settlements` | bool | `true` | Settled contracts with P&L |
| `include_open_orders` | bool | `true` | Resting limit orders |
| `ticker` | str | | Filter to specific market |
| `limit` | int | `25` | Records per section |

---

## Architecture

```
Claude Desktop
    │
    │  MCP (stdio)
    ▼
kalshi_mcp/server.py      ← FastMCP server, tool definitions, formatting
    │
    ▼
kalshi_mcp/client.py      ← Kalshi REST API client (httpx)
    │
    ▼
kalshi_mcp/auth.py        ← RSA-PSS signing (Kalshi API v2 auth scheme)
    │
    ▼
https://api.elections.kalshi.com/trade-api/v2
```

**Auth scheme (RSA-PSS):**
```
Signature = RSA-PSS(
    message  = f"{unix_timestamp}{METHOD}{/trade-api/v2/endpoint}",
    hash     = SHA-256,
    mgf      = MGF1(SHA-256),
    salt_len = 32
)

Headers:
  KALSHI-ACCESS-KEY       = api_key_uuid
  KALSHI-ACCESS-SIGNATURE = base64(signature)
  KALSHI-ACCESS-TIMESTAMP = unix_timestamp_seconds
```

---

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Type check
mypy kalshi_mcp/

# Lint
ruff check kalshi_mcp/

# Test the server manually (stdio transport)
python -m kalshi_mcp.server
```

### Project Structure

```
kalshi-mcp-server/
├── kalshi_mcp/
│   ├── __init__.py      # Package metadata
│   ├── server.py        # MCP server & tool definitions
│   ├── client.py        # Kalshi API client
│   └── auth.py          # RSA-PSS authentication
├── tests/
│   └── test_client.py   # Unit tests
├── README.md
├── requirements.txt
├── pyproject.toml
└── .env.example
```

---

## Pricing & Tiers

### 🆓 Free Tier
- **Market browsing** — search and filter thousands of markets
- **Live odds** — real-time YES/NO prices and order books
- **Price history** — OHLC candlestick data for any market
- No API credentials required

### 🔑 Pro Tier
Everything in Free, plus:
- **Portfolio view** — balance, positions, unrealized P&L
- **Order placement** — buy YES/NO contracts with confirmation flow
- **Order history** — fills, settlements, open orders

**Available at:** [PaidMCP](https://paidmcp.com) | [GitHub Sponsors](https://github.com/sponsors/shadowfax-mitch)

---

## Security

- **Never trade with funds you can't afford to lose.** Prediction markets carry real financial risk.
- Store your API key and private key securely. Never commit them to version control.
- The `place_order` tool defaults to `dry_run=True` — orders require explicit confirmation.
- Consider setting position size limits at the Kalshi account level as an extra safeguard.

---

## Troubleshooting

**"Auth init failed (free-tier only)"**  
→ Check that `KALSHI_API_KEY` is a valid UUID and `KALSHI_PRIVATE_KEY_PATH` points to your PEM file.

**"Kalshi API 401"**  
→ Your key may be expired or revoked. Regenerate at kalshi.com/account/settings.

**"Kalshi API 403"**  
→ You may be trying a pro feature without valid credentials, or your account may be restricted.

**Tools not showing in Claude Desktop**  
→ Verify the `cwd` path in your config. Restart Claude Desktop after any config change.

**"period_interval must be 1, 60, or 1440"**  
→ Kalshi only supports these candle sizes. Use 1 (minute), 60 (hourly), or 1440 (daily).

---

## Contributing

Pull requests welcome! Please open an issue first for significant changes.

```bash
git clone https://github.com/shadowfax-mitch/kalshi-mcp-server
cd kalshi-mcp-server
pip install -e ".[dev]"
pytest tests/
```

---

## License

MIT License — see [LICENSE](LICENSE)

---

## Disclaimer

This is an unofficial third-party tool. It is not affiliated with, endorsed by, or sponsored by Kalshi Inc. Use of the Kalshi API is subject to [Kalshi's Terms of Service](https://kalshi.com/legal/terms-of-service). Trading prediction markets involves financial risk.