KIS 주문체결조회 — TTTC8001R 대신 TTTC0081R

KIS API 발급 가이드대로 앱키를 받고 TTTC0802U로 첫 매수 주문을 넣으면 응답에 ODNO(주문번호)가 돌아옵니다. 여기서 많은 사람이 "응답이 200이니 체결된 것"으로 처리합니다. 아닙니다. 그 응답은 "주문이 접수됐다"까지입니다. 지정가로 걸어 둔 주문은 하루 종일 미체결로 남을 수 있고, 절반만 체결될 수도 있습니다.

이 글은 그 다음을 확인하는 API 하나만 다룹니다. KIS 에러코드 목록에 안 나오는 문제인데, 호출은 성공하는데 tr_id가 옛 값이면 조회 자체가 서지 않거나 결과가 비어 오기 때문입니다.

1. tr_id 4종 — 실전·모의 × 3개월 안팎

이 API의 첫 관문은 파라미터가 아니라 tr_id입니다. 계좌 종류(실전·모의)와 조회 기간(3개월 이내·이전)의 조합으로 네 개가 존재합니다. 한국투자증권이 GitHub에 공개한 공식 예제 저장소 open-trading-api의 examples_llm/domestic_stock/inquire_daily_ccld 파일(상단 작성일 20250601) 기준으로 정리하면 이렇습니다.

"3개월"이라는 경계도 그냥 관례가 아닙니다. 같은 URL, 같은 파라미터인데 tr_id만 바뀌면 다른 저장소를 조회하는 구조입니다. 그래서 봇이 INQR_STRT_DT를 4개월 전으로 잡아 놓고 TTTC0081R로 부르면 기대한 데이터가 안 옵니다. 조회 시작일이 오늘 기준 3개월을 넘는지 계산해 tr_id를 자동으로 갈아 끼우는 분기를 만들어 두는 편이 낫습니다.

2. 요청 파라미터 — 필수 7개와 선택 5개

엔드포인트는 /uapi/domestic-stock/v1/trading/inquire-daily-ccld 하나입니다. CANO와 ACNT_PRDT_CD는 계좌번호 앞 8자리와 뒤 2자리를 나눠 넣는 규칙을 그대로 따릅니다.

맨 아래 EXCG_ID_DVSN_CD는 최근에 의미가 커진 항목입니다. 대체거래소가 열리면서 같은 종목이라도 주문이 어디로 나갔는지가 갈리기 때문에, KRX·NXT·SOR 주문 라우팅을 쓰는 봇이라면 조회에서도 이 값을 명시하는 편이 결과 해석이 쉽습니다. 구분 없이 전부 보고 싶다면 ALL입니다.

3. 실물 코드 — 오늘 미체결만 뽑기

가장 자주 쓰는 형태는 "오늘 낸 주문 중 아직 안 붙은 것"을 뽑는 것입니다. CCLD_DVSN을 02로 두면 됩니다. 아래는 requests만 쓰는 최소 코드입니다. ACCESS_TOKEN은 발급받아 캐시해 둔 값을 씁니다.

import requests, datetime

BASE = "https://openapi.koreainvestment.com:9443"
PATH = "/uapi/domestic-stock/v1/trading/inquire-daily-ccld"
today = datetime.date.today().strftime("%Y%m%d")

headers = {
    "content-type": "application/json; charset=utf-8",
    "authorization": f"Bearer {ACCESS_TOKEN}",
    "appkey":        APP_KEY,
    "appsecret":     APP_SECRET,
    "tr_id":         "TTTC0081R",   # 실전 · 3개월 이내
    "custtype":      "P",           # 개인
    "tr_cont":       "",            # 최초 조회는 공란
}

params = {
    "CANO": CANO, "ACNT_PRDT_CD": ACNT_PRDT_CD,
    "INQR_STRT_DT": today, "INQR_END_DT": today,
    "SLL_BUY_DVSN_CD": "00",   # 매수·매도 전체
    "CCLD_DVSN": "02",         # 02 = 미체결만
    "INQR_DVSN": "00",         # 역순(최신 주문부터)
    "INQR_DVSN_3": "00",
    "PDNO": "", "ODNO": "", "ORD_GNO_BRNO": "", "INQR_DVSN_1": "",
    "EXCG_ID_DVSN_CD": "KRX",
    "CTX_AREA_FK100": "", "CTX_AREA_NK100": "",
}

r = requests.get(BASE + PATH, headers=headers, params=params, timeout=5)
body = r.json()

for row in body["output1"]:
    print(row["odno"], row["prdt_name"],
          "주문", row["ord_qty"], "체결", row["tot_ccld_qty"],
          "잔여", row["rmn_qty"], "취소", row["cncl_yn"])

output1은 주문 한 건씩의 배열이고, output2는 합계 한 덩어리입니다. 봇에서 실제로 보게 되는 필드는 이 정도입니다.

4. 100건에서 끊길 때 — 연속조회

공식 예제 설명에 따르면 실전계좌는 한 번의 호출에 최대 100건, 모의계좌는 최대 15건입니다. 모의로 테스트하다가 15건에서 잘리는 것을 버그로 오해하는 경우가 많은데 정상 동작입니다. 나머지는 잔고조회와 동일한 연속조회 규약으로 받습니다.

# 응답 헤더 tr_cont 가 M 또는 F → 다음 페이지 있음
rows, fk, nk, cont = [], "", "", ""
while True:
    headers["tr_cont"] = cont
    params["CTX_AREA_FK100"], params["CTX_AREA_NK100"] = fk, nk
    r = requests.get(BASE + PATH, headers=headers, params=params, timeout=5)
    b = r.json()
    if b.get("rt_cd") != "0":
        raise RuntimeError(b.get("msg_cd"), b.get("msg1"))
    rows += b["output1"]

    if r.headers.get("tr_cont") not in ("M", "F"):
        break
    fk, nk, cont = b["ctx_area_fk100"], b["ctx_area_nk100"], "N"
    time.sleep(0.3)          # 초당 호출 제한 회피
