키움 REST API 실현손익 ka10072·ka10073 함정

봇이 주문을 내기 시작하면 곧바로 다음 질문이 옵니다. "그래서 얼마 벌었나." 잔고 조회로는 평가손익만 보이고, 판 것까지 포함한 실현손익은 별도 API입니다. 그런데 키움 REST에서 이 영역은 api_id가 네 개로 쪼개져 있고, 이름이 비슷한 것들의 응답 구조가 서로 다릅니다.

이 글은 키움 REST API 자동매매 가이드에서 계좌 영역만 떼어 낸 글입니다. 아래 항목명은 키움증권 공식 저장소(Kiwoom-Securities/Kiwoom-REST-API)의 examples/국내주식/계좌/ 샘플 코드 원문에서 확인했습니다.

1. 실현손익 api_id 4개 — 무엇을 언제 쓰나

네 개 모두 POST /api/dostk/acnt로 나가고, 요청 헤더 api-id로만 갈립니다. 잔고조회 kt00018과 같은 경로를 쓴다는 뜻입니다.

고르는 기준은 간단합니다.

• 하루치 종목별 내역이 필요하다 → ka10072 (시작일자만 주면 됨)
• 기간 전체의 종목별 내역이 필요하다 → ka10073
• 날짜별 합계와 총계만 필요하다 → ka10074
• 오늘 장중 특정 종목의 손익을 본다 → ka10077

2. 함정 1 — 리스트 키가 다르다

ka10072와 ka10073은 이름이 일자별종목별실현손익요청_일자와 일자별종목별실현손익요청_기간으로 끝 두 글자만 다릅니다. 그래서 하나를 먼저 붙이고 다른 하나를 복사해 붙이는 순서가 자연스럽습니다. 여기서 사고가 납니다.

# ka10072 — 공식 예제의 결과 키
TABLE_KEYS = {"dt_stk_div_rlzt_pl": "일자별종목별실현손익"}

# ka10073 — 같은 이름인데 키가 다르다
TABLE_KEYS = {"dt_stk_rlzt_pl": "일자별종목별실현손익"}

방어법은 하나입니다. 키를 상수로 박지 말고 api-id와 같이 묶어 두는 것입니다.

LIST_KEY = {
    "ka10072": "dt_stk_div_rlzt_pl",   # 일자
    "ka10073": "dt_stk_rlzt_pl",       # 기간
    "ka10074": "dt_rlzt_pl",
    "ka10077": "tdy_rlzt_pl_dtl",
}

rows = body.get(LIST_KEY[api_id])
if rows is None:
    raise RuntimeError(f"{api_id}: 응답에 {LIST_KEY[api_id]} 키가 없음 — 명세 변경 의심")

.get(key, [])가 아니라 .get(key) 뒤에 None 검사를 두는 것이 핵심입니다. 빈 결과와 키 오타를 구분할 수 있어야 합니다.

3. 함정 2 — ka10072에는 종료일자가 없다

ka10072의 요청 본문은 strt_dt와 stk_cd 둘뿐입니다. end_dt를 넣어도 받는 자리가 없습니다. 기간으로 뽑으려면 ka10073으로 가야 합니다.

# ka10072 — 시작일자 + 종목코드
{"strt_dt": "20260827", "stk_cd": "005930"}

# ka10073 — 시작일자 + 종료일자 + 종목코드
{"strt_dt": "20260801", "end_dt": "20260827", "stk_cd": "005930"}

# ka10074 — 기간만, 종목 구분 없이 날짜별 합계
{"strt_dt": "20260801", "end_dt": "20260827"}

ka10074는 종목코드를 받지 않는 대신 요약 항목이 함께 옵니다. 총매수금액 tot_buy_amt, 총매도금액 tot_sell_amt, 실현손익 rlzt_pl, 매매수수료 trde_cmsn, 매매세금 trde_tax입니다. 월간 리포트를 만들 때 가장 값싼 호출이 이것입니다. 종목별로 쪼갤 필요 없이 한 번에 총계가 나옵니다.

4. 함정 3 — 손익과 비용이 따로 온다

ka10072의 응답 항목은 아래와 같습니다.

손익 금액 tdy_sel_pl과 수수료·세금이 별도 항목으로 내려옵니다. ka10073에는 여기에 당일hts매도수수료 tdy_htssel_cmsn이 하나 더 붙습니다. 즉 두 API의 컬럼 집합도 완전히 같지 않습니다.

그리고 이 값들은 거래 집계이지 세무 신고 기준이 아닙니다. 국내주식·해외주식·파생의 과세 방식이 각각 다르고 연도별로 바뀝니다. 자동매매 세금 정리는 개념 정리용이고, 실제 신고는 세무 전문가와 국세청 공식 안내로 확인하십시오.

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

키움 REST 응답의 숫자 항목은 문자열로 옵니다. 손익은 음수가 나올 수 있어서 부호가 붙은 문자열이 섞입니다.

{
  "return_code": 0,
  "return_msg": "정상적으로 처리되었습니다",
  "dt_stk_div_rlzt_pl": [
    {
      "stk_cd": "005930",
      "stk_nm": "삼성전자",
      "cntr_qty": "10",
      "buy_uv": "71200",
      "cntr_pric": "72500",
      "tdy_sel_pl": "11420",
      "pl_rt": "1.60",
      "tdy_trde_cmsn": "230",
      "tdy_trde_tax": "1305",
      "wthd_alowa": "1842300",
      "loan_dt": "",
      "crd_tp": "00"
    }
  ]
}

from decimal import Decimal, InvalidOperation

