KIS API 매도가능수량조회 TTTC8408R — 보유 100주인데 70주만 팔리는 이유

이 글은 KIS API 잔고조회 — 50건에서 잘리는 연속조회 해결의 매도 수량 편입니다. 잔고조회 글이 "보유 종목 목록을 끝까지 받는 법"이었다면, 여기서는 그중 한 종목을 지금 몇 주 팔 수 있나 한 가지만 다룹니다. 근거는 한국투자증권 공식 GitHub 저장소 koreainvestment/open-trading-api의 examples_llm/domestic_stock/inquire_psbl_sell와 legacy/README.md의 API 제공 목록입니다.

1. TTTC8408R 스펙 — 입력 3개

연속조회 키(CTX_AREA_FK100 같은 것)가 없습니다. 종목 하나를 넣고 한 행을 받는 API라서 잔고조회처럼 50건 페이지 처리를 신경 쓸 필요가 없습니다. 계좌번호 두 필드를 나누는 법은 CANO·ACNT_PRDT_CD 정리에 있습니다.

import os, requests

BASE = "https://openapi.koreainvestment.com:9443"   # 실전 도메인
H = {
    "content-type": "application/json; charset=utf-8",
    "authorization": f"Bearer {access_token}",
    "appkey": os.environ["KIS_APPKEY"],
    "appsecret": os.environ["KIS_APPSECRET"],
    "tr_id": "TTTC8408R",
    "custtype": "P",
}

def sellable_qty(pdno: str) -> int:
    r = requests.get(BASE + "/uapi/domestic-stock/v1/trading/inquire-psbl-sell",
                     headers=H, timeout=10,
                     params={"CANO": CANO, "ACNT_PRDT_CD": "01", "PDNO": pdno}).json()
    if r["rt_cd"] != "0":
        raise RuntimeError(f'{r["msg_cd"]} {r["msg1"]}')
    out = r["output"]
    out = out[0] if isinstance(out, list) else out   # 공식 예제도 dict/list 둘 다 처리
    return int(out["ord_psbl_qty"])

access_token 발급과 만료 처리는 KIS 접근토큰 만료·재발급을 보십시오. rt_cd가 "0"이 아니면 msg_cd·msg1을 그대로 로그에 남기는 것이 원칙입니다(KIS API 에러코드 허브).

2. 응답 필드 12개 — 봐야 할 건 ord_psbl_qty 하나

공식 테스트 코드 chk_inquire_psbl_sell.py의 COLUMN_MAPPING 기준 응답 필드입니다.

응답은 이런 모양입니다(필드는 공식 매핑 기준, 값은 설명용 가상 값). 모든 숫자가 문자열로 오므로 int() 변환을 빼먹으면 "70" > "100" 같은 문자열 비교 버그가 납니다.

{
  "rt_cd": "0",
  "msg_cd": "...",
  "msg1": "...",
  "output": {
    "pdno": "005930",
    "buy_qty": "0",
    "sll_qty": "0",
    "cblc_qty": "100",
    "nsvg_qty": "...",
    "ord_psbl_qty": "70",
    "pchs_avg_pric": "...",
    "now_pric": "...",
    "evlu_pfls_rt": "..."
  }
}

3. 보유 100주인데 왜 70주만 팔 수 있나

가장 흔한 원인은 이미 걸어 둔 미체결 매도주문입니다. 증권사는 접수된 매도주문 수량만큼을 묶어 두므로, 잔고수량이 100주여도 30주짜리 지정가 매도가 걸려 있으면 새로 낼 수 있는 건 70주입니다. 봇이 hldg_qty(또는 cblc_qty)로 "전량 매도"를 내면 이 30주가 겹쳐 주문이 거부됩니다.

그 밖에도 권리 발생 등으로 매도가 막히는 경우가 있습니다. 공식 저장소의 예약주문 설명문은 거부 사유로 "매도가능수량 부족"을 따로 적고 있고, 해외 예약주문 설명에는 "주권변경 등 권리발생으로 인한 주문불가사유"도 나옵니다. 어떤 경우든 봇이 할 일은 같습니다 — 팔기 직전에 ord_psbl_qty를 다시 읽는다.

전량 청산이 목적이라면 순서는 미체결 조회 → 정정취소 TTTC0013U로 취소 → 매도가능수량 재조회 → 매도입니다. 정정취소의 원주문번호·가능수량 처리는 KIS API 정정·취소에 있습니다.

