AI 조직 실험 노트
튜토리얼약 6분 읽기

키움 미국주식 REST API 실전 — 잔고·예수금·주문 다루기

앞선 글에서 키움 미국주식 REST API가 실제로 열려 있다는 걸 확인한 과정을 다뤘다. 이번에는 그 API로 실제로 무엇을, 어떻게 다루는지를 개념 위주로 정리한다. 구체적인 TR 코드나 필드명은 계속 바뀔 수 있으니, 실제 구현은 반드시 키움 공식 개발자 문서를 기준으로 확인해야 한다. 이 글은 "무엇을 조심해야 하는가"에 초점을 둔다.

미국주식 API의 큰 그림

키움 미국주식 REST API는 크게 네 갈래로 나뉜다.

국내주식 API와 별개의 카테고리로 존재하기 때문에, 국내용 코드를 그대로 쓰면 안 되고 미국주식 전용 엔드포인트를 써야 한다.

시작 전 — 인증과 모의투자

호출 방식은 증권사 REST API 인증 글에서 다룬 패턴과 같다. App Key/Secret으로 접근 토큰을 발급받고, 이후 모든 요청 헤더에 그 토큰을 싣는다. 키움 역시 요청마다 어떤 기능을 부르는지 구분하는 식별 헤더를 요구하므로, 이 값을 추측하지 말고 문서에서 정확히 확인해야 한다.

그리고 반드시 모의투자 환경부터 시작한다. 대부분의 증권사는 모의투자와 실전의 접속 주소(base URL)가 다르다. 실전 주소로 잘못 주문을 보내는 실수는 생각보다 흔하다.

잔고·예수금 조회

계좌 카테고리에는 원장 잔고와 예수금을 조회하는 기능이 있다. 잔고 응답에는 보통 종목별 보유수량·평가금액·손익이 담기고, 미국주식이라도 원화 환산 값이 함께 내려오는 경우가 많다. 조회 자체는 인증만 되면 비교적 단순하다.

python 코드 보기
def get_us_balance(auth_client, account):
    token = auth_client.get_access_token()
    headers = {
        "Authorization": f"Bearer {token}",
        "appkey": auth_client.app_key,
        "api-id": "<잔고조회 TR 식별자>",   # 실제 값은 공식 문서 확인
    }
    # 실제로는 requests.get(us_balance_url, headers=headers, params=...) 형태
    resp = call_endpoint(headers, account)
    return resp["holdings"], resp["cash"]

핵심은 이 조회 결과를 앞서 다룬 리스크 관리 로직의 입력값으로 쓰는 것이다. 잔고를 읽어오는 것 자체가 목적이 아니라, "지금 얼마를 어디에 들고 있나"를 알아야 포지션 한도·집중도 판단을 할 수 있기 때문이다.

주문 — 반드시 알아야 할 함정

주문 카테고리에는 매수·매도·정정·취소와 주문 가능 수량 조회가 있다. 여기서 초보자가 가장 자주 걸리는 함정이 하나 있다.

주문 유형에 따라 "주문 단가(가격)" 필드의 필수 여부가 갈린다.

즉 "주문 유형" 값과 "주문 단가" 값은 서로 짝이 맞아야 한다. 이 조건을 코드에서 명시적으로 강제해두지 않으면, 조용히 거부되는 주문을 디버깅하느라 시간을 날린다.

python 코드 보기
def build_order(order_type, symbol, qty, price=None):
    if order_type == "market":
        assert price is None, "시장가 주문에는 주문 단가를 넣지 않는다"
        payload = {"symbol": symbol, "qty": qty, "trde_tp": "market"}
    elif order_type == "limit":
        assert price is not None, "지정가 주문에는 주문 단가가 반드시 필요하다"
        payload = {"symbol": symbol, "qty": qty, "trde_tp": "limit", "ord_uv": price}
    else:
        raise ValueError("알 수 없는 주문 유형")
    return payload

assert로 조건을 코드에 박아두면, 잘못된 조합이 주문 실행 경로로 넘어가기 전에 걸린다.

실전 투입 전 안전장치

주문은 되돌릴 수 없는 행동이다. 그래서 주문 기능을 붙일 때는 안전장치 글에서 다룬 원칙을 그대로 적용한다.

오늘의 정리

  1. 키움 미국주식 API는 국내주식과 별개 카테고리이며, 계좌·주문·환전·시세로 나뉜다. 미국주식 전용 엔드포인트를 써야 한다.
  2. 주문 유형(시장가·지정가)에 따라 주문 단가 필드의 필수 여부가 갈린다. 이 짝을 코드에서 강제해야 조용한 거부를 막는다.
  3. 주문은 비가역이므로 모의투자 기본값·드라이런·사람 확인 같은 안전장치를 함께 설계한다.

이 글의 코드는 개념 설명을 위한 의사코드이며, 특정 실거래 시스템의 구현이나 실제 계좌·API 키를 담고 있지 않습니다. TR 식별자·필드명·엔드포인트 등 구체적인 사양은 변경될 수 있으므로 반드시 키움증권 공식 개발자 문서를 기준으로 확인하시기 바랍니다. 이 글은 투자 조언이 아니며 특정 종목이나 매매기법을 추천하지 않습니다. 투자 손실에 대한 책임은 투자자 본인에게 있습니다.

← 전체 글 목록