Communitygithub.com

Kalshi 예측 시장 API

미국 CFTC 규제 예측 시장에서 정치, 경제, 스포츠, 날씨 등 다양한 주제의 바이너리 이벤트 계약을 거래하고 조회합니다.

Kalshi 예측 시장 API란 무엇인가요?

이 스킬은 AI 에이전트가 Kalshi 예측 시장 거래소의 CFTC 규제 바이너리 계약 시장과 상호작용할 수 있도록 설계되었습니다. Kalshi는 '예' 또는 '아니오'로 결정되는 실제 세계 이벤트(예: CPI 3% 이상, 스포츠 경기 결과, 고용 보고서 수치)에 대한 계약을 제공하며, 가격은 1~99센트 범위의 내재 확률을 나타냅니다. 이 스킬은 시리즈(반복 이벤트 템플릿), 이벤트(특정 인스턴스), 마켓(개별 바이너리 결과)의 계층 구조를 통해 탐색하는 방법을 설명합니다. 특히 스포츠 경기나 선거와 같은 시리즈 기반 카테고리의 경우, 잘못된 정보를 반환할 수 있는 키워드 검색 대신 올바른 엔드포인트를 사용하여 탐색해야 합니다. 인증은 RSA 키-쌍 서명(PSS, SHA256)을 사용하며, 특정 환경 변수 포맷과 서명 시 주의사항(예: 쿼리 문자열 제외)이 포함됩니다. 이 스킬은 Claude Code, Cursor, Codex 등 AI 코딩 도구에서 Kalshi 거래를 자동화하거나 예측 시장 데이터를 분석할 때 사용할 수 있습니다.

지원 대상~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/Starchild-ai-agent/official-skills/tree/HEAD/kalshi

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Kalshi API

CFTC 규제 최초의 예측 시장 거래소에서 거래하고 조회합니다. 실제 세계 이벤트에 대한 바이너리 예/아니오 계약으로 가격은 1~99센트입니다.

기본 URL: https://external-api.kalshi.com/trade-api/v2 데모 URL: https://external-api.demo.kalshi.co/trade-api/v2

https://kalshi.com/account/api-keys 에서 API 키를 받으세요 (프리미어 또는 마켓 메이커 티어 필요)

주요 개념

계층 구조: 시리즈 > 이벤트 > 마켓

  • 시리즈 — 반복 이벤트 템플릿 (예: "월간 고용 보고서", "주간 실업 수당 청구")
  • 이벤트 — 시리즈 내 특정 인스턴스 (예: "2026년 5월 고용 보고서")
  • 마켓 — 이벤트 내 개별 바이너리 결과 (예: "추가된 일자리가 200k 이상인가?")

바이너리 계약 가격 책정

  • 가격은 센트 단위 (1-99)이며, 내재 확률을 나타냅니다.
  • 65c의 예 계약 = 시장이 65% 확률을 의미함
  • 가격 X의 예 매수는 (100 - X)의 아니오 매도와 동일합니다. — 오더북에는 예 매수와 아니오 매수만 표시됩니다.
  • 정산: 예이면 $1.00(100센트) 지급, 아니오이면 $0 지급
  • 모든 금전적 가치 (잔고, 가격, 정산)는 센트 단위입니다.

티커 형식

  • 시리즈: KXBTC, KXJOBLESS, KXINX
  • 이벤트: KXBTC-25MAY30 (시리즈 + 날짜)
  • 마켓: KXBTC-25MAY30-T100000 (이벤트 + 임계값/결과)

스포츠 경기 티커는 다른 패턴을 따릅니다: {시리즈}-{YYMMDD}{팀1}{팀2}-{팀}

  • 예시: KXNHLGAME-25MAY12EDMORL-EDM (NHL, 2025년 5월 12일, 에드먼턴 vs 올랜도, 에드먼턴 승리)
  • 각 경기 이벤트에는 상호 배타적인 두 개의 예 마켓이 있습니다. — 팀당 하나씩

중요: 시리즈 기반 마켓 탐색

스포츠, 선거 또는 시리즈 기반 카테고리에 /markets?keyword=를 사용하지 마십시오. 이는 실제 경기 수준 마켓이 아닌 멀티 게임 팔레이 번들만 표시합니다. "NHL", "Fulham", "Premier League" 등을 검색하면 결과가 없거나 관련 없는 결과가 반환됩니다.

