Kalshi Kernel

Un servidor no oficial de Model Context Protocol (MCP) centrado en la seguridad para contratos de eventos y mercados perpetuos de Kalshi. El servidor está diseñado para arneses de agentes como Hermes y expone una superficie de herramientas deliberadamente pequeña generada a partir de los contratos de API publicados por Kalshi.

Editor canónico: CopyleftDev. Los lanzamientos planificados de código fuente y contenedores usan github.com/copyleftdev/kalshi-kernel y ghcr.io/copyleftdev/kalshi-kernel respectivamente.

[!CAUTION] Software de prelanzamiento: no listo para operar. La versión 0.1.1 es un andamiaje probado por conformidad. Solo kernel_status es operativo. Los adaptadores de datos de mercado, cartera, paper-trading y trading en vivo no están conectados y fallan de forma cerrada con capability_not_ready.

[!IMPORTANT] Este proyecto comunitario no es un producto oficial de Kalshi y no está afiliado, respaldado, patrocinado ni soportado por KalshiEX LLC o sus afiliados. "Kalshi" se usa únicamente para identificar la interoperabilidad con las API publicadas de Kalshi.

Por qué existe este proyecto

Las API de trading son amplias y están optimizadas para desarrolladores de aplicaciones. Los agentes necesitan un límite más estrecho con intención explícita, esquemas estrictos, errores predecibles y una separación fuerte entre simulación y ejecución con dinero real. Kalshi Kernel proporciona ese límite mientras prueba continuamente sus clientes generados contra los últimos contratos ascendentes.

Las prioridades de diseño son:

• modo paper por defecto;

• modo de ejecución inmutable durante la vida de un proceso;

• reconocimiento explícito y credenciales antes de que el modo en vivo pueda armarse;

• cadenas de punto fijo para precios y cantidades;

• esquemas de herramientas generados estrictos con anotaciones de seguridad;

• comportamiento de fallo cerrado cuando una capacidad no está disponible;

• alineación trazable con operaciones OpenAPI exactas y canales AsyncAPI; y

• pruebas repetibles de protocolo MCP, condiciones de carrera, fuzzing y deriva ascendente.

Related MCP server: MCP Server Kalshi

Estado actual

No anuncie, despliegue ni confíe en esta versión como una integración de trading funcional. Consulte ARCHITECTURE.md, THREAT_MODEL.md y las puertas de lanzamiento en PUBLICATION.md.

Herramientas orientadas al agente

Los clientes MCP conectados también reciben instrucciones a nivel de servidor que les indican llamar a kernel_status primero, distinguir el modo paper del modo en vivo y nunca informar una acción como exitosa a menos que su respuesta estructurada contenga ok: true.

Compilar y ejecutar localmente

Requisitos previos:

• Go 1.25.13 o superior;

• Node.js 22 solo para el ejecutor de conformidad MCP oficial; y

• un cliente MCP compatible.

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

El modo paper es el predeterminado cuando KALSHI_KERNEL_MODE no está definido. Descartar intencionalmente la configuración de credenciales en vivo.

Hermes

Agregue un servidor stdio local a ~/.hermes/config.yaml:

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

Reinicie Hermes y llame a kernel_status antes de cualquier otra herramienta.

Claude Code

Después de compilar el binario:

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

Luego ejecute claude mcp get kalshi-kernel o abra /mcp para confirmar la conexión. Esta configuración local es independiente del Directorio de Conectores público de Anthropic, que requiere un servidor remoto desplegado.

Otros clientes stdio

Use la forma de configuración MCP estándar:

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

Modos de ejecución

Modo paper

KALSHI_KERNEL_MODE=paper ./bin/kalshi-kernel

El modo paper usará un libro mayor simulado local después de que ese backend esté implementado. Nunca debe enviar una orden a Kalshi. Las ejecuciones simuladas no predecirán ni garantizarán ejecuciones en vivo, liquidez, latencia, deslizamiento, comisiones o rentabilidad.

Modo en vivo

El modo en vivo es deliberadamente difícil de habilitar:

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

Estas variables actualmente solo arman la validación de configuración; no hay ningún adaptador de ejecución en vivo conectado. Nunca comprometa credenciales, claves privadas o archivos .env. Use credenciales de corta duración cuando estén disponibles, un administrador de secretos en producción y una cuenta o subcuenta con los menores privilegios y capital requeridos.

Generación impulsada por especificaciones

