OctagonAI/kalshi-trading-bot-cli

源码：https://github.com/OctagonAI/kalshi-trading-bot-cli

Kalshi 交易机器人 CLI

AI 驱动的 Kalshi 命令行交易工具，自动发现优势并执行下单。对每一个市场都做深度基本面研究——独立概率估算、核心驱动因素排序、事件日历——然后计算模型价格与实时盘口之间的价差作为“优势”。信号按半凯利（half-Kelly）仓位管理，并通过 5 道风控闸门后才投入真金白银。
集成 Octagon Research API（https://app.octagonai.co），用 AI 生成的概率估算为优势检测引擎提供火力。

Kalshi 交易机器人 CLI

前置条件

• Bun（https://bun.com/）≥ 1.1（必需——脚本依赖 bun:sqlite 并直接运行 .tsx，Node.js 无法使用）

  curl -fsSL https://bun.com/install | bash
  

• Kalshi 账户并开通 API（需 API key + RSA 私钥）
• 任意 LLM 供应商密钥（OpenAI / Anthropic / Google / xAI / OpenRouter / Ollama）。首次运行时会通过设置向导收集。
• 可选：Octagon（https://app.octagonai.co）密钥用于 AI 优势分析，Tavily 密钥用于网络研究。

快速开始

bunx kalshi-trading-bot-cli@latest

无需克隆、无需安装，首次启动自动进入设置向导。
想全局安装？

bun add -g kalshi-trading-bot-cli

然后直接 kalshi 即可。
或者克隆运行：

git clone https://github.com/OctagonAI/kalshi-trading-bot-cli.git
cd kalshi-trading-bot-cli
bun install
bun start

文件位置

• 配置、缓存、SQLite 数据库： ~/.kalshi-bot/
• API 密钥（.env）： ~/.kalshi-bot/.env——由设置向导生成。当前目录下的 .env 优先级更高（开发时方便）。
• 首次无密钥启动会自动弹出设置向导。

更新

bunx 命令里加 @latest 永远拉最新版：

bunx kalshi-trading-bot-cli@latest

若之前没加 @latest，Bun 可能用缓存，可强制刷新：

bunx kalshi-trading-bot-cli@latest      # 本次强制最新
bun pm cache rm                         # 或清空 Bun 安装缓存

全局安装后：

bun update -g kalshi-trading-bot-cli    # 就地更新
bun add -g kalshi-trading-bot-cli@latest # 或重装到最新

查看版本：kalshi --version（或 bun pm ls -g | grep kalshi）

会话示例

$ bunx kalshi-trading-bot-cli@latest
Welcome to Kalshi Trading Bot CLI
Type help for commands, or just ask a question.
> search crypto
Ticker               Title                                  Last   Volume
KXBTC-26APR-B95000   Bitcoin above $95k by Apr 30         $0.58  12,841
KXBTC-26APR-B100000  Bitcoin above $100k by Apr 30        $0.31  8,203
KXETH-26APR-B2000    Ethereum above $2k by Apr 30         $0.72  5,419
3 markets found
> analyze KXBTC-26APR-B95000
Octagon Research Report — KXBTC-26APR-B95000
───────────────────────────────────────────────
Model Probability     72%
Market Price          58%
Edge                  +14.0% (very_high confidence)
Top Drivers
1. Bitcoin ETF inflows accelerating   impact: high
2. Halving cycle momentum              impact: high
3. Macro risk-on sentiment             impact: moderate
Kelly Sizing
Recommended: 3 contracts YES at $0.58
Risk gates: ✓ Kelly ✓ Liquidity ✓ Correlation ✓ Concentration ✓ Drawdown
> buy KXBTC-26APR-B95000 3 58
✓ Order placed: BUY 3 YES @ $0.58
Order ID: abc-123-def
> portfolio
Ticker                  Side  Qty  Entry  Now   Edge  P&L
KXBTC-26APR-B95000      YES   3    $0.58  $0.61 +11.0% +$0.09
Cash: $487.26 · Exposure: $1.74 · Positions: 1

命令

参数

回测

模型到底有没有真优势？回看 N 天，把模型当时的预测与现在市场结果对比。

• 已结算——按 Kalshi 最终结算评分（YES=100%，NO=0%）
• 未结算——按当前 Kalshi 交易价格盯市

方法论（与 Supabase 参考一致）：

• 每条合约的 mp/kp 取自对应 Octagon 快照的 outcome_probabilities，不回落到事件级。
• 可交易性闸门优先用快照里的单合约 volume/volume_24h；若无则回退到缓存里 Kalshi 终身成交量。
• --min-edge 默认 0.5pp，让 0-5% 优势桶可见；每条信号打 edge_bucket 标签（0-5%、5-10% … 90%+）。
• flat_bet_roi 按资本加权：sum(pnl) / sum(capital)，其中 YES 优势 capital = kp/100，NO 优势 capital = (100-kp)/100。

