키움 REST API 공매도 추이 ka10014 — 함정 6가지

1. ka10014가 실제로 주는 것

키움증권 공식 REST API 저장소의 examples/국내주식/공매도/get_domestic_short_sale_trend.py 머리말에 스펙이 그대로 적혀 있습니다.

# ---
# api_id: ka10014
# api_name: 공매도추이요청
# category: 국내주식
# sub_category: 공매도
# api_url: /api/dostk/shsa
# menu_path: 국내주식 > 공매도 > 공매도추이요청(ka10014)
# ---

요청 바디는 네 개뿐입니다. stk_cd(종목코드)·strt_dt(시작일자 YYYYMMDD)·end_dt(종료일자)가 필수이고 tm_tp(시간구분)가 선택입니다. 예제 코드는 앞의 셋이 비어 있으면 ValueError를 먼저 던집니다.

body = {
    "stk_cd": "005930",     # 종목코드
    "strt_dt": "20250501",  # 시작일자
    "end_dt":  "20250519",  # 종료일자
}
if tm_tp is not None:
    body["tm_tp"] = tm_tp   # 시간구분 — 0:시작일, 1:기간

응답은 shrts_trnsn이라는 키 아래 배열로 옵니다. 예제의 COLUMNS 매핑이 필드 의미의 1차 출처입니다.

2. 함정 1 — 여기엔 '잔고'가 없다

공매도 데이터를 찾는 사람의 절반은 사실 잔고를 찾고 있습니다. "이 종목에 공매도가 얼마나 쌓여 있나"가 궁금한 것이지, "어제 하루 얼마나 팔았나"가 궁금한 게 아니기 때문입니다. 그런데 위 열한 개 필드 어디에도 잔고가 없습니다.

잔고 성격의 값은 다른 카테고리에 있습니다. 같은 저장소의 examples/국내주식/대차거래/에 있는 ka20068 대차거래추이요청(종목별)입니다.

3. 함정 2 — ovr_shrts_qty는 구간 누적이다

필드명이 누적공매도량이라 잔량으로 읽기 쉽지만, 이 값은 조회 구간 안에서 공매도 거래량이 쌓인 합의 성격입니다. 빌린 주식을 갚으면 줄어드는 잔고와 달리, 거래량 누적은 상환이 반영되지 않습니다. 즉 되갚기가 아무리 많아도 이 숫자는 내려가지 않습니다.

실무에서는 이렇게 구분해 쓰는 편이 안전합니다.

• 그날의 압력 크기 → shrts_qty와 trde_wght(매매비중)
• 금액 기준 규모 → shrts_trde_prica
• 단가 위치 → shrts_avg_pric을 close_pric과 대조
• 쌓여 있는 양 → ka10014로는 알 수 없다. ka20068의 rmnd나 KRX 공시로

4. 함정 3 — tm_tp 0과 1

예제 함수의 docstring에 적힌 설명은 한 줄입니다.

tm_tp: 시간구분 — 0:시작일, 1:기간          # 기본값 '1'

기본값 '1'은 strt_dt~end_dt 구간 조회입니다. '0'은 시작일 기준이라 응답 행 수가 달라집니다. 선택 파라미터라 None이면 바디에서 아예 빠지는데, 그 경우 서버 기본 동작이 무엇인지는 예제만으로 확정할 수 없습니다. 봇에 넣기 전에 두 값을 각각 한 번씩 호출해 응답 행 수를 눈으로 비교하고, 쓰는 값을 명시적으로 고정하십시오. 이런 코드값 계열은 차트 조회의 기간 구분에서도 같은 방식으로 확인해야 합니다.

5. 함정 4 — 10페이지에서 조용히 잘린다

키움 REST API의 연속조회는 응답 헤더의 cont-yn과 next-key를 다음 요청에 다시 실어 보내는 구조입니다. 공식 예제의 루프는 이렇게 생겼습니다.

MAX_PAGES = 10             # 최대 조회 페이지 수
REQUEST_DELAY_SECONDS = 0.2

for page in range(MAX_PAGES):
    response = client.fetch_page(api_id=API_ID, path=API_URL, body=body,
                                 cont_yn=next_cont_yn, next_key=next_key)
    ...
    next_cont_yn = response.continuation.cont_yn
    next_key     = response.continuation.next_key

    if next_cont_yn != "Y":
        break
    if page + 1 >= MAX_PAGES:
        break                      # ← 경고도 예외도 없이 그냥 끝난다
    time.sleep(REQUEST_DELAY_SECONDS)

연속조회 자체의 동작 방식은 cont-yn·next-key 연속조회에서 더 자세히 다뤘습니다.

6. 함정 5 — 값은 전부 문자열이다

예제에 들어 있는 _format_display_value를 값 변환 함수로 착각하면 안 됩니다. 실제 동작은 이렇습니다.

