Getting Started

시작하기

kiwoom-cli를 설치하고 첫 명령어를 실행하기까지의 과정을 안내합니다.

설치

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
시스템 비밀번호	인증정보 암호화에 사용할 비밀번호	(사용자 설정)

$ kiwoom config setup
App Key: PSabcdefghijklmn
Secret Key:
도메인 (prod=실거래, mock=모의투자) [mock]: mock
계좌번호 (없으면 Enter):
시스템 비밀번호 (인증정보 암호화에 사용):
설정 완료! (프로필: default)
  App Key/Secret Key: 암호화되어 키체인에 저장됨
  도메인: https://mockapi.kiwoom.com

App Key와 Secret Key는 Fernet(AES-128-CBC + HMAC)으로 암호화되어 OS 키체인에 저장됩니다. 파일에 평문으로 존재하지 않습니다.

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

모의투자 vs 실거래

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

kiwoom config set domain mock   # 모의투자 (기본값, 테스트용)
kiwoom config set 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 set 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

  프로필: default
  설정 파일: /Users/username/.kiwoom/config.toml
  도메인: mock
  App Key: 설정됨 (암호화)
  계좌번호: 1234567
  보안: SecureStore 활성

다음 단계

• 명령어 가이드 -- 전체 명령어 구조 파악
• 종목 조회 -- 종목 정보 조회
• 멀티 프로필 -- 여러 계좌 관리
• 보안 -- 보안 아키텍처 이해