Kalshi Kernel

Kalshi Kernel

一个面向 Kalshi 事件合约和永续市场的非官方、安全优先的模型上下文协议（MCP）服务。本项目处于预发布阶段，尚未准备好用于交易。该服务专为 Hermes 等 Agent 运行框架设计，其工具集刻意保持精简，并根据 Kalshi 发布的 API 合约生成。

官方发布者：CopyleftDev。计划发布的源码和容器分别使用 github.com/copyleftdev/kalshi-kernel 和 ghcr.io/copyleftdev/kalshi-kernel。

注意

**预发布软件，可能提交真实订单。**已发布的标签是经过一致性测试的脚手架；当前的 main 分支增加了市场数据、模拟交易和实时事件合约适配器。配置为实时模式后，可以下单、修改和取消真实订单。使用凭据运行前，请检查确切的 提交、配置、测试和限制；不要根据版本字符串推断其已准备就绪。

重要

这个社区项目不是 Kalshi 的官方产品，也不隶属于 KalshiEX LLC 或其关联公司，未获其认可、赞助或支持。“Kalshi”仅用于说明与 Kalshi 已发布 API 的互操作性。

独立的 Kernel 标志遵循对 Kalshi 已发布的颜色、对比度、留白和误用指南的保守解读。它未使用或修改 Kalshi 的标志。请参阅视觉识别使用规则。

项目缘起

交易 API 功能广泛，针对应用开发者进行了优化。Agent 需要更精简的边界，具备明确的意图、严格的架构、可预测的错误，以及模拟与真实资金执行之间的强隔离。Kalshi Kernel 提供了这样的边界，同时持续根据最新的上游合约测试其生成的客户端。

设计优先事项包括：

• 默认使用模拟模式；
• 在进程的整个生命周期内保持执行模式不可变；
• 启用实时模式前，必须明确确认并提供凭据；
• 价格和数量使用定点数字字符串；
• 使用严格的生成式工具架构，并附带安全注释；
• 能力不可用时安全失败；
• 可追溯地对齐确切的 OpenAPI 操作和 AsyncAPI 通道；以及
• 可重复进行 MCP 协议、竞态、模糊测试和上游变更测试。

当前状态

此表描述的是当前的 main 分支，而非已发布的 v0.1.1 标签。 新增内容尚未发布，版本元数据也尚未更新。

区域	当前行为和限制
MCP stdio 传输和生成的架构	正常运行
公开市场数据	事件合约和永续合约：搜索、市场详情、REST 订单簿快照、K 线和最新报价。公开成交记录仅支持事件合约
模拟交易	内存中的余额、持仓、成交日志、精确的定点费用，以及按当前显示的盘口价即时全部成交或不成交
实时投资组合	已验证身份的事件合约余额、持仓、订单和成交记录。不支持永续合约账户和非主账户
实时事件合约订单	下单、修改和撤单已接入生产 API。下单和修改要求进程本地启用，并受内核侧限制；撤单会检查挂单状态并在超时后进行核对
实时永续合约订单	尚未实现
订单簿流式核对	尚未实现；get_orderbook 当前仅返回一份公开 REST 快照
kernel_status	可调用，但部分就绪状态和启用状态字段仍反映旧脚手架，不应视为权威信息
上游规范自动新鲜度检查	正常运行
生产级远程 HTTPS/OAuth 服务	尚未实现
公开注册表列表	已准备，尚未提交

请将当前分支视为开发中的软件，而非已发布或经过审计的交易集成。部分设计和发布文档仍描述 v0.1.1 脚手架；依赖相关说法前，请先与实际实现进行核对。请参阅 ARCHITECTURE.md、THREAT_MODEL.md 以及 PUBLICATION.md 中的发布门槛。

面向 Agent 的工具

工具	类别	当前行为
kernel_status	只读	返回模式和就绪状态信息；新增的后端和启用状态尚未准确反映
search_markets	只读	通过公开 REST 搜索事件合约或永续合约市场
get_market	只读	返回单个事件合约或永续合约市场的权威元数据
get_orderbook	只读	返回任一产品的公开 REST 快照，其中包含 yes/no 买单价位
get_candles	只读	返回事件合约或永续合约的 1、60 或 1440 分钟 OHLC 区间
get_trades	只读	返回一页通过游标分页的公开事件合约成交记录
get_last	只读	返回简洁的事件合约或永续合约报价和状态快照
arm_live_trading	破坏性／控制	在收到完全一致的二次确认后，为此进程启用或禁用实时下单／修改调用
get_portfolio	只读	在模拟模式下返回本地模拟账本；在实时模式下返回经过身份验证的事件合约投资组合
place_order	破坏性／写入	在模拟模式下模拟即时成交；在实时模式下提交已启用且受限额控制的事件合约订单
amend_order	破坏性／写入	模拟模式下没有挂单；实时模式下修改已启用的挂单事件合约订单
cancel_order	破坏性／写入	模拟模式下没有挂单；实时模式下检查状态并撤销挂单事件合约订单

