KIS API 미국주식 주문 — TTTT1002U와 ORD_DVSN

KIS API 발급부터 첫 주문까지를 따라 국내주식 매수가 한 번 나가고 나면 다음 질문은 대개 같습니다. "그럼 테슬라도 이 코드로 사면 되나요?"

답은 아니오입니다. 국내주식 주문 코드에서 종목코드만 TSLA로 바꾸면 경로·tr_id·필수 파라미터 세 군데에서 동시에 막힙니다. 해외주식은 같은 계좌·같은 appkey를 쓰지만 사실상 다른 API 묶음입니다. 이 글은 그중 미국주식 주문 한 건을 넣는 데 필요한 것만 다룹니다.

1. 국내주식 주문과 다른 3가지

국내주식 현금주문은 /uapi/domestic-stock/v1/trading/order-cash에 tr_id TTTC0802U(매수)를 붙여 보냅니다. 해외주식은 이 세 가지가 전부 바뀝니다.

계좌 필드인 CANO·ACNT_PRDT_CD는 국내와 동일한 규칙이라 계좌번호 8자리 + 상품코드 2자리를 그대로 씁니다. hashkey도 마찬가지로 국내주식 주문과 같은 규칙이 적용됩니다.

2. tr_id — 시장별·실전/모의별로 갈린다

한국투자증권이 공개한 오픈API 예제 코드 기준, 미국 시장의 tr_id는 다음과 같습니다.

미국 외 시장도 각각 별도의 tr_id를 씁니다. 홍콩(SEHK)·중국(SHAA·SZAA)· 일본(TKSE)·베트남(HASE·VNSE)을 함께 다룰 계획이라면 처음부터 (시장, 매수/매도, 실전/모의) → tr_id 매핑 테이블을 만들어 두는 편이 낫습니다.

3. OVRS_EXCG_CD와 PDNO(티커)

OVRS_EXCG_CD는 주문이 나갈 거래소입니다. 공개 예제에 명시된 값은 다음과 같습니다.

종목이 실제 상장된 거래소와 코드가 어긋나면 주문은 거부됩니다. "미국주식이니까 전부 NASD"로 하드코딩한 봇이 흔한데, 뉴욕에 상장된 종목을 NASD로 보내면 그 종목만 조용히 실패합니다. 종목 목록을 관리할 때 티커와 거래소코드를 한 쌍으로 저장해야 합니다.

PDNO도 국내와 다릅니다. 국내는 005930 같은 6자리 숫자지만 해외는 AAPL·TSLA 같은 티커 문자열입니다. 국내 종목코드 마스터 파일을 파싱해 만든 종목 딕셔너리를 그대로 해외에 쓰면 여기서 어긋납니다.

4. ORD_DVSN — 매수와 매도가 비대칭이다

이 글에서 가장 실무적인 부분입니다. 공개 예제에 적힌 허용값은 매수와 매도가 다릅니다.

국내주식의 시장가(ORD_DVSN 01)에 해당하는 값이 미국 매수에는 없습니다. "일단 시장가로 사고 본다"는 로직을 그대로 옮기면 주문 자체가 나가지 않습니다. 현실적인 대안은 지정가 00에 호가 대비 여유를 준 가격을 넣는 것입니다. 다만 여유를 크게 주면 그만큼 불리한 가격에 체결될 수 있으므로, 주문 유형별 성질을 이해한 상태에서 폭을 정해야 합니다.

5. 실제 요청 코드와 응답

미국 나스닥 종목을 지정가로 1주 매수하는 최소 형태입니다. 토큰 발급은 access_token 재발급 규칙과 동일합니다.

import requests

BASE = "https://openapi.koreainvestment.com:9443"   # 모의: openapivts...:29443

TR = {                       # (시장, 매수/매도, 실전/모의) → tr_id
    ("US", "BUY",  "REAL"): "TTTT1002U",
    ("US", "SELL", "REAL"): "TTTT1006U",
    ("US", "BUY",  "PAPER"): "VTTT1002U",
    ("US", "SELL", "PAPER"): "VTTT1001U",
}

def order_us(token, appkey, appsecret, cano, prdt, exchange, ticker,
             qty, price, side="BUY", env="REAL"):
    url = BASE + "/uapi/overseas-stock/v1/trading/order"
    body = {
        "CANO": cano,                    # 계좌 앞 8자리
        "ACNT_PRDT_CD": prdt,            # 상품코드 2자리
        "OVRS_EXCG_CD": exchange,        # NASD / NYSE / AMEX
        "PDNO": ticker,                  # 티커 문자열 (예: AAPL)
        "ORD_QTY": str(qty),
        "OVRS_ORD_UNPR": f"{price:.2f}", # 해외 주문단가
        "ORD_SVR_DVSN_CD": "0",
        "ORD_DVSN": "00",                # 00=지정가 (매수는 00/32/34만)
    }
    headers = {
        "content-type": "application/json; charset=utf-8",
        "authorization": f"Bearer {token}",
        "appkey": appkey,
        "appsecret": appsecret,
        "tr_id": TR[("US", side, env)],
        "custtype": "P",
    }
    return requests.post(url, headers=headers, json=body, timeout=10).json()

