Kalshi Kernel

一个非官方、以安全为核心的 Kalshi 事件合约与永续市场 Model Context Protocol (MCP) 服务器。该服务器专为 Hermes 等代理框架设计，并暴露一个刻意精简的工具面，该工具面由 Kalshi 已发布的 API 合约生成。

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

[!CAUTION] 预发布软件——不可用于交易。 版本 0.1.1 是一个通过一致性测试的脚手架。目前仅有 kernel_status 可用。市场数据、投资组合、模拟交易和实盘交易适配器均未连接，并以 capability_not_ready 状态安全失败（fail closed）。

[!IMPORTANT] 本社区项目并非 Kalshi 官方产品，与 KalshiEX LLC 或其关联公司无关联、未获其背书、赞助或支持。“Kalshi” 仅用于标识与 Kalshi 已发布 API 的互操作性。

项目存在的原因

交易 API 覆盖面广，且针对应用程序开发者优化。代理需要更窄的边界，具备明确的意图、严格的模式、可预测的错误，以及模拟与真实资金执行之间的强隔离。Kalshi Kernel 提供了这一边界，同时持续针对最新的上游合约测试其生成的客户端。

设计优先级如下：

• 默认模拟模式（paper mode）；

• 进程生命周期内执行模式不可变；

• 实盘模式启用前需明确确认并提供凭据；

• 价格和数量使用定点字符串；

• 严格、生成式的工具模式并附带安全注解；

• 能力不可用时安全失败（fail-closed）；

• 与精确的 OpenAPI 操作和 AsyncAPI 通道保持可追溯的对齐；

• 可重复的 MCP 协议、竞态、模糊测试和上游漂移测试。

Related MCP server: MCP Server Kalshi

当前状态

请勿将本版本宣传、部署或依赖为可正常运作的交易集成。请参阅 ARCHITECTURE.md、THREAT_MODEL.md 以及 PUBLICATION.md 中的发布门禁。

面向代理的工具

已连接的 MCP 客户端还会收到服务器级指令，要求其首先调用 kernel_status，区分模拟模式与实盘模式，并且除非结构化响应中包含 ok: true，否则不得将任何操作报告为成功。

本地构建与运行

前置条件：

• Go 1.25.13 或更高版本；

• Node.js 22（仅用于官方 MCP 一致性测试运行器）；

• 受支持的 MCP 客户端。

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

当 KALSHI_KERNEL_MODE 未设置时，默认使用模拟模式。该模式会刻意丢弃实盘凭据配置。

Hermes

将本地 stdio 服务器添加到 ~/.hermes/config.yaml：

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"
      }
    }
  }
}

执行模式

模拟模式

KALSHI_KERNEL_MODE=paper ./bin/kalshi-kernel

模拟模式将在该后端实现后使用本地模拟账本。它绝不得向 Kalshi 提交订单。模拟成交不会预测或保证实盘成交、流动性、延迟、滑点、费用或盈利能力。

实盘模式

实盘模式被刻意设计为难以启用：

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

这些变量目前仅启用配置验证；尚未连接任何实盘执行适配器。切勿提交凭据、私钥或 .env 文件。在可用时使用短期凭据，在生产环境中使用密钥管理器，并使用权限和资金最少的账户或子账户。

规范驱动生成

精选的代理接口位于 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 还会每日运行，以便即使仓库处于空闲状态也能检测到漂移。

[!WARNING] 下载的 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 模式、工具标题和安全提示、安全失败行为、并发性以及 Streamable HTTP 协商。

分发与注册表

仓库包含官方 MCP Registry 的发布元数据，以及 OpenAI Plugins Directory 和 Anthropic 目录的提交档案。元数据是准备工作——并非批准、背书或发布的证据。

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

有关确切的渠道矩阵、当前阻塞项、发布步骤、收录文案和审查测试用例，请参阅 PUBLICATION.md。不会自动执行任何外部注册表提交。

贡献与安全

在提交拉取请求之前，请阅读 CONTRIBUTING.md。根据 SECURITY.md 私下报告漏洞；对于疑似凭据泄露或交易安全漏洞，请勿公开提交 issue。一般使用帮助请参见 SUPPORT.md。

法律与风险声明

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

AI 系统和软件可能误解意图、产生错误参数、重复请求或出现意外行为。在任何实盘部署之前，必须进行人工审查、交易所侧风险限制、最小权限凭据、监控以及独立的紧急停止机制。

请阅读完整的 DISCLAIMER.md、PRIVACY.md 和 SECURITY.md。本项目根据 Apache License 2.0 许可；第三方材料按 THIRD_PARTY_NOTICES.md 中的说明排除在外。