키움 REST API 자동매매 완전 가이드

"키움으로 자동매매를 하려는데, 검색하면 죄다 32bit Python에 PyQt5에 영웅문 로그인 이야기뿐이다" — 오랫동안 키움 자동매매의 표준이었던 OpenAPI+(OCX) 이야기입니다. 그런데 키움증권이 REST API + WebSocket 방식의 차세대 인터페이스를 내놓으면서, 그동안 키움을 피하게 만들던 32bit·Windows 종속·이벤트 콜백 지옥이 상당 부분 사라졌습니다.

이 글은 키움 REST API로 자동매매를 시작하려는 분을 기준으로, OpenAPI+와 무엇이 다른지부터 인증·주문·실시간·요청 제한·마이그레이션까지 순서대로 정리한 hub입니다. 자동매매 자체가 처음이라면 먼저 주식 자동매매 완전 입문 가이드를, 키움과 한투 중 무엇을 고를지 고민이라면 키움 vs KIS 비교를 함께 보세요(단, 그 글은 키움을 레거시 OpenAPI+ 기준으로 비교합니다 — 이번 글이 그 빈칸을 채웁니다).

1키움 REST API란 — 무엇이 새로워졌나

키움 REST API는 표준 HTTP 요청-응답(REST)으로 주문·조회를 하고, WebSocket으로 실시간 시세·체결을 받는 방식입니다. 핵심 변화는 OCX(COM) 의존이 사라졌다는 것입니다. 이 한 가지가 다음을 전부 바꿉니다.

• OS 독립 — Windows뿐 아니라 macOS·Linux에서 그대로 동작
• 64bit — 32bit 강제가 사라져 판다스·머신러닝 라이브러리와 충돌 없음
• 영웅문·KOA Studio 불필요 — HTS 자동 로그인 대신 토큰 인증
• 동기 요청-응답 — 이벤트 콜백/시그널 대기 구조에서 벗어남
• 서버 배포 용이 — VPS·클라우드에 그대로 올림

요약하면, "KIS API에서 좋았던 점들을 키움에서도 쓸 수 있게 된 것"에 가깝습니다.

2키움 OpenAPI+ (구) vs 키움 REST API (신)

3키움 REST API vs 한투 KIS API

그동안 "REST·OS독립·64bit·다봇 운영"은 한국투자증권 KIS API의 장점이었습니다. 키움 REST API가 나오면서 이 격차가 상당히 좁혀졌습니다. 둘 다 앱키·시크릿 → 접근토큰 방식이라 인증 흐름이 매우 비슷합니다.

인증 토큰 방식이 닮아서, KIS 토큰 발급 가이드를 이해했다면 키움 REST 토큰도 금방 적응합니다. 국내는 키움 REST, 해외는 KIS로 병행하는 구성도 합리적입니다. 증권사 전체 비교는 → 키움·KIS·LS·대신 자동매매 API 비교를 참고하세요.

4누가 REST로 가야 하나

이미 잘 도는 OpenAPI+ 봇을 굳이 갈아엎을 필요는 없습니다. 다음에 해당하면 REST의 이점이 큽니다.

• macOS·Linux에서 개발/운영하고 싶다
• 64bit 라이브러리(판다스·사이킷런 등)를 봇과 같은 환경에서 쓰고 싶다
• VPS·클라우드에 무인 배포하고 싶다
• 한 계정으로 봇을 여러 개 돌리고 싶다(토큰 기반)
• 32bit·OCX·PyQt5 이벤트 함정에 자주 막힌다
• 새 프로젝트라 처음부터 깔끔하게 시작하고 싶다

5시작 준비 — 계좌·앱키·시크릿

6인증 — 접근토큰 발급과 캐싱

키움 REST API는 앱키·시크릿으로 접근토큰을 발급받아, 이후 모든 요청 헤더에 그 토큰을 실어 보냅니다(KIS와 동일한 패턴). 토큰은 만료 시간이 있으므로 캐싱하고 만료 전에만 재발급해야 합니다. 개념 예시는 다음과 같습니다.

import os, requests

# 실전: https://api.kiwoom.com  /  모의: 별도 도메인 (공식 문서 확인)
BASE = "https://api.kiwoom.com"
APP_KEY    = os.environ["KIWOOM_APPKEY"]
APP_SECRET = os.environ["KIWOOM_SECRETKEY"]

