키움 ka10037 외국계창구 — trde_tp 1이 거꾸로다

1. ka10034와 무엇이 다른가 — 창구 vs 투자자

ka10034 외인기간별매매상위는 "외국인(투자자 유형)이 기간 동안 몇 주를 샀나"를 줍니다. ka10037은 같은 /api/dostk/rkinfo 경로, 같은 dt 코드표를 쓰지만 집계 기준이 다릅니다. 주문을 받은 증권사가 외국계 회원사인가로 묶은 숫자입니다.

둘이 다른 개념이라는 건 키움 명세가 스스로 보여 줍니다. ka10063(장중투자자별매매요청)의 요청 필드에는 투자자 구분 invsr(6:외국인, 7:기관계, …)이 있고, 그와 별도로 frgn_all(외국계전체, 1:체크, 0:미체크)이 있습니다. 외국인 투자자가 국내 증권사로 주문하거나 국내 투자자가 외국계 창구를 쓰면 두 숫자는 엇갈립니다. 거래원 데이터의 성격은 ka10040 거래원 글에서 자세히 다뤘습니다.

ka10034 글에서 "금액 기준이 필요하면 직접 근사해야 한다"고 적었는데, ka10037은 sort_tp 1로 서버가 금액 순으로 줄을 세워 줍니다. 대신 대상이 외국계 창구로 좁아집니다.

2. 요청·응답 실물

명세의 request_example 원문입니다. 공식 예제 examples/국내주식/순위정보/get_domestic_foreign_broker_trade_top.py의 __main__도 같은 값입니다.

POST https://api.kiwoom.com/api/dostk/rkinfo
api-id: ka10037
authorization: Bearer {접근토큰}

{
    "mrkt_tp": "000",
    "dt": "0",
    "trde_tp": "1",
    "sort_tp": "2",
    "stex_tp": "1"
}

응답 response_example 원문(3행 중 1행)입니다. 모든 값이 문자열이고, 매도거래량에는 -, 매수거래량에는 + 부호가 붙어 옵니다.

{
    "frgn_wicket_trde_upper": [
        {
            "rank": "1",
            "stk_cd": "005930",
            "stk_nm": "삼성전자",
            "cur_prc": "69",
            "pred_pre_sig": "3",
            "pred_pre": "0",
            "flu_rt": "0.00",
            "sel_trde_qty": "-0",
            "buy_trde_qty": "+0",
            "netprps_trde_qty": "0",
            "netprps_prica": "0",
            "trde_qty": "0",
            "trde_prica": "0"
        }
    ],
    "return_code": 0,
    "return_msg": "정상적으로 처리되었습니다"
}

3. trde_tp 1의 뜻이 세 갈래다 — 명세 전수

"ka10034만 특이한 것 아닌가" 싶어서 kiwoom_api_spec.json의 apis 337개에서 요청 필드 trde_tp를 가진 TR을 전부 뽑아 첫 번째 코드의 뜻으로 묶었습니다(주문 TR의 호가구분 trde_tp는 제외).

for name, api in spec["apis"].items():
    for f in api["request"]["body"]:
        if f["element"] == "trde_tp":
            print(name, api["meta"]["URL"], f["description"])

같은 rkinfo 경로 안에서도 ka10034·ka10035는 1이 매도 쪽, ka10037·ka10039·ka10062·ka10065는 1이 매수 쪽입니다. 여러 순위 TR을 함수 하나로 감싸며 trde_tp="1"을 "순매수"로 하드코딩하면, 에러 없이 절반의 TR에서 반대 목록을 받습니다. 순위 TR을 묶어 쓰는 구조는 rkinfo 순위조회 글을 참고하십시오.

4. 함정 5가지

① 상수는 TR별로 둔다

BUY = "1" 같은 전역 상수는 위 표 때문에 성립하지 않습니다. TRDE_TP = {"ka10037": {"net_buy": "1"}, "ka10034": {"net_buy": "2"}}처럼 TR 코드를 키로 두고, 첫 운영 호출에서 상위 종목의 netprps_trde_qty 부호가 의도와 맞는지 한 번 확인하는 단언문을 넣어 두면 안전합니다.

② 매도거래량은 -가 붙어 온다

예시의 sel_trde_qty는 "-0", buy_trde_qty는 "+0"입니다. 부호는 방향 표시일 가능성이 높으므로 순매수를 직접 다시 계산할 때 buy - sel로 쓰면 두 수를 더한 값이 나옵니다. 서버가 주는 netprps_trde_qty를 쓰거나, 직접 계산하려면 abs()를 먼저 씌우십시오. 예시 값이 전부 0이라 부호 규칙은 운영 응답으로 한 번 확인해야 합니다.

③ 금액 단위가 TR마다 다르다 — 백만원 vs 천원

ka10037의 netprps_prica·trde_prica는 백만원입니다. 한 회원사가 많이 사고판 종목을 주는 ka10039(증권사별매매상위)의 netprps_amt·buy_amt·sell_amt는 천원입니다. "외국계 전체 vs 특정 외국계 회원사" 비중을 계산하면 1,000배가 어긋나니, 저장할 때 원 단위로 통일하십시오. ka10039는 mmcm_cd(회원사코드)가 필수라 ka10102(회원사 리스트)를 먼저 불러야 합니다.

