한국투자증권 KIS API로 실시간 시세 받기 (WebSocket 실전)
TECH INSIGHT / EXPLAINED
실시간 시세는 파서, 구독 상태, 신선도 검사가 일치할 때 쓸 수 있습니다. KIS의 채널은 각각의 스키마로 다루고 비슷한 숫자 배열이라고 섞어 읽지 않습니다.
시장 체결과 내 계좌 체결을 구분한다
H0STASP0은 KRX 호가, H0STCNT0은 KRX 시장 체결가입니다. 시장 체결은 내 주문이 체결됐다는 뜻이 아닙니다. 계좌 체결 통보와 주문 조회는 별도로 대사해야 합니다. 다른 거래 장소와 통합 시세는 식별자가 다르므로 사용할 시장을 명시하세요.
전략의 기준선을 바꾸는 인덱스 오류
공식 H0STCNT0 샘플의 0부터 시작하는 배열에서 2는 STCK_PRPR, 7은 STCK_OPRC, 10은 ASKP1, 13은 ACML_VOL입니다. 따라서 10을 시가로, 13을 전일종가로 읽으면 틀립니다. 스키마와 필드명을 매핑하고 행 길이·숫자 변환·유한한 양수 가격을 검증합니다. 전일종가는 문서에 명시된 데이터에서 구하며 누적거래량을 재해석하지 않습니다.
파서가 통과해야 할 가상 사례
현재가 70,100, 시가 70,000, 매도 1호가 70,200, 누적거래량 45,678인 행에서 시가 대비 변화율은 (70,100/70,000−1)×100≈0.142857%입니다. 70,200이나 45,678을 기준선에 넣으면 안 됩니다. 잘린 행, 빈 필드, 숫자가 아닌 값, 한 봉투 안의 복수 레코드, 다른 TR을 시험하세요. 재현용 로그는 인증 메시지를 제외한 공개 시세 표본으로 만듭니다.
신청한 구독과 승인된 구독은 다르다
(TR, 종목, 연결 세대)를 키로 희망·대기·승인·거절 상태를 나눕니다. 문서의 승인 응답을 받은 뒤에만 승인 집합에 넣고, 재연결하면 연결별 승인 기록을 비운 뒤 필요한 구독을 복구합니다. 현재 서비스 한도를 확인하며 50ms 대기만으로 구독 성공을 보장하지 않습니다.
두 시계로 감시하고 매매는 별도로 막는다
전송/하트비트 최종 시각과 종목별 정상 시세 최종 시각을 따로 관리합니다. 거래가 뜸한 종목이 곧 연결 장애는 아니며, 하트비트가 왔다고 오래된 시세가 최신이 되지도 않습니다. 30/60초를 보편적인 규칙으로 쓰지 말고 세션과 관측값에 맞춰 정하세요. 입력 시세가 오래되면 신호를 중지하고 구독 복구와 정상 시세 수신 후 재개합니다.
프레임 해석과 전략 입력 사이에 경계를 둔다
수신 콜백이 곧바로 매매 조건을 계산하면 제어 응답과 데이터가 섞일 때 원인을 찾기 어렵습니다. 먼저 제어 메시지·시세 데이터·알 수 없는 형식으로 분류하고, 선택한 TR의 스키마로 레코드를 해석한 뒤 검증된 이벤트만 전략 큐에 넣습니다. KIS 공식 공통 예제도 시스템 응답과 PINGPONG을 별도로 처리합니다. 실제 하트비트 응답 형식은 해당 예제와 채널 규칙을 따릅니다.
복수 레코드라면 봉투에 표시된 개수와 해당 스키마의 필드 폭이 맞는지 확인합니다. 모르는 TR을 가장 비슷한 배열로 추측해 읽거나 잘린 마지막 행을 정상 가격으로 넘기지 않습니다. 실패한 프레임은 사유와 제한된 공개 표본만 격리하고, 인증·계좌 통보 원문을 일반 파서 로그에 남기지 않습니다.
재연결 뒤에는 예전 연결의 응답을 버린다
연결 3에서 신청한 구독 응답이 지연된 사이 연결 4가 시작될 수 있습니다. 콜백이 생성된 연결 세대를 보관하고 현재 세대와 다르면 상태를 갱신하지 않도록 하세요. 새 연결의 구독 승인은 그 연결에서 받은 확인으로만 판단합니다. 화면에서 이미 제거한 종목에 늦은 승인이 와도 희망 구독 집합에 되살리지 않습니다.
교육용 시나리오는 '구독 요청 → 연결 종료 → 새 연결 → 이전 승인 도착 → 새 승인 → 새 시세'입니다. 이전 승인은 아무 효과가 없어야 하고, 새 승인만 받았을 때도 시세의 신선도까지 만족한 것으로 간주하지 않습니다. 승인과 첫 유효 시세를 모두 관측한 뒤 해당 입력을 필요로 하는 신호를 재평가합니다.
최신 값만 필요한 입력과 모든 사건이 필요한 입력
소비 속도가 느려지면 큐를 무한히 늘리는 대신 데이터 용도를 먼저 구분합니다. 채널이 완전한 최신 스냅샷을 제공하고 전략도 현재 상태만 필요로 한다면 종목별 최신 값으로 합칠 수 있습니다. 반면 체결량 누적이나 틱 순서를 사용하는 계산은 중간 사건을 버리면 결과가 바뀝니다. 같은 큐 정책을 두 용도에 공통 적용하지 않습니다.
KIS 시세 스키마의 CNTG_VOL과 ACML_VOL처럼 단일 체결량과 누적값의 의미도 구분해야 합니다. 누적값 차이로 누락된 개별 틱의 시각·가격 경로까지 복원할 수는 없습니다. 이력 조회로 필요한 공백을 채울 수 있는지 확인하고, 불가능하면 관련 지표를 초기화하거나 충분한 새 데이터가 쌓일 때까지 기다립니다.
시간대와 세션 경계까지 포함한 재생 시험
시각만 있는 필드를 처리할 때는 시장 시간대, 거래일, 세션 문맥을 함께 보존합니다. 수신 PC의 오늘 날짜를 무조건 붙이면 장 경계와 지연 메시지를 잘못 분류할 수 있습니다. 원본 사건 시각과 로컬 수신 시각은 따로 기록하고, 정렬 근거가 부족한 입력에는 정확한 전역 순서를 보장한다고 표시하지 않습니다.
공개 가상 표본으로 정상 프레임, 다른 TR, 레코드 수 불일치, 빈 숫자, 폭주, 재연결 중 지연 콜백을 재생합니다. 검사 대상은 가격 계산뿐 아니라 전략에 들어간 이벤트 수, 격리 수, 큐 대기 시간, 연결 세대입니다. 구독 복구가 끝나도 누락 구간의 거래가 자동 복원됐다고 말하지 않는 것이 중요합니다. 이 절차는 로컬 파서·상태 관리 훈련이며 실시간 증권 연결이나 주문을 수행하지 않습니다.
공식 문서와 이어 읽기
내용·예제 검토: 2026-10-01
댓글
댓글 쓰기