키움 REST API 주식 주문 — kt10000과 trde_tp

키움 REST API 자동매매 완전 가이드에서 OpenAPI+를 벗어나 토큰을 받고 시세까지 붙였다면, 남은 건 하나입니다. 주문을 실제로 내보내는 것.

그런데 여기서 많이 헤맵니다. KIS처럼 기능마다 URL이 다를 거라고 예상하고 문서를 뒤지기 때문입니다. 키움 REST는 구조가 다릅니다. 주문은 경로 하나로 끝나고, 무엇을 하는지는 헤더가 정합니다. 이 글은 주문 한 건을 내보내는 것만 다룹니다.

1. 구조 — 경로 하나 + api-id 헤더

키움 REST API의 주식 주문은 POST /api/dostk/ordr 하나입니다. 매수인지 매도인지, 현금인지 신용인지는 api-id 요청 헤더로 지정합니다.

이 구조는 조회 API도 동일합니다. 그래서 키움 REST 클라이언트를 만들 때는 "경로별 함수"가 아니라 "api-id를 인자로 받는 공통 호출 함수" 하나를 두고 그 위에 얇은 래퍼를 얹는 편이 훨씬 짧아집니다. 연속조회의 cont-yn·next-key도 같은 헤더 계층에서 처리되기 때문입니다.

2. api-id 목록 (현금·신용)

자동매매 봇이 신용을 쓰는 것은 권하지 않습니다. 반대매매·이자·증거금 조건이 얽히면 봇이 판단해야 할 상태의 가짓수가 급격히 늘어나기 때문입니다. 현금 주문 kt10000·kt10001만으로 시작하는 편이 안전합니다.

3. 요청 바디 5개 필드

KIS와 비교하면 감이 옵니다. KIS 국내 현금주문은 CANO·ACNT_PRDT_CD로 계좌를 바디에 직접 실어 보내지만, 키움 REST 주문 바디에는 계좌 필드가 보이지 않습니다. 두 증권사의 차이는 키움과 KIS API 비교에서 더 다룹니다.

4. trde_tp — 지정가·시장가·IOC·FOK

trde_tp는 어떤 방식으로 체결시킬지를 정하는 값입니다. 실무에서 실제로 쓰는 것들만 추리면 다음과 같습니다.

IOC·FOK는 부분체결을 허용할 것인가의 문제입니다. IOC는 즉시 체결되는 수량만 체결하고 나머지를 자동 취소하고, FOK는 전량 체결이 안 되면 전부 취소합니다. 분할매수 로직을 짤 때 미체결 잔량을 봇이 직접 관리할지, 거래소에 맡길지를 여기서 결정하게 됩니다.

5. dmst_stex_tp — KRX·NXT·SOR

OpenAPI+ 시절 코드를 옮겨 오면 이 필드가 없어서 가장 자주 빠뜨립니다. 국내 시장이 한국거래소(KRX)와 넥스트레이드(NXT)로 나뉘면서 주문마다 어디로 보낼지를 명시하게 됐기 때문입니다. SOR은 둘 중 유리한 쪽으로 자동 라우팅하는 방식입니다.

어느 값이 유리한지는 종목·시간대·호가 상황에 따라 달라지므로 코드에 상수로 박지 말고 설정 파일로 빼 두는 것을 권합니다. 시장별 차이와 판단 기준은 NXT·KRX 주문 라우팅에서 따로 다뤘습니다.

6. 실제 요청과 응답

삼성전자를 지정가 1주 매수하는 최소 형태입니다. token은 접속 토큰이고, api-id만 바꾸면 매도·정정·취소가 됩니다.

import requests

HOST = "https://api.kiwoom.com"        # 모의: https://mockapi.kiwoom.com

def order(token, api_id, body):
    url = HOST + "/api/dostk/ordr"
    headers = {
        "Content-Type": "application/json;charset=UTF-8",
        "authorization": f"Bearer {token}",
        "api-id": api_id,              # kt10000 매수 / kt10001 매도
        "cont-yn": "N",
        "next-key": "",
    }
    r = requests.post(url, headers=headers, json=body, timeout=10)
    return r.json()

