# Kalshi — API Reference

## Sport-Aware Commands

| Command | Required | Optional | Description |
|---|---|---|---|
| `get_sports_config` | | | Available sport codes and series tickers |
| `get_todays_events` | sport | limit | Today's events for a sport with nested markets |
| `search_markets` | | sport, query, status, limit | Find markets by sport and/or keyword |
| `get_esports_odds` | | game, status, limit | Esports implied probabilities (game: cs2/lol/dota2). Prices in cents (0-100) like other commands; adds `implied_probability` (0-1) and `decimal_odds` |

## Raw API Commands

| Command | Required | Optional | Description |
|---|---|---|---|
| `get_exchange_status` | | | Exchange trading status |
| `get_exchange_schedule` | | | Operating hours |
| `get_series_list` | | category, tags | All series (leagues) |
| `get_series` | series_ticker | | Series details |
| `get_events` | | limit, cursor, status, series_ticker, with_nested_markets | Event listing |
| `get_event` | event_ticker | with_nested_markets | Event details |
| `get_markets` | | limit, cursor, event_ticker, series_ticker, status, tickers | Market listing |
| `get_market` | ticker | | Market details |
| `get_market_orderbook` | ticker | depth | Order book — yes/no bid depth (dollar-string levels) |
| `get_trades` | | limit, cursor, ticker, min_ts, max_ts | Recent trades |
| `get_market_candlesticks` | series_ticker, ticker, start_ts, end_ts, period_interval | | OHLC data |
| `get_sports_filters` | | | Filter categories |

## Sport Codes

### US Sports

| Sport | Code | Series Ticker |
|---|---|---|
| NBA | `nba` | KXNBA |
| NFL | `nfl` | KXNFL |
| MLB | `mlb` | KXMLB |
| NHL | `nhl` | KXNHL |
| WNBA | `wnba` | KXWNBA |
| College Football | `cfb` | KXCFB |
| College Basketball | `cbb` | KXCBB |

### Football (Soccer)

| League | Code | Series Tickers |
|---|---|---|
| English Premier League | `epl` | KXEPLGAME, KXEPLTOTAL, KXEPLBTTS, KXEPLSPREAD, KXEPLGOAL |
| Champions League | `ucl` | KXUCL, KXUEFAGAME |
| La Liga | `laliga` | KXLALIGA |
| Bundesliga | `bundesliga` | KXBUNDESLIGA |
| Serie A | `seriea` | KXSERIEA |
| Ligue 1 | `ligue1` | KXLIGUE1 |
| MLS | `mls` | KXMLSGAME |
| FIFA World Cup 2026 | `worldcup` | KXMENWORLDCUP, KXWCGAME, KXWCGROUPQUAL, KXWCGROUPORDER, KXWCSTAGE, KXWCHOSTSTAGE, KXWCBESTHOST, KXWCNOEURSA, KXWCREGIONKO, KXWCEVERYTEAMGOAL |

See `references/series-tickers.md` for the full series ticker list and `references/api.md` for raw API documentation.

## Price Scale

Kalshi prices are on a 0-100 integer scale:
- `last_price` of `20` = 20% implied probability
- `yes_bid` / `no_bid` = current bid prices for Yes and No sides
- Always use `status="open"` to exclude settled/closed markets

# Kalshi API

- **Base URL:** `https://api.elections.kalshi.com/trade-api/v2`
- All endpoints are public, read-only. No authentication required.

# Valid Commands & Common Mistakes

## CRITICAL: Always use the `sport` parameter

For single-game markets, ALWAYS pass `sport='<code>'` to `search_markets` and `get_todays_events`.

```
WRONG: search_markets(query="Leeds")           → 0 results
RIGHT: search_markets(sport='epl', query='Leeds') → returns all Leeds markets
```

## Sport-Aware Commands (recommended)

These use sport codes (`nba`, `nfl`, `mlb`, `epl`, `ucl`, etc.) — same interface as Polymarket:
- `get_sports_config` — **list all available sport codes** and series tickers
- `get_todays_events` — **today's events for a sport** (requires `sport` param)
- `search_markets` — **find markets by sport and keyword** (use `sport` param for single-game markets)

## Raw API Commands

These query the Kalshi API directly using series/event/market tickers:
- `get_exchange_status`
- `get_exchange_schedule`
- `get_series_list`
- `get_series`
- `get_events`
- `get_event`
- `get_markets`
- `get_market`
- `get_market_orderbook`
- `get_trades`
- `get_market_candlesticks`
- `get_sports_filters`

## Key Usage Patterns

### Finding sport markets (MOST COMMON)
```bash
# Use the sport parameter — maps to the right series ticker(s) automatically
sports-skills kalshi search_markets --sport=nba
sports-skills kalshi search_markets --sport=nba --query="Lakers"
sports-skills kalshi search_markets --sport=epl --query="Leeds"
sports-skills kalshi get_todays_events --sport=nba
sports-skills kalshi get_todays_events --sport=epl
```