kalshi backtest                      # 默认 15 天回看
kalshi backtest --days 30            # 30 天回看
kalshi backtest --max-age 14         # 只评 <=14 天的预测
kalshi backtest --resolved           # 仅已结算
kalshi backtest --unresolved --min-edge 10  # 未结算且优势≥10pp
kalshi backtest --category crypto    # 仅加密类别
kalshi backtest --min-volume 10 --min-price 5 --max-price 95  # 可交易过滤
kalshi backtest --export results.csv # 导出明细

Octagon Backtest — 15-day lookback (04/02 – 04/17)
══════════════════════════════════════════════════════════
VERDICT: Model has edge (Skill +12.5% [CI: +4.1%, +20.8%]; ROI +7.8%)
Events                83
Markets               247 (142 resolved, 105 unresolved)
Brier (Octagon)       0.168
Brier (Market)        0.192
Skill Score           +12.5% [95% CI: +4.1% to +20.8%]
Hit rate              61.4% [95% CI: 54.2% to 68.1%]
Flat-bet P&L          +$14.38 (ROI: +7.8%)

RESOLVED (142 markets)
Ticker                    Model  Mkt Then  Outcome  Edge  P&L
KXBTC-26APR-B95000        72%    58%       YES      +14pp +$0.42
...

UNRESOLVED (105 markets)
Ticker                    Model  Mkt Then  Now   Edge  M2M
KXBTC-26MAY-B110000       71%    58%       68%   +13pp +$0.10
...

演示模式

在 .env 里设置 KALSHI_USE_DEMO=true 即可接入 Kalshi 模拟环境，所有下单均为虚拟，不投入真金。

代理调用

所有命令都支持 --json 结构化输出，方便脚本或 AI 代理编排。

kalshi search crypto --json
kalshi analyze KXBTC-26APR-B95000 --json
kalshi buy KXBTC-26APR-B95000 3 58 --json
kalshi portfolio --json

JSON 响应格式

统一信封：

{
  "ok": true,
  "command": "analyze",
  "data": {
    "ticker": "KXBTC-26APR-B95000",
    "modelProb": 0.72,
    "marketProb": 0.58,
    "edge": 0.14,
    "confidence": "very_high",
    "drivers": [
      { "claim": "Bitcoin ETF inflows accelerating", "impact": "high" }
    ]
  },
  "meta": {
    "octagon_credits_used": 3,
    "octagon_cache_hits": 0
  },
  "timestamp": "2026-03-30T10:00:00.000Z"
}

失败返回 "ok": false 并带 error 对象。退出码 0 成功，1 失败。

编排示例

# 1. 找市场
MARKETS=$(kalshi search crypto --json | jq '.data')
# 2. 分析首选
ANALYSIS=$(kalshi analyze KXBTC-26APR-B95000 --json)
EDGE=$(echo "$ANALYSIS" | jq '.data.edge')
# 3. 优势够大就下单
if (( $(echo "$EDGE > 0.05" | bc -l) )); then
  kalshi buy KXBTC-26APR-B95000 3 58 --json
fi
# 4. 查持仓
kalshi portfolio --json

watch --theme 输出 NDJSON（每行一个 JSON），适合流式管道。

配置

环境变量

设置向导（首次自动或 kalshi init）会交互式完成。手动编辑：

cp env.example ~/.kalshi-bot/.env

必填：

可选：

注意： 默认模型 GPT-5.4。若换供应商，请用 config 命令切换，否则缺 OPENAI_API_KEY 会报错。

Octagon 额度

每份报告 3 额度。报告按到期临近程度分级缓存——快关市的市场缓存时间更短。用 --refresh 强制刷新。
可用 config octagon.daily_credit_ceiling <N> 设置每日上限。

运行时设置

kalshi config                          # 列出所有设置
kalshi config risk.kelly_multiplier    # 查看某值
kalshi config risk.kelly_multiplier 0.3 # 设置值

架构

Kalshi 交易流程
CLI 与两大外部服务通信：Kalshi 交易所 API（行情、下单、持仓）与 Octagon 研究 API（AI 概率、驱动因素）。结果缓存在本地 SQLite，减少调用与额度消耗。

LLM 供应商

默认 GPT-5.4，可用 config 命令切换。

开发

bun dev          # 热重载开发模式
bun run typecheck # 类型检查
bun test         # 跑测试

遥测

本应用收集匿名使用遥测以改进产品。绝不收集任何个人数据、API 密钥、交易详情或自然语言输入。 仅追踪命令名、工具使用、耗时与成败指标。
遥测默认开启。关闭方式：
在 .env 添加

TELEMETRY_ENABLED=false

或运行前设置环境变量：

TELEMETRY_ENABLED=false bunx kalshi-trading-bot-cli@latest

文档

详见 用户指南 获取详细用法、示例与技巧。

Star History

许可证

MIT 许可证 — 详见 LICENSE。