Kalshi Kernel

Kalshi Kernel

An unofficial, safety-focused Model Context Protocol (MCP) server for Kalshi event contracts and perpetual markets. This is a pre-release project that is not ready for trading. The server is designed for agent harnesses such as Hermes and exposes a deliberately small tool surface generated from Kalshi's published API contracts.

Canonical publisher: [CopyleftDev](https://github.com/copyleftdev). Planned source and container releases use github.com/copyleftdev/kalshi-kernel and ghcr.io/copyleftdev/kalshi-kernel respectively.

[!CAUTION]

Pre-release software that can submit real orders. Published tags are

conformance-tested scaffolds; the current main branch adds market-data,

paper-trading, and live event-contract adapters. Configured live mode can

place, amend, and cancel real orders. Review the exact

commit, configuration, tests, and limits before running it with credentials;

do not infer readiness from the version string.

[!IMPORTANT]

This community project is not an official Kalshi product and is not affiliated

with, endorsed by, sponsored by, or supported by KalshiEX LLC or its

affiliates. “Kalshi” is used only to identify interoperability with Kalshi's

published APIs.

The independent Kernel mark follows a conservative interpretation of Kalshi's published color, contrast, clear-space, and misuse guidance. It does not use or modify Kalshi's logo. See the visual identity usage rules.

Why this project exists

Trading APIs are broad and optimized for application developers. Agents need a narrower boundary with explicit intent, strict schemas, predictable errors, and strong separation between simulation and real-money execution. Kalshi Kernel provides that boundary while continuously testing its generated clients against the latest upstream contracts.

The design priorities are:

• paper mode by default;
• immutable execution mode for the lifetime of a process;
• explicit acknowledgement and credentials before live mode can arm;
• fixed-point strings for prices and quantities;
• strict, generated tool schemas with safety annotations;
• fail-closed behavior when a capability is unavailable;
• traceable alignment with exact OpenAPI operations and AsyncAPI channels; and
• repeatable MCP protocol, race, fuzz, and upstream-drift testing.

Current status

The table describes the current main branch, not the published v0.1.1 tag. The additions are unreleased and the version metadata has not yet advanced.

Treat the current branch as development software, not as a published or audited trading integration. Some design and publication documents still describe the v0.1.1 scaffold; compare them with the implementation before relying on a claim. See ARCHITECTURE.md, THREAT_MODEL.md, and the release gates in PUBLICATION.md.

Agent-facing tools

Connected MCP clients also receive server-level instructions telling them to call kernel_status first, distinguish paper from live mode, and never report an action as successful unless its structured response contains ok: true. Until its readiness reporting is updated, confirm live arm state from the arm_live_trading response rather than from kernel_status.

Build and run locally

Prerequisites:

• Go 1.25.13 or newer;
• Node.js 22 only for the official MCP conformance runner; and
• a supported MCP client.

make test

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

Paper mode is the default when KALSHI_KERNEL_MODE is unset. It intentionally discards live credential configuration.

Hermes

Add a local stdio server to ~/.hermes/config.yaml:

mcp_servers:

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

Restart Hermes and call kernel_status before any other tool.

Claude Code

After building the binary:

claude mcp add --scope user --transport stdio kalshi-kernel \

--env KALSHI_KERNEL_MODE=paper -- /absolute/path/to/bin/kalshi-kernel

Then run claude mcp get kalshi-kernel or open /mcp to confirm the connection. This local setup is separate from Anthropic's public Connectors Directory, which requires a deployed remote server.

Other stdio clients

Use the standard MCP configuration shape:

{

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

Execution modes

Paper mode

KALSHI_KERNEL_MODE=paper ./bin/kalshi-kernel

Paper mode uses an in-memory simulated ledger and never submits an order to Kalshi. It starts with $100.00 by default; set KALSHI_PAPER_CASH_DOLLARS before startup to choose another balance. The ledger, positions, idempotency records, and fill journal reset when the process exits.

place_order fetches a fresh public order-book snapshot and supports only immediate, all-or-nothing marketable fills. The requested price must exactly equal the current touch and the displayed size must cover the full quantity. The simulator uses fixed-point arithmetic, applies the published fee formula, records a hash of the book used, and treats client_order_id as an idempotency key. Because paper orders never rest, amend_order and cancel_order return typed failures.

Every paper response is labeled simulated: true. Simulated fills do not predict or guarantee live fills, liquidity, latency, slippage, fees, or profitability.

Live mode

Live mode is deliberately difficult to enable:

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

Startup configuration selects immutable live mode and enables authenticated event-contract portfolio reads and cancellation. It does not authorize place/amend calls. Those calls require a second, process-local MCP action:

{

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

Pass that object to arm_live_trading; pass the same object with arm: false to disarm. Arming is never persisted. place_order also requires a stable, caller-provided client_order_id. Place/amend requests are rejected before submission when they exceed the startup-only per-order, UTC-day notional, or UTC-day order-count limits. These counters are process-local and reset when the process restarts.

[!WARNING]

cancel_order is available in configured live mode without the separate

arm_live_trading step. It verifies that the order is resting before sending

the cancellation. Place/amend validate price syntax and notional limits, but

the current implementation does not independently compare the requested limit

price with a fresh quote. Use exchange-side limits, least-privilege credentials,

human review, monitoring, and an independent emergency stop.

Live account reads and writes currently support event contracts only. Perpetual-account operations and non-primary subaccounts are unavailable; omit subaccount or pass 0. Network failures after a write produce reconciled or explicitly indeterminate outcomes rather than blind retries.

Never commit credentials, private keys, or .env files. Use short-lived credentials where available, a secrets manager in production, and an account with only the privileges and capital required.

Specification-driven generation

The curated agent interface lives in specs/mcp-tools.yaml. It maps each MCP tool to exact OpenAPI operation IDs and AsyncAPI channels. Administrative and account-management endpoints are not automatically exposed merely because they exist upstream.

Four authoritative contracts are fetched from https://docs.kalshi.com:

• openapi.yaml — event-contract REST API;
• asyncapi.yaml — event-contract WebSocket API;
• perps_openapi.yaml — perpetuals REST API; and
• perps_asyncapi.yaml — perpetuals WebSocket API.

The fetcher pins HTTPS and the source hostname, limits response sizes, validates the expected dialect and non-empty surface, and records hashes and HTTP provenance. The upstream contract bodies are ignored by Git and fetched into a local cache as needed. Upstream-derived REST clients are also generated locally and excluded from source releases. Only the provenance lock, curated MCP overlay, and generated MCP tool boundary are versioned. Regeneration and testing happen in a temporary repository copy before a tested lock and MCP boundary can be promoted.

make upstream-test      # test latest contracts without r