키움 REST API 공식 샘플코드 — kwcli로 첫 호출

1. 저장소에 실제로 뭐가 들어 있나

키움증권은 REST API 전환 이후 공식 클라이언트와 샘플코드를 깃허브 공개 저장소 Kiwoom-Securities/Kiwoom-REST-API에 올려 두고 있습니다. 이 저장소를 git clone하면 루트에 폴더 6개와 파일 몇 개가 보이는데, 이름만 보고 넘기기 쉬운 것들이라 먼저 정리합니다.

2. 왜 .env가 아니라 kwcli인가

증권사 API 예제라고 하면 보통 .env에 APP_KEY와 APP_SECRET을 적는 방식을 떠올립니다. 한국투자증권 공식 저장소도 kis_devlp.yaml이라는 설정 파일을 쓰고, 사용자가 그 파일을 홈 폴더로 옮기는 과정에서 자주 막힙니다.

키움 공식 저장소는 그 순서를 뒤집었습니다. 기본 경로가 CLI 인증이고, .env는 예외 상황용 대체 경로입니다. kiwoomcli setup을 한 번 마치면 App Key와 App Secret이 운영체제 자격 증명 저장소(macOS 키체인 · Windows 자격 증명 관리자 · Linux Secret Service)에 저장되고, 프로젝트 폴더나 깃 저장소에는 키가 남지 않습니다. 그리고 같은 자격 증명을 examples/의 예제도 그대로 사용합니다.

실무에서 이 차이가 의미가 있는 이유는 두 가지입니다. 첫째, App Key가 프로젝트 폴더 밖에 있으면 실수로 깃허브에 올릴 경로 자체가 사라집니다. .gitignore에 .env를 넣어 두는 것과 파일을 아예 만들지 않는 것은 사고 확률이 다릅니다. 둘째, 계좌를 여러 개 쓸 때 별칭(profile)으로 갈라 둘 수 있어서 모의투자와 실전을 같은 터미널에서 섞어 쓰다 생기는 사고를 줄입니다.

3. 설치 8단계 — Python 3.13부터 첫 조회까지

공식 README가 정리한 순서 그대로입니다. 앞의 세 단계는 환경 준비이고, 실제 키움 관련 작업은 4단계부터 시작합니다.

1단계 — App Key / App Secret 발급

키움증권 OpenAPI 개발자센터에서 앱(App)을 등록하고 App Key와 App Secret을 발급받습니다. 여기서 중요한 것은 운영과 모의투자의 키가 따로 발급된다는 점입니다. 두 환경을 다 쓸 계획이면 이 단계에서 각각 받아 두십시오. 발급 화면의 메뉴 이름과 위치는 키움 포털 정책에 따라 달라질 수 있으므로 키 발급 절차는 포털 안내를 기준으로 확인하시기 바랍니다.

2~3단계 — Python 3.13 이상과 uv

이 프로젝트는 Python 3.13 이상을 기준으로 합니다. PyPI의 kwcli 패키지도 requires_python이 >=3.13이라 3.11이나 3.12에서는 설치 단계에서 걸립니다. 의존성 동기화와 예제 실행에는 uv를 씁니다.

# macOS / Linux
python3 --version                       # Python 3.13.x 이상인지 확인
brew install [email protected]                # 없으면 설치 (macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version

# Windows PowerShell
py --version
winget install Python.Python.3.13
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv --version

4단계 — CLI 설치

uv tool install kwcli      # 설치는 kwcli
kiwoomcli --help           # 실행은 kiwoomcli

uv tool install로 설치하면 어느 폴더에서나 kiwoomcli 명령을 쓸 수 있습니다. 명령을 못 찾는다는 메시지가 나오면 uv tool 실행 경로가 PATH에 반영되도록 새 터미널을 열고 다시 시도하십시오. 안내가 나올 경우 uv tool update-shell을 실행합니다.

5단계 — kiwoomcli setup

kiwoomcli setup
kiwoomcli auth status

6~8단계 — 확인과 예제

kiwoomcli domestic stocks info --code 005930
kiwoomcli overseas stocks info --exchange NASDAQ --code AAPL

cd <저장소를-clone한-폴더>
uv sync
uv run python "examples/국내주식/종목정보/list_domestic_stocks.py"