def issue_token():
    res = requests.post(
        f"{BASE}/oauth2/token",
        headers={"Content-Type": "application/json;charset=UTF-8"},
        json={
            "grant_type": "client_credentials",
            "appkey":   APP_KEY,
            "secretkey": APP_SECRET,
        },
        timeout=10,
    )
    data = res.json()
    # 응답 필드명(token / expires_dt 등)은 공식 문서 기준 확인
    return data["token"], data.get("expires_dt")

실제 운영에서는 토큰을 파일/메모리에 캐싱하고, 만료 시각 이전에 자동 재발급하는 래퍼를 둡니다.

import time

_cache = {"token": None, "exp": 0}

def get_token():
    # 만료 60초 전이면 재발급
    if not _cache["token"] or time.time() > _cache["exp"] - 60:
        token, _ = issue_token()
        _cache["token"] = token
        _cache["exp"]   = time.time() + 23 * 3600   # 보수적으로(실제 만료는 문서 확인)
    return _cache["token"]

7주문·조회 — api-id(TR) 구조

키움 REST API는 기능(주문, 잔고조회, 시세조회 등)을 api-id(TR 코드)로 구분합니다. 같은 엔드포인트라도 헤더의 api-id 값에 따라 다른 거래(TR)가 실행되는 구조입니다(레거시의 TR명 개념이 헤더로 옮겨온 형태). 개념 예시:

def post_tr(path, api_id, body):
    res = requests.post(
        f"{BASE}{path}",
        headers={
            "authorization": f"Bearer {get_token()}",
            "api-id": api_id,                    # 정확한 코드는 공식 문서 참조
            "Content-Type": "application/json;charset=UTF-8",
        },
        json=body,
        timeout=10,
    )
    return res.json()

# 예: 국내주식 매수 주문 (경로·api-id·필드명은 공식 문서 기준 확인)
def buy(stock_code, qty, price=0):
    return post_tr(
        "/api/dostk/ordr",          # 주문 엔드포인트 (예시)
        api_id="<주문 TR api-id>",   # 예시 — 실제 코드는 문서에서
        body={
            "dmst_stex_tp": "KRX",  # 거래소 구분
            "stk_cd": stock_code,   # 종목코드 (예: 005930)
            "ord_qty": str(qty),    # 주문수량
            "ord_uv":  str(price),  # 주문단가 (시장가는 0/구분값)
            "trde_tp": "3",         # 매매구분 (지정가/시장가 등)
        },
    )

8실시간 데이터 — WebSocket

실시간 시세·체결·잔고 변동은 WebSocket으로 받습니다. 접속 후 토큰으로 로그인(인증) 메시지를 보내고, 원하는 실시간 항목(종목·타입)을 등록(구독)하면 이벤트가 푸시됩니다. 레거시의 "화면번호 + 실시간 등록" 개념이 WebSocket 구독으로 바뀐 것입니다.

import json, websocket   # websocket-client

# WebSocket 주소·로그인/등록 메시지 포맷은 공식 문서 기준 확인
WS_URL = "wss://api.kiwoom.com:10000/api/dostk/websocket"  # 예시

def on_open(ws):
    ws.send(json.dumps({"trnm": "LOGIN", "token": get_token()}))  # 인증
    # 인증 응답 후 실시간 등록 메시지 전송 (종목/타입 구독)

def on_message(ws, msg):
    data = json.loads(msg)
    # PING 수신 시 PONG 응답 (연결 유지)
    # 실시간 체결/호가 데이터 처리

ws = websocket.WebSocketApp(WS_URL, on_open=on_open, on_message=on_message)
ws.run_forever()

9TR limit(요청 제한) 다루기

"키움 rest api tr limit"은 많이 검색되는 주제입니다. REST로 바뀌어도 초당 요청 수 제한은 존재합니다. 무한정 빠르게 호출하면 차단되므로, 다음 원칙으로 설계합니다.

