kalshi-agent

Kalshi 预测市场代理 - 通过 Kalshi v2 API 分析市场并执行交易

# Kalshi Agent Skill

CLI tool for trading prediction markets on [Kalshi](https://kalshi.com).

## Installation

```bash
npm install -g kalshi-cli
```

## Configuration

1. Get API credentials at: https://kalshi.com/api
2. Place your RSA private key at `~/.kalshi/private_key.pem`
3. Set your access key in `~/.kalshi/.env`:

```
KALSHI_ACCESS_KEY=your_access_key_id
```

Or run `kalshi setup-shell` to add it to your shell config.

---

## Commands

### Browse & Research

```bash
# List open markets (default 20)
kalshi markets
kalshi markets -l 50
kalshi markets --status settled

# Search by keyword, ticker, or category
kalshi search "Super Bowl"
kalshi search soccer
kalshi search hockey
kalshi search KXWO-GOLD-26

# Search with filters
kalshi search politics --min-odds 5     # hide markets where either side < 5%
kalshi search soccer --expiring          # sort by soonest expiry, show expiry column
kalshi search soccer -e -m 2 -l 20      # combine flags: expiring, 2% min-odds, 20 results

# Browse all active series (interactive — pick a number to drill down)
kalshi series
kalshi series soccer
kalshi series --all                      # include series with no active markets
kalshi series -e                         # sort by soonest expiry

# View single market detail
kalshi detail KXWO-GOLD-26-NOR

# View orderbook depth
kalshi orderbook KXWO-GOLD-26-NOR
```

### Search Behavior

Search uses a multi-strategy approach:

1. **Direct ticker lookup** — tries the query as a market ticker, event ticker (`KX` prefix), or series ticker
2. **Series matching** — dynamically searches all Kalshi series by title, category, and tags (e.g. "soccer" matches series tagged "Soccer")
   - If many series match, shows an **interactive numbered list** — enter a number to drill into that series' markets
   - If few series match, fetches and displays markets directly
3. **Market title search** — falls back to searching open market titles/tickers

Common sport/category aliases are expanded automatically (e.g. "nfl" also searches "football").

### Interactive Series Lists

Both `kalshi search` and `kalshi series` display numbered tables when listing series. After the table, you're prompted:

```
Enter # to drill down (or q to quit):
```

Pick a number to load that series' open markets inline. The prompt loops so you can explore multiple series without re-running the command.

### Portfolio

```bash
# Check balance
kalshi balance

# View positions
kalshi positions

# View open orders
kalshi orders
```

### Trading

```bash
# Buy 10 YES contracts at 68c each
kalshi buy KXSB-26 10 68

# Buy NO contracts
kalshi buy KXWO-GOLD-26-NOR 5 32 --side no

# Sell (same syntax)
kalshi sell KXWO-GOLD-26-NOR 5 40 --side no

# Skip confirmation prompt
kalshi buy KXSB-26 10 68 --force

# Cancel an open order
kalshi cancel <order-id>
```

### Notes

- Prices are in **cents** (68 = $0.68 = 68% implied probability)
- Prices display as both dollars and percentages (e.g. `$0.68 (68%)`)
- `--side` defaults to `yes` if not specified
- `buy` and `sell` show a cost/proceeds summary and ask for confirmation (bypass with `--force`)
- `--min-odds` / `-m` filters out markets where either side's bid is below a percentage threshold (default 0.5%)
- `--expiring` / `-e` sorts results by soonest expiry, adds an "Expires" column, and excludes already-expired entries
- Expiry times are human-readable: "8h 35m", "Fri 04:00PM", "Apr 01", "Jan 01, 2027"
- Event tickers start with `KX` (e.g. `KXWO-GOLD-26`); market tickers have more segments (e.g. `KXWO-GOLD-26-NOR`)
- Market tables show outcome names (e.g. "Norway" instead of raw tickers) when available

---

## API Reference

Full API docs: https://docs.kalshi.com/api-reference/

---

## 中文说明

# Kalshi Agent Skill

用于在 [Kalshi](https://kalshi.com) 上交易预测市场的 CLI 工具。

## 安装

```bash
npm install -g kalshi-cli
```

## 配置

1. 在此处获取 API 凭据：https://kalshi.com/api
2. 将你的 RSA 私钥放在 `~/.kalshi/private_key.pem`
3. 在 `~/.kalshi/.env` 中设置你的访问密钥：

```
KALSHI_ACCESS_KEY=your_access_key_id
```

或运行 `kalshi setup-shell` 将其添加到你的 shell 配置中。

---

## 命令

### 浏览与研究

```bash
# List open markets (default 20)
kalshi markets
kalshi markets -l 50
kalshi markets --status settled

# Search by keyword, ticker, or category
kalshi search "Super Bowl"
kalshi search soccer
kalshi search hockey
kalshi search KXWO-GOLD-26

# Search with filters
kalshi search politics --min-odds 5     # hide markets where either side < 5%
kalshi search soccer --expiring          # sort by soonest expiry, show expiry column
kalshi search soccer -e -m 2 -l 20      # combine flags: expiring, 2% min-odds, 20 results

# Browse all active series (interactive — pick a number to drill down)
kalshi series
kalshi series soccer
kalshi series --all                      # include series with no active markets
kalshi series -e                         # sort by soonest expiry

# View single market detail
kalshi detail KXWO-GOLD-26-NOR

# View orderbook depth
kalshi orderbook KXWO-GOLD-26-NOR
```

### 搜索行为

搜索采用多策略方式：

1. **直接 ticker 查找** —— 将查询作为市场 ticker、事件 ticker（`KX` 前缀）或系列 ticker 尝试
2. **系列匹配** —— 按标题、类别和标签动态搜索所有 Kalshi 系列（例如 "soccer" 匹配标记为 "Soccer" 的系列）
   - 如果有许多系列匹配，会显示一个**交互式编号列表**——输入编号即可深入该系列的市场
   - 如果只有少数系列匹配，会直接获取并显示市场
3. **市场标题搜索** —— 退而搜索开放市场的标题/ticker

常见的运动/类别别名会被自动展开（例如 "nfl" 也会搜索 "football"）。

### 交互式系列列表

`kalshi search` 和 `kalshi series` 在列出系列时都会显示编号表格。表格之后，会提示你：

```
Enter # to drill down (or q to quit):
```

选择一个编号即可内联加载该系列的开放市场。该提示会循环出现，因此你无需重新运行命令即可探索多个系列。

### 投资组合

```bash
# Check balance
kalshi balance

# View positions
kalshi positions

# View open orders
kalshi orders
```

### 交易

```bash
# Buy 10 YES contracts at 68c each
kalshi buy KXSB-26 10 68

# Buy NO contracts
kalshi buy KXWO-GOLD-26-NOR 5 32 --side no

# Sell (same syntax)
kalshi sell KXWO-GOLD-26-NOR 5 40 --side no

# Skip confirmation prompt
kalshi buy KXSB-26 10 68 --force

# Cancel an open order
kalshi cancel <order-id>
```

### 注意事项

- 价格以**美分**为单位（68 = $0.68 = 68% 的隐含概率）
- 价格同时显示为美元和百分比（例如 `$0.68 (68%)`）
- 若未指定，`--side` 默认为 `yes`
- `buy` 和 `sell` 会显示成本/收益摘要并请求确认（用 `--force` 绕过）
- `--min-odds` / `-m` 会过滤掉任一方报价低于某百分比阈值的市场（默认 0.5%）
- `--expiring` / `-e` 按最近到期排序，添加一个 "Expires" 列，并排除已过期的条目
- 到期时间采用人类可读格式："8h 35m"、"Fri 04:00PM"、"Apr 01"、"Jan 01, 2027"
- 事件 ticker 以 `KX` 开头（例如 `KXWO-GOLD-26`）；市场 ticker 有更多分段（例如 `KXWO-GOLD-26-NOR`）
- 市场表格在可用时显示结果名称（例如显示 "Norway" 而非原始 ticker）

---

## API 参考

完整 API 文档：https://docs.kalshi.com/api-reference/