Kalshi Kernel

Ein inoffizieller, sicherheitsorientierter Model Context Protocol (MCP)-Server für Kalshi-Event-Kontrakte und Perpetual-Märkte. Der Server ist für Agent-Umgebungen wie Hermes gedacht und zeigt eine bewusst kleine Tool-Oberfläche, die aus Kalshis veröffentlichten API-Verträgen generiert wird.

Kanonischer Herausgeber: CopyleftDev. Geplante Source- und Container-Releases verwenden github.com/copyleftdev/kalshi-kernel bzw. ghcr.io/copyleftdev/kalshi-kernel.

[!CAUTION] Vorabversion – nicht handelsbereit. Version 0.1.1 ist ein konformitätsgetestetes Grundgerüst. Nur kernel_status ist funktionsfähig. Markt­daten-, Portfolio-, Paper-Trading- und Live-Trading-Adapter sind nicht angebunden und schlagen mit capability_not_ready fail-closed fehl.

[!IMPORTANT] Dieses Community-Projekt ist kein offizielles Kalshi-Produkt und ist weder mit KalshiEX LLC noch mit deren verbundenen Unternehmen verbunden und wird von diesen weder befürwortet gesponsert noch unterstützt. „Kalshi“ wird nur verwendet, um die Interoperabilität mit Kalshis veröffentlichten APIs zu kennzeichnen.

Warum es dieses Projekt gibt

Trading-APIs sind breit ausgelegt und auf Anwendungsentwickler optimiert. Agents benötigen eine schmalere Grenzfläche mit expliziter Absicht, strengen Schemas, vorhersehbaren Fehlern und einer starken Trennung zwischen Simulation und Ausführung mit echtem Geld. Kalshi Kernel bietet diese Grenze und testet seine generierten Clients kontinuierlich gegen die neuesten Upstream-Verträge.

Die Design-Prioritäten sind:

• Paper-Modus als Standard;

• unveränderlicher Ausführungsmodus für die Lebensdauer eines Prozesses;

• explizite Bestätigung und Anmeldedaten, bevor der Live-Modus aktiviert werden kann;

• Festkomma-Zeichenfolgen für Preise und Mengen;

• strikte, generierte Tool-Schemas mit Sicherheitshinweisen;

• Fail-Closed-Verhalten, wenn eine Fähigkeit nicht verfügbar ist;

• nachvollziehbare Zuordnung zu exakten OpenAPI-Operationen und AsyncAPI-Kanälen;

• wiederholbare Tests für MCP-Protokoll, Race-Conditions, Fuzzing und Upstream-Drift.

Related MCP server: MCP Server Kalshi

Aktueller Stand

Diese Version darf nicht als funktionierende Handelsintegration beworben, eingesetzt oder darauf vertraut werden. Siehe ARCHITECTURE.md, THREAT_MODEL.md sowie die Release-Gates in PUBLICATION.md.

Tools für Agents

Verbundene MCP-Clients erhalten außerdem Anweisungen auf Serverebene, zuerst kernel_status aufzurufen, Paper- vs. Live-Modus zu beurteilen und eine Aktion niemals als erfolgreich zu melden, es sei denn, die strukturierte Antwort enthält ok: true.

Lokal erstellen und ausführen

Voraussetzungen:

• Go 1.25.13 oder neuer;

• Node.js 22 nur für den offiziellen MCP-Konformitäts-Testrunner; und

• einen unterstützten MCP-Client.

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

Der Paper-Modus ist die Standardeinstellung, wenn KALSHI_KERNEL_MODE nicht gesetzt ist. Er verwirft eine Konfiguration für Live-Anmeldedaten hierbei bewusst.

Hermes

Fügen Sie einen lokalen stdio-Server zu ~/.hermes/config.yaml hinzu:

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

Starten Sie Hermes neu und rufen Sie kernel_status vor jedem anderen Tool auf.

Claude Code

Nach dem Erstellen der Binärdatei:

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

Führen Sie dann claude mcp get kalshi-kernel aus oder öffnen Sie /mcp, um die Verbindung zu bestätigen. Diese lokale Konfiguration ist getrennt vom öffentlichen Connectors-Verzeichnis von Anthropic, die einen bereitgestellten Remote-Server erfordert.

Andere stdio-Clients

Verwenden Sie die Standard-MCP-Konfigurationsstruktur:

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

Ausführungsmodi

Paper-Modus

KALSHI_KERNEL_MODE=paper ./bin/kalshi-kernel

Der Paper-Modus wird ein lokales simuliertes Hauptbuch verwenden, sobald dieses Backend implementiert ist. Es darf niemals eine Order an Kalshi weitergeben. Simulierte Fills sagen oder garantieren keine Live-Fills, Liquidität, Latenz, Slippage, Gebühren oder Rentabilität.

Live-Modus

Der Live-Modus ist absichtlich schwer zu aktivieren:

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

Diese Variablen aktivieren derzeit nur die Konfigurationsvalidierung; ein Live-Ausführungsadapter ist nicht angeschlossen. Übergeben Sie niemals Anmeldedaten, private Schlüssel oder .env-Dateien. Verwenden Sie zwir kurzlebige Anmeldedaten, in der Produktion einen Secrets-Manager sowie ein Konto oder Unterkonto mit den geringsten erforderlichen Berechtigungen und Schlüssen.

Durch Spezifikationen gesteuerte Generierung

