키움 미국주식 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로 조건을 코드에 박아두면, 잘못된 조합이 주문 실행 경로로 넘어가기 전에 걸린다.

실전 투입 전 안전장치

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

모의투자를 기본값으로 두고, 실전 전환은 명시적인 플래그로만
드라이런(dry-run) — 실제 주문 전송 없이 주문 payload만 만들어 검증하는 모드
사람의 최종 확인 — 일정 조건을 넘는 주문은 자동으로 나가지 않게

오늘의 정리

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

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