连接的 MCP 客户端还会收到服务级指令，要求其先调用 kernel_status、区分模拟模式和实时模式，并且只有在结构化响应包含 ok: true 时才能报告操作成功。在就绪状态报告更新之前，请根据 arm_live_trading 的响应确认实时启用状态，而不要依赖 kernel_status。

在本地构建和运行

前置条件：

• Go 1.25.13 或更高版本；
• 仅官方 MCP 一致性运行器需要 Node.js 22；以及
• 受支持的 MCP 客户端。

make test
make build
KALSHI_KERNEL_MODE=paper ./bin/kalshi-kernel

如果未设置 KALSHI_KERNEL_MODE，默认使用 Paper 模式。该模式会有意丢弃实时凭证配置。

Hermes

在 ~/.hermes/config.yaml 中添加本地 stdio 服务：

mcp_servers:
  kalshi-kernel:
    command: "/absolute/path/to/kalshi-kernel/bin/kalshi-kernel"
    env:
      KALSHI_KERNEL_MODE: "paper"

重启 Hermes，并在调用任何其他工具前调用 kernel_status。

Claude Code

构建二进制文件后：

claude mcp add --scope user --transport stdio kalshi-kernel \
  --env KALSHI_KERNEL_MODE=paper -- /absolute/path/to/bin/kalshi-kernel

然后运行 claude mcp get kalshi-kernel，或打开 /mcp，确认连接正常。此本地设置与 Anthropic 的公共 Connectors Directory 相互独立；后者需要部署远程服务。

其他 stdio 客户端

使用标准 MCP 配置格式：

{
  "mcpServers": {
    "kalshi-kernel": {
      "command": "/absolute/path/to/bin/kalshi-kernel",
      "env": {
        "KALSHI_KERNEL_MODE": "paper"
      }
    }
  }
}

执行模式

Paper 模式

KALSHI_KERNEL_MODE=paper ./bin/kalshi-kernel

Paper 模式使用内存中的模拟账本，绝不会向 Kalshi 提交订单。默认初始余额为 $100.00；启动前设置 KALSHI_PAPER_CASH_DOLLARS 可选择其他余额。进程退出时，账本、持仓、幂等记录和成交日志都会重置。

place_order 会获取最新的公开订单簿快照，且仅支持即时、全有或全无的可成交订单。请求价格必须与当前最优报价完全一致，且显示数量必须足以满足全部订单数量。模拟器使用定点运算，应用已公布的费用公式，记录所用订单簿的哈希值，并将 client_order_id 视为幂等键。由于 Paper 订单不会挂单，amend_order 和 cancel_order 会返回类型化失败结果。

每个 Paper 响应都会标记为 simulated: true。模拟成交不代表也不保证实际成交、流动性、延迟、滑点、费用或盈利能力。

Live 模式

Live 模式的启用经过刻意设计，难以操作：

KALSHI_KERNEL_MODE=live
KALSHI_API_KEY_ID=...
KALSHI_PRIVATE_KEY_PATH=/absolute/path/to/private-key.pem
KALSHI_LIVE_TRADING_ACK=I_UNDERSTAND_THIS_TRADES_REAL_MONEY

# Optional startup-only overrides; these are the defaults.
KALSHI_MAX_ORDER_NOTIONAL_DOLLARS=25.00
KALSHI_MAX_DAILY_NOTIONAL_DOLLARS=100.00
KALSHI_MAX_DAILY_ORDERS=200

启动配置会选择不可变的 Live 模式，并启用经过身份验证的事件合约投资组合读取和取消操作。但这不会授权 place/amend 调用。这些调用还需要执行第二个进程本地 MCP 操作：

{
  "acknowledgement": "I_UNDERSTAND_THIS_TRADES_REAL_MONEY",
  "arm": true
}

将该对象传递给 arm_live_trading；取消启用时，传递相同对象并设置 arm: false。启用状态绝不会持久化。place_order 还要求提供稳定且由调用方指定的 client_order_id。如果 place/amend 请求超出仅能在启动时设置的单笔订单限额、UTC 日名义金额限额或 UTC 日订单数量限额，系统会在提交前拒绝请求。这些计数器仅存在于进程本地，并会在进程重启时重置。

警告

在已配置的 Live 模式下，无需单独执行 arm_live_trading 步骤即可使用 cancel_order。它会先验证订单是否处于挂单状态，再发送取消请求。Place/amend 会验证价格语法和名义金额限额，但当前实现不会独立将请求的限价与最新报价进行比较。请使用交易所端限额、最小权限凭证、人工审核、监控和独立的紧急停止机制。

