{ "markdown": "\n \n \n \"Kernel\"\n\n\n# Kalshi Kernel\n\nAn unofficial, safety-focused Model Context Protocol (MCP) server for Kalshi\nevent contracts and perpetual markets. This is a **pre-release** project that\nis **not ready for trading**. The server is designed for agent\nharnesses such as Hermes and exposes a deliberately small tool surface generated\nfrom Kalshi's published API contracts.\n\nCanonical publisher: **[CopyleftDev](https://github.com/copyleftdev)**. Planned\nsource and container releases use `github.com/copyleftdev/kalshi-kernel` and\n`ghcr.io/copyleftdev/kalshi-kernel` respectively.\n\n> [!CAUTION]\n> **Pre-release software that can submit real orders.** Published tags are\n> conformance-tested scaffolds; the current `main` branch adds market-data,\n> paper-trading, and live event-contract adapters. Configured live mode can\n> place, amend, and cancel real orders. Review the exact\n> commit, configuration, tests, and limits before running it with credentials;\n> do not infer readiness from the version string.\n\n> [!IMPORTANT]\n> This community project is not an official Kalshi product and is not affiliated\n> with, endorsed by, sponsored by, or supported by KalshiEX LLC or its\n> affiliates. “Kalshi” is used only to identify interoperability with Kalshi's\n> published APIs.\n\nThe independent Kernel mark follows a conservative interpretation of Kalshi's\npublished color, contrast, clear-space, and misuse guidance. It does not use or\nmodify Kalshi's logo. See the [visual identity usage rules](assets/brand/README.md).\n\n## Why this project exists\n\nTrading APIs are broad and optimized for application developers. Agents need a\nnarrower boundary with explicit intent, strict schemas, predictable errors, and\nstrong separation between simulation and real-money execution. Kalshi Kernel\nprovides that boundary while continuously testing its generated clients against\nthe latest upstream contracts.\n\nThe design priorities are:\n\n- paper mode by default;\n- immutable execution mode for the lifetime of a process;\n- explicit acknowledgement and credentials before live mode can arm;\n- fixed-point strings for prices and quantities;\n- strict, generated tool schemas with safety annotations;\n- fail-closed behavior when a capability is unavailable;\n- traceable alignment with exact OpenAPI operations and AsyncAPI channels; and\n- repeatable MCP protocol, race, fuzz, and upstream-drift testing.\n\n## Current status\n\nThe table describes the current `main` branch, not the published `v0.1.1` tag.\nThe additions are unreleased and the version metadata has not yet advanced.\n\n| Area | Current behavior and limits |\n| --- | --- |\n| MCP stdio transport and generated schemas | Working |\n| Public market data | Event contracts and perpetuals: search, market details, REST order-book snapshots, candles, and last quote. Public trade tape is event-contract only |\n| Paper trading | In-memory balance, positions, fill journal, exact fixed-point fees, and immediate all-or-nothing fills at the current displayed touch |\n| Live portfolio | Authenticated event-contract balance, positions, orders, and fills. Perpetual accounts and non-primary subaccounts are not supported |\n| Live event-contract orders | Place, amend, and cancel are connected to the production API. Place/amend require process-local arming and kernel-side limits; cancel performs a resting-state check and timeout reconciliation |\n| Live perpetual orders | Not implemented |\n| Streaming order-book reconciliation | Not implemented; `get_orderbook` currently returns one public REST snapshot |\n| `kernel_status` | Callable, but some readiness and arming fields still describe the old scaffold and must not be treated as authoritative |\n| Automatic upstream specification freshness gate | Working |\n| Production remote HTTPS/OAuth service | Not implemented |\n| Public registry listings | Prepared, not submitted |\n\nTreat the current branch as development software, not as a published or audited\ntrading integration. Some design and publication documents still describe the\n`v0.1.1` scaffold; compare them with the implementation before relying on a\nclaim. See [ARCHITECTURE.md](docs/ARCHITECTURE.md),\n[THREAT_MODEL.md](docs/THREAT_MODEL.md), and the release gates in\n[PUBLICATION.md](docs/PUBLICATION.md).\n\n## Agent-facing tools\n\n| Tool | Class | Current behavior |\n| --- | --- | --- |\n| `kernel_status` | Read-only | Returns mode and a readiness envelope; newly added backend and arm state are not yet reflected accurately |\n| `search_markets` | Read-only | Searches event-contract or perpetual markets through public REST |\n| `get_market` | Read-only | Returns authoritative metadata for one event-contract or perpetual market |\n| `get_orderbook` | Read-only | Returns a public REST snapshot of yes/no bid levels for either product |\n| `get_candles` | Read-only | Returns 1-, 60-, or 1440-minute event-contract or perpetual OHLC buckets |\n| `get_trades` | Read-only | Returns one cursor-paginated page of the public event-contract trade tape |\n| `get_last` | Read-only | Returns a compact event-contract or perpetual quote and status snapshot |\n| `arm_live_trading` | Destructive/control | Arms or disarms live place/amend calls for this process after an exact second acknowledgement |\n| `get_portfolio` | Read-only | Returns the local paper ledger in paper mode or the authenticated event-contract portfolio in live mode |\n| `place_order` | Destructive/write | Simulates an immediate fill in paper mode; submits an armed, capped event-contract order in live mode |\n| `amend_order` | Destructive/write | Paper mode has no resting orders; live mode amends an armed, resting event-contract order |\n| `cancel_order` | Destructive/write | Paper mode has no resting orders; live mode state-checks and cancels a resting event-contract order |\n\nConnected MCP clients also receive server-level instructions telling them to\ncall `kernel_status` first, distinguish paper from live mode, and never report\nan action as successful unless its structured response contains `ok: true`.\nUntil its readiness reporting is updated, confirm live arm state from the\n`arm_live_trading` response rather than from `kernel_status`.\n\n## Build and run locally\n\nPrerequisites:\n\n- Go 1.25.13 or newer;\n- Node.js 22 only for the official MCP conformance runner; and\n- a supported MCP client.\n\n```sh\nmake test\nmake build\nKALSHI_KERNEL_MODE=paper ./bin/kalshi-kernel\n```\n\nPaper mode is the default when `KALSHI_KERNEL_MODE` is unset. It intentionally\ndiscards live credential configuration.\n\n### Hermes\n\nAdd a local stdio server to `~/.hermes/config.yaml`:\n\n```yaml\nmcp_servers:\n kalshi-kernel:\n command: \"/absolute/path/to/kalshi-kernel/bin/kalshi-kernel\"\n env:\n KALSHI_KERNEL_MODE: \"paper\"\n```\n\nRestart Hermes and call `kernel_status` before any other tool.\n\n### Claude Code\n\nAfter building the binary:\n\n```sh\nclaude mcp add --scope user --transport stdio kalshi-kernel \\\n --env KALSHI_KERNEL_MODE=paper -- /absolute/path/to/bin/kalshi-kernel\n```\n\nThen run `claude mcp get kalshi-kernel` or open `/mcp` to confirm the\nconnection. This local setup is separate from Anthropic's public Connectors\nDirectory, which requires a deployed remote server.\n\n### Other stdio clients\n\nUse the standard MCP configuration shape:\n\n```json\n{\n \"mcpServers\": {\n \"kalshi-kernel\": {\n \"command\": \"/absolute/path/to/bin/kalshi-kernel\",\n \"env\": {\n \"KALSHI_KERNEL_MODE\": \"paper\"\n }\n }\n }\n}\n```\n\n## Execution modes\n\n### Paper mode\n\n```sh\nKALSHI_KERNEL_MODE=paper ./bin/kalshi-kernel\n```\n\nPaper mode uses an in-memory simulated ledger and never submits an order to\nKalshi. It starts with `$100.00` by default; set\n`KALSHI_PAPER_CASH_DOLLARS` before startup to choose another balance. The\nledger, positions, idempotency records, and fill journal reset when the process\nexits.\n\n`place_order` fetches a fresh public order-book snapshot and supports only\nimmediate, all-or-nothing marketable fills. The requested price must exactly\nequal the current touch and the displayed size must cover the full quantity.\nThe simulator uses fixed-point arithmetic, applies the published fee formula,\nrecords a hash of the book used, and treats `client_order_id` as an idempotency\nkey. Because paper orders never rest, `amend_order` and `cancel_order` return\ntyped failures.\n\nEvery paper response is labeled `simulated: true`. Simulated fills do not\npredict or guarantee live fills, liquidity, latency, slippage, fees, or\nprofitability.\n\n### Live mode\n\nLive mode is deliberately difficult to enable:\n\n```sh\nKALSHI_KERNEL_MODE=live\nKALSHI_API_KEY_ID=...\nKALSHI_PRIVATE_KEY_PATH=/absolute/path/to/private-key.pem\nKALSHI_LIVE_TRADING_ACK=I_UNDERSTAND_THIS_TRADES_REAL_MONEY\n\n# Optional startup-only overrides; these are the defaults.\nKALSHI_MAX_ORDER_NOTIONAL_DOLLARS=25.00\nKALSHI_MAX_DAILY_NOTIONAL_DOLLARS=100.00\nKALSHI_MAX_DAILY_ORDERS=200\n```\n\nStartup configuration selects immutable live mode and enables authenticated\nevent-contract portfolio reads and cancellation. It does **not** authorize\nplace/amend calls. Those calls require a second, process-local MCP action:\n\n```json\n{\n \"acknowledgement\": \"I_UNDERSTAND_THIS_TRADES_REAL_MONEY\",\n \"arm\": true\n}\n```\n\nPass that object to `arm_live_trading`; pass the same object with `arm: false`\nto disarm. Arming is never persisted. `place_order` also requires a stable,\ncaller-provided `client_order_id`. Place/amend requests are rejected before\nsubmission when they exceed the startup-only per-order, UTC-day notional, or\nUTC-day order-count limits. These counters are process-local and reset when the\nprocess restarts.\n\n> [!WARNING]\n> `cancel_order` is available in configured live mode without the separate\n> `arm_live_trading` step. It verifies that the order is resting before sending\n> the cancellation. Place/amend validate price syntax and notional limits, but\n> the current implementation does not independently compare the requested limit\n> price with a fresh quote. Use exchange-side limits, least-privilege credentials,\n> human review, monitoring, and an independent emergency stop.\n\nLive account reads and writes currently support event contracts only.\nPerpetual-account operations and non-primary subaccounts are unavailable; omit\n`subaccount` or pass `0`. Network failures after a write produce reconciled or\nexplicitly indeterminate outcomes rather than blind retries.\n\nNever commit credentials, private keys, or `.env` files. Use short-lived\ncredentials where available, a secrets manager in production, and an account\nwith only the privileges and capital required.\n\n## Specification-driven generation\n\nThe curated agent interface lives in `specs/mcp-tools.yaml`. It maps each MCP\ntool to exact OpenAPI operation IDs and AsyncAPI channels. Administrative and\naccount-management endpoints are not automatically exposed merely because they\nexist upstream.\n\nFour authoritative contracts are fetched from `https://docs.kalshi.com`:\n\n- `openapi.yaml` — event-contract REST API;\n- `asyncapi.yaml` — event-contract WebSocket API;\n- `perps_openapi.yaml` — perpetuals REST API; and\n- `perps_asyncapi.yaml` — perpetuals WebSocket API.\n\nThe fetcher pins HTTPS and the source hostname, limits response sizes, validates\nthe expected dialect and non-empty surface, and records hashes and HTTP\nprovenance. The upstream contract bodies are ignored by Git and fetched into a\nlocal cache as needed. Upstream-derived REST clients are also generated locally\nand excluded from source releases. Only the provenance lock, curated MCP\noverlay, and generated MCP tool boundary are versioned. Regeneration and testing\nhappen in a temporary repository copy before a tested lock and MCP boundary can\nbe promoted.\n\n```sh\nmake upstream-test # test latest contracts without requiring snapshot parity\nmake upstream-check # require parity and run MCP conformance\nmake upstream-promote # promote only the exact artifacts that passed\n```\n\nEvery CI run performs the strict upstream check; CI also runs daily so drift is\ndetected even when the repository is idle.\n\n> [!WARNING]\n> The downloaded Kalshi contract files identify at least part of the upstream\n> material as proprietary. They are not covered by this project's Apache-2.0\n> license and must not be committed or redistributed. Review\n> [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) before publishing generated\n> artifacts.\n\n## Verification\n\n```sh\nmake test # unit, integration, and contract alignment tests\nmake test-alignment # OpenAPI, AsyncAPI, and MCP overlay alignment\nmake check-generated # deterministic generated-code check\nmake test-race # concurrent calls under Go's race detector\nmake test-fuzz # execution-mode parser safety fuzzing\nmake conformance # pinned official MCP protocol scenarios\nmake release-test # complete local release gate\nmake public-check # vulnerability, metadata, and public-readiness gate\nmake upstream-check # latest Kalshi contracts plus conformance\n```\n\nThe suite checks transport security, authentication contracts, mutation\nsecurity, operation-ID uniqueness, fixed-point types, curated surface area,\nrequired-field parity, strict JSON Schemas, tool titles and safety hints,\nfail-closed behavior, concurrency, and Streamable HTTP negotiation.\n\n## Distribution and registries\n\nThe repository contains publication metadata for the official MCP Registry and\nsubmission dossiers for the OpenAI Plugins Directory and Anthropic directories.\nMetadata is preparation—not evidence of approval, endorsement, or publication.\n\nAnthropic's current connector review criteria do not accept connectors that\ntransfer money or other financial assets. Any Claude Connectors Directory build\nof this project must therefore be a distinct read-only and/or paper-only\nartifact with live order tools omitted, subject to Anthropic's review.\n\nSee [PUBLICATION.md](docs/PUBLICATION.md) for the exact channel matrix, current\nblockers, release steps, listing copy, and review test cases. No external\nregistry submission is performed automatically.\n\n## Contributing and security\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Report\nvulnerabilities privately according to [SECURITY.md](SECURITY.md); do not open a\npublic issue for a suspected credential leak or trading-safety vulnerability.\nGeneral usage help belongs in [SUPPORT.md](SUPPORT.md).\n\n## Legal and risk notice\n\nThis software is provided for development and research. It does not provide\ninvestment, financial, legal, tax, compliance, or trading advice. Event\ncontracts and leveraged products can result in rapid and substantial loss,\nincluding loss of the entire amount committed. You are responsible for account\neligibility, jurisdictional restrictions, exchange rules, regulatory\nrequirements, taxes, strategy, orders, and losses.\n\nAI systems and software can misunderstand intent, produce incorrect parameters,\nrepeat requests, or behave unexpectedly. Human review, exchange-side risk\nlimits, least-privilege credentials, monitoring, and an independent emergency\nstop are required before any live deployment.\n\nRead the full [DISCLAIMER.md](DISCLAIMER.md), [PRIVACY.md](PRIVACY.md), and\n[SECURITY.md](SECURITY.md). The project is licensed under\n[Apache License 2.0](LICENSE); third-party material is excluded as described in\n[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n", "bytes": 15613, "sha": "8aaa1762a4d30ebc8a15c2947141f3a075666b689e1ead5b978f3976290224ff", "repo_slug": "copyleftdev/kalshi-kernel", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_copyleftdev_kalshi_kernel_98342c02/readme" }