90%가 실수하는 5가지
키움증권 REST API를 처음 알아보면 가장 먼저 부딪히는 벽이 있다.
"OpenAPI+랑 REST API, 도대체 뭐가 다른 건가?"
그리고 그다음 벽은 더 위험하다. 신청은 했는데 어디서부터 손대야 할지 모르겠다는 막막함. 이 단계에서 잘못 시작하면 실전 키 발급 횟수 제한에 걸리거나, 최악의 경우 첫 주문에서 중복 매수 사고가 난다.
이 글은 그 두 벽을 한 번에 정리하는 가이드다. 신청 → 토큰 발급 → 첫 호출 → 모의투자 검증까지의 전 과정을 핵심만 추려본다.
키움증권은 두 가지 자동매매 API를 운영한다. 둘은 완전히 다른 시스템이다.
| 구분 | OpenAPI+ (기존) | REST API (신규) |
|---|---|---|
| 방식 | OCX 기반, OS 의존 | HTTP 요청 기반 |
| 실행 환경 | Windows + 32bit + HTS 실행 필수 | Windows·Mac·Linux·서버 모두 가능 |
| 개발 구조 | PyQt·이벤트 루프·콜백 | 토큰 발급 → JSON 호출 → 응답 파싱 |
| 인증 방식 | 로그인 프로그램 연동 | AppKey + SecretKey + Access Token |
| 주요 활용 | HTS 연동 자동매매 | 서버·웹·자동화 봇 |
핵심 차이는 한 줄로 요약된다.
OpenAPI+는 "내 PC에 설치해서 돌리는 자동매매", REST API는 "인터넷으로 키움 서버와 직접 대화하는 자동매매"다.
서버에서 24시간 돌리는 자동매매·퀀트 시스템을 만들 거라면 REST API가 정답이다. 다만 현재 시점 기준 REST API의 주력은 국내주식 중심이고, 해외주식 등 일부 상품은 여전히 OpenAPI+ 병행이 필요하다는 점은 감안해야 한다.
REST API 사용 신청 전에 다음 4가지가 준비되어야 한다.
신청은 키움 REST API 전용 포털에서 진행한다.
openapi.kiwoom.com 접속 후 키움증권 ID로 로그인발급된 두 키의 역할은 다음과 같다.
AppKey: 서비스 식별자 (ID 같은 느낌)
SecretKey: 비밀키 (비밀번호 같은 느낌)
이 두 키를 코드에 직접 적는 순간 사고의 절반은 시작된 셈이다.
❌ 나쁜 예 (절대 금지):
APPKEY = "내진짜앱키"
SECRETKEY = "내진짜시크릿키"✅ 올바른 방식: .env 파일을 쓰고 .gitignore에 .env를 추가한다.
KIWOOM_APPKEY=발급받은_앱키
KIWOOM_SECRETKEY=발급받은_시크릿키
KIWOOM_HOST=https://mockapi.kiwoom.comfrom dotenv import load_dotenv
import os
load_dotenv()
APPKEY = os.getenv("KIWOOM_APPKEY")
SECRETKEY = os.getenv("KIWOOM_SECRETKEY")자동매매는 투자 실력만큼 보안 실력이 중요하다. GitHub에 SecretKey가 그대로 올라간 사례는 매년 반복적으로 발생한다.
키움 REST API의 모든 요청은 접근 토큰(Access Token) 기반으로 돌아간다. 흐름은 단순하다.
access_token 수신Authorization: Bearer {token} 포함토큰 발급 정보:
| Method | POST |
|
| 실전 URL | https://api.kiwoom.com/oauth2/token |
|
| 모의 URL | https://mockapi.kiwoom.com/oauth2/token |
|
| Content-Type | application/json;charset=UTF-8 |
|
Python 코드 예시:
import os
import requests
from dotenv import load_dotenv
load_dotenv()
APPKEY = os.getenv("KIWOOM_APPKEY")
SECRETKEY = os.getenv("KIWOOM_SECRETKEY")
HOST = os.getenv("KIWOOM_HOST", "https://mockapi.kiwoom.com")
url = f"{HOST}/oauth2/token"
headers = {"Content-Type": "application/json;charset=UTF-8"}
data = {
"grant_type": "client_credentials",
"appkey": APPKEY,
"secretkey": SECRETKEY
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)
# {"token": "...", "token_type": "Bearer", "expires_dt": "..."}응답 JSON의 token 값을 이후 모든 API 호출 헤더에 다음과 같이 붙인다.
"authorization": f"Bearer {token}"expires_dt를 기록해두고 만료 전 자동 갱신, 또는 401 응답 시 자동 재발급 로직을 코드에 넣어두는 게 필수다.토큰 발급에 성공했다면 다음은 실제 API 호출이다. 키움 REST API의 요청 구조는 항상 3개 요소로 나뉜다.
① URL — 기능별 엔드포인트 (예: 주문은 /api/dostk/ordr)
② Header — 인증 + API 식별값
headers = {
"Content-Type": "application/json;charset=UTF-8",
"authorization": f"Bearer {token}",
"cont-yn": "N", # 연속조회 여부
"next-key": "", # 다음 조회 키
"api-id": "kt10000" # 요청 API의 TR ID
}③ Body — 실제 요청 내용
data = {
"dmst_stex_tp": "KRX", # 국내 거래소 구분
"stk_cd": "039490", # 종목코드
"ord_qty": "1", # 주문수량
"ord_uv": "", # 주문단가 (시장가는 빈값)
"trde_tp": "3", # 거래구분
"cond_uv": "" # 조건단가
}api-id가 가장 중요하다. 키움 API는 기능마다 고유한 TR ID가 있다. 주문(kt10000), 추정자산조회(kt00003), 계좌평가현황(kt00004) 등 기능마다 ID가 다르다. 한 글자라도 틀리면 정상 응답이 안 온다.처음 REST API를 다루는 사람이 반복적으로 빠지는 함정이다.
mockapi.kiwoom.com과 api.kiwoom.com을 섞어 쓰면서 "왜 주문이 안 되지?" 하는 경우가 가장 많다.자동매매에서 가장 무서운 건 손실이 아니라 중복 주문과 의도하지 않은 주문이다. 실전 키 연결 전에 다음을 반드시 점검한다.
코드는 감정이 없다. 조건이 맞으면 망설임 없이 주문을 넣는다. 그래서 실전 연결은 개발의 영역이 아니라 리스크 관리의 영역이다.
긴 가이드였지만 핵심은 한 줄로 요약된다.
이 구조만 이해하면 시세 조회·잔고 조회·주문·체결 조회·실시간 시세까지 하나씩 확장할 수 있다.
다만 실전 계좌에 연결하는 순간 게임이 바뀐다는 점은 잊지 말아야 한다. 키움 REST API는 자동매매의 문턱을 낮춰줬지만, 실전 연결 후에는 코드보다 운영·로그·예외 처리·보안이 더 중요한 영역이 된다.
처음 시작하는 사람이라면 다음 순서로 가는 걸 권한다.
이 순서를 지키면 실전 키 발급 한도에 걸리거나 첫 주문에서 사고가 나는 일은 거의 없다.
실전 계좌 연결 후엔 개발보다 리스크 관리의 영역이다.
이 한 가지 원칙이 첫 사고를 막는다.
'트레이딩노하우' 카테고리의 다른 글
| 주도주 매매 vs 단기매매,하락장에서 어느 쪽이 덜 망할까? (0) | 2026.05.02 |
|---|---|
| 어제 반도체 ETF 들고 있던 분들!, '변동성 지옥' 진입신호 꼭 확인하세요! (0) | 2026.04.29 |
| 키움 영웅문 조건검색기로시장 주도주 잡는 완전 실전 가이드 (1) | 2026.04.17 |
| 더블-B V7 시그널 시스템 완전 해부— 볼린저밴드 + RSI + VWCCI의 구조 (0) | 2026.04.13 |
| 자동매매 시스템의 원리와 실전 전략— 일반 투자채널과 구분되는 블루오션인 이유 (0) | 2026.04.13 |