Kalshi Kernel

Kalshi 이벤트 컨트랙트 및 무기한(perpetual) 시장을 위한 비공식적이고 안전성에 중점을 둔 Model Context Protocol(MCP) 서버입니다. 이 서버는 Hermes와 같은 에이전트 하니스(harness)를 위해 설계되었으며, Kalshi가 공개한 API 컨트랙트에서 생성된 의도적으로 작은 도구 표면(tool surface)을 노출합니다.

공식 게시자: CopyleftDev. 계획된 소스 및 컨테이너 릴리스는 각각 github.com/copyleftdev/kalshi-kernel 및 ghcr.io/copyleftdev/kalshi-kernel을 사용합니다.

[!CAUTION] 사전 릴리스 소프트웨어 — 거래용으로 준비되지 않음. 버전 0.1.1은 적합성 테스트를 거친 스캐폴드입니다. kernel_status만 작동합니다. 시장 데이터, 포트폴리오, 페이퍼 트레이딩 및 실거래 어댑터는 연결되어 있지 않으며 capability_not_ready로 안전하게 실패(fail closed)합니다.

[!IMPORTANT] 이 커뮤니티 프로젝트는 공식 Kalshi 제품이 아니며 KalshiEX LLC 또는 그 계열사와 제휴, 보증, 후원 또는 지원 관계가 없습니다. "Kalshi"는 Kalshi의 공개 API와의 상호 운용성을 식별하는 데에만 사용됩니다.

이 프로젝트가 존재하는 이유

거래 API는 광범위하며 애플리케이션 개발자에 최적화되어 있습니다. 에이전트는 명시적인 의도, 엄격한 스키마, 예측 가능한 오류, 그리고 시뮬레이션과 실거래 실행 사이의 강력한 분리를 갖춘 더 좁은 경계가 필요합니다. Kalshi Kernel은 생성된 클라이언트를 최신 업스트림 컨트랙트에 대해 지속적으로 테스트하면서 그러한 경계를 제공합니다.

설계 우선순위는 다음과 같습니다:

• 기본적으로 페이퍼 모드(paper mode);

• 프로세스 수명 동안 변경 불가능한 실행 모드;

• 라이브 모드가 활성화되기 전에 명시적 확인 및 자격 증명 필요;

• 가격 및 수량에 대한 고정 소수점 문자열;

• 안전 주석이 포함된 엄격하고 생성된 도구 스키마;

• 기능을 사용할 수 없을 때 안전하게 실패(fail-closed)하는 동작;

• 정확한 OpenAPI 작업 및 AsyncAPI 채널과의 추적 가능한 정렬; 그리고

• 반복 가능한 MCP 프로토콜, 레이스(race), 퍼즈(fuzz) 및 업스트림 드리프트 테스트.

Related MCP server: MCP Server Kalshi

현재 상태

이 버전을 기능하는 거래 통합으로 광고, 배포 또는 의존하지 마십시오. ARCHITECTURE.md, THREAT_MODEL.md 및 PUBLICATION.md의 릴리스 게이트를 참조하십시오.

에이전트 지향 도구

연결된 MCP 클라이언트는 또한 먼저 kernel_status를 호출하고, 페이퍼 모드와 라이브 모드를 구분하며, 구조화된 응답에 ok: true가 포함되지 않는 한 작업을 성공으로 보고하지 말라는 서버 수준 지침을 받습니다.

로컬 빌드 및 실행

전제 조건:

• Go 1.25.13 이상;

• 공식 MCP 적합성 러너(runner)에만 필요한 Node.js 22; 그리고

• 지원되는 MCP 클라이언트.

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

KALSHI_KERNEL_MODE가 설정되지 않은 경우 페이퍼 모드가 기본값입니다. 페이퍼 모드는 의도적으로 라이브 자격 증명 구성을 폐기합니다.

Hermes

로컬 stdio 서버를 ~/.hermes/config.yaml에 추가합니다:

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

Hermes를 다시 시작하고 다른 도구보다 먼저 kernel_status를 호출하십시오.

Claude Code

바이너리를 빌드한 후:

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

그런 다음 claude mcp get kalshi-kernel을 실행하거나 /mcp를 열어 연결을 확인하십시오. 이 로컬 설정은 배포된 원격 서버가 필요한 Anthropic의 공개 Connectors Directory와는 별개입니다.

기타 stdio 클라이언트

표준 MCP 구성 형식을 사용하십시오:

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

실행 모드

페이퍼 모드

KALSHI_KERNEL_MODE=paper ./bin/kalshi-kernel

페이퍼 모드는 해당 백엔드가 구현된 후 로컬 시뮬레이션 원장을 사용합니다. 페이퍼 모드는 Kalshi에 주문을 제출해서는 안 됩니다. 시뮬레이션 체결은 실제 체결, 유동성, 지연 시간, 슬리피지, 수수료 또는 수익성을 예측하거나 보장하지 않습니다.

라이브 모드

라이브 모드는 의도적으로 활성화하기 어렵게 설계되었습니다:

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

