통합증거금 TTTC0869R — 봇은 환전을 못 한다

1. API 목록에 환전이 없다 — 334개 전수 확인

미국주식 자동매매를 처음 붙일 때 가장 많이 나오는 요청이 “원화만 넣어 두면 봇이 알아서 환전하고 사게 해 달라” 입니다. 그런데 KIS Developers 에는 환전을 실행하는 엔드포인트가 없습니다.

한국투자증권이 GitHub 에 공개한 저장소 koreainvestment/open-trading-api 안에는 API 메타데이터 파일이 들어 있습니다. 여기 실린 항목 334개 전체를 대상으로 이름에 “환전”이 들어간 것을 찾으면 결과가 비어 있습니다.

# 공개 저장소 MCP/KIS Code Assistant MCP/data.csv 전수 검색
전체 API: 334개
api_name 에 '환전' 포함: 0개

# 반면 '환전'이라는 단어가 응답 필드로는 존재한다
overseas_stock  | 해외주식 매수가능금액조회 | echm_af_ord_psbl_amt  '환전이후주문가능금액'
overseas_stock  | 해외주식 매수가능금액조회 | echm_af_ord_psbl_qty  '환전이후주문가능수량'
overseas_futureoption | 해외선물옵션 예수금현황 | fm_echm_rqrm_amt  'FM환전요청금액'

즉 환전의 결과는 읽을 수 있지만 환전을 시킬 수는 없습니다. 이 비대칭이 해외주식 봇 설계의 출발점입니다. 선택지는 두 개뿐입니다.

2. 통합증거금이 무엇이고, 무엇이 아닌가

통합증거금은 주문 전에 거래통화로 환전하지 않고도 원화와 다른 통화의 환전가능금액·매도결제예정금액을 매수증거금으로 쓰게 해 주는 서비스입니다. 매수한 종목의 결제일에 부족한 금액만큼 기준환율로 자동 환전이 실행됩니다.

• 대상 통화 — 원화(KRW)·미국달러(USD)·홍콩달러(HKD)·위안화(CNY)·엔화(JPY)
• 주문 통화 — 매수하려는 종목이 속한 시장의 통화. 애플은 USD, 텐센트는 HKD 입니다.
• 자동환전 시점 — 결제일에 부족분만큼. 통상 결제일 오전 중 처리되지만 시스템 상황에 따라 차이가 있습니다.
• 신청제 — 기본으로 켜져 있지 않습니다. 증권사 MTS·HTS 의 해외주식 거래신청 메뉴에서 신청·해지합니다.

세부 운영 방식·수수료·대상 시장은 증권사마다 다르고 변경될 수 있으니, 반드시 해당 증권사의 통합증거금 서비스 설명서와 공식 안내로 현재 조건을 확인하십시오. 이 글은 KIS API 가 그 상태를 어떤 필드로 알려 주는지에 집중합니다.

3. TTTC0869R — 일반과 통합이 쌍으로 나온다

통합증거금 상태를 보는 API 는 주식통합증거금 현황 입니다. 국내 범주에 들어 있지만 해외 주문가능금액까지 같이 내려 주는 것이 핵심입니다.

# 공개 저장소 예제 — 주식통합증거금 현황 (tr_id: TTTC0869R)
df = intgr_margin(
        cano=trenv.my_acct,
        acnt_prdt_cd=trenv.my_prod,
        cma_evlu_amt_icld_yn="N",    # CMA평가금액 포함여부  Y | N
        wcrc_frcr_dvsn_cd="01",      # 원화외화구분  01: 외화기준, 02: 원화기준
        fwex_ctrt_frcr_dvsn_cd="01", # 선도환계약외화구분  01: 외화기준, 02: 원화기준
)
print(df)

wcrc_frcr_dvsn_cd 를 02(원화기준)으로 주면 금액이 원화로 환산돼 옵니다. 리포트를 원화로 찍을 때 유용하지만, 주문 수량 계산에는 외화기준(01)을 쓰는 편이 안전합니다 — 주문 단가가 외화이기 때문입니다.

봐야 할 필드는 통합 쪽이다

응답 컬럼이 100개를 넘습니다. 그중 해외주식 봇이 실제로 쓰는 것은 한 줌이고, 같은 통화에 대해 “일반”과 “통합”이 쌍으로 나온다는 점이 이 API 의 전부입니다.