Die Events für Agents kuratierte Schnittstelle ist in specs/mcp-tools.yaml hinterlegt. Sie bildet jedes MCP-Tool exakt auf OpenAPI-Operation-IDs und AsyncAPI-Kanäle ab. Administrations- und Kontoverwaltungs-Endpunkte werden nicht automatisch bereitgestellt, sondern nur, weil die upstream vorhandenen sind.

Vier verbindliche Verträge werden von https://docs.kalshi.com abgerufen:

• openapi.yaml — REST-API für Event-Kontrakte;

• asyncapi.yaml — WebSocket-API für Event-Kontrakte;

• perps_openapi.yaml — REST-API für Perpetual-Märkte;

• perps_asyncapi.yaml — WebSocket-API für Perpetual-Märkte.

Der Fetcher erzwingt die Verwendung von HTTPS und den Quell-Hostnamen, begrenzt Antwortgrößen, validiert den erwarteten Dialekt und eine nicht leere Fläche und protokolliert Hashes sowie HTTP-Provenienz. Die Inhalte der Upstream-Verträge werden von Git ignoriert und bei Bedarf in einen lokalen Cache geladen. Die von den Upstream-Spezifikationen abgeleiteten REST-Clients werden ebenfalls nur locally erzeugt und davon im Source-Release ausgeschlossen. Nur die Provenance-Lock, das kuratierte MCP-Overlay und die generierte MCP-Tool-Grenze werden versioniert. Regenerierung und Tests erfolgen in einer temporären Kopie des Repository, bevor ein getesteter Lock und die MCP-Grenze übernommen werden können.

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

Jeder CI-Lauf führt die strikte Upstream-Prüfung durch; CI läuft auch täglich, damit Drift auch bei inaktivem Repository erkannt wird.

[!WARNING] Die heruntergeladenen Kalshi-Vertragsdateien kennzeichnen einen Teil der upstream data als proprietär. Sie sind nicht von der Apache-2.0-Lizenz dieses Projekts abgedeckt und dürfen weder festgehalten noch weiterverbreitet werden. Prüfen Sie THIRD_PARTY_NOTICES.md, da sie generierte Artefakte veröffentlichen.

Verifikation

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

Die Suite prüft Transportsicherheit, Authentifizierungs- und Autorisierungskontrakte, Sicherheit von Mutationen, eindeutige Operations-IDs, Festpunkttypen, die kuratierte Oberfläche, Feld-Anteil-Parität, strikte JSON-Schemas, Titel und Sicherheitshinweise der Werkzeuge, Fail-Closed-Verhalten, Konkurrenz und Streamable-HTTP-Verhandlung.

Distribution und Registries

Das Repository enthält Metadaten zur Veröffentlichung im offiziellen MCP-Registry sowie Einreichungs-Datensätze für das OpenAI-Plugins-Verzeichnis und Anthropic -Verzeichnisse. Metadaten sind Vorbereitung – kein Nachweis für Zulassung, Empfehlung oder Veröffentlichung.

Die aktuellen Kriterien von Anthropic für Connectors unterstützen keine Connectors, die Geld oder andere finanzielle Vermögenswerte übertragen. Jede Build dieses Projekts für das Claude-MCP-Verzeichnis muss daher ein eigenständiges Lese- und/oder Paper-only-Artefakt sein, ohne Live-Order-Tools, und unterliegt der Prüfung durch Anthropic.

Weitere Informationen finden Sie in PUBLICATION.md für die exakte Kanalmatrix, aktuelle Blocker, Releaseschritte, Verzeichnis-Texte und Review-Testfälle. Es sind keine automatischen Einreichungen an externe Registries imple.

Mitwirken und Sicherheit

Lesen Sie CONTRIBUTING.md, bevor Sie einen Pull-Request erstellen. Melden Sie Sicherheitslücken vertraulich gemäß SECURITY.md. Öffnen Sie keine öffentlichen Issues bei: einen vermuteten Anmeldedaten-Leck oder trading-ite relevanten Sicherheitslücke. Allgemeine Nutzungshilfe gehört in SUPPORT.md.

Rechts- und Risikohinweis

Diese Software wird für Entwicklungs- und Forschungszwecke bereitgestellt. Sie erhebt keinen Anspruch auf Investment-, Finanz-, Rechts-, Steuer-, Compliance- oder Handelsberatung. Event-Kontrakte und gehebelte Produkte können zu schnellen und erheblichen Verlusten führen, einschließlich des Verlusts des gesamten eingesetzten Betrags. Eigenverantwortung: Sie sind für Kontoberechtigung, jurisdiktionsbedingte Beschränkungen, Börsenregeln, regulatorische Anforderungen, Steuern, Strategie, Orders und Verluste.

KI-Systeme und Software können Missverständnisse erzeugen, falsche Parameter, Wiederholungen von Requests oder unerwartetes Verhalten verursachen. Bevor eine Live-Bereitstellung, erforderlich sind menschliche Kontrolle,

Seiten-Risikolimits, nebenrechte-Anmeldedaten, Überwachung und emotionale unabhängige Notabschaltung.

Lesen Sie die DISCLAIMER.md, PRIVACY.md und SECURITY.md vollständig durch. Das Projekt ist lizenziert unter Apache License 2.0; Third-Party-Material wird, wie in THIRD_PARTY_NOTICES.md beschrieben, nicht abgedecktider unbegründet ausgeschlossen.