4. kiwoomcli setup이 묻는 네 가지

setup은 대화형입니다. 순서대로 네 가지를 처리합니다.

1. 계좌 별칭 — 모의계좌·실전계좌처럼 이름을 붙입니다. 그냥 Enter를 누르면 기본 별칭으로 저장됩니다.
2. 서버 선택 — [1] demo(모의투자) 또는 [2] real(실전투자). Enter는 안전을 위해 demo가 기본입니다.
3. App Key / App Secret 입력 — 1단계에서 받은 값을 붙여넣습니다. 입력값은 화면에 표시되지 않습니다.
4. 연결 검증 — CLI가 안전한 조회 API로 연결을 확인하고, 성공하면 자격 증명 저장소에 저장합니다.

성공하면 다음 단계 안내가 그대로 출력됩니다.

kiwoomcli auth status --profile <별칭>
kiwoomcli domestic stocks info --code 005930 --profile <별칭>

kiwoomcli auth status는 자격 증명 존재 여부와 토큰 유효·만료 시각을 출력합니다. 키움 REST 토큰은 만료 시각(expires_dt)과 폐기 절차가 따로 있으므로, "왜 어제는 되던 게 오늘 안 되나" 싶을 때 가장 먼저 볼 명령입니다. 같은 별칭으로 setup을 다시 실행하면 전환 / 토큰만 재발급 / 키 다시 입력 / 삭제 후 재설정 중에서 고를 수 있습니다.

5. examples/ 예제 실행과 응답 형태

examples/는 OAuth 인증 · 국내주식 · 미국주식 세 갈래이고, 국내주식 아래는 기능별 폴더 17개로 나뉩니다 — 계좌 · 시세 · 차트 · 주문 · 신용주문 · 종목정보 · 순위정보 · 조건검색 · 실시간시세 · 업종 · 테마 · 공매도 · 대차거래 · 기관_외국인 · 관심종목 · ETF · ELW.

uv run python "examples/국내주식/시세/get_domestic_stock_quote.py"
uv run python "examples/국내주식/차트/get_domestic_stock_daily_chart.py"
uv run python "examples/국내주식/계좌/list_domestic_accounts.py"
uv run python "examples/미국주식/종목정보/get_overseas_stock_list.py"
uv run python "examples/미국주식/시세/get_overseas_stock_quote.py"

경로에 한글과 공백이 들어 있으므로 따옴표로 감싸야 합니다. 실행 결과는 API에 따라 pandas.DataFrame 또는 dict[str, pandas.DataFrame] 형태이고, 복수 테이블 응답은 [테이블명] 단위로 나뉘어 표시됩니다. 차트 계열(ka10081·ka10080)처럼 한 응답에 여러 테이블이 실리는 API에서 이 구분이 눈에 띕니다.

WebSocket 실시간 예제는 *_async.py와 *_pubsub.py 두 패턴으로 제공되며, 연결을 유지하므로 장시간 실행됩니다. Postman 컬렉션에는 WebSocket API 31개가 들어 있지 않아서, 실시간 등록(0B·0D)을 확인하려면 이 예제를 써야 합니다.

6. Postman 컬렉션 306 × 2

postman/kiwoom-openapi.postman_collection.json을 Postman에서 Import 하면 PRD(운영) 306개와 MOCK(모의투자) 306개, 합계 612개 요청이 들어옵니다. 컬렉션 변수는 네 개입니다.

OAuth 토큰 발급 요청을 실행하면 토큰이 컬렉션 변수에 저장되어 이후 요청에 자동으로 실립니다. 편하지만 그 상태로 컬렉션을 export 하거나 공유하면 키와 토큰이 그대로 따라갑니다. 공식 문서가 별도 경고를 붙여 둔 지점입니다.

코드를 쓰지 않고 요청 규격만 확인할 때, 또는 유량 제한(429)이 코드 문제인지 계정 문제인지 가를 때 Postman으로 한 번 쏴 보는 편이 빠릅니다.

7. 자주 막히는 오류 5가지

공식 README 부록 B가 정리한 오류들입니다. 대부분 코드가 아니라 설정 문제입니다.