print(len(rows), "건")

tr_cont가 M·F면 다음 페이지가 있고, D·E면 마지막입니다. 다음 호출의 요청 헤더 tr_cont는 N으로 바꿔야 한다는 점을 자주 빠뜨립니다. time.sleep을 뺐다가 EGW00201을 만나는 것도 흔한 순서인데, 그 에러는 초당 거래건수 초과 해결에 따로 정리해 뒀습니다.

5. 공식 예제 코드 안의 함정 2가지

이 API는 공식 샘플을 그대로 가져다 쓰는 경우가 많은데, 2025-06-01자 inquire_daily_ccld.py에는 그대로 복사하면 곤란한 지점이 두 곳 있습니다. 비난하려는 게 아니라, 붙여넣고 나서 원인을 못 찾는 일이 실제로 생기기 때문입니다.

① 연속조회 재귀 호출의 인자 순서

함수 시그니처는 … sll_buy_dvsn_cd, ccld_dvsn, inqr_dvsn, inqr_dvsn_3, pdno … 순인데, 다음 페이지를 부르는 재귀 호출은 … sll_buy_dvsn_cd, pdno, ccld_dvsn, inqr_dvsn, inqr_dvsn_3 … 순으로 넘깁니다. 키워드 인자가 아니라 위치 인자로 넘기기 때문에 2페이지부터 pdno가 ccld_dvsn 자리로 들어갑니다. 1페이지는 멀쩡한데 2페이지부터 결과가 이상해지는 전형적인 증상입니다. 재귀 호출을 전부 키워드 인자로 바꾸면 끝납니다.

② 컬럼 한글 매핑표의 라벨 밀림

같은 폴더의 chk_inquire_daily_ccld.py에 있는 COLUMN_MAPPING 끝부분은 tot_ccld_amt를 "매입평균가격", prsm_tlex_smtl을 "총체결금액", pchs_avg_pric을 "추정제비용합계"로 붙여 놓았습니다. 이름과 라벨이 한 칸씩 밀려 있습니다. 출력만 보고 금액을 읽으면 총체결금액과 매입평균가를 뒤집어 해석하게 됩니다. 표시용 한글 라벨을 믿지 말고 영문 필드명으로 접근하세요.

6. 폴링과 웹소켓 체결통보를 같이 쓰는 법

체결 확인 방법은 두 가지이고, 둘 중 하나만 쓰면 각각 다른 방식으로 틀립니다.

• 실시간 체결통보 웹소켓(실전 H0STCNI0, 모의 H0STCNI9) — 즉시 알려 주지만 연결이 끊긴 동안의 이벤트는 사라집니다. 게다가 체결통보 데이터는 복호화가 필요해 처리도 한 겹 더 듭니다 (웹소켓 실시간 시세·체결통보 참고).
• 주문체결조회 폴링(TTTC0081R) — 느리지만 계좌에 기록된 사실을 돌려줍니다. 재접속 후 공백을 메우는 데 이만한 게 없습니다.

실무에서 쓰는 조합은 단순합니다. 웹소켓을 주 경로로 두고, ① 재접속 직후 ② 주문 후 일정 시간이 지나도 통보가 없을 때 ③ 장 마감 후 하루 마감 처리, 이 세 시점에만 조회를 부릅니다. 매초 폴링하면 호출 제한에 걸리고, 안 부르면 유실을 못 잡습니다.

7. 자주 묻는 질문

모의투자에서도 같은 코드가 도나요?

도메인과 tr_id만 바꾸면 됩니다. 모의는 https://openapivts.koreainvestment.com:29443이고 tr_id는 VTTC0081R입니다. 건수 상한이 15건이라는 점, 그리고 모의계좌에서는 체결 시뮬레이션이 실전과 다르게 동작할 수 있다는 점만 감안하세요. 실전 전환 시 바꿔야 할 항목은 도메인과 tr_id만이 아니라는 점도 함께 기억해 두세요.

조회는 되는데 output1이 빈 배열로 옵니다

rt_cd가 0인데 결과가 비었다면 거의 조건 문제입니다. ① INQR_STRT_DT가 휴장일이거나 ② CCLD_DVSN이 01(체결)인데 아직 체결이 없거나 ③ EXCG_ID_DVSN_CD를 KRX로 고정했는데 주문이 다른 경로로 나갔거나 ④ tr_id가 기간과 안 맞는 경우입니다. ①은 휴장일 판별을 스케줄러에 붙이면 애초에 안 부르게 됩니다.

주문 직후에 바로 조회하면 나오나요?

보통은 나오지만 0.1초 뒤에 부르는 것을 전제로 로직을 짜지는 마세요. 접수와 기록 사이에는 지연이 있을 수 있고, 그 짧은 창에 비어 있다고 해서 주문이 없는 것이 아닙니다. "조회 결과가 없으면 재주문" 같은 분기는 중복 주문의 가장 흔한 원인입니다. 최소 몇 초의 유예와 ODNO 기준 멱등 처리를 함께 두세요.

이 값들을 그대로 믿어도 되나요?

이 글의 tr_id·건수 상한·파라미터는 2026-08-15 시점에 공개된 한국투자증권 공식 예제 코드를 근거로 정리한 것입니다. 증권사 API 명세는 예고 없이 바뀌고, 앞서 본 것처럼 공식 자료 안에서도 표기가 엇갈리는 경우가 있습니다. 운영에 쓰기 전 KIS Developers 포털의 현재 명세로 반드시 대조하시기 바랍니다.