KIS 신용잔고 API — 융자·대주·대차 구분 3가지

1. 융자 · 대주 · 대차 — 뭐가 다른가

한국투자증권 KIS API의 국내주식 시세분석 그룹에는 빚과 대여에 관한 데이터가 세 종류 들어 있습니다. 이름이 비슷해서 하나로 뭉뚱그려 쓰기 쉬운데, 주체도 방향도 다릅니다.

실무에서 제일 흔한 사고가 융자와 대주를 더해 "신용잔고"라고 부르는 것입니다. 하나는 매수 포지션이고 하나는 매도 포지션이라 방향이 반대입니다. 수급 데이터를 봇에 넣을 때의 일반 원칙은 KIS API 외국인·기관 순매수 — 당일치는 장 끝나야 나온다에 정리해 두었는데, 신용 데이터는 거기에 "둘을 섞지 말 것"이 하나 더 붙습니다.

2. 종목 하나의 흐름 — 일별추이 API

종목 하나의 시계열은 국내주식 신용잔고 일별추이로 받습니다. 공식 파이썬 래퍼의 함수명은 daily_credit_balance이고, 필수 인자가 네 개입니다.

fid_cond_mrkt_div_code (str): [필수] 시장 분류 코드   (ex. J: 주식)
fid_cond_scr_div_code  (str): [필수] 화면 분류 코드   (ex. 20476)
fid_input_iscd         (str): [필수] 종목코드         (ex. 005930)
fid_input_date_1       (str): [필수] 결제일자         (ex. 20240313)

df = daily_credit_balance("J", "20476", "005930", "20240313")

이 API는 HTS(eFriend Plus)의 [0476] 국내주식 신용잔고 일별추이 화면을 그대로 옮긴 것이라, 막히면 HTS 화면을 띄워 놓고 대조하는 게 가장 빠릅니다. fid_cond_scr_div_code의 20476도 그 화면 번호에서 왔습니다.

3. 응답 필드는 8쌍 대칭이다

응답을 처음 열면 필드가 많아 보이지만 구조는 단순합니다. 융자(whol_loan_)와 대주(whol_stln_)가 같은 이름 규칙으로 8개씩 대칭을 이룹니다.

여기에 주가 쪽 필드(stck_prpr 현재가, stck_oprc·stck_hgpr·stck_lwpr, acml_vol 누적 거래량, prdy_vrss·prdy_ctrt 전일 대비)가 붙어 가격과 잔고를 따로 조인하지 않아도 됩니다. 일봉을 별도로 받아 붙이는 수고가 줄어드는 셈인데, 가격 시계열 자체가 필요하면 KIS 일봉 API FHKST03010100이 정석입니다.

파싱 코드는 접두사만 바꿔 한 번에 정리하는 편이 안전합니다.

import pandas as pd

FIELDS = ["new_stcn", "rdmp_stcn", "rmnd_stcn",
          "new_amt",  "rdmp_amt",  "rmnd_amt",
          "rmnd_rate", "gvrt"]

def split_loan_stln(df: pd.DataFrame) -> pd.DataFrame:
    """융자(loan)와 대주(stln)를 한 번에 뜯어 접두사를 떼어 낸다."""
    out = df[["deal_date", "stlm_date", "stck_prpr", "acml_vol"]].copy()
    for side in ("loan", "stln"):
        for f in FIELDS:
            src = f"whol_{side}_{f}"
            if src in df.columns:
                out[f"{side}_{f}"] = pd.to_numeric(df[src], errors="coerce")
    # 절대 합치지 않는다 — 융자는 매수 포지션, 대주는 매도 포지션이다
    return out

4. 시장 전체 상위 — 정렬 코드에 두 축이 섞였다

종목을 고르는 쪽은 국내주식 신용잔고 상위(credit_balance)입니다. [국내주식-109]로 분류돼 있고, 파라미터가 다섯 개입니다.