# 주식통합증거금 현황 응답 컬럼 매핑 발췌 (공개 저장소 원문)
{
  'ovrs_stck_itgr_mgna_dvsn_name' : '해외주식통합증거금구분명',   ← 계좌 상태

  'usd_gnrl_ord_psbl_amt' : '미화일반주문가능금액',   ← 달러 예수금만
  'usd_itgr_ord_psbl_amt' : '미화통합주문가능금액',   ← 원화까지 끌어 쓴 금액
  'hkd_gnrl_ord_psbl_amt' : '홍콩달러일반주문가능금액',
  'hkd_itgr_ord_psbl_amt' : '홍콩달러통합주문가능금액',
  'jpy_gnrl_ord_psbl_amt' : '엔화일반주문가능금액',
  'jpy_itgr_ord_psbl_amt' : '엔화통합주문가능금액',
  'cny_gnrl_ord_psbl_amt' : '위안화일반주문가능금액',
  'cny_itgr_ord_psbl_amt' : '위안화통합주문가능금액',

  'usd_frst_bltn_exrt' : '미국달러최초고시환율',
  'hkd_frst_bltn_exrt' : '홍콩달러최초고시환율',
  'jpy_frst_bltn_exrt' : '일본엔화최초고시환율',
  'cny_frst_bltn_exrt' : '중국위안화최초고시환율',

  'usd_oth_mket_use_amt' : '미화타시장사용금액',   ← 다른 시장에서 이미 쓴 금액
  'stck_cash_ovrs_use_amt' : '주식현금해외사용금액'
}

4. TTTC2101R — 통화별 통합주문가능금액

공식 설명은 “해외 국가별 상세한 증거금현황을 원하면 해외증거금 통화별조회 API 를 이용하라”고 안내합니다. 이쪽이 통화별로 한 행씩 떨어져서 파싱이 훨씬 편합니다.

# 해외증거금 통화별조회 응답 컬럼 매핑 전체 (tr_id: TTTC2101R)
{
  'natn_name'              : '국가명',
  'frcr_dncl_amt1'         : '외화예수금액',
  'ustl_buy_amt'           : '미결제매수금액',
  'ustl_sll_amt'           : '미결제매도금액',
  'frcr_rcvb_amt'          : '외화미수금액',
  'frcr_mgn_amt'           : '외화증거금액',
  'frcr_gnrl_ord_psbl_amt' : '외화일반주문가능금액',   ← 일반
  'frcr_ord_psbl_amt1'     : '외화주문가능금액',
  'itgr_ord_psbl_amt'      : '통합주문가능금액',       ← 통합
  'bass_exrt'              : '기준환율'
}

필드가 열 개뿐이라 봇 입장에서는 이 API 하나로 대시보드를 만들 수 있습니다. itgr_ord_psbl_amt 와 frcr_gnrl_ord_psbl_amt 를 나란히 찍고 bass_exrt 를 같이 남기면, 나중에 “왜 이 주문이 이 수량으로 나갔나”를 사후에 재구성할 수 있습니다. 잔고 쪽 함정은 KIS API 해외주식 잔고 TTTS3012R 함정 6가지에 따로 정리했습니다.

5. TTTS3007R — echm_af_ 가 붙은 값

앞의 두 API 는 계좌 단위 금액입니다. 실제 주문 수량은 종목·단가까지 넣어야 나오고, 그 API 가 해외주식 매수가능금액조회 입니다. 실전은 TTTS3007R, 모의는 VTTS3007R 로 TR 이 갈립니다.

# 해외주식 매수가능금액조회 응답 컬럼 매핑 (tr_id: TTTS3007R / 모의 VTTS3007R)
{
  'tr_crcy_cd'            : '거래통화코드',
  'ord_psbl_frcr_amt'     : '주문가능외화금액',
  'ovrs_ord_psbl_amt'     : '해외주문가능금액',
  'max_ord_psbl_qty'      : '최대주문가능수량',
  'echm_af_ord_psbl_amt'  : '환전이후주문가능금액',   ← 통합증거금을 쓰면 여기를 본다
  'echm_af_ord_psbl_qty'  : '환전이후주문가능수량',   ← 봇이 실제로 쓸 수량
  'exrt'                  : '환율',
  'sll_ruse_psbl_amt'     : '매도재사용가능금액',
  'ord_psbl_qty'          : '주문가능수량'
}

이름이 헷갈리기 쉬운데, echm_af_ 는 “환전 이후”라는 뜻입니다. 환전이 이미 일어났다는 말이 아니라 “원화를 끌어 환전한다고 가정했을 때” 의 금액입니다. 그래서 통합증거금을 쓰는 계좌의 봇은 ord_psbl_qty 가 아니라 echm_af_ord_psbl_qty 를 써야 매수 신호를 건너뛰지 않습니다.

필수 파라미터에 ovrs_excg_cd(NASD·NYSE·AMEX·SEHK·SHAA·SZAA·TKSE·HASE·VNSE)와 ovrs_ord_unpr 가 들어가고, env_dv 로 real·demo 를 가릅니다. 거래소코드를 틀리면 금액이 0 으로 떨어지므로 심볼-거래소 매핑을 먼저 고정해 두십시오.

6. 봇이 틀리는 세 지점

① 일반 금액만 보고 매수를 건너뛴다

가장 흔합니다. 원화는 충분한데 달러 예수금이 0 이면 usd_gnrl_ord_psbl_amt·ord_psbl_qty 가 0 으로 나오고, 봇은 “매수가능금액 부족”으로 판단해 조용히 넘어갑니다. 오류가 아니라서 로그에도 이상이 안 보입니다. 통합증거금 계좌라면 통합·환전이후 필드를 봐야 합니다.

