KIS 실시간 시세 TR — H0STCNT0는 KRX 전용

거래량이 조금씩 모자란 봇

넥스트레이드(NXT) 출범 이후 국내 주식은 같은 종목이 두 곳에서 체결됩니다. 주문을 어디로 보낼지는 이미 NXT·KRX 주문 라우팅 쪽에서 다룬 주제인데, 실시간 시세를 받는 쪽에서 더 조용한 문제가 생깁니다.

증상은 이렇게 나타납니다. 봇은 멀쩡히 돌아갑니다. 웹소켓도 끊기지 않고, 체결 데이터도 계속 들어옵니다. 그런데 누적 거래량이 HTS 화면보다 조금씩 적습니다. 거래량 급증을 조건으로 쓰는 전략이라면 신호가 늦게 뜨거나 아예 안 뜹니다. 체결강도(CTTR)를 쓰는 전략이면 값이 미묘하게 다릅니다.

이 글은 연결하는 방법에 관한 글이 아닙니다. approval_key 발급, AES CBC 복호화, PINGPONG 처리 같은 접속 절차는 KIS API 웹소켓 실시간 시세 편에서 이미 다뤘습니다. 여기서 답하는 질문은 하나입니다 — 어느 TR을 구독해야 내가 원하는 데이터가 오는가.

TR ID 8자리를 읽는 법

KIS 실시간 TR ID는 8자리이고 자리마다 의미가 정해져 있습니다. 공식 예제 25개의 tr_id 상수를 전부 뽑아 놓고 보면 규칙이 한눈에 드러납니다.

이 규칙을 알면 H0UNASP0은 통합 호가, H0NXPGM0은 NXT 프로그램매매로 바로 읽힙니다. 반대로 내가 지금 구독 중인 TR이 어느 시장인지도 셋째 글자만 보면 즉시 확인됩니다.

국내주식 실시간 25종 전수표

공식 저장소 examples_llm/domestic_stock/ 아래의 실시간 함수 25개를 전부 열어 tr_id 상수와 columns 리스트를 뽑은 결과입니다. 필드 수는 예제가 정의한 컬럼 개수를 그대로 센 값입니다.

여기에 시장 구분이 없는 7종이 더 있습니다.

함정 1 — 46필드 중 22번만 이름이 다르다

체결가 세 TR은 필드 수가 46개로 완전히 같습니다. 순서도 같습니다. 딱 하나, 22번째 필드의 이름만 다릅니다.

# ccnl_krx.py — H0STCNT0 (KRX)
columns = [
    "MKSC_SHRN_ISCD", "STCK_CNTG_HOUR", "STCK_PRPR", "PRDY_VRSS_SIGN",
    ...
    "SELN_CNTG_SMTN", "SHNU_CNTG_SMTN",
    "CCLD_DVSN",          # ← 22번째
    "SHNU_RATE", ...
]

# ccnl_nxt.py — H0NXCNT0 (NXT)  /  ccnl_total.py — H0UNCNT0 (통합)
columns = [
    "MKSC_SHRN_ISCD", "STCK_CNTG_HOUR", "STCK_PRPR", "PRDY_VRSS_SIGN",
    ...
    "SELN_CNTG_SMTN", "SHNU_CNTG_SMTN",
    "CNTG_CLS_CODE",      # ← 22번째 (이름만 다름)
    "SHNU_RATE", ...
]

의미는 같은 체결구분입니다. 그런데 이름이 다르기 때문에, 응답을 딕셔너리로 만들어 놓고 row["CCLD_DVSN"]으로 읽던 코드는 통합(H0UNCNT0)으로 바꾸는 순간 KeyError가 납니다.

함정 2 — 호가는 필드 수가 다르다

체결가와 달리 호가는 필드 개수 자체가 다릅니다. KRX H0STASP0은 59개, NXT H0NXASP0과 통합 H0UNASP0은 65개입니다. 늘어난 여섯 개는 전부 중간가 관련 항목입니다.

10호가 잔량으로 지정가를 정하는 방식은 KIS API 호가 조회 편에서 다뤘는데, 그 로직을 실시간으로 옮길 때 시장별 필드 수를 먼저 확인해야 하는 이유가 이것입니다.

