[튜토리얼] 키움증권 REST API 시작하기 — 개발자 등록·앱 키 발급·모의투자 신청

이 글의 범위

이 시리즈는 키움증권이 공개한 개발자 문서에 나오는 일반적인 절차를 정리한다. 실제 화면 캡처, 우리 계좌번호, 발급받은 App Key/Secret 값은 담지 않는다. 화면 구성이나 메뉴 이름은 공지 없이 바뀔 수 있으므로, 실제로 신청할 때는 반드시 키움증권 공식 개발자센터 문서를 기준으로 진행해야 한다. 이 글은 그 문서를 처음 열기 전에 "전체 그림"을 잡는 용도다.

왜 증권사 API는 바로 못 쓰는가

주식 데이터를 웹으로 조회하는 것과 달리, 자동매매용 REST API는 계좌에 직접 접근하는 권한을 요구한다. 그래서 대부분의 증권사는 아무나 즉시 API를 호출하게 두지 않고, 아래와 같은 등록·심사 절차를 거치게 한다.

증권사 개발자센터(또는 Open API 포털)에 가입한다
"앱" 단위로 API 이용 신청을 하고, 신청이 승인되면 App Key / App Secret 한 쌍을 발급받는다
실전 계좌와는 별도로 모의투자(페이퍼 트레이딩) 계좌를 신청해, 실제 자금 없이 API 호출을 연습할 수 있게 한다
이후 인증·시세조회·주문·잔고조회 등 각 기능별 API 문서를 참고해 연동을 시작한다

키움증권도 이 공통 패턴을 따른다. 세부 메뉴명이나 신청 화면은 시기에 따라 다를 수 있어 이 글에서는 다루지 않는다.

1단계 — 개발자센터 가입

키움증권은 REST API 이용을 위한 별도의 개발자센터(Open API 포털)를 운영한다. 가입 시 보통 아래 정보가 필요하다.

실제 증권 계좌(본인 명의) 존재 여부 확인
이용약관·개인정보 처리 동의
API 이용 목적에 대한 간단한 확인(개인 개발/연구용인지 등)

가입 자체는 대부분 무료이며, 계좌를 이미 보유한 고객을 대상으로 한다. 정확한 가입 조건과 화면은 시기별로 달라질 수 있으니 개발자센터 공지사항을 확인하는 게 안전하다.

2단계 — 앱 등록과 App Key/Secret 발급

가입 후에는 "앱"을 하나 등록해야 API 키를 받을 수 있다. 일반적으로 아래 정보를 입력하게 된다.

앱 이름 (자신이 구분할 수 있는 아무 이름)
사용 목적 (개인용 자동화, 학습용 등)
사용할 API 범위 (시세조회, 주문, 잔고조회 등 필요한 항목 선택)

등록이 완료되면 App Key와 App Secret이 발급된다. 이 둘은 이후 인증 절차에서 신분증처럼 사용되는 값이라, 비밀번호와 동급으로 다뤄야 한다.

증권사 REST API 인증 흐름 — 키로 토큰을 발급받아 이후 요청 헤더에 싣는 공통 패턴

코드 저장소(GitHub 등)에 절대 커밋하지 않는다
.env 파일이나 별도 설정 파일로 분리하고, 해당 파일은 .gitignore에 반드시 포함한다
실수로 노출됐다면 즉시 재발급받아 이전 값을 무효화한다

의사코드로 표현하면 이런 형태로 값을 외부에서 주입받는 게 표준적이다.

python 코드 보기

import os

app_key = os.environ["KIWOOM_APP_KEY"]
app_secret = os.environ["KIWOOM_APP_SECRET"]

3단계 — 모의투자 계좌 신청

App Key/Secret 발급과 별개로, 실제 자금을 쓰지 않고 연습할 수 있는 모의투자 계좌를 신청하는 절차가 있다. 대체로 아래 흐름을 따른다.

개발자센터 또는 증권사 앱/HTS에서 모의투자 서비스를 신청한다
모의투자용 계좌번호가 발급된다 (실전 계좌와는 별개의 번호)
모의투자 환경은 실전 환경과 API 접속 주소(base URL)가 다른 경우가 많다 — 이 부분을 혼동하면 의도치 않게 실전 주문이 나갈 수 있으니 반드시 문서에서 확인한다

처음 코드를 짤 때는 base URL을 상수 하나로 몰아서 관리하고, 환경변수로 "지금 모의투자인지 실전인지"를 명시적으로 구분하는 습관을 들이는 게 좋다.

python 코드 보기

ENV = os.environ.get("KIWOOM_ENV", "paper")  # "paper" 또는 "live"
BASE_URL = {
    "paper": "https://mock-api.example-broker.com",
    "live": "https://api.example-broker.com",
}[ENV]

물론 실제 도메인은 키움증권 공식 문서를 따라야 하며, 위 코드는 개념을 보여주기 위한 예시일 뿐이다.

처음 신청할 때 흔한 실수

모의투자 신청을 건너뛰고 바로 실전 연동을 시도하는 것: 코드에 버그가 있어도 실제 자금이 걸려 있으면 되돌리기 어렵다. 모의투자에서 충분히 검증한 뒤 넘어가는 순서를 지키는 게 안전하다.
앱 등록 시 필요 이상으로 넓은 API 범위를 선택하는 것: 나중에 쓰지 않을 주문 권한까지 부여하면, 키가 유출됐을 때 피해 범위가 커진다. 실제로 쓸 기능만 최소한으로 신청하는 게 원칙이다.
발급받은 키를 캡처해서 메신저나 문서에 그대로 붙여넣는 것: 공유가 필요하면 값 자체가 아니라 "어디에 저장했는지"를 공유해야 한다.

오늘의 정리

키움증권 REST API를 쓰려면 개발자센터 가입 → 앱 등록·App Key/Secret 발급 → 모의투자 계좌 신청 순서를 거친다.
App Key/Secret은 비밀번호와 동급이며, 코드가 아니라 환경변수 등 외부에서 주입해야 한다.
모의투자와 실전 환경은 접속 주소가 다른 경우가 많아, 처음부터 환경 구분을 코드에 명시적으로 넣어두는 게 안전하다.

다음 글에서는 이렇게 발급받은 App Key/Secret으로 실제로 접근 토큰을 발급받고 관리하는 절차를 의사코드 중심으로 다룬다.

이 글은 키움증권이 공개한 개발자 문서 수준의 일반적인 절차를 정리한 것이며, 특정 계좌·API 키·실제 화면을 담고 있지 않습니다. 실제 신청과 연동은 반드시 키움증권 공식 개발자센터 문서를 기준으로 진행하시기 바랍니다. 이 글은 투자 조언이 아니며 특정 종목이나 매매기법을 추천하지 않습니다. 수익을 보장하지 않으며, 투자 손실에 대한 책임은 투자자 본인에게 있습니다.