• 토큰 캐싱 — 토큰 발급은 가장 아껴야 할 호출. 한 번 받아 재사용.
• 요청 직렬화/큐잉 — 동시에 쏟아붓지 말고 큐에 넣어 일정 간격으로 처리.
• 레이트 리미터 — 초당 허용 횟수에 맞춘 토큰버킷/슬립 적용.
• 조회 통합 — 잔고 응답에 포함된 정보로 별도 조회를 줄임.
• 실시간은 WebSocket으로 — 시세를 폴링하지 말고 구독으로 전환(REST 호출 수 급감).

import time, threading

class RateLimiter:
    def __init__(self, per_sec):
        self.interval = 1.0 / per_sec
        self.lock = threading.Lock()
        self.last = 0.0
    def wait(self):
        with self.lock:
            now = time.time()
            gap = self.interval - (now - self.last)
            if gap > 0: time.sleep(gap)
            self.last = time.time()

limiter = RateLimiter(per_sec=4)   # 허용치는 공식 문서 기준으로 설정
# 매 REST 호출 전에 limiter.wait()

참고로 레거시 OpenAPI+는 보통 초당 약 5회 수준을 권장했습니다. REST의 정확한 허용치는 엔드포인트별로 다를 수 있으니 공식 문서 값을 기준으로 잡으세요.

10OpenAPI+ → REST 마이그레이션 + 함정 + 비용

마이그레이션 체크리스트

함정 5가지

1. 토큰 매 요청 재발급 → 제한 차단. 캐싱 필수.
2. 실전/모의 도메인 혼동 → 모의로 짠 코드를 실전에 그대로. base URL을 환경변수 토글로.
3. api-id 헤더 누락·오타 → 엉뚱한 TR 실행 또는 에러.
4. WebSocket 재연결·재등록 누락 → 끊긴 줄 모르고 매매 정지.
5. 요청 제한 초과 → 일시 차단. 직렬화·레이트 리미터로 방지.

레거시 설치·환경 함정(32bit·OCX 등록 등)은 → 키움 OpenAPI+ 설치·오류 해결 가이드에서 다룹니다. REST는 이 종류의 설치 함정 자체가 거의 없습니다.

비용 — 직접 vs 외주

외주 전 요구사항을 정리하면 견적·기간이 정확해집니다 → 자동매매 명세서 작성 가이드. 키움 자동매매 서비스 페이지는 → 키움 자동매매 봇 제작.

자주 묻는 질문

Q. 키움 REST API와 OpenAPI+의 가장 큰 차이는?

OpenAPI+는 OCX/COM(Windows·32bit·PyQt5·이벤트 콜백), REST는 HTTP+WebSocket(OS 독립·64bit·토큰 인증·동기 응답). OCX의 32bit·Windows 종속이 사라집니다.

Q. Mac/Linux에서도 되나요?

네. REST는 표준 HTTP라 OS·비트 무관. Mac 개발 + Linux VPS 운영이 그대로 됩니다. 영웅문·OCX 설치 불필요.

Q. 토큰은 매번 발급하나요? (TR limit)

아니요. 만료 시간이 있으니 캐싱 후 만료 전 재발급. 매 요청 재발급하면 요청 제한에 걸립니다. 주문·조회도 초당 제한이 있어 직렬화·큐잉 필요.

Q. 기존 OpenAPI+ 봇을 꼭 옮겨야 하나요?

필수는 아닙니다. 잘 도는 봇은 유지, 신규는 REST 권장. Mac·64bit·서버배포·다봇이 필요하면 전환 이점이 큼.

Q. 해외주식도 되나요?

키움 REST는 국내 중심. 해외주식 폭넓은 커버리지는 KIS가 강점. 국내 키움 + 해외 KIS 병행이 흔함.

Q. 제작 비용은?

직접은 학습 1~3개월 + VPS 월 5천~3만원. 외주는 단순 봇 80~150만원, 다종목+리스크 150~300만원, 실시간+무중단 300~500만원 선.

다음 단계

1. 자동매매가 처음이면 → 주식 자동매매 완전 입문 가이드
2. Python 기초가 필요하면 → 파이썬 자동매매 입문 가이드
3. 키움 vs 한투 고민이면 → 키움 vs KIS 비교 + 증권사 API 전체 비교
4. 24시간 운영이 필요하면 → VPS 24시간 봇 운영 가이드
5. 외주를 고려하면 → 명세서 작성 가이드 후 알고랩 무료 상담