KIS API 통합 레퍼런스

1. 시스템 개요 + 환경 구분

KIS API 시스템 특징

• 인증: appkey + appsecret → access_token (24시간 유효)
• 주문 보안: hashkey 추가 인증 (주문 body 변조 방지)
• TR_ID 기반: 같은 URL이라도 TR_ID로 세부 기능 구분
• 실전/모의 분리: URL + TR_ID 앞 글자(T/V)로 구분
• Rate Limit: 실전 20TPS, 모의 2TPS (초당 호출 수)

환경 2종 — 절대 섞이지 말 것

TR_ID 명명 규칙

필수 헤더 5개 (모든 API 공통)

2. OAuth 인증 + HashKey

Access Token 발급

url = 'https://openapivts.koreainvestment.com:29443/oauth2/tokenP'
body = {
    'grant_type': 'client_credentials',
    'appkey': APP_KEY,
    'appsecret': APP_SECRET
}
response = requests.post(url, json=body, timeout=10)
token = response.json()['access_token']

HashKey 생성

주문 API 호출 전에 반드시 실행. 주문 Body를 먼저 해시 엔드포인트에 보내 HASH를 받고, 그 HASH를 실제 주문의 헤더에 첨부.

def get_hashkey(body: dict) -> str:
    """주문 Body로 HashKey 생성."""
    url = 'https://openapivts.koreainvestment.com:29443/uapi/hashkey'
    headers = {
        'content-type': 'application/json',
        'appkey': APP_KEY,
        'appsecret': APP_SECRET
    }
    r = requests.post(url, json=body, headers=headers)
    return r.json()['HASH']

# 사용 예: 매수 주문
order_body = {
    'CANO': CANO,
    'ACNT_PRDT_CD': '01',
    'PDNO': '005930',
    'ORD_DVSN': '01',
    'ORD_QTY': '10',
    'ORD_UNPR': '0'
}
hash_key = get_hashkey(order_body)

headers = {
    'content-type': 'application/json',
    'authorization': f'Bearer {token}',
    'appkey': APP_KEY,
    'appsecret': APP_SECRET,
    'tr_id': 'VTTC0802U',
    'hashkey': hash_key   # 여기!
}
# order_body는 완전히 동일한 것을 재사용
response = requests.post(order_url, json=order_body, headers=headers)

3. 국내주식 시세 API

4. 국내주식 주문 API

5. 계좌/잔고 조회 API

6. TR_ID 전체 맵

7. 에러 코드 + 대응법

자주 만나는 에러 코드 20선

에러 응답 구조

{
  "rt_cd": "1",             // 0=성공, 1=실패
  "msg_cd": "EGW00121",     // 에러 코드
  "msg1": "해쉬키가 일치하지 않습니다."
}

def handle_kis_response(response):
    data = response.json()
    if data.get('rt_cd') == '0':
        return data['output']
    
    code = data.get('msg_cd')
    
    if code == 'EGW00201':
        time.sleep(2)
        raise RetryableError('Rate limit')
    elif code == 'EGW00123':
        refresh_token()
        raise RetryableError('Token expired')
    elif code in ['APBK0912', 'APBK0919']:
        notify_discord(f'자금/수량 부족: {data[\"msg1\"]}')
    
    raise Exception(f'KIS Error {code}: {data[\"msg1\"]}')

8. Rate Limit + 운영 패턴

Rate Limit 정책

운영 패턴 5가지

장 시간 (중요)

로깅 필수 항목

• □ 모든 주문 요청의 Body + Timestamp 저장 (재현용)
• □ 응답의 rt_cd, msg_cd, ODNO 저장
• □ Daily 단위 매매 건수·체결률·수익률 집계
• □ Rate Limit 발생 시간·빈도 추적 → 코드 개선
• □ 에러 로그는 별도 Sheet에 분리 저장