정상 접수되면 응답의 rt_cd가 0이고 output에 주문번호가 들어옵니다. 아래는 필드 구조를 보이기 위해 값을 임의로 채운 예시입니다.

{
  "rt_cd": "0",
  "msg_cd": "APBK0013",
  "msg1": "주문 전송 완료 되었습니다.",
  "output": {
    "KRX_FWDG_ORD_ORGNO": "01790",
    "ODNO": "0000123456",
    "ORD_TMD": "223015"
  }
}

6. 주문 뒤 확인 — 미체결·체결내역·잔고

해외주식은 조회 tr_id도 국내와 완전히 별개입니다. 공개 예제 기준으로 정리하면 다음과 같습니다.

매수가능금액이 국내와 결정적으로 다른 점은 OVRS_ORD_UNPR(주문 단가)와 ITEM_CD(종목)를 입력으로 요구한다는 것입니다. "지금 얼마까지 살 수 있나"가 종목과 가격에 따라 달라진다는 뜻이라, 국내 매수가능조회처럼 계좌 잔액만 물어보는 감각으로 부르면 값이 비어 보입니다.

잔고 조회는 CTX_AREA_FK200·CTX_AREA_NK200를 쓰는 연속조회 구조입니다. 보유 종목이 많으면 한 번에 다 오지 않으므로 국내 잔고조회 연속조회와 같은 방식으로 반복 호출해야 합니다.

7. 한국 새벽에 안 깨는 법 — 예약주문

미국 정규장은 한국 시각으로 밤·새벽입니다. 24시간 도는 서버가 없다면 해외주식 예약주문 API가 현실적인 선택입니다.

경로는 /uapi/overseas-stock/v1/trading/order-resv입니다. 다만 예약주문은 접수 시점과 실제 주문 시점 사이에 시장이 움직인다는 성질이 있어, 변동성이 큰 구간에서는 의도와 다른 가격에 걸릴 수 있습니다. 예약 가능 시간·취소 방법·시장별 제약은 공식 안내에서 반드시 확인하십시오.

8. 자주 막히는 자리 5곳

1. 모의 매도 tr_id — VTTT1001U입니다. 규칙으로 유추하지 말고 표로 관리하십시오.
2. 거래소코드 하드코딩 — 뉴욕 상장 종목을 NASD로 보내면 그 종목만 실패합니다.
3. 매수 시장가 시도 — 31·33은 매도 전용입니다. 매수는 00·32·34뿐입니다.
4. 가격 소수점 — OVRS_ORD_UNPR는 문자열입니다. 부동소수 오차가 그대로 실리지 않도록 자릿수를 고정해 보내십시오.
5. 서머타임 — 미국 개장 시각이 국내 기준으로 1시간 이동합니다. 시각을 상수로 박으면 1년에 두 번 스케줄이 어긋납니다.

환전 방식(원화 주문 가능 여부·통합증거금 적용 여부)은 계좌 설정에 따라 달라지고 정책도 바뀝니다. 이 부분은 코드가 아니라 계좌 조건의 문제이므로, 자동매매를 붙이기 전에 증권사 안내로 자기 계좌 상태를 먼저 확인하는 편이 빠릅니다. 증권사별로 해외주식을 API로 열어 주는 범위 자체가 다르다는 점도 함께 보십시오.

자주 묻는 질문

Q. 국내주식 봇 코드를 재사용할 수 있나요?

인증·토큰·hashkey·에러 처리 계층은 재사용됩니다. 그러나 주문·조회 계층은 경로와 tr_id가 전부 달라 사실상 새로 써야 합니다. 처음부터 브로커 계층을 인터페이스로 분리해 두는 편이 유지보수가 쉽습니다.

Q. 미국 매수에 시장가가 정말 없나요?

공개 예제 기준 미국 매수 ORD_DVSN은 00·32·34뿐입니다. 실무에서는 지정가에 여유 폭을 준 가격으로 대체합니다.

Q. 체결 여부를 실시간으로 받을 수 있나요?

국내주식은 웹소켓 체결통보(H0STCNI0)가 있습니다. 해외주식 실시간 지원 범위는 별도 명세를 따르므로, 우선 TTTS3018R·TTTS3035R 폴링으로 확인 로직을 만들어 두는 편이 안전합니다.

Q. 주문을 취소·정정하려면요?

해외주식에도 정정·취소 API가 따로 있으며 원주문번호(ODNO)를 반드시 보관해야 합니다. 구조는 국내 정정·취소와 같은 발상입니다 — 주문번호를 안 들고 있으면 취소할 방법이 없습니다.

마무리

한 줄로 줄이면 이렇습니다. 미국주식 주문은 국내주식 주문의 확장이 아니라 별개의 API다. tr_id는 표로 관리하고, 거래소코드는 종목과 한 쌍으로 저장하고, 매수에는 시장가가 없다는 것만 기억하면 첫 주문은 나갑니다.

나머지 난이도는 전부 "한국이 잠든 시간에 봇이 혼자 판단한다"는 데서 나옵니다. 접수와 체결을 구분하지 않는 코드가 그 시간대에 가장 비싼 실수를 합니다.