키움증권 API 사용법, 신청·키 발급부터 파이썬 연동까지

키움증권 API는 공식 홈페이지에서 사용 신청을 한 뒤, IP와 계좌를 등록하고 App Key·App Secret을 발급받아 사용합니다.

발급받은 키로 접근 토큰을 만들면 프로그램에서 주식 정보를 조회할 수 있습니다.

아래는 키움 REST API 기준입니다. OpenAPI+ 모듈이나 KOA Studio를 설치하는 방법과는 다릅니다.

처음에는 실제 주문 없이 모의투자 환경에서 종목 정보 조회부터 진행하겠습니다.

키움증권 API 신청방법

구글이나 네이버에서 ‘키움 REST API’를 검색합니다.
주소가 openapi.kiwoom.com인 공식 홈페이지로 들어갑니다.

키움 REST API 신청 시작하기

키움 REST API 홈페이지 전체 화면과 API 사용신청 클릭 위치 — 홈페이지 우측 상단의 API 사용신청 버튼을 누릅니다. 빨간 사각형과 화살표로 표시한 위치입니다.

홈페이지 우측 상단의 ‘API 사용신청’을 누릅니다.

로그인하면 서비스 신청 화면으로 이동합니다.
약관과 필수 동의 내용을 확인한 뒤 ‘신청하기’를 누릅니다.
신청이 완료되면 카카오톡 알림톡이 발송됩니다.

키움증권 계좌가 없다면 계좌 개설부터 필요합니다.

신청 화면별 설명은 공식 서비스 이용안내에서 확인할 수 있습니다.

참고로 기존 프로그램에서 OpenAPI+나 KOA Studio 설치를 요구한다면, 아래 REST API 절차를 그대로 적용하면 안 됩니다.

OpenAPI+는 별도 사용 등록과 모듈 설치를 거치는 Windows 기반 서비스입니다.

키움증권 API 발급, IP·계좌 등록하기

처음 연습한다면 모의투자부터 준비하세요.

모의투자는 API 사용 신청과 별도로 신청해야 합니다.

REST API 홈페이지에서 찾는 순서

서비스 소개를 누릅니다.
모의투자 이용안내로 들어갑니다.
국내 모의투자 바로가기를 누릅니다.

키움증권 홈페이지에서 직접 찾는 경우에는 다음 순서입니다.

모의투자 → 상시모의투자 → 주식/선물옵션 → 안내

모의투자 신청 경로 확인하기

모의투자 신청을 마쳤다면 REST API 홈페이지로 돌아와 ‘모의투자 App Key 관리’에서 진행합니다.

실전투자와 모의투자는 App Key를 별도로 관리하므로, 처음부터 사용할 환경을 구분해야 합니다.

키움 REST API 모의투자 탭과 IP·계좌 등록 순서를 빨간 사각형 및 번호로 표시한 전체 화면 — 공식 이용안내 화면 예시입니다. 먼저 1번 모의투자 탭을 선택한 뒤, 표시된 2~4번 순서로 진행합니다.

등록 순서는 다음과 같습니다.

모의투자 탭 선택
‘모의투자 App Key 관리’ 탭을 선택합니다.
현재 IP 입력
프로그램을 실행할 PC의 인터넷 연결에서 ‘현재 나의 IP’를 확인하고 입력합니다.
추가 클릭
IP 입력란 오른쪽의 ‘추가’ 버튼을 누릅니다.
계좌 등록
‘계좌 등록하기’를 누르고, 안내에 따라 계좌 선택과 비밀번호·SMS 인증을 진행합니다.
키 다운로드
신청현황에서 App Key와 App Secret을 각각 다운로드합니다.

키움 REST API는 등록된 IP에서만 인증할 수 있습니다.

공식 안내상 키 파일 다운로드는 1회만 가능하므로 안전한 위치에 보관하세요.

App Key·App Secret·접근 토큰은 글, 댓글, 공개 코드에 올리지 않습니다.

오류 화면을 공유할 때도 해당 값은 가려야 합니다.

키움증권 API 파이썬 연동 방법

아래는 파이썬이 설치된 윈도우 PC 기준입니다.

명령 프롬프트에서 다음 명령을 입력합니다.

python --version

버전이 표시되면 필요한 라이브러리를 설치합니다.

python -m pip install requests

일반 웹사이트도 열리지 않고 패키지 설치부터 네트워크 오류로 막힌다면, API 설정을 바꾸기 전에 인터넷 연결 상태를 먼저 확인하세요.

python 명령을 찾을 수 없거나 버전이 나오지 않으면 파이썬 설치 상태부터 확인해야 합니다.

접근 토큰 발급 후 종목 조회하기

홈페이지 상단의 ‘API 가이드’를 누릅니다.
왼쪽 메뉴에서 ‘OAuth 인증’을 선택합니다.
‘접근토큰발급’을 눌러 인증 요청 형식을 확인합니다.

API 가이드, OAuth 인증, 접근토큰발급 메뉴와 모의투자 주소를 빨간 사각형 및 번호로 표시한 전체 화면 — 1 API 가이드 → 2 OAuth 인증 → 3 접근토큰발급. 4번은 예제에서 사용하는 모의투자 서버 주소입니다.

토큰은 발급받은 키로 만드는 API 접속용 인증값입니다.

이후 조회 요청에 함께 전달합니다.

아래 예제는 모의투자 서버에서 토큰을 발급받고, 삼성전자 종목 정보를 한 번 조회합니다.

매수·매도 주문은 포함하지 않았습니다.

메모장을 열어 아래 코드를 붙여넣습니다.
저장할 때 파일 형식을 ‘모든 파일’로 선택합니다.
파일 이름을 kiwoom_test.py로 저장합니다.

import json
from getpass import getpass
import requests

BASE = "https://mockapi.kiwoom.com"

def post(path, body, headers=None):
    response = requests.post(
        BASE + path,
        headers={
            "Content-Type": "application/json;charset=UTF-8",
            **(headers or {}),
        },
        json=body,
        timeout=15,
    )
    response.raise_for_status()
    result = response.json()

    if str(result.get("return_code", 0)) != "0":
        raise RuntimeError(
            f"{result.get('return_code')}: "
            f"{result.get('return_msg')}"
        )
    return result

auth = post("/oauth2/token", {
    "grant_type": "client_credentials",
    "appkey": getpass("모의투자 App Key: ").strip(),
    "secretkey": getpass("모의투자 App Secret: ").strip(),
})

token = auth.get("token")
if not token:
    raise RuntimeError("토큰이 없습니다. 인증 응답을 확인하세요.")

print("토큰 발급 성공")

result = post(
    "/api/dostk/stkinfo",
    {"stk_cd": "005930"},
    {
        "authorization": f"Bearer {token}",
        "api-id": "ka10001",
    },
)
print(json.dumps(result, ensure_ascii=False, indent=2))

공식 API 문서의 요청 형식을 바탕으로 작성한 예제입니다. 실제 계정으로 실행 검증한 코드는 아니므로 모의투자 환경에서 확인하세요.

👉키움 REST API 가이드 바로가기