Live 账户读取和写入目前仅支持事件合约。 永续账户操作和非主子账户不可用；请省略 subaccount 或传入 0。写入后发生网络故障时，系统会返回经过核对或明确标记为结果不确定的状态，而不是盲目重试。

切勿提交凭证、私钥或 .env 文件。尽可能使用短期凭证，在生产环境中使用密钥管理器，并使用仅具备所需权限和资金的账户。

规范驱动的生成

精选的 Agent 接口位于 specs/mcp-tools.yaml。它将每个 MCP 工具映射到精确的 OpenAPI 操作 ID 和 AsyncAPI 通道。上游存在的管理和账户管理端点不会因此自动公开。

四份权威契约从 https://docs.kalshi.com 获取：

• openapi.yaml — 事件合约 REST API；
• asyncapi.yaml — 事件合约 WebSocket API；
• perps_openapi.yaml — 永续合约 REST API；以及
• perps_asyncapi.yaml — 永续合约 WebSocket API。

获取器固定使用 HTTPS 和源主机名，限制响应大小，验证预期方言和非空接口，并记录哈希和 HTTP 来源信息。上游契约正文会被 Git 忽略，并按需获取到本地缓存。基于上游契约生成的 REST 客户端也会在本地生成，并从源代码发行包中排除。只有来源锁定文件、精选 MCP 覆盖配置和生成的 MCP 工具边界会纳入版本控制。重新生成和测试会在临时的仓库副本中进行，只有经过测试的锁定文件和 MCP 边界才能被提升。

make upstream-test      # test latest contracts without requiring snapshot parity
make upstream-check     # require parity and run MCP conformance
make upstream-promote   # promote only the exact artifacts that passed

每次 CI 运行都会执行严格的上游检查；CI 也会每天运行，以便即使仓库处于闲置状态也能检测到变更。

警告

下载的 Kalshi 契约文件表明，至少部分上游材料属于专有内容。它们不受本项目 Apache-2.0 许可证的约束，且不得提交或重新分发。发布生成的构件前，请阅读 THIRD_PARTY_NOTICES.md。

验证

make test              # unit, integration, and contract alignment tests
make test-alignment    # OpenAPI, AsyncAPI, and MCP overlay alignment
make check-generated   # deterministic generated-code check
make test-race         # concurrent calls under Go's race detector
make test-fuzz         # execution-mode parser safety fuzzing
make conformance       # pinned official MCP protocol scenarios
make release-test      # complete local release gate
make public-check      # vulnerability, metadata, and public-readiness gate
make upstream-check    # latest Kalshi contracts plus conformance

测试套件会检查传输安全、身份验证契约、变更操作安全性、操作 ID 唯一性、定点数类型、精选接口范围、必填字段一致性、严格 JSON Schema、工具标题和安全提示、失败关闭行为、并发，以及 Streamable HTTP 协商。

分发和注册目录

仓库包含用于官方 MCP Registry 的发布元数据，以及提交至 OpenAI Plugins Directory 和 Anthropic 目录的材料。元数据仅用于准备，不代表已获批准、认可或发布。

Anthropic 当前的连接器审核标准不接受会转移资金或其他金融资产的连接器。因此，本项目面向 Claude Connectors Directory 的任何构建都必须是独立的只读和/或仅模拟交易构件，并省略实时下单工具，且须经过 Anthropic 审核。

请参阅 PUBLICATION.md，了解准确的渠道矩阵、当前阻碍事项、发布步骤、上架文案和审核测试用例。不会自动向任何外部注册目录提交内容。

贡献和安全

提交拉取请求前，请阅读 CONTRIBUTING.md。请按照 SECURITY.md 中的说明私下报告漏洞；如果怀疑存在凭据泄露或交易安全漏洞，请勿创建公开问题。一般使用帮助请参阅 SUPPORT.md。

法律和风险声明

本软件仅供开发和研究使用。它不提供投资、金融、法律、税务、合规或交易建议。事件合约和杠杆产品可能导致迅速且重大的损失，包括损失全部投入金额。您须自行负责账户资格、司法管辖区限制、交易所规则、监管要求、税务、策略、订单和损失。

AI 系统和软件可能误解意图、生成错误参数、重复请求或出现意外行为。在任何实盘部署前，必须进行人工审核，设置交易所端风险限额，使用最小权限凭据，进行监控，并配备独立的紧急停止机制。

请阅读完整的 DISCLAIMER.md、PRIVACY.md 和 SECURITY.md。本项目依据 Apache License 2.0 授权；第三方材料不在许可范围内，具体说明见 THIRD_PARTY_NOTICES.md。