Skip to content

Getting Started

Jump to bottom
Yu Jin edited this page Jul 15, 2026 · 2 revisions

시작하기

kiwoom-cli를 설치하고 첫 명령어를 실행하기까지의 과정을 안내합니다. v2.1부터 어떤 단계에서도 비밀번호를 묻지 않습니다.

설치

pip install kiwoom-cli

Python 3.10 이상이 필요합니다.

개발 환경에서 설치하려면:

git clone https://github.com/gejyn14/kiwoom-cli.git
cd kiwoom-cli
pip install -e ".[dev]"

초기 설정

1단계: kiwoom config setup

키움증권 Open API 홈페이지에서 발급받은 App Key와 Secret Key가 필요합니다.

kiwoom config setup

실행하면 다음 항목을 순서대로 입력합니다:

프롬프트 설명 예시
App Key 키움 API 앱 키 PSabcdefghijklmn
Secret Key 키움 API 시크릿 키 (입력 시 화면에 표시되지 않음) abc123...
도메인 prod (실거래) 또는 mock (모의투자) mock
계좌번호 계좌번호 (없으면 Enter로 건너뛰기) 1234567

App Key와 Secret Key는 OS 키체인(macOS Keychain / Windows Credential Manager / Linux Secret Service)에 저장됩니다. 파일에 존재하지 않으며, 별도의 비밀번호 설정도 없습니다 — gh, aws, docker CLI와 동일한 모델입니다. 자세한 내용은 보안 참고.

2단계: kiwoom auth login

토큰을 발급받습니다. 프롬프트 없이 바로 실행됩니다.

kiwoom auth login
$ kiwoom auth login
토큰 발급 완료!
  토큰: PSabcdefgh...xyz9
  저장 위치: 키체인

3단계: 첫 명령어 실행

# 삼성전자 기본정보 조회
kiwoom stock info 005930

# 현재가 한 줄
kiwoom stock price 005930

# 호가창
kiwoom stock orderbook 005930

# 계좌 잔고 (국내+미국 통합)
kiwoom account balance

# 거래량 상위
kiwoom market rank volume

v2.0 이하에서 업그레이드했다면

v2.1에서 앱 자체 암호화 저장소(비밀번호 방식)가 제거되었습니다. 이전 버전에서 업그레이드한 경우 명령 실행 시 안내 메시지가 표시되며, kiwoom config setup을 한 번만 다시 실행하면 됩니다. 토큰은 그대로 유지됩니다.

모의투자 vs 실거래

config setup 시 도메인을 선택합니다. 이후 변경하려면:

kiwoom config domain mock       # 모의투자 (기본값, 테스트용)
kiwoom config domain prod       # 실거래

kiwoom config show              # 현재 설정 확인
구분 도메인 WebSocket 비고
모의투자 https://mockapi.kiwoom.com wss://mockapi.kiwoom.com:10000 KRX만 지원
실거래 https://api.kiwoom.com wss://api.kiwoom.com:10000 KRX + NXT 지원

중요: 도메인을 전환한 후에는 반드시 kiwoom auth login으로 토큰을 재발급해야 합니다. 모의투자 토큰과 실거래 토큰은 호환되지 않습니다.

처음 사용할 때는 모의투자로 시작하는 것을 권장합니다:

kiwoom config domain mock
kiwoom auth login
kiwoom stock info 005930        # 모의투자에서 테스트

환경변수

도메인, 계좌번호, 프로필은 환경변수로 설정할 수 있습니다:

환경변수 설명 예시
KIWOOM_DOMAIN 도메인 (prod 또는 mock) export KIWOOM_DOMAIN="prod"
KIWOOM_ACCOUNT 계좌번호 export KIWOOM_ACCOUNT="1234567"
KIWOOM_PROFILE 활성 프로필 이름 export KIWOOM_PROFILE="isa"

환경변수는 config.toml 설정보다 우선합니다.

보안 참고: appkey와 secretkey는 환경변수를 지원하지 않습니다. 반드시 kiwoom config setup으로 키체인에 저장하세요. 환경변수에 키를 노출하면 프로세스 목록이나 로그에서 유출될 수 있습니다.

토큰 관리

kiwoom auth status    # 토큰 상태 확인
kiwoom auth login     # 토큰 발급
kiwoom auth logout    # 토큰 폐기

토큰이 만료되면 CLI가 exit code 3을 반환하며 kiwoom auth login으로 재발급을 안내합니다:

인증 오류: 토큰이 만료되었습니다. kiwoom auth login

설정 확인

kiwoom config show

다음 단계

홈

시작하기

명령어 레퍼런스

가이드

프로젝트

Clone this wiki locally