② 환율을 상수로 박는다

1350 같은 값을 코드에 박아 수량을 계산하면, 환율이 움직인 날 주문 금액이 예수금을 넘어 거부되거나 반대로 덜 삽니다. API 가 exrt·bass_exrt·usd_frst_bltn_exrt 를 내려 주므로 상수를 쓸 이유가 없습니다. 애초에 수량은 직접 계산하기보다 max_ord_psbl_qty·echm_af_ord_psbl_qty 를 쓰는 편이 어긋날 여지를 줄입니다. 위탁계좌 국내주식에서도 같은 원칙이고 그 이유는 KIS 매수가능조회 — 주문가능금액을 직접 계산하면 안 되는 이유에 있습니다.

③ 결제일 자동환전 전 잔고를 최종값으로 읽는다

통합증거금 매수 직후에는 원화가 아직 빠지지 않은 상태입니다. 이 시점의 원화 예수금을 보고 “아직 여유가 있다”고 판단해 또 매수하면, 결제일에 환전이 한꺼번에 몰립니다. ustl_buy_amt(미결제매수금액)와 frcr_rcvb_amt(외화미수금액)를 같이 봐야 합니다. 미결제 구간을 어떻게 다루는지는 KIS 주식일별주문체결조회의 판정 기준과 같은 발상입니다.

7. 최소 구현 — 주문 전에 읽을 순서

순서만 지키면 위 세 가지가 대부분 사라집니다.

# 해외주식 매수 1건 — 금액 확인 순서 (의사코드)

# 0) 봇 기동 시 딱 한 번: 계좌가 통합증거금 대상인지 남긴다
m = intgr_margin(cano, prod, "N", "01", "01")            # TTTC0869R
log.info("통합증거금 구분=%s", m["ovrs_stck_itgr_mgna_dvsn_name"])
USE_ITGR = bool(m["ovrs_stck_itgr_mgna_dvsn_name"])      # 값의 내용으로 판정

# 1) 통화 단위 여력 — 국가별 한 행
for row in foreign_margin(cano, prod):                   # TTTC2101R
    if row["natn_name"] == "미국":
        head = row["itgr_ord_psbl_amt"] if USE_ITGR else row["frcr_gnrl_ord_psbl_amt"]
        rate = row["bass_exrt"]
        pend = row["ustl_buy_amt"]                        # 미결제매수 — 이미 쓴 돈

# 2) 종목 단위 수량 — 거래소코드·단가 필요
q = inquire_psamount(cano, prod, ovrs_excg_cd="NASD",
                     item_cd="AAPL", ovrs_ord_unpr="230.00",
                     env_dv="real")                      # TTTS3007R
qty = q["echm_af_ord_psbl_qty"] if USE_ITGR else q["ord_psbl_qty"]

# 3) 내 위험한도로 다시 깎는다 — API 최대치를 그대로 쓰지 않는다
qty = min(int(qty), position_cap(head, pend, rate))
if qty <= 0:
    log.warning("주문 생략: head=%s pend=%s qty=%s", head, pend, qty)
    return

# 4) 주문 — 미국 매수와 매도는 tr_id 가 다르다
place_order(tr_id="TTTT1002U", qty=qty, unpr="230.00")   # 매수

3번이 실무에서 가장 중요합니다. echm_af_ord_psbl_qty 는 “최대 이만큼까지 가능”이지 “이만큼 사라”가 아닙니다. 통합증거금은 원화까지 끌어오기 때문에 이 최대치가 생각보다 큽니다. 한 종목에 계좌를 다 밀어 넣지 않도록 포지션 사이징·주문 수량 설계의 상한을 반드시 한 겹 더 씌우십시오.

주문 TR 자체는 매수 TTTT1002U, 매도 TTTS1002U 로 갈리고 이 구분이 초보자가 가장 먼저 막히는 지점입니다 — KIS 미국주식 주문 TTTT1002U — 매도는 TR이 다르다가 그 허브 글입니다. 정규장 밖 주간거래는 TTTS6036U·TTTS6037U 로 또 갈리는데, 그쪽은 KIS 미국주식 주간거래 API에 정리돼 있습니다. 키움증권으로 해외주식을 다룰 때의 지원 범위는 키움증권 해외·미국주식 API 지원 범위 쪽입니다.

※ 본 글의 TR·엔드포인트·필드명은 한국투자증권이 공개한 open-trading-api 저장소 원문이며 작성 시점(2026-09-26) 기준입니다. 통합증거금 서비스의 신청 방법·대상 통화·자동환전 처리 방식·수수료는 증권사별로 다르고 변경될 수 있으니 반드시 해당 증권사 공식 설명서와 안내로 현재 조건을 확인하십시오. 환율 변동에 따른 손익은 투자자에게 귀속됩니다. 본 글은 수익을 보장하거나 특정 종목을 추천하지 않습니다. 알고랩(퀀트웍스)은 투자자문업·투자일임업을 영위하지 않으며, 본 글은 도구 제작에 관한 기술 정보 제공입니다.