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 등
알려진 스포츠 시리즈 티커:
| 스포츠 | 시리즈 티커 | 예시 |
|---|---|---|
| NHL | KXNHLGAME | KXNHLGAME-25MAY12EDMORL |
| NBA | KXNBAGAME | KXNBAGAME-25MAY12BOSLAL |
| NFL | KXNFLGAME | KXNFLGAME-25SEP07KCDET |
| MLB | KXMLBGAME | KXMLBGAME-25MAY12NYYLAD |
| EPL (프리미어 리그) | KXEPLGAME | KXEPLGAME-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-KEY | API 키 ID ($KALSHI_ACCESS_KEY) |
KALSHI-ACCESS-SIGNATURE | timestamp + method + path의 RSA-PSS 서명 |
KALSHI-ACCESS-TIMESTAMP | Unix 타임스탬프 (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 | /events | limit (1-200), cursor, status, series_ticker, with_nested_markets | 이벤트 목록 (다변량 제외) |
| GET | /events/{event_ticker} | event_ticker, with_nested_markets | 특정 이벤트 조회 |
| GET | /events/{event_ticker}/metadata | event_ticker | 이벤트 메타데이터만 |
| GET | /events/multivariate | limit, cursor, series_ticker, collection_ticker, with_nested_markets | 다변량 (콤보) 이벤트 목록 |
마켓
| 메서드 | 엔드포인트 | 주요 매개변수 | 설명 |
|---|---|---|---|
| GET | /markets | limit, cursor, status, ticker, event_ticker, series_ticker, min_close_ts, max_close_ts | 마켓 목록/필터 |
| GET | /markets/{ticker} | ticker | 특정 마켓 세부 정보 조회 |
| GET | /markets/{ticker}/orderbook | ticker, depth | 현재 오더북 (예 매수 + 아니오 매수) |
| GET | /markets/orderbooks | tickers (배열, 최대 100) | 배치 오더북 |
| GET | /markets/trades | ticker, limit, cursor, min_ts, max_ts | 마켓 간 거래 내역 |
캔들스틱
| 메서드 | 엔드포인트 | 주요 매개변수 | 설명 |
|---|---|---|---|
| GET | /series/{series_ticker}/markets/{ticker}/candlesticks | series_ticker, ticker, start_ts, end_ts, period_interval | 마켓 수준 캔들 |
| GET | /series/{series_ticker}/events/{ticker}/candlesticks | series_ticker, ticker, start_ts, end_ts, period_interval | 집계된 이벤트 수준 캔들 |
| GET | /markets/candlesticks | market_tickers, start_ts, end_ts, period_interval | 배치 캔들스틱 |
period_interval 값: 1 (1분), 60 (1시간), 1440 (1일)
예측 및 실시간 데이터
| 메서드 | 엔드포인트 | 주요 매개변수 | 설명 |
|---|---|---|---|
| GET | /series/{series_ticker}/events/{ticker}/forecast_percentile_history | percentiles (0-10000), start_ts, end_ts, period_interval | 과거 예측 백분위수 |
| GET | /live_data/milestone/{milestone_id} | milestone_id, include_player_stats | 실시간 마일스톤 데이터 |
| GET | /live_data/batch | milestone_ids (배열, 최대 100), include_player_stats | 배치 실시간 데이터 |
| GET | /live_data/game-stats/{milestone_id} | milestone_id | 실시간 통계 (축구, 농구, 축구, 하키, 야구) |
시리즈
| 메서드 | 엔드포인트 | 주요 매개변수 | 설명 |
|---|---|---|---|
| GET | /series/{series_ticker} | series_ticker, include_volume | 시리즈 템플릿 조회 |
| GET | /series | category, tags, include_volume, min_updated_ts | 모든 시리즈 목록 |
거래소 정보
| 메서드 | 엔드포인트 | 주요 매개변수 | 설명 |
|---|---|---|---|
| GET | /exchange/status | — | 현재 거래소 상태 |
| GET | /exchange/schedule | — | 운영 시간 |
| GET | /exchange/announcements | — | 플랫폼 공지사항 |
| GET | /exchange/user_data_timestamp | — | 데이터 동기화 타임스탬프 |
| GET | /series/fee_changes | series_ticker, show_historical | 수수료 변경 내역 |
검색 및 탐색
| 메서드 | 엔드포인트 | 주요 매개변수 | 설명 |
|---|---|---|---|
| GET | /search/tags_by_categories | — | 시리즈 카테고리별 태그 |
| GET | /search/filters_by_sport | — | 스포츠별 필터 |
주문 (인증 필요)
| 메서드 | 엔드포인트 | 주요 매개변수 | 설명 |
|---|---|---|---|
| GET | /portfolio/orders | ticker, 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}/amend | order_id, 본문: 새 count/price | 주문 변경 |
| POST | /portfolio/orders/{order_id}/decrease | order_id, 본문: 감소 금액 | 주문 수량 감소 |
| POST | /portfolio/orders/batched | 본문: 주문 배열 | 배치 생성 (최대 크기는 티어에 따라 다름) |
| DELETE | /portfolio/orders/batched | 본문: 주문 ID 배열 | 배치 취소 |
| GET | /portfolio/orders/queue_positions | market_tickers, event_ticker, subaccount | 모든 대기 주문 큐 위치 |
| GET | /portfolio/orders/{order_id}/queue_position | order_id | 특정 주문 큐 위치 |
주문 V2 — 이벤트-마켓 주문 (인증 필요, 고정 소수점)
| 메서드 | 엔드포인트 | 주요 매개변수 | 설명 |
|---|---|---|---|
| POST | /portfolio/events/orders | 본문: 이벤트 티커, 마켓 방향, 가격 (고정 소수점), 수량 | V2 주문 생성 |
| POST | /portfolio/events/orders/batched | 본문: V2 주문 배열 | V2 배치 생성 |
| DELETE | /portfolio/events/orders/{order_id} | order_id, subaccount | V2 주문 취소 |
| DELETE | /portfolio/events/orders/batched | 본문: 주문 ID 배열 | V2 배치 취소 |
| POST | /portfolio/events/orders/{order_id}/amend | order_id, 본문: 새 수량/가격 | V2 주문 변경 |
| POST | /portfolio/events/orders/{order_id}/decrease | order_id, 본문: 새 남은 수량 | V2 주문 감소 |
주문 그룹 (인증 필요)
| 메서드 | 엔드포인트 | 주요 매개변수 | 설명 |
|---|---|---|---|
| GET | /portfolio/order_groups | subaccount | 모든 주문 그룹 목록 |
| POST | /portfolio/order_groups/create | 본문: 계약 한도 | 주문 그룹 생성 |
| GET | /portfolio/order_groups/{id} | id, subaccount | 특정 그룹 조회 |
| DELETE | /portfolio/order_groups/{id} | id, subaccount | 그룹 삭제 및 모든 주문 취소 |
| PUT | /portfolio/order_groups/{id}/limit | id, 본문: 새 한도 | 계약 한도 업데이트 |
| PUT | /portfolio/order_groups/{id}/trigger | id, subaccount | 그룹 트리거 (모든 주문 취소) |
| PUT | /portfolio/order_groups/{id}/reset | id, subaccount | 체결된 계약 카운터 재설정 |
포트폴리오 (인증 필요)
| 메서드 | 엔드포인트 | 주요 매개변수 | 설명 |
|---|---|---|---|
| GET | /portfolio/balance | subaccount | 잔고 및 포트폴리오 가치 (센트 단위) |
| GET | /portfolio/positions | cursor, limit, count_filter, ticker, event_ticker, subaccount | 사용자 포지션 |
| GET | /portfolio/fills | ticker, order_id, min_ts, max_ts, limit, cursor, subaccount | 모든 거래 체결 내역 |
| GET | /portfolio/settlements | limit, cursor, ticker, event_ticker, min_ts, max_ts, subaccount | 정산 내역 |
| GET | /portfolio/deposits | limit, cursor | 입금 내역 |
| GET | /portfolio/withdrawals | limit, cursor | 출금 내역 |
| GET | /portfolio/summary/total_resting_order_value | — | 총 대기 주문 가치 (...) |
[잘림: 전체 내용은 원본 참조]