### Discovering sport codes
```bash
sports-skills kalshi get_sports_config
# Returns: nba, nfl, mlb, nhl, wnba, cfb, cbb, epl, ucl, laliga, bundesliga, seriea, ligue1, mls, worldcup
```

## Commands that DO NOT exist (commonly hallucinated)

- ~~`get_odds`~~ / ~~`get_probability`~~ — market prices ARE the implied probability. Use `search_markets` or `get_todays_events`, which return `last_price` in cents (e.g., 20 = 20% implied probability).
- ~~`get_market_odds`~~ — use `search_markets`/`get_todays_events` and interpret `last_price` as probability. Note: raw `get_market`/`get_markets` payloads carry dollar-string fields instead (`last_price_dollars: "0.2000"`), not integer cents.
- ~~`get_series_by_sport`~~ — use `get_sports_config()` to see sport codes and series tickers.

## Other common mistakes

- **Not using the `sport` parameter** — without it, you need to know series tickers. `search_markets(sport='nba')` automatically resolves to `KXNBA`. `search_markets(sport='epl')` resolves to all EPL series.
- **Searching by team name without `sport`** — `search_markets(query="Leeds")` returns 0 results. Always include `sport='epl'`.
- Confusing NFL with football on Kalshi — Kalshi's "Football" category = NFL. For football (EPL, UCL, etc.), use `epl`, `ucl`, `laliga`, etc.
- Guessing series or event tickers instead of using `get_sports_config()` or `get_series_list()`.
- Forgetting `status="open"` when querying raw markets — without it, results include settled/closed markets.

If you're unsure whether a command exists, check this list. Do not try commands that aren't listed above.

# Sport Codes & Series Tickers

## Sport Codes (use with search_markets, get_todays_events)

### US Sports

| Sport | Code | Series Ticker(s) |
|---|---|---|
| NBA | `nba` | KXNBA |
| NFL | `nfl` | KXNFL |
| MLB | `mlb` | KXMLB |
| NHL | `nhl` | KXNHL |
| WNBA | `wnba` | KXWNBA |
| College Football | `cfb` | KXCFB |
| College Basketball | `cbb` | KXCBB |

### Football

| League | Code | Series Ticker(s) |
|---|---|---|
| English Premier League | `epl` | KXEPLGAME, KXEPLTOTAL, KXEPLBTTS, KXEPLSPREAD, KXEPLGOAL |
| Champions League | `ucl` | KXUCL, KXUEFAGAME |
| La Liga | `laliga` | KXLALIGA |
| Bundesliga | `bundesliga` | KXBUNDESLIGA |
| Serie A | `seriea` | KXSERIEA |
| Ligue 1 | `ligue1` | KXLIGUE1 |
| MLS | `mls` | KXMLSGAME |
| FIFA World Cup 2026 | `worldcup` | KXMENWORLDCUP, KXWCGAME, KXWCGROUPQUAL, KXWCGROUPORDER, KXWCSTAGE, KXWCHOSTSTAGE, KXWCBESTHOST, KXWCNOEURSA, KXWCREGIONKO, KXWCEVERYTEAMGOAL |

Use `get_sports_config()` to see all available codes.

**Football leagues have multiple series per league.** The `sport` parameter queries all of them automatically. For example, `search_markets(sport='epl')` queries KXEPLGAME, KXEPLTOTAL, KXEPLBTTS, KXEPLSPREAD, and KXEPLGOAL in one call.

## Other Football Series Tickers (raw API only)

**Note:** On Kalshi's API, "Football" = American Football (NFL). Football leagues are categorized under "Soccer" in Kalshi's taxonomy.

| League | Series Ticker | Notes |
|---|---|---|
| FA Cup | `KXFACUP` | Futures |
| Europa League | `KXUEL` | Futures |
| Conference League | `KXUECL` | Futures |

Not all football leagues have futures/winner markets. Use `get_sports_filters()` to discover all available competitions.

#!/bin/bash
# Validates kalshi parameters
COMMAND="${1:-}"

# Ticker format hints
if [[ "$*" == *"--series_ticker="* ]]; then
  TICKER=$(echo "$*" | grep -o '\-\-series_ticker=[^ ]*' | cut -d= -f2)
  if [[ ! "$TICKER" =~ ^KX ]]; then
    echo "WARNING: Kalshi series tickers typically start with 'KX' (e.g., KXNBA, KXNFL). Got: $TICKER"
  fi
fi

# Timestamp check for candlesticks
if [[ "$COMMAND" == "get_market_candlesticks" ]]; then
  if [[ "$*" != *"--start_ts="* || "$*" != *"--end_ts="* ]]; then
    echo "ERROR: get_market_candlesticks requires --start_ts and --end_ts (Unix timestamps)."
    exit 1
  fi
fi
echo "OK"