항상 탐색: 시리즈 → 이벤트 → 마켓. 경기 수준 마켓은 시리즈/이벤트 계층 구조 아래에 있으며 /events?series_ticker=KXXX를 통해 접근해야 합니다. 또한 /markets/{ticker}는 경기 마켓에 대해 404를 반환할 수 있습니다. — 매수/매도 가격은 이벤트 엔드포인트 응답(/events/{event_ticker}와 with_nested_markets=true)에만 나타납니다.

이 패턴은 스포츠뿐만 아니라 모든 시리즈 기반 카테고리에 적용됩니다:

  • 스포츠 경기 — NHL, NBA, NFL, MLB, EPL 등
  • 정치 경선 — 다중 후보 이벤트 내 개별 후보 마켓
  • 회사별 마켓 — 실적, CEO 변경 등
  • 반복 경제 데이터 — 고용 보고서, 실업 수당 청구, CPI 등

알려진 스포츠 시리즈 티커:

스포츠시리즈 티커예시
NHLKXNHLGAMEKXNHLGAME-25MAY12EDMORL
NBAKXNBAGAMEKXNBAGAME-25MAY12BOSLAL
NFLKXNFLGAMEKXNFLGAME-25SEP07KCDET
MLBKXMLBGAMEKXMLBGAME-25MAY12NYYLAD
EPL (프리미어 리그)KXEPLGAMEKXEPLGAME-25MAY12FULARS

스포츠 올바른 워크플로우:

# 1. 스포츠의 열린 경기 목록 조회
curl -s "https://external-api.kalshi.com/trade-api/v2/events?series_ticker=KXNHLGAME&status=open&with_nested_markets=true"

# 2. 실시간 매수/매도가 포함된 특정 경기 조회
curl -s "https://external-api.kalshi.com/trade-api/v2/events/KXNHLGAME-25MAY12EDMORL?with_nested_markets=true"

# 틀린 방법 — 이렇게 하지 마세요:
# curl -s "https://external-api.kalshi.com/trade-api/v2/markets?keyword=NHL"  ← 팔레이 반환, 경기 아님

호출 방법

Kalshi는 RSA 키-쌍 서명 인증을 사용합니다. 인증된 요청에는 세 가지 헤더가 필요합니다.

헤더값
KALSHI-ACCESS-KEYAPI 키 ID ($KALSHI_ACCESS_KEY)
KALSHI-ACCESS-SIGNATUREtimestamp + method + path의 RSA-PSS 서명
KALSHI-ACCESS-TIMESTAMPUnix 타임스탬프 (ms)

공개 GET 엔드포인트 (마켓, 이벤트, 오더북)는 인증 헤더 없이 호출할 수 있습니다.

# 공개 엔드포인트 — 인증 불필요
curl -s "https://external-api.kalshi.com/trade-api/v2/markets?limit=10&status=open"

인증된 엔드포인트의 경우 직접 RSA-PSS 서명을 사용하십시오 (kalshi_python SDK는 작동하지 않습니다):

import os, time, base64, requests
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.backends import default_backend
from dotenv import load_dotenv
load_dotenv('/data/workspace/.env')

BASE_URL = "https://api.elections.kalshi.com"

def kalshi_headers(method: str, path: str) -> dict:
    import re
    raw = os.environ["KALSHI_PRIVATE_KEY"]
    # 일부 입력 채널에서 '\n'을 실제 개행 대신 백슬래시+n 두 문자로 저장하는 경우를 처리하기 위해
    # 먼저 리터럴 이스케이프 시퀀스를 디코딩합니다.
    raw = (raw.replace('\\r\\n', '\n').replace('\\n', '\n')
              .replace('\\r', '\n').replace('\\t', ' '))
    # PEM 마커가 있으면 제거한 다음, 모든 공백을 제거하고 다시 감쌉니다.
    body = re.sub(r'-----BEGIN[^-]+-----', '', raw)
    body = re.sub(r'-----END[^-]+-----', '', body)
    body = re.sub(r'\s+', '', body)
    wrapped = '\n'.join(body[i:i+64] for i in range(0, len(body), 64))
    pem = f"-----BEGIN RSA PRIVATE KEY-----\n{wrapped}\n-----END RSA PRIVATE KEY-----\n"
    private_key = serialization.load_pem_private_key(pem.encode(), password=None, backend=default_backend())
    ts = str(int(time.time() * 1000))
    msg = (ts + method + path).encode()  # path는 쿼리 문자열을 포함하지 않아야 함
    sig = private_key.sign(msg, padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.DIGEST_LENGTH), hashes.SHA256())
    return {
        "KALSHI-ACCESS-KEY": os.environ["KALSHI_ACCESS_KEY"].strip(),
        "KALSHI-ACCESS-TIMESTAMP": ts,
        "KALSHI-ACCESS-SIGNATURE": base64.b64encode(sig).decode(),
        "Content-Type": "application/json"
    }

