Kalshi Kernel

Неофициальный, ориентированный на безопасность сервер Model Context Protocol (MCP) для событийных контрактов Kalshi и вечных рынков. Сервер предназначен для агентских обвязок, таких как Hermes, и предоставляет намеренно ограниченную поверхность инструментов, сгенерированную из опубликованных API-контрактов Kalshi.

Официальный издатель: CopyleftDev. Планируемые релизы исходников и контейнеров используют github.com/copyleftdev/kalshi-kernel и ghcr.io/copyleftdev/kalshi-kernel соответственно.

[!CAUTION] Предрелизное программное обеспечение — не готово для торговли. Версия 0.1.1 — scaffold, прошедший проверку соответствия. Работает только kernel_status. Адаптеры рыночных данных, портфеля, бумажной и реальной торговли не подключены и завершаются с ошибкой capability_not_ready (fail closed).

[!IMPORTANT] Этот проект сообщества не является официальным продуктом Kalshi и не аффилирован с KalshiEX LLC или ее аффилиатами, не одобрен и не поддерживается ими. Название «Kalshi» используется только для обозначения совместимости с опубликованными API Kalshi.

Зачем существует этот проект

API Kalshi широки и оптимизированы для разработчиков приложений. Агентам нужна более узкая граница с явным намерением, предсказуемыми ошибками и строгим разделением между симуляцией и исполнением на реальные деньги, а также строгими схемами. Kalshi Kernel предоставляет эту границу и непрерывно тестирует свои сгенерированные клиенты на соответствие актуальным контрактам.

Приоритеты дизайна:

• бумажный режим по умолчанию;

• неизменяемый режим исполнения на время жизни процесса;

• явное подтверждение и учетные данные, прежде чем сможет активироваться live-режим;

• строки фиксированной точности для цен и объемов;

• сгенерированные строгие схемы инструментов с аннотациями безопасности;

• 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.5 или новее;

• Node.js 22 — только для официального раннера проверки соответствия MCP;

• поддерживаемый MCP-клиент.

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

Бумажный режим используется по умолчанию, когда KALSHI_KERNEL_MODE не задан. При этом конфигурация учетных данных live-режима намеренно игнорируется.

Hermes

Добавьте локальный stdio-сервер в ~/.hermes/config.yaml:

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

Затем вызовите kernel_status перед любым другим инструментом.

Claude Code

После сборки двоичного файла:

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

Перезапустите Hermes и вызовите kernel_status, прежде чем использовать другие инструменты. Сервер возвращает режим исполнения и готовность адаптеров.

Claude Code

После сборки бинарного файла выполните:

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

Затем запустите claude mcp list, чтобы убедиться, что сервер зарегистрирован.

Другие stdio-клиенты

Используйте стандартную конфигурацию MCP:

KALSHI_KERNEL_MODE=paper ./bin/kalshi-kernel

Режимы и безопасность

Режим «бумага» используется по умолчанию, если KALSHI_KERNEL_MODE не задан. Он намеренно игнорирует конфигурацию 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

Переменные окружения в настоящее время только активируют проверку конфигурации; сам адаптер live-исполнения не подключен. Никогда не коммитьте учетные данные. Используйте короткоживущие учетные данные там, где это возможно, и счет или субсчет с минимальными привилегиями.

Генерация на основе спецификаций

Курируемая граница инструментов агента описана в mcp-tools.yaml. Каждый инструмент сопоставлен с точными operation ID OpenAPI и каналами 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; версионируются только файл блокировки происхождения, курируемый оверлей 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

[!WARNING] Загруженные контракты содержат хотя бы часть исходных материалов апстрима и не покрываются лицензией Apache-2.0 этого проекта. Не коммитьте и не распространяйте их. См. THIRD_PARTY_NOTICES.md.

Проверка

Каждый запуск CI выполняет строгую проверку соответствия:

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

Проверяются безопасность транспорта, контракты аутентификации, безопасность мутаций, уникальность схемы, требуемые поля, поведение fail-closed, согласованность курируемой поверхности и переговоры по протоколу MCP.

Распространение и реестры

Репозиторий содержит метаданные для MCP Registry, а также материалы для подачи в каталоги Anthropic. Они подготовлены, но не отправлены автоматически.

Текущие рекомендации Anthropic запрещают передачу денег или финансовых активов коннекторами MCP. Любая публикация в каталоге Anthropic должна быть отдельным, только для чтения вариантом без торговых инструментов, соответствующим требованиям Anthropic.

Юридические и нормативные замечания

Данный проект не предоставляет инвестиционных, финансовых или торговых советов. Торговля событиями и вечными контрактами сопряжена с высоким риском и может привести к значительным потерям. Вы несете ответственность за соответствие требованиям, юрисдикционные ограничения, налоги, стратегию и исполнение ордеров.

См. DISCLAIMER.md, CONTRIBUTING.md и THREAT_MODEL.md. Лицензия — Apache-2.0, за исключением сторонних материалов, как указано в THIRD_PARTY_NOTICES.md.