④ 공식 예시는 자리표시자다

response_example 3행은 전부 005930 삼성전자이고 현재가가 69·316·675, 거래량·대금은 모두 0입니다. 형식 확인용이라 이 값으로 단위 테스트의 기대값을 만들면 안 됩니다. 운영 응답에서 같은 종목코드가 두 번 나오면 결측·중복으로 처리하는 방어 코드를 두십시오.

⑤ 공식 예제는 숫자로 바꿔 주지 않는다

예제의 NUMERIC_COLUMNS는 거래대금·거래량·등락율·매도거래량·매수거래량·순매수거래량·순매수대금·현재가 여덟 개이고 전일대비(pred_pre)는 빠져 있습니다. 게다가 이 목록은 화면 출력용 천 단위 쉼표(_format_display)에만 쓰입니다. 예시 응답을 pandas 2.2.3 DataFrame으로 만들어 보면 13개 열이 전부 object입니다. 그대로 netprps_prica로 정렬하면 문자열 순서("9" > "10000")가 나옵니다. dt 설명의 10;10일 오타와 기준일 필드 부재도 ka10034와 같습니다(ka10034 글 ②).

5. 최소 호출 코드

토큰은 환경변수에서 읽고, 연속조회는 공식 예제와 같은 MAX_PAGES = 10·REQUEST_DELAY_SECONDS = 0.2입니다. ①·②·③·⑤를 코드에서 막습니다.

import os, time, requests
import pandas as pd

BASE   = "https://api.kiwoom.com"              # 모의: https://mockapi.kiwoom.com
TOKEN  = os.environ["KIWOOM_TOKEN"]
TRDE   = {"net_buy": "1", "net_sell": "2", "buy": "3", "sell": "4"}   # ka10037 전용 ①
DT_OK  = {"0", "1", "5", "10", "20", "60"}
NUM    = ["cur_prc", "pred_pre", "flu_rt", "sel_trde_qty", "buy_trde_qty",
          "netprps_trde_qty", "netprps_prica", "trde_qty", "trde_prica"]

def ka10037(side="net_buy", dt="0", sort_tp="1", mrkt_tp="000", stex_tp="1",
            max_pages=10, delay=0.2):
    if str(dt) not in DT_OK:
        raise ValueError(f"ka10037 dt={dt} 불가")
    body = {"mrkt_tp": mrkt_tp, "dt": str(dt), "trde_tp": TRDE[side],
            "sort_tp": sort_tp, "stex_tp": stex_tp}
    rows, cont_yn, next_key = [], None, None
    for _ in range(max_pages):
        h = {"Content-Type": "application/json;charset=UTF-8",
             "authorization": f"Bearer {TOKEN}", "api-id": "ka10037"}
        if cont_yn == "Y":
            h.update({"cont-yn": "Y", "next-key": next_key})
        r = requests.post(BASE + "/api/dostk/rkinfo", headers=h, json=body, timeout=10)
        j = r.json()
        if j.get("return_code") not in (None, 0):
            raise RuntimeError(f"ka10037 {j.get('return_code')}: {j.get('return_msg')}")
        rows += j.get("frgn_wicket_trde_upper", [])
        cont_yn, next_key = r.headers.get("cont-yn"), r.headers.get("next-key")
        if cont_yn != "Y":
            break
        time.sleep(delay)
    df = pd.DataFrame(rows)
    df[NUM] = df[NUM].apply(pd.to_numeric, errors="coerce")        # ⑤
    df["sel_trde_qty"] = df["sel_trde_qty"].abs()                   # ②
    df["netprps_won"] = df["netprps_prica"] * 1_000_000             # ③ 원 단위
    df = df.drop_duplicates("stk_cd")                               # ④
    df["dt"], df["asof"] = dt, pd.Timestamp.now().strftime("%Y-%m-%d")
    return df

return_code가 0이 아닐 때의 의미는 키움 return_code 글, cont-yn·next-key는 연속조회 글에 있습니다. 순위 TR 여러 개를 연달아 부를 때는 키움 429 호출 제한을 먼저 계산하십시오.

봇에서 쓴다면 장 마감 뒤 같은 dt로 ka10037(외국계 창구)과 ka10034(외국인 투자자)를 함께 받아 asof와 저장하고, 두 목록에 같이 나오는 종목을 표시하는 정도가 무난합니다. 한국투자증권 계좌라면 종목별 투자자 수급은 FHKST01010900(주식현재가 투자자)으로 받습니다. 외국계 창구 수급은 해석이 갈리는 데이터라 이 목록 자체가 매매 근거가 되지는 않으며, 이 글은 특정 종목이나 전략을 권하지 않습니다. 명세는 바뀔 수 있으니 키움 REST API 공식 문서로 현재 값을 확인하십시오.

6. 자주 묻는 질문