4. 모의투자에서는 — TTTC8434R로 대체

공식 저장소 legacy/README.md와 legacy/postman/README.md의 제공 목록에서 매도가능수량조회는 실전투자만 ⭕이고 모의투자 칸이 비어 있습니다. Postman 샘플도 실전용 J_매도가능수량조회만 있습니다. 반면 주식잔고조회는 모의투자 ⭕이고, 그 응답 output1에 같은 이름의 ord_psbl_qty(주문가능수량)가 들어 있습니다.

def sellable_qty_any(pdno: str, env: str) -> int:
    if env == "real":
        return sellable_qty(pdno)                  # TTTC8408R — 종목 1개, 1회 호출
    # 모의: 잔고조회(VTTC8434R) 전체를 받아 해당 종목 행만 찾는다
    for row in inquire_balance_all(env="demo"):     # 연속조회까지 끝낸 output1 목록
        if row["pdno"] == pdno:
            return int(row["ord_psbl_qty"])
    return 0

모의투자로 매도 로직을 검증한 뒤 실전으로 넘어갈 때 경로가 바뀌는 지점이 여기입니다. 모의에서 잘 돌던 봇이 실전 첫날 다른 API를 타게 되므로, 실전 전환 체크리스트에 한 줄 넣어 두십시오(KIS 모의투자로 어디까지 검증되나). 실전에서도 TTTC8434R로 통일할 수는 있지만, 보유 종목이 많으면 잔고 전체를 페이지 단위로 받아야 하므로 종목 1개 확인에는 TTTC8408R이 호출 수가 적습니다(호출 제한은 EGW00201 초당 제한).

5. 매도 주문으로 잇기 — TTTC0011U

def sell_all(pdno: str, env: str = "real"):
    qty = sellable_qty_any(pdno, env)
    if qty <= 0:
        log.info("skip %s: 주문가능수량 0", pdno)
        return None
    return order_cash(env_dv=env, ord_dv="sell",           # 실전 TTTC0011U / 모의 VTTC0011U
                      cano=CANO, acnt_prdt_cd="01", pdno=pdno,
                      ord_dvsn="01",                        # 시장가
                      ord_qty=str(qty),                     # 문자열로 전달
                      ord_unpr="0",
                      excg_id_dvsn_cd="KRX",
                      sll_type="01")                        # 01 일반매도

공식 order_cash() 설명문 그대로 ORD_QTY·ORD_UNPR는 문자열로 넘기고, 매도 시 sll_type은 01(일반매도)·02(임의매매)·05(대차매도) 중에서 고릅니다. 현재 매도 tr_id가 구 TTTC0801U가 아니라 TTTC0011U인 이유와 EXCG_ID_DVSN_CD 필수화는 KIS 주문 tr_id 신·구 대조에 정리돼 있습니다. 매수 쪽 짝은 매수가능조회 TTTC8908R입니다.

자주 묻는 것

KIS API 매도가능수량조회 tr_id는 무엇인가요?

TTTC8408R입니다. GET /uapi/domestic-stock/v1/trading/inquire-psbl-sell에 CANO·ACNT_PRDT_CD·PDNO 세 가지를 넣어 호출하고, 응답의 ord_psbl_qty(주문가능수량)가 지금 매도할 수 있는 수량입니다.

모의투자에서 TTTC8408R을 쓸 수 있나요?

공식 저장소의 API 제공 목록에서 매도가능수량조회는 모의투자 제공 칸이 비어 있어 실전 전용입니다. 모의 계좌에서는 주식잔고조회(VTTC8434R) 응답 output1의 ord_psbl_qty를 대신 사용하십시오.

보유수량(hldg_qty)으로 매도하면 안 되나요?

미체결 매도주문이 걸려 있으면 그 수량만큼 주문가능수량이 줄어들어, 보유수량 전체로 낸 매도는 거부될 수 있습니다. 매도 수량은 항상 직전에 조회한 ord_psbl_qty로 정하십시오.

잔고조회 TTTC8434R과 매도가능수량조회 중 무엇을 써야 하나요?

둘 다 ord_psbl_qty를 줍니다. 종목 하나만 확인할 때는 TTTC8408R이 호출 한 번으로 끝나고, 모의투자이거나 전 종목을 한꺼번에 볼 때는 TTTC8434R(연속조회 포함)을 씁니다.