fid_cond_scr_div_code (str): Unique key(11701)
fid_input_iscd        (str): 0000:전체, 0001:거래소, 1001:코스닥, 2001:코스피200
fid_option            (str): 2~999
fid_cond_mrkt_div_code(str): 시장구분코드 (주식 J)
fid_rank_sort_cls_code(str): 정렬 기준

df1, df2 = credit_balance('11701', '0000', '2', 'J', '0')

fid_option의 2~999는 얼핏 정체불명인데, 응답을 보면 바로 풀립니다. nday_vrss_loan_rmnd_inrt(N일 대비 융자 잔고 증가율)와 nday_vrss_stln_rmnd_inrt(N일 대비 대주 잔고 증가율)의 N이 이 값입니다. 즉 "며칠 전과 비교할 것인가"를 호출자가 정합니다. 3·4번(증가/감소 상위) 정렬을 쓸 때는 이 값이 결과를 완전히 바꿉니다.

응답이 df1·df2 두 개로 돌아오는 것도 기억해 두십시오. output1은 기준 일자(stnd_date1·stnd_date2)와 업종 구분 같은 헤더성 정보이고, 종목 목록은 output2에 있습니다. 순위 API를 여러 개 다룬다면 거래량 순위 API 종목 스캐너의 구조를 같이 보시면 빠릅니다.

5. 대차거래는 아예 다른 TR

종목별 일별 대차거래추이(daily_loan_trans)는 앞의 둘과 파라미터 이름부터 다릅니다. fid_ 접두사를 쓰지 않습니다.

mrkt_div_cls_code (str): [필수] 조회구분 (1:코스피, 2:코스닥, 3:종목)
mksc_shrn_iscd    (str): [필수] 종목코드
start_date        (str): 시작일자
end_date          (str): 종료일자
cts               (str): 이전조회KEY

df = daily_loan_trans(mrkt_div_cls_code="1", mksc_shrn_iscd="005930")

• 한 번에 100건입니다(일별추이의 30건과 다릅니다). 다음 페이지는 cts 또는 날짜 이동으로 받습니다.
• 시장 전체 집계도 됩니다 — mrkt_div_cls_code에 1/2를 넣으면 코스피·코스닥 단위 추이가 나옵니다.
• 필드가 짧습니다 — new_stcn(당일 증가, 체결), rdmp_stcn(당일 감소, 상환), rmnd_stcn(당일 잔고 주수), rmnd_amt(잔고 금액), prdy_rmnd_vrss(대차거래 증감).

대차 잔고를 공매도 잔고와 같은 것으로 읽지 마십시오. 빌린 주식을 전부 파는 것은 아닙니다. 실제 공매도 체결량은 국내주식 공매도 일별추이가 ssts_cntg_qty·ssts_vol_rlim로 따로 줍니다. 같은 축을 키움 쪽에서 보는 방법은 키움 REST API 공매도 추이 ka10014에 있습니다.

6. 봇에 넣을 때 — 필터는 신호가 아니다

실제로 쓰는 방식은 대부분 유니버스 필터입니다. 매수 후보를 뽑은 뒤, 융자 잔고 비율이 과하게 높은 종목을 후보에서 제외하는 식이죠.

MAX_LOAN_RATE = 5.0   # 예시 값일 뿐, 근거 있는 임계값이 아니다

def drop_high_margin(codes: list[str]) -> list[str]:
    keep = []
    for code in codes:
        df = daily_credit_balance("J", "20476", code, settle_date)  # 결제일자
        if df.empty:
            continue                      # 데이터가 없으면 거르지 말고 로그를 남긴다
        rate = float(df.iloc[0]["whol_loan_rmnd_rate"])
        if rate < MAX_LOAN_RATE:
            keep.append(code)
    return keep

7. 자주 묻는 질문

KIS API로 종목별 신용잔고를 받으려면 어떤 API를 쓰나요?