La interfaz de agente curada vive en specs/mcp-tools.yaml. Mapea cada herramienta MCP a IDs de operación OpenAPI exactos y canales AsyncAPI. Los endpoints administrativos y de gestión de cuentas no se exponen automáticamente solo porque existan aguas arriba.

Se obtienen cuatro contratos autorizados de https://docs.kalshi.com:

• openapi.yaml — API REST de contratos de eventos;

• asyncapi.yaml — API WebSocket de contratos de eventos;

• perps_openapi.yaml — API REST de perpetuos; y

• perps_asyncapi.yaml — API WebSocket de perpetuos.

El buscador fija HTTPS y el nombre de host de origen, limita los tamaños de respuesta, valida el dialecto esperado y la superficie no vacía, y registra hashes y procedencia HTTP. Los cuerpos de contrato ascendentes son ignorados por Git y se obtienen en una caché local según sea necesario. Los clientes REST derivados de aguas arriba también se generan localmente y se excluyen de los lanzamientos de código fuente. Solo el bloqueo de procedencia, la superposición MCP curada y el límite de herramientas MCP generado están versionados. La regeneración y las pruebas ocurren en una copia temporal del repositorio antes de que se pueda promover un bloqueo probado y un límite 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

Cada ejecución de CI realiza la verificación estricta ascendente; CI también se ejecuta diariamente para que la deriva se detecte incluso cuando el repositorio está inactivo.

[!WARNING] Los archivos de contrato de Kalshi descargados identifican al menos parte del material ascendente como propietario. No están cubiertos por la licencia Apache-2.0 de este proyecto y no deben comprometerse ni redistribuirse. Revise THIRD_PARTY_NOTICES.md antes de publicar artefactos generados.

Verificación

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

El conjunto verifica seguridad del transporte, contratos de autenticación, seguridad de mutaciones, unicidad de IDs de operación, tipos de punto fijo, área de superficie curada, paridad de campos requeridos, esquemas JSON estrictos, títulos de herramientas y sugerencias de seguridad, comportamiento de fallo cerrado, concurrencia y negociación HTTP Streamable.

Distribución y registros

El repositorio contiene metadatos de publicación para el Registro MCP oficial y expedientes de envío para el Directorio de Plugins de OpenAI y los directorios de Anthropic. Los metadatos son preparación, no evidencia de aprobación, respaldo o publicación.

Los criterios actuales de revisión de conectores de Anthropic no aceptan conectores que transfieran dinero u otros activos financieros. Por lo tanto, cualquier compilación de este proyecto para el Directorio de Conectores de Claude debe ser un artefacto distinto de solo lectura y/o solo paper con las herramientas de órdenes en vivo omitidas, sujeto a la revisión de Anthropic.

Consulte PUBLICATION.md para la matriz de canales exacta, los bloqueadores actuales, los pasos de lanzamiento, el texto del listado y los casos de prueba de revisión. No se realiza ningún envío automático a registros externos.

Contribución y seguridad

Lea CONTRIBUTING.md antes de abrir una solicitud de extracción. Reporte vulnerabilidades de forma privada según SECURITY.md; no abra un problema público por una sospecha de fuga de credenciales o una vulnerabilidad de seguridad de trading. La ayuda general de uso pertenece a SUPPORT.md.

Aviso legal y de riesgo

Este software se proporciona para desarrollo e investigación. No proporciona asesoramiento de inversión, financiero, legal, fiscal, de cumplimiento o de trading. Los contratos de eventos y los productos apalancados pueden resultar en pérdidas rápidas y sustanciales, incluida la pérdida de la totalidad del monto comprometido. Usted es responsable de la elegibilidad de la cuenta, las restricciones jurisdiccionales, las reglas del intercambio, los requisitos regulatorios, los impuestos, la estrategia, las órdenes y las pérdidas.

Los sistemas de IA y el software pueden malinterpretar la intención, producir parámetros incorrectos, repetir solicitudes o comportarse inesperadamente. Se requiere revisión humana, límites de riesgo del lado del intercambio, credenciales de privilegio mínimo, monitoreo y una parada de emergencia independiente antes de cualquier despliegue en vivo.

Lea el DISCLAIMER.md completo, PRIVACY.md y SECURITY.md. El proyecto está licenciado bajo Apache License 2.0; el material de terceros se excluye como se describe en THIRD_PARTY_NOTICES.md.