이 변수들은 현재 구성 검증만 준비합니다. 라이브 실행 어댑터는 연결되어 있지 않습니다. 자격 증명, 개인 키 또는 .env 파일을 커밋하지 마십시오. 가능한 경우 단기 자격 증명, 프로덕션의 비밀 관리자(secrets manager), 그리고 최소한의 권한과 자본이 필요한 계정 또는 하위 계정을 사용하십시오.

사양 기반 생성

큐레이팅된 에이전트 인터페이스는 specs/mcp-tools.yaml에 있습니다. 각 MCP 도구를 정확한 OpenAPI 작업 ID 및 AsyncAPI 채널에 매핑합니다. 관리 및 계정 관리 엔드포인트는 단지 업스트림에 존재한다는 이유만으로 자동으로 노출되지 않습니다.

https://docs.kalshi.com에서 네 개의 권위 있는 컨트랙트를 가져옵니다:

• openapi.yaml — 이벤트 컨트랙트 REST API;

• asyncapi.yaml — 이벤트 컨트랙트 WebSocket API;

• perps_openapi.yaml — 무기한(perpetuals) REST API; 그리고

• perps_asyncapi.yaml — 무기한(perpetuals) WebSocket API.

페처(fetcher)는 HTTPS 및 소스 호스트 이름을 고정하고, 응답 크기를 제한하며, 예상 방언과 비어 있지 않은 표면을 검증하고, 해시 및 HTTP 출처를 기록합니다. 업스트림 컨트랙트 본문은 Git에서 무시되며 필요에 따라 로컬 캐시로 가져옵니다. 업스트림 파생 REST 클라이언트도 로컬에서 생성되며 소스 릴리스에서 제외됩니다. 출처 잠금(provenance lock), 큐레이팅된 MCP 오버레이 및 생성된 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

모든 CI 실행은 엄격한 업스트림 검사를 수행합니다. CI는 또한 매일 실행되므로 저장소가 유휴 상태일 때도 드리프트가 감지됩니다.

[!WARNING] 다운로드된 Kalshi 컨트랙트 파일은 업스트림 자료의 적어도 일부를 독점(proprietary)으로 식별합니다. 이 파일들은 이 프로젝트의 Apache-2.0 라이선스의 적용을 받지 않으며 커밋하거나 재배포해서는 안 됩니다. 생성된 아티팩트를 게시하기 전에 THIRD_PARTY_NOTICES.md를 검토하십시오.

검증

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

이 스위트는 전송 보안, 인증 컨트랙트, 변형(mutation) 보안, 작업 ID 고유성, 고정 소수점 유형, 큐레이팅된 표면 영역, 필수 필드 일치, 엄격한 JSON 스키마, 도구 제목 및 안전 힌트, 안전 실패(fail-closed) 동작, 동시성 및 Streamable HTTP 협상을 확인합니다.

배포 및 레지스트리

저장소에는 공식 MCP 레지스트리용 게시 메타데이터와 OpenAI Plugins Directory 및 Anthropic 디렉토리용 제출 문서가 포함되어 있습니다. 메타데이터는 준비 상태일 뿐 승인, 보증 또는 게시의 증거가 아닙니다.

Anthropic의 현재 커넥터 검토 기준은 금전 또는 기타 금융 자산을 이체하는 커넥터를 허용하지 않습니다. 따라서 이 프로젝트의 Claude Connectors Directory 빌드는 라이브 주문 도구가 생략된 별개의 읽기 전용 및/또는 페이퍼 전용 아티팩트여야 하며, Anthropic의 검토를 받아야 합니다.

정확한 채널 매트릭스, 현재 차단 항목, 릴리스 단계, 등재 문구 및 검토 테스트 사례는 PUBLICATION.md를 참조하십시오. 외부 레지스트리 제출은 자동으로 수행되지 않습니다.

기여 및 보안

풀 리퀘스트를 열기 전에 CONTRIBUTING.md를 읽으십시오. SECURITY.md에 따라 취약점을 비공개로 신고하십시오. 의심되는 자격 증명 유출 또는 거래 안전 취약점에 대해 공개 이슈를 열지 마십시오. 일반적인 사용 도움말은 SUPPORT.md에 있습니다.

법적 고지 및 위험 고지

이 소프트웨어는 개발 및 연구용으로 제공됩니다. 투자, 금융, 법률, 세무, 규정 준수 또는 거래 조언을 제공하지 않습니다. 이벤트 컨트랙트 및 레버리지 상품은 투입한 전체 금액의 손실을 포함하여 빠르고 상당한 손실을 초래할 수 있습니다. 계정 자격, 관할권 제한, 거래소 규칙, 규제 요구 사항, 세금, 전략, 주문 및 손실에 대한 책임은 사용자에게 있습니다.

AI 시스템 및 소프트웨어는 의도를 오해하고, 잘못된 매개변수를 생성하고, 요청을 반복하거나 예기치 않게 동작할 수 있습니다. 라이브 배포 전에 인간 검토, 거래소 측 위험 한도, 최소 권한 자격 증명, 모니터링 및 독립적인 비상 중지가 필요합니다.

전체 DISCLAIMER.md, PRIVACY.md 및 SECURITY.md를 읽으십시오. 이 프로젝트는 Apache License 2.0에 따라 라이선스가 부여됩니다. 타사 자료는 THIRD_PARTY_NOTICES.md에 설명된 대로 제외됩니다.