키움 증거금율 API kt00011 — 증거금율이 3개로 온다

키움 주문가능금액 — kt00001 vs kt00010에서 답하지 못하고 남겨 둔 질문이 하나 있었습니다. "증거금율을 API로 알 수 있나요?" 그 두 TR은 증거금율 20%면 얼마, 40%면 얼마 하는 구간별 금액은 주는데, 이 종목이 몇 %짜리인지는 알려 주지 않습니다. 그래서 그 글의 코드는 율을 모르면 가장 보수적인 100% 기준으로 떨어지게 짜여 있었습니다.

빈칸을 채우는 것이 kt00011입니다. 이 글은 그 한 가지만 다룹니다. 기준은 키움증권 공식 저장소의 단일 명세 파일 kiwoom/_data/kiwoom_api_spec.json 원문(request.body·response.body 전수)입니다.

1. kt00011 호출 — 파라미터가 두 개뿐이다

요청 바디는 두 개입니다. 이웃 TR과 비교하면 차이가 바로 보입니다.

import requests

def margin_rate(base_url, token, stk_cd, price=None):
    """kt00011 증거금율별주문가능수량조회요청"""
    body = {"stk_cd": stk_cd}
    if price is not None:
        body["uv"] = str(int(price))        # 선택 — 수량이 필요할 때만
    res = requests.post(
        f"{base_url}/api/dostk/acnt",
        headers={
            "Content-Type": "application/json;charset=UTF-8",
            "authorization": f"Bearer {token}",
            "api-id": "kt00011",            # ← 키움은 tr_id 가 아니라 api-id 헤더
        },
        json=body, timeout=5,
    )
    res.raise_for_status()
    return res.json()

2. 함정 ① 증거금율이 3개로 온다

응답 response.body 36개 항목 중 맨 앞 세 줄이 이 TR의 존재 이유입니다.

3. 함정 ② 율에 % 기호가 붙어 있다

공식 명세는 이 세 필드의 description을 "%가 포함된 백분율 값"이라고 적어 두었습니다. 즉 "40"이 아니라 "40%" 형태로 옵니다.

>>> float(resp["aplc_rt"])
ValueError: could not convert string to float: '40%'

그런데 같은 응답 안의 금액·수량 필드는 형식이 또 다릅니다. profa_40ord_alowq 같은 항목의 설명은 "단위: 1주, 좌측 0-padding 처리된 부호 포함 12자리 숫자"입니다. 한 응답 안에 두 가지 문자열 규격이 섞여 있다는 뜻이라, 파서를 필드 종류별로 갈라야 합니다.

def pct(v: str) -> float:
    """'40%' → 40.0 · 빈 값 → 0.0"""
    return float((v or "0").replace("%", "").strip() or 0)

def won(v: str) -> int:
    """'000000012345' → 12345 · 부호 포함 · lstrip('0') 쓰지 말 것"""
    return int((v or "0").strip() or 0)     # '0000' 을 lstrip 하면 '' 가 되어 깨진다

rate = pct(resp["aplc_rt"])                 # 적용증거금율
cash = won(resp["ord_alowa"])               # 주문가능현금
debt = won(resp["uncla"])                   # 미수금 — 0 이 아니면 이미 사고다

4. 함정 ③ kt00012는 칸 수가 다르다

신용으로 사는 봇이라면 kt00012(신용보증금율별주문가능수량)를 같이 씁니다. 요청 바디가 stk_cd·uv로 똑같이 생겨서 함수를 복사하고 싶어지는데, 응답이 다릅니다.

# TR 마다 구간과 접두어가 다르다 — 상수를 공유하지 말 것
TIERS = {
    "kt00011": (("profa_", (20, 30, 40, 50, 60, 100)), ("min_ord_alow_amt", "min_ord_alowq")),
    "kt00012": (("assr_",  (30, 40, 50, 60)),          ("min_amt",          "min_qty")),
}