함정 3 — 대소문자가 TR마다 갈린다

공식 예제의 columns 리스트를 25개 전부 비교하면 대소문자가 일정하지 않습니다.

가장 헷갈리는 조합은 예상체결입니다. 같은 데이터인데 시장에 따라 표기와 개수가 둘 다 바뀝니다.

# exp_ccnl_krx.py — H0STANC0 (KRX 예상체결) : 소문자 45개
columns = [
    "mksc_shrn_iscd",  # 유가증권단축종목코드
    "stck_cntg_hour",  # 주식체결시간
    "stck_prpr",       # 주식현재가
    ...
]

# exp_ccnl_nxt.py — H0NXANC0 (NXT 예상체결) : 대문자 46개
columns = [
    "MKSC_SHRN_ISCD",
    "STCK_CNTG_HOUR",
    "STCK_PRPR",
    ...
]

함정 4 — 시간외·지수에는 시장 구분이 없다

앞의 매트릭스에서 3열이 채워지는 것은 여섯 종류뿐입니다. 나머지는 시장 구분 자체가 존재하지 않습니다.

• 시간외 3종은 KRX 접두사만 있습니다 — H0STOUP0(체결) · H0STOAA0(호가) · H0STOAC0(예상체결). 공식 예제 목록에 H0NXOUP0 같은 항목은 없습니다.
• 지수는 UP 접두사를 씁니다 — H0UPCNT0 · H0UPANC0 · H0UPPGM0. UN(통합)과 한 글자 차이라 오타가 나기 쉽습니다.
• 체결통보는 H0STCNI0 하나뿐이고, 실전/모의만 갈립니다(모의는 H0STCNI9). 내 주문의 체결 알림이므로 시장 구분이 필요 없습니다.

참고로 지수 프로그램매매 H0UPPGM0은 필드가 88개로 국내주식 실시간 중 가장 많습니다. 종목 단위 프로그램매매(H0STPGM0, 11필드)와 전혀 다른 크기라 같은 파서로 처리할 수 없습니다.

시장 중립으로 짜는 법

구독 TR을 설정값으로 빼 두면 시장 전환이 한 줄로 끝납니다. 아래는 앞서 확인한 네 가지 차이를 전부 흡수하는 구조입니다.

import os

# 시장 코드 → TR 접두사. 셋째·넷째 글자만 갈린다.
MARKET_PREFIX = {"KRX": "H0ST", "NXT": "H0NX", "UNIFIED": "H0UN"}

# 데이터 종류 → 접두사 뒤에 붙는 세 글자
FEED_SUFFIX = {
    "ccnl":    "CNT0",   # 체결가
    "asking":  "ASP0",   # 호가
    "exp":     "ANC0",   # 예상체결
    "program": "PGM0",   # 프로그램매매
    "member":  "MBC0",   # 회원사
    "mkop":    "MKO0",   # 장운영정보
}

# 기본값을 통합으로 둔다. NXT 누락을 막는 가장 싼 방법이다.
MARKET = os.getenv("KIS_MARKET", "UNIFIED")

def tr_id(feed: str, market: str = MARKET) -> str:
    """예: tr_id("ccnl") -> 'H0UNCNT0',  tr_id("asking", "KRX") -> 'H0STASP0'"""
    return MARKET_PREFIX[market] + FEED_SUFFIX[feed]

# 체결구분 필드는 시장에 따라 이름이 다르다 (KRX만 CCLD_DVSN)
def contract_division(row: dict):
    for key in ("CNTG_CLS_CODE", "CCLD_DVSN", "cntg_cls_code", "ccld_dvsn"):
        if key in row:
            return row[key]
    return None

def to_dict(msg_fields: list, columns: list) -> dict:
    """예제가 돌려준 columns를 그대로 써서 대소문자·개수 차이를 흡수한다."""
    keys = [c.upper() for c in columns]
    return dict(zip(keys, msg_fields))

핵심은 세 가지입니다.

