키움 REST API 순위 조회 — rkinfo 함정 5가지

이 글은 키움 REST API 자동매매 완전 가이드에서 순위 조회 한 가지만 떼어 낸 글입니다. 인증·토큰·TR limit 같은 공통 부분은 그 글을 먼저 보십시오.

1. 순위 조회 TR 은 어디에 있나

키움증권 공식 API 가이드의 순위정보 분류에 들어 있는 TR 은 다음과 같습니다. 국내주식 화면에서 “상위”·“급증”으로 부르는 목록이 대부분 여기 있습니다.

공통 경로는 POST /api/dostk/rkinfo 이고, 방식은 다른 키움 REST API 와 같습니다. 도메인은 실전이 https://api.kiwoom.com, 모의투자가 https://mockapi.kiwoom.com 입니다.

2. 요청 실물 — 경로와 api-id 는 한 쌍이다

키움 REST API 는 URL 경로 하나에 여러 TR 을 묶고 api-id 헤더로 구분합니다. 이 구조 때문에 “잘 되던 코드에서 api-id 문자열만 바꾸면 되겠지”가 통하지 않습니다.

import requests

BASE = "https://api.kiwoom.com"          # 모의투자는 https://mockapi.kiwoom.com

# ★ 경로와 api-id 를 한 쌍으로 묶어 둔다. 문자열만 갈아 끼우다 사고가 난다.
TR = {
    "ka10030": "/api/dostk/rkinfo",      # 당일거래량상위
    "ka10032": "/api/dostk/rkinfo",      # 거래대금상위
    "ka00198": "/api/dostk/stkinfo",     # 실시간종목조회순위 — 경로가 다르다
}

def call(api_id: str, body: dict, token: str, cont_yn="N", next_key=""):
    url = BASE + TR[api_id]
    headers = {
        "Content-Type": "application/json;charset=UTF-8",
        "authorization": f"Bearer {token}",
        "api-id": api_id,
        "cont-yn": cont_yn,
        "next-key": next_key,
    }
    resp = requests.post(url, headers=headers, json=body, timeout=10)
    resp.raise_for_status()              # ← 이것만으로는 업무 오류를 못 잡는다
    data = resp.json()

    # ★ 키움은 업무 오류도 HTTP 200 으로 내려준다. return_code 를 반드시 본다.
    rc = data.get("return_code")
    if rc not in (0, None):
        raise RuntimeError(f"키움 {api_id} 오류 rc={rc} msg={data.get('return_msg')}")
    return data, resp.headers.get("cont-yn"), resp.headers.get("next-key")

자주 보는 업무 오류는 아래와 같습니다. 8050 은 코드 문제가 아니라 PC 등록 문제라, 개발자가 몇 시간을 코드에서 찾다가 결국 키움 포털에서 해결하는 대표적인 코드입니다.

3. ka00198 의 qry_tp — 실시간이라는 이름의 1분 지연

ka00198 실시간종목조회순위는 이름에 ‘실시간’이 들어 있지만 WebSocket 이 아니라 REST 요청입니다. 요청 바디는 사실상 qry_tp 하나뿐인데, 이 값이 갱신 주기를 결정합니다.

# 실측 응답(값은 예시). item_inq_rank 배열로 온다.
{
  "item_inq_rank": [
    {"stk_cd": "005930", "stk_nm": "삼성전자", "bigd_rank": "1",
     "past_curr_prc": "75000", "base_comp_chgr": "+1.2",
     "dt": "20260501", "tm": "123445"},
    {"stk_cd": "000660", "stk_nm": "SK하이닉스", "bigd_rank": "2", "...": "..."}
  ],
  "return_code": 0,
  "return_msg": "정상적으로 처리되었습니다"
}

응답의 dt·tm 은 데이터가 만들어진 시각입니다. 폴링 결과를 신뢰할 수 있는지 확인하려면 응답을 받은 로컬 시각이 아니라 이 두 필드를 로그에 남기십시오. 값이 계속 같으면 갱신 주기 안에서 헛돌고 있다는 뜻입니다.

4. 순위 TR 에는 WebSocket 이 없다 — 폴링을 서버 시각에 맞춘다

키움 REST API 의 WebSocket 은 0B 주식체결, 0D 호가잔량 같은 종목 단위 실시간과 00 주문체결 통보, 04 잔고 통보를 다룹니다. 순위 계열은 등록 대상이 아니라서 REST 폴링만 가능합니다. 이 구조에서 흔한 실수는 “빠르게 받으려고 5초마다 호출”하는 것입니다. 서버가 30초마다 계산하므로 같은 값을 여섯 번 받고 호출 한도만 태웁니다.

더 골치 아픈 쪽은 PC 시계입니다. 실제 납품 PC 에서 NTP 동기화가 꺼져 있어 30초 지연이 고정으로 생긴 사례가 있었습니다. 매번 경계 직전에 호출하니 항상 직전 구간 값을 받았고, 로그만 보면 폴링은 정상이었습니다. 해결은 응답 헤더의 Date 로 서버 시각을 잡아 경계 직후에 호출하는 것입니다.

import time
from email.utils import parsedate_to_datetime

_offset = 0.0   # 서버시각 - 로컬시각

def sync_clock(resp):
    """응답 헤더 Date 로 서버 시각과의 차이를 잡아 둔다."""
    global _offset
    d = resp.headers.get("Date")
    if d:
        _offset = parsedate_to_datetime(d).timestamp() - time.time()

def next_wait(interval=30, buffer=1.5):
    """서버 시각 기준 다음 갱신 경계 + buffer 까지 대기한다."""
    server_now = time.time() + _offset
    boundary = ((int(server_now) // interval) + 1) * interval + buffer
    return max(1.0, boundary - server_now)

while market_open():
    data, _, _ = call("ka00198", {"qry_tp": "5"}, token)
    rows = data.get("item_inq_rank") or []
    if rows:
        log.info("순위 갱신 dt=%s tm=%s 1위=%s",
                 rows[0]["dt"], rows[0]["tm"], rows[0]["stk_nm"])
    else:
        log.warning("순위 응답이 비어 있음 — return_code 와 장 운영시간 확인")
    time.sleep(next_wait(30))

순위 응답이 비는 경우도 예외가 아니라 정상 상태일 수 있습니다. 장이 열리지 않은 날이 대표적입니다. 휴장일 판별은 KRX 휴장일 확인과 봇 스케줄링에서 다뤘고, 호출 한도 자체의 설계는 API 호출 제한 설계와 키움 REST 429 대응을 참고하십시오.

5. HTS 화면과 목록이 다를 때

같은 시각에 조회했는데 영웅문 화면과 목록이 다르면, 대개 조회 조건 파라미터가 기본값으로 들어간 것입니다. ka10020 호가잔량상위요청의 경우 바디에 거래량 구분 trde_qty_tp, 종목 조건 stk_cnd, 신용 조건 crd_cnd 같은 필드가 있습니다. HTS 화면에서는 사람이 상단 콤보박스로 골랐던 값들입니다.

또 하나 자주 놓치는 것은 거래소 구분입니다. 국내에 넥스트레이드(NXT)가 들어오면서 같은 종목이 거래소별로 나뉘어 집계될 수 있고, 종목코드에 접미사가 붙는 응답도 있습니다. 이 부분은 NXT·KRX 주문 라우팅에 정리해 뒀습니다.

붙이기 전 체크리스트