국내주식 신용잔고 일별추이를 씁니다. 공식 래퍼 함수명은 daily_credit_balance, 필수 인자는 fid_cond_mrkt_div_code(J), fid_cond_scr_div_code(20476), fid_input_iscd(종목코드), fid_input_date_1(기준 일자) 네 개입니다. 한 번에 최대 30건이 오고, 더 과거를 보려면 fid_input_date_1을 바꿔 이어서 조회합니다.

신용잔고 조회의 기준 날짜는 거래일인가요 결제일인가요?

명세는 fid_input_date_1을 결제일자로 적고 있고, 응답에도 deal_date(매매 일자)와 stlm_date(결제 일자)가 따로 들어 있습니다. 국내 주식 결제는 통상 거래일 기준 이틀 뒤이므로 거래일을 그대로 넣으면 구간이 어긋날 수 있습니다. 적용 전에 최근 며칠을 호출해 두 필드를 대조하십시오.

융자 잔고와 대주 잔고는 무엇이 다른가요?

융자는 돈을 빌려 산 것, 대주는 주식을 빌려 판 것입니다. 응답 필드가 whol_loan_과 whol_stln_ 접두사로 대칭이며 각각 8개씩 들어 있습니다. 접두사 하나만 다르기 때문에 파싱에서 가장 헷갈리는 지점이고, 상환 수량은 매도상환수량 + 현금상환수량의 합계라는 점도 명세에 명시돼 있습니다.

신용잔고 상위 종목을 뽑을 때 정렬 코드는 어떻게 넣나요?

fid_rank_sort_cls_code 하나에 두 축이 들어 있습니다. 융자는 0 잔고비율 · 1 잔고수량 · 2 잔고금액 · 3 비율 증가 · 4 비율 감소이고, 대주는 5부터 9까지 같은 순서로 이어집니다. fid_option에는 2~999를 넣으며, 이 값이 응답의 nday_vrss_loan_rmnd_inrt·nday_vrss_stln_rmnd_inrt에서 말하는 N입니다.

신용잔고가 높은 종목을 봇 유니버스에서 빼면 더 안전한가요?

그렇게 단정할 수 없습니다. 신용잔고 수준으로 주가 방향이나 반대매매 발생을 예측할 수 없고, 어떤 임계값도 손실을 막아 주지 않습니다. 이 필터는 예측이 아니라 운영상의 선택이며, 필터를 걸수록 표본이 줄어 통계적 신뢰도가 낮아지는 비용이 같이 발생합니다.

마무리 — 이름이 비슷할 뿐 다른 데이터다

정리하면 세 문장입니다. 융자와 대주는 한 응답에 접두사로 나뉘어 오고 절대 더하면 안 됩니다. 일별추이의 기준일은 결제일자이고 한 번에 30건입니다. 대차는 별개 TR이고 페이지 크기도 100건으로 다릅니다. 나머지는 이 세 가지를 코드에 상수로 박아 두면 따라옵니다.

파라미터·필드·건수 제한은 바뀔 수 있으므로 KIS Developers 포털의 현재 문서가 기준입니다. KIS 키 발급부터 처음 시작한다면 KIS API 발급 30분, 증권사 선택 단계라면 증권사 API 비교 — 키움·KIS·LS·대신부터 보시는 편이 빠릅니다.

알고랩(퀀트웍스)은 자동매매 프로그램을 맞춤 제작하는 도구 제공 사업자이며, 투자자문업·투자일임업을 영위하지 않습니다. 이 글은 공개된 API 명세를 기술적으로 설명한 것으로 특정 종목·전략의 매매를 권유하지 않으며, 본문의 임계값은 코드 예시용 자리표시자입니다. 신용·대차 데이터로 주가 방향이나 반대매매 발생을 예측할 수 없습니다. 파라미터·건수 제한·정책은 변경될 수 있으므로 KIS Developers 포털의 현재 문서를 확인하십시오.