NUMERIC = ("tdy_sel_pl", "pl_rt", "tdy_trde_cmsn", "tdy_trde_tax",
           "buy_uv", "cntr_pric", "wthd_alowa")

def coerce(row):
    out = dict(row)
    for k in NUMERIC:
        v = (out.get(k) or "").strip()
        try:
            out[k] = Decimal(v) if v else Decimal(0)
        except InvalidOperation:
            out[k] = Decimal(0)      # 빈 값·구분자 섞인 값 방어
    return out

loan_dt처럼 빈 문자열이 정상인 항목도 있습니다. 신용·대출 거래가 아니면 비어 있는 것이 맞으므로, 빈 값을 에러로 처리하면 안 됩니다.

6. 함정 5 — 연속조회를 안 돌리면 앞부분만 나온다

기간을 길게 잡으면 한 번의 응답에 다 안 들어옵니다. 키움 REST는 이때 응답 헤더에 cont-yn: Y와 next-key를 내려주고, 다음 요청 헤더에 그 두 값을 실어 보내야 이어지는 페이지가 옵니다.

headers = {
    "authorization": f"Bearer {token}",
    "api-id": "ka10073",
    "cont-yn": cont_yn,      # 첫 요청은 생략, 이후 직전 응답의 값
    "next-key": next_key,
}

공식 예제 코드는 반복 상한을 10페이지로 두고 요청 사이에 0.2초를 쉬는 형태로 작성돼 있습니다. 상한을 두는 이유는 무한 루프 방지이고, 간격을 두는 이유는 호출 한도입니다. 연속조회 헤더를 다루는 방법은 키움 REST 연속조회 cont-yn·next-key에, 한도를 넘겼을 때의 429 처리는 키움 REST 429 대응에 정리했습니다.

7. 봇에 넣는 일일 손익 집계 (전체 코드)

import time
from decimal import Decimal
import requests

BASE = "https://api.kiwoom.com"          # 모의는 mockapi.kiwoom.com
PATH = "/api/dostk/acnt"
LIST_KEY = {"ka10072": "dt_stk_div_rlzt_pl",
            "ka10073": "dt_stk_rlzt_pl",
            "ka10074": "dt_rlzt_pl",
            "ka10077": "tdy_rlzt_pl_dtl"}

def fetch_all(token, api_id, body, max_pages=10, delay=0.2):
    """cont-yn이 Y가 아닐 때까지 이어서 읽는다."""
    key = LIST_KEY[api_id]
    rows, cont_yn, next_key = [], None, None

    for _ in range(max_pages):
        headers = {"authorization": "Bearer " + token,
                   "api-id": api_id,
                   "Content-Type": "application/json;charset=UTF-8"}
        if cont_yn:
            headers["cont-yn"] = cont_yn
            headers["next-key"] = next_key

        r = requests.post(BASE + PATH, json=body, headers=headers, timeout=10)
        r.raise_for_status()
        data = r.json()

        if data.get("return_code") not in (None, 0):
            raise RuntimeError(f"{api_id}: {data.get('return_msg')}")

        page = data.get(key)
        if page is None:                  # 키 오타·명세 변경을 빈 결과와 구분
            raise RuntimeError(f"{api_id}: 응답에 {key} 없음")
        rows.extend(page)

        cont_yn  = r.headers.get("cont-yn")
        next_key = r.headers.get("next-key")
        if cont_yn != "Y":
            break
        time.sleep(delay)

    return rows


def daily_pnl(token, ymd):
    """오늘 하루 종목별 실현손익 합계 — ka10072 한 번으로 끝낸다."""
    rows = fetch_all(token, "ka10072", {"strt_dt": ymd, "stk_cd": ""})

    gross = sum(Decimal(r["tdy_sel_pl"] or 0) for r in rows)
    fee   = sum(Decimal(r["tdy_trde_cmsn"] or 0) for r in rows)
    tax   = sum(Decimal(r["tdy_trde_tax"] or 0) for r in rows)

    return {"date": ymd, "rows": len(rows),
            "sel_pl": gross, "cmsn": fee, "tax": tax}

8. 정리 — 체크리스트

• 실현손익 api-id는 4개: ka10072(일자) · ka10073(기간) · ka10074(합계) · ka10077(당일).
• 경로는 넷 다 /api/dostk/acnt. 구분은 헤더 api-id.
• 리스트 키는 dt_stk_div_rlzt_pl / dt_stk_rlzt_pl / dt_rlzt_pl / tdy_rlzt_pl_dtl — 전부 다름.
• .get(key, []) 금지. 키 없음과 빈 결과를 구분할 것.
• ka10072에 end_dt는 없다. 기간은 ka10073.
• 손익과 수수료·세금은 별도 항목. 순손익 정의는 직접 하고 실계좌로 대조.
• 숫자는 전부 문자열. 합계 전에 Decimal로 변환.
• cont-yn이 Y면 next-key로 이어서 조회.

본문의 api-id·요청 본문 항목·응답 리스트 키와 컬럼명은 2026-08-27 확인 기준 키움증권 공식 저장소 Kiwoom-Securities/Kiwoom-REST-API의 examples/국내주식/계좌/ 샘플 코드에서 확인한 값이고, 응답 예시의 숫자는 구조 이해를 돕기 위한 것입니다. 증권사 명세와 호출 한도 정책은 예고 없이 바뀝니다. 운영에 넣기 전 개발자 포털의 현재 명세로 대조하시고, 도메인·api-id·리스트 키는 코드에 흩어 두지 말고 한 곳에 모아 두시기 바랍니다.