def orderable_by_tier(api_id: str, resp: dict) -> dict[int, int]:
    (prefix, tiers), _ = TIERS[api_id]
    out = {}
    for r in tiers:
        key = f"{prefix}{r}ord_alowq"       # profa_40ord_alowq / assr_40ord_alowq
        if key in resp:
            out[r] = won(resp[key])
    return out

5. kt00013 증거금세부내역 — 요청 바디가 없다

종목이 아니라 계좌 전체의 증거금 구성을 볼 때 씁니다. kt00013은 명세상 request.body가 비어 있습니다 — 종목코드를 넣지 않습니다. 응답은 50개 항목이고, 봇이 실제로 보게 되는 것은 대개 이쪽입니다.

• ch_profa(현금증거금) · repl_profa(대용증거금) — 증거금이 현금과 대용으로 갈린다
• use_pos_ch_fin(사용가능현금최종) · use_pos_repl_fin(사용가능대용최종) — 제한을 반영한 최종값
• tdy_reu_alowa_fin·pred_reu_alowa_fin — 금일·전일 재사용 가능 금액
• d2vexct_entr(D2가정산예수금) · d2ch_ord_alow_amt(D2현금주문가능금액)
• uncla(미수금) — 0이 아니면 이미 사고가 난 상태

6. 실전 코드 — 안전 수량 결정기

규칙은 둘입니다. "율을 못 읽으면 가장 보수적인 칸을 쓴다", "API가 준 수량을 그대로 주문하지 않는다".

def safe_buy_qty(base_url, token, stk_cd, price, safety=0.95) -> int:
    resp = margin_rate(base_url, token, stk_cd, price)

    if won(resp.get("uncla")) > 0:          # 미수금이 있으면 신규 매수를 막는다
        return 0

    rate = pct(resp.get("aplc_rt"))         # 종목이 아니라 '적용' 율
    tiers = orderable_by_tier("kt00011", resp)

    # 적용율 이상인 칸 중 가장 낮은 칸 = 그 종목에 해당하는 한도
    candidates = [r for r in sorted(tiers) if r >= rate]
    tier = candidates[0] if candidates else 100      # 못 읽으면 100% 칸
    qty = tiers.get(tier, 0)

    # 미수를 절대 내지 않으려면 이쪽이 정답
    no_debt = won(resp.get("min_ord_alowq"))
    if no_debt:
        qty = min(qty, no_debt)

    return int(qty * safety)

7. 자주 묻는 질문

키움 REST API로 종목의 증거금율을 알 수 있나요?

kt00011이 답합니다. POST /api/dostk/acnt + api-id: kt00011 + stk_cd. 응답 맨 앞에 stk_profa_rt·profa_rt·aplc_rt가 오고 실제 적용값은 aplc_rt입니다.

증거금율을 float()로 바꾸면 왜 에러가 나나요?

명세가 세 율 필드를 "%가 포함된 백분율 값"이라고 적어 뒀기 때문입니다. "40%"가 그대로 옵니다. 금액·수량은 반대로 0-padding 12자리 문자열이라 int()로 처리하고 lstrip("0")은 쓰지 마십시오.

kt00011과 kt00012는 뭐가 다른가요?

구간이 6칸 대 4칸이고 접두어가 profa_ 대 assr_입니다. kt00012에는 20%·100% 칸이 없고 미수불가 필드 이름도 min_amt·min_qty로 다릅니다. 같은 파서를 쓰면 깨집니다.

kt00013 증거금세부내역은 언제 쓰나요?

계좌 단위 구성을 볼 때입니다. 요청 바디가 없고 응답이 50개 필드이며 금액이 15자리라 kt00011의 12자리와 다릅니다.

모의투자에서도 되나요?

공식 명세는 세 TR 모두에 운영 api.kiwoom.com과 모의 mockapi.kiwoom.com을 함께 적어 두고 있습니다. 도메인과 접근토큰이 다르므로 운영 토큰으로 모의 도메인을 부르면 인증에서 막힙니다 (토큰 유효기간과 폐기).