path = "/trade-api/v2/portfolio/balance"
resp = requests.get(BASE_URL + path, headers=kalshi_headers("GET", path))
print(resp.json())  # {"balance": 5000, ...} — 잔고는 센트 단위

서명 시 주의사항:

  • PSS, PKCS1v15 아님 — PKCS1v15 패딩은 401을 반환합니다. SHA256과 함께 PSS를 사용해야 합니다.
  • 서명 전 쿼리 문자열 제거 — 서명은 기본 경로에 대해서만 계산됩니다 (예: /trade-api/v2/portfolio/balance), /trade-api/v2/portfolio/balance?param=value가 아닙니다. 쿼리 문자열을 포함하면 401이 반환됩니다.
  • 키 환경 변수 형식 — KALSHI_PRIVATE_KEY는 다음 형식을 허용합니다: 원시 base64 본문, 실제 개행이 포함된 전체 PEM, 또는 웹 양식을 통해 붙여넣을 때 일반적으로 나타나는 공백으로 축소된 개행이 포함된 전체 PEM. 헬퍼 함수는 모든 형식을 자동으로 정규화합니다. 가장 강력한 저장을 위해 .env에 \n 이스케이프가 포함된 큰따옴표로 묶인 여러 줄 PEM으로 저장하여 python-dotenv가 실제 PEM 문자열로 복원하도록 하십시오.

API 스펙

전체 OpenAPI 스펙: https://docs.kalshi.com/openapi.yaml

의도 라우팅

사용자 의도를 올바른 엔드포인트에 매핑합니다. 모든 경로는 기본 URL을 기준으로 합니다.

이벤트

메서드엔드포인트주요 매개변수설명
GET/eventslimit (1-200), cursor, status, series_ticker, with_nested_markets이벤트 목록 (다변량 제외)
GET/events/{event_ticker}event_ticker, with_nested_markets특정 이벤트 조회
GET/events/{event_ticker}/metadataevent_ticker이벤트 메타데이터만
GET/events/multivariatelimit, cursor, series_ticker, collection_ticker, with_nested_markets다변량 (콤보) 이벤트 목록

마켓

메서드엔드포인트주요 매개변수설명
GET/marketslimit, cursor, status, ticker, event_ticker, series_ticker, min_close_ts, max_close_ts마켓 목록/필터
GET/markets/{ticker}ticker특정 마켓 세부 정보 조회
GET/markets/{ticker}/orderbookticker, depth현재 오더북 (예 매수 + 아니오 매수)
GET/markets/orderbookstickers (배열, 최대 100)배치 오더북
GET/markets/tradesticker, limit, cursor, min_ts, max_ts마켓 간 거래 내역

캔들스틱

메서드엔드포인트주요 매개변수설명
GET/series/{series_ticker}/markets/{ticker}/candlesticksseries_ticker, ticker, start_ts, end_ts, period_interval마켓 수준 캔들
GET/series/{series_ticker}/events/{ticker}/candlesticksseries_ticker, ticker, start_ts, end_ts, period_interval집계된 이벤트 수준 캔들
GET/markets/candlesticksmarket_tickers, start_ts, end_ts, period_interval배치 캔들스틱

period_interval 값: 1 (1분), 60 (1시간), 1440 (1일)

예측 및 실시간 데이터

메서드엔드포인트주요 매개변수설명
GET/series/{series_ticker}/events/{ticker}/forecast_percentile_historypercentiles (0-10000), start_ts, end_ts, period_interval과거 예측 백분위수
GET/live_data/milestone/{milestone_id}milestone_id, include_player_stats실시간 마일스톤 데이터
GET/live_data/batchmilestone_ids (배열, 최대 100), include_player_stats배치 실시간 데이터
GET/live_data/game-stats/{milestone_id}milestone_id실시간 통계 (축구, 농구, 축구, 하키, 야구)