이 다섯 개를 다 통과했는데도 결과가 이상하면, 응답에 실린 키움 서버의 return_code · return_msg를 확인하십시오. 이 단계부터는 설정이 아니라 요청 파라미터·계좌 권한·운영/모의 환경·장 운영 시간의 문제입니다. 키움 REST API 자동매매 전체 구조에서 토큰·TR 제한·WebSocket이 어떻게 묶이는지 함께 보시면 원인을 좁히기 쉽습니다.

8. 이 저장소로 어디까지 되고, 어디부터 안 되나

공식 예제는 API 호출 단위로 짜여 있습니다. "종목 정보를 조회한다", "일봉을 받는다", "주문을 낸다"까지가 한 파일 한 기능입니다. 이걸 이어 붙여 실제로 돌아가는 봇을 만들려면 그 위에 다른 층이 필요합니다 — 장 시작·종료 스케줄링, 토큰 만료 시 재발급, 유량 제한에 걸렸을 때의 재시도, 부분 체결 처리, 오류로 죽었을 때의 복구, 그리고 무엇보다 전략이 틀렸을 때 멈추는 장치입니다.

반대로 말하면, 이 저장소는 "증권사 API가 실제로 어떻게 생겼는지" 확인하는 가장 빠른 경로입니다. 제작을 맡길지 직접 만들지 정하기 전에 kiwoomcli domestic stocks info --code 005930 한 줄을 돌려 보는 것만으로도 견적서에 적힌 항목들이 무슨 뜻인지 훨씬 잘 읽힙니다.

자주 묻는 질문

키움증권 REST API 공식 샘플코드는 어디에 있나요?

깃허브의 Kiwoom-Securities/Kiwoom-REST-API 저장소입니다. kiwoom/에 OAuth·REST·WebSocket 런타임과 337개 API 스펙, examples/에 파이썬 예제 362개(OAuth 2 · 국내주식 226 · 미국주식 134), postman/에 HTTP API 306개를 운영·모의 환경별로 담은 컬렉션이 있습니다. CLI 소스는 이 저장소에 없고 PyPI 패키지 kwcli로 따로 배포됩니다.

kwcli와 kiwoomcli는 뭐가 다른가요?

같은 것입니다. 배포 패키지 이름이 kwcli, 실행 명령 이름이 kiwoomcli입니다. 설치는 uv tool install kwcli, 확인은 kiwoomcli --help입니다. 2026-09-10 기준 PyPI의 kwcli는 1.0.2이고 requires_python은 >=3.13입니다.

App Key를 .env에 넣어야 하나요?

공식 권장은 .env가 아니라 CLI 인증입니다. kiwoomcli setup이 키를 운영체제 자격 증명 저장소에 넣고, examples/도 같은 자격 증명을 쓰므로 .env를 만들 필요가 없습니다. 둘을 같이 두면 예제가 .env를 먼저 사용해 충돌합니다. .env는 자격 증명 저장소를 쓸 수 없는 환경을 위한 대체 경로입니다.

모의투자와 실전은 같은 App Key를 쓰나요?

아닙니다. 운영과 모의투자의 키가 따로 발급됩니다. CLI에서는 별칭을 나눠 저장하고 --profile로 지정하며, .env 방식이면 KIWOOM_MODE=real일 때 APP_KEY·APP_SECRET, KIWOOM_MODE=demo일 때 APP_KEY_MOCK·APP_SECRET_MOCK을 씁니다. 엔드포인트 값(PRD·MOCK·W_PRD·W_MOCK)은 기본값이 내장돼 있어 손댈 필요가 없습니다.

이 내용을 그대로 믿어도 되나요?

이 글의 폴더 구조·명령·환경변수 이름·오류 이름은 2026-09-10 시점 Kiwoom-Securities/Kiwoom-REST-API 저장소의 main 브랜치 (README.md, mcpb/README.md, 저장소 트리)와 PyPI의 kwcli 메타데이터를 직접 확인한 것입니다. 저장소와 API 명세, 발급 화면은 예고 없이 바뀌므로 실제 작업 시점의 저장소와 키움증권 OpenAPI 개발자센터 안내로 대조하십시오. 이 글은 개발 실무 안내이며 투자 권유나 수익 보장이 아닙니다.