buy = {
    "dmst_stex_tp": "KRX",             # KRX / NXT / SOR
    "stk_cd": "005930",
    "ord_qty": "1",
    "ord_uv": "75000",                 # 시장가(trde_tp=3)면 비움
    "trde_tp": "0",                    # 0 보통(지정가), 3 시장가
}
res = order(TOKEN, "kt10000", buy)

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

{
  "ord_no": "0000455",
  "dmst_stex_tp": "KRX",
  "return_code": 0,
  "return_msg": "KRX 매수주문이 완료되었습니다"
}

7. 정정·취소는 ord_no가 있어야 한다

정정(kt10002)·취소(kt10003)는 원주문번호를 함께 보냅니다. 즉 ord_no를 저장하지 않으면 그 주문은 API로 손댈 수 없습니다.

봇을 만들 때 실수가 나오는 지점은 재시작입니다. 주문번호를 메모리에만 들고 있으면 프로세스가 죽는 순간 미체결 주문이 고아가 됩니다. 주문번호는 발급 즉시 파일이나 DB에 남기는 편이 안전합니다. 같은 문제를 KIS 쪽에서 다룬 글은 KIS 주문 취소·정정과 원주문번호입니다.

8. 자주 막히는 자리 4곳

1. 토큰 만료 — 401 계열이 뜨면 대개 접속 토큰 문제입니다. 만료 시각을 보고 미리 갱신하는 규칙은 키움 REST 토큰 유효기간과 폐기에 정리해 뒀습니다.
2. 유량 초과 — 주문 루프를 간격 없이 돌리면 허용된 요청 개수를 넘겨 거부됩니다. 대응은 429 허용 요청 개수 초과 글과 같습니다.
3. 모의 도메인 혼동 — 모의투자는 mockapi.kiwoom.com입니다. 도메인만 바꾸고 토큰은 실전 것을 그대로 쓰면 인증에서 막힙니다.
4. 종목코드 형식 — stk_cd는 6자리 문자열입니다. 숫자로 처리하면 005930의 앞 0이 사라져 존재하지 않는 종목이 됩니다.

조건검색식으로 종목을 고른 뒤 그 결과를 바로 주문으로 넘기는 구성이라면 조건검색 실시간 편입과 이 글을 이어 붙이면 됩니다. "편입 신호 → 주문 → 주문번호 저장 → 체결 확인"이 한 사이클입니다.

자주 묻는 질문

Q. OpenAPI+의 SendOrder를 그대로 옮기면 되나요?

개념은 비슷하지만 필드 이름과 거래소 구분이 다릅니다. 특히 dmst_stex_tp는 OpenAPI+ 시절에 없던 값이라 그대로 옮기면 빠집니다. 윈도우·ActiveX 의존에서 벗어나는 전체 그림은 허브 글을 참고하십시오.

Q. 시장가 주문에 ord_uv를 0으로 넣어도 되나요?

비우는 것이 원칙입니다. 값이 남아 있으면 거부되거나 의도와 다르게 접수될 수 있으므로, trde_tp에 따라 바디를 분기해서 만드는 편이 안전합니다.

Q. 하나의 계정으로 전략을 여러 개 돌려도 되나요?

가능하지만 유량은 계정 단위로 합산됩니다. 전략별로는 여유가 있어도 합쳐서 한도를 넘기면 전부 거부되므로, 주문 호출을 하나의 큐로 모으는 구조를 권합니다.

Q. 체결 확인은 어떻게 하나요?

접수 응답으로는 알 수 없습니다. 미체결·체결 조회를 주기적으로 부르거나 실시간 체결통보를 구독해야 합니다. 봇의 포지션 상태는 접수가 아니라 체결로만 바꿔야 합니다.

마무리

한 줄로 줄이면 이렇습니다. 키움 REST 주문은 /api/dostk/ordr 하나에 api-id로 기능을 지정하고, trde_tp와 ord_uv의 짝만 틀리지 않으면 나간다.

그리고 진짜 일은 그다음입니다. ord_no를 어디에 저장할 것인가 — 이걸 정하지 않은 봇은 재시작 한 번에 미체결 주문을 놓칩니다.