시리즈

메서드엔드포인트주요 매개변수설명
GET/series/{series_ticker}series_ticker, include_volume시리즈 템플릿 조회
GET/seriescategory, tags, include_volume, min_updated_ts모든 시리즈 목록

거래소 정보

메서드엔드포인트주요 매개변수설명
GET/exchange/status—현재 거래소 상태
GET/exchange/schedule—운영 시간
GET/exchange/announcements—플랫폼 공지사항
GET/exchange/user_data_timestamp—데이터 동기화 타임스탬프
GET/series/fee_changesseries_ticker, show_historical수수료 변경 내역

검색 및 탐색

메서드엔드포인트주요 매개변수설명
GET/search/tags_by_categories—시리즈 카테고리별 태그
GET/search/filters_by_sport—스포츠별 필터

주문 (인증 필요)

메서드엔드포인트주요 매개변수설명
GET/portfolio/ordersticker, event_ticker, status, limit, cursor, subaccount사용자 주문 목록
GET/portfolio/orders/{order_id}order_id특정 주문 조회
POST/portfolio/orders본문: ticker, action, side, type, count, yes_price/no_price주문 생성
DELETE/portfolio/orders/{order_id}order_id, subaccount주문 취소
POST/portfolio/orders/{order_id}/amendorder_id, 본문: 새 count/price주문 변경
POST/portfolio/orders/{order_id}/decreaseorder_id, 본문: 감소 금액주문 수량 감소
POST/portfolio/orders/batched본문: 주문 배열배치 생성 (최대 크기는 티어에 따라 다름)
DELETE/portfolio/orders/batched본문: 주문 ID 배열배치 취소
GET/portfolio/orders/queue_positionsmarket_tickers, event_ticker, subaccount모든 대기 주문 큐 위치
GET/portfolio/orders/{order_id}/queue_positionorder_id특정 주문 큐 위치

주문 V2 — 이벤트-마켓 주문 (인증 필요, 고정 소수점)

메서드엔드포인트주요 매개변수설명
POST/portfolio/events/orders본문: 이벤트 티커, 마켓 방향, 가격 (고정 소수점), 수량V2 주문 생성
POST/portfolio/events/orders/batched본문: V2 주문 배열V2 배치 생성
DELETE/portfolio/events/orders/{order_id}order_id, subaccountV2 주문 취소
DELETE/portfolio/events/orders/batched본문: 주문 ID 배열V2 배치 취소
POST/portfolio/events/orders/{order_id}/amendorder_id, 본문: 새 수량/가격V2 주문 변경
POST/portfolio/events/orders/{order_id}/decreaseorder_id, 본문: 새 남은 수량V2 주문 감소

주문 그룹 (인증 필요)

메서드엔드포인트주요 매개변수설명
GET/portfolio/order_groupssubaccount모든 주문 그룹 목록
POST/portfolio/order_groups/create본문: 계약 한도주문 그룹 생성
GET/portfolio/order_groups/{id}id, subaccount특정 그룹 조회
DELETE/portfolio/order_groups/{id}id, subaccount그룹 삭제 및 모든 주문 취소
PUT/portfolio/order_groups/{id}/limitid, 본문: 새 한도계약 한도 업데이트
PUT/portfolio/order_groups/{id}/triggerid, subaccount그룹 트리거 (모든 주문 취소)
PUT/portfolio/order_groups/{id}/resetid, subaccount체결된 계약 카운터 재설정

포트폴리오 (인증 필요)

메서드엔드포인트주요 매개변수설명
GET/portfolio/balancesubaccount잔고 및 포트폴리오 가치 (센트 단위)
GET/portfolio/positionscursor, limit, count_filter, ticker, event_ticker, subaccount사용자 포지션
GET/portfolio/fillsticker, order_id, min_ts, max_ts, limit, cursor, subaccount모든 거래 체결 내역
GET/portfolio/settlementslimit, cursor, ticker, event_ticker, min_ts, max_ts, subaccount정산 내역
GET/portfolio/depositslimit, cursor입금 내역
GET/portfolio/withdrawalslimit, cursor출금 내역
GET/portfolio/summary/total_resting_order_value—총 대기 주문 가치 (...)

[잘림: 전체 내용은 원본 참조]

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

관련 스킬