text = str(value).strip()
sign = "-" if text.startswith("-") else ""
unsigned = text[1:] if sign else text
...
if unsigned.isdigit() and len(unsigned) >= 6:
    return f"{sign}{int(unsigned or '0'):,}"     # 6자리 이상만 콤마
return value                                      # 나머지는 원본 그대로

부호를 먼저 떼고, 여섯 자리 이상일 때만 콤마를 찍습니다. 다섯 자리 값은 콤마 없이 그대로 나가므로 출력 서식이 자릿수에 따라 달라집니다. 이건 화면에 예쁘게 찍기 위한 코드지 숫자 변환이 아닙니다. 계산에 쓸 값은 별도 함수로 처리하십시오.

def to_num(v, default=0.0):
    if v is None:
        return default
    s = str(v).replace(",", "").strip()
    if s in ("", "-", "+"):
        return default
    try:
        return float(s)
    except ValueError:
        return default

wght = to_num(row["trde_wght"])          # 매매비중
qty  = to_num(row["shrts_qty"])          # 공매도량
avgp = to_num(row["shrts_avg_pric"])     # 공매도평균가

7. 함정 6 — HTTP 200과 거래소 접미사

키움 REST API는 업무 오류도 HTTP 200으로 내려보내고 실패 여부는 응답 본문의 return_code에만 담습니다. 예제도 return_code가 None도 0도 아닐 때 return_msg와 함께 별도 메시지 표로 모아 둡니다. requests의 raise_for_status()만 믿으면 실패를 성공으로 처리하게 됩니다.

종목코드도 주의해야 합니다. stk_cd 설명에 거래소별 표기가 명시돼 있습니다.

같은 종목이라도 접미사에 따라 다른 요청이 됩니다. 거래소 분리 자체가 봇 설계에 주는 영향은 NXT·KRX 주문 라우팅에서 다뤘습니다.

8. 실전 코드

공식 예제를 그대로 쓰되 앞의 함정 세 개(잘림 경고·숫자 변환·return_code)를 막은 형태입니다.

import logging, time
import pandas as pd
from kiwoom import get_client, KiwoomError

API_ID, API_URL = "ka10014", "/api/dostk/shsa"
COLUMNS = {"dt":"일자","close_pric":"종가","trde_qty":"거래량",
           "shrts_qty":"공매도량","ovr_shrts_qty":"누적공매도량",
           "trde_wght":"매매비중","shrts_trde_prica":"공매도거래대금",
           "shrts_avg_pric":"공매도평균가"}

def short_sale_trend(stk_cd, strt_dt, end_dt, tm_tp="1", max_pages=50):
    client = get_client()
    rows, cont_yn, next_key = [], None, None

    for page in range(max_pages):
        res = client.fetch_page(api_id=API_ID, path=API_URL,
                                body={"stk_cd": stk_cd, "strt_dt": strt_dt,
                                      "end_dt": end_dt, "tm_tp": tm_tp},
                                cont_yn=cont_yn, next_key=next_key)
        b = res.body
        if b.get("return_code") not in (None, 0):          # HTTP 200이어도 실패일 수 있다
            raise KiwoomError(f'{b.get("return_code")} {b.get("return_msg")}')

        rows.extend(r for r in b.get("shrts_trnsn", []) if isinstance(r, dict))
        cont_yn, next_key = res.continuation.cont_yn, res.continuation.next_key
        if cont_yn != "Y":
            break
        if page + 1 >= max_pages:
            logging.warning("연속조회가 %d페이지에서 잘렸다 — 구간을 줄이거나 max_pages를 늘릴 것",
                            max_pages)
            break
        time.sleep(0.2)

    df = pd.DataFrame(rows).rename(columns=COLUMNS)
    for c in ("거래량","공매도량","누적공매도량","매매비중","공매도거래대금","공매도평균가","종가"):
        if c in df:
            df[c] = pd.to_numeric(df[c].astype(str).str.replace(",", ""), errors="coerce")
    return df.assign(일자=pd.to_datetime(df["일자"], format="%Y%m%d")).set_index("일자").sort_index()

if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)
    df = short_sale_trend("005930", "20250501", "20250519")
    print(df[["종가","공매도량","매매비중","공매도평균가"]].tail())

9. 정리

• ka10014 = POST /api/dostk/shsa + stk_cd·strt_dt·end_dt·tm_tp
• 잔고는 없다. 잔고 성격은 ka20068의 rmnd·remn_amt — 단 대차잔고 ≠ 공매도잔고
• ovr_shrts_qty는 구간 누적이라 상환이 반영되지 않는다
• tm_tp는 0=시작일 / 1=기간, 기본값 1
• 연속조회는 MAX_PAGES에서 경고 없이 잘린다 — 경고 한 줄을 넣을 것
• 값은 문자열이고 예제 포매터는 표시 전용, 실패도 HTTP 200으로 온다