1. 기본값을 UNIFIED로 둡니다. 명시적으로 KRX만 보겠다고 정하지 않는 한 통합을 받는 편이 누락을 막습니다.
2. 체결구분은 네 가지 키를 모두 시도합니다. 대소문자 두 갈래 × 이름 두 갈래를 한 함수에 가둡니다.
3. 필드 매핑은 반드시 columns로 합니다. 호가 59 ↔ 65처럼 개수가 달라져도 인덱스가 밀리지 않습니다.

정리

실시간 시세에서 시장 구분은 연결이 되느냐 마느냐의 문제가 아니라, 데이터가 맞느냐의 문제입니다. 틀린 TR을 써도 에러는 나지 않습니다. 그래서 더 오래갑니다.

• H0STCNT0은 KRX 전용 — 통합은 H0UNCNT0
• 셋째·넷째 글자가 시장 — ST/NX/UN/UP
• 체결가 22번 필드 이름이 갈린다 — CCLD_DVSN ↔ CNTG_CLS_CODE
• 호가는 59 ↔ 65로 개수가 갈린다 — 중간가 6필드
• 대소문자가 TR마다 다르다 — columns를 그대로 쓸 것
• 시간외·지수는 시장 구분이 없다

자동매매를 어떤 증권사로 붙일지 고르는 단계라면 증권사 API 비교와 키움 실시간 0B·0D 쪽도 같이 보십시오. 실시간 항목 구성은 증권사마다 꽤 다릅니다.

자주 묻는 질문

H0STCNT0를 구독하면 NXT 체결도 들어오나요?

들어오지 않습니다. 공식 저장소 예제에서 H0STCNT0은 ccnl_krx, 즉 국내주식 실시간체결가 (KRX)에 할당돼 있습니다. NXT는 H0NXCNT0, 통합은 H0UNCNT0입니다. 셋 다 응답 필드가 46개라 데이터가 정상으로 보이고, 누락은 거래량이 실제보다 적게 잡히는 형태로만 드러납니다.

KIS 실시간 TR ID는 어떻게 읽나요?

H0 + 시장 2자 + 데이터 3자 + 0 구조입니다. 시장은 ST(KRX)·NX(NXT)·UN(통합)·UP(지수), 데이터는 CNT(체결가)·ASP(호가)·ANC(예상체결)·PGM(프로그램매매)·MBC(회원사)·MKO(장운영정보)입니다. 시간외 3종과 체결통보는 이 규칙에서 벗어나므로 개별 확인이 필요합니다.

KRX와 NXT의 응답 필드가 같은가요?

체결가는 46개로 같지만 22번째 이름이 CCLD_DVSN(KRX) ↔ CNTG_CLS_CODE(NXT·통합)로 다릅니다. 호가는 개수가 다릅니다 — KRX 59개, NXT·통합 65개이고 늘어난 여섯은 KMID_PRC·KMID_TOTAL_RSQN·KMID_CLS_CODE·NMID_PRC·NMID_TOTAL_RSQN·NMID_CLS_CODE입니다. 위치로 읽는 파서는 여섯 칸이 어긋납니다.

실시간 응답 필드명이 대문자인가요 소문자인가요?

TR마다 다릅니다. 체결가·호가·체결통보는 대문자, KRX의 예상체결·프로그램매매·회원사·장운영정보와 시간외·지수는 소문자입니다. 같은 예상체결인데 H0STANC0는 소문자 45개, H0NXANC0는 대문자 46개입니다. 예제가 돌려주는 columns 리스트를 그대로 받아 쓰는 편이 안전합니다.

시간외와 지수도 NXT가 있나요?

공식 예제 목록 기준으로는 없습니다. 시간외는 H0STOUP0·H0STOAA0·H0STOAC0 세 종목뿐이고 전부 KRX 접두사입니다. 지수는 UP 접두사로 H0UPCNT0·H0UPANC0·H0UPPGM0 세 종목이 있고 여기에도 시장 구분이 없습니다. 항목 구성과 운영 정책은 바뀔 수 있으므로 구축 전에 KIS Developers 공식 문서에서 현재 기준을 다시 확인하십시오.