Metadata-Version: 2.4
Name: kiwoom-cli
Version: 0.2.2
Summary: User-friendly CLI for the Kiwoom Securities REST API (키움증권)
License: MIT
Project-URL: Homepage, https://github.com/gejyn14/kiwoom-cli
Project-URL: Repository, https://github.com/gejyn14/kiwoom-cli
Project-URL: Issues, https://github.com/gejyn14/kiwoom-cli/issues
Keywords: kiwoom,stock,trading,cli,korea,finance
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Requires-Dist: tomli-w>=1.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.30; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# kiwoom-cli

키움증권 REST API를 터미널에서 사용하기 위한 CLI 도구.

- 207개 API 전체 지원 (188 REST + 19 WebSocket 실시간)
- 종목 조회, 호가, 차트, 계좌, 주문, 순위, 업종, 테마, ETF, ELW, 금현물
- 출력 형식: Rich 테이블 / JSON / CSV (`-f json`, `-f csv`)
- 실시간 WebSocket 스트리밍 (체결, 호가, VI, 잔고 등)
- AI 에이전트 친화적: 구조화된 JSON 출력, exit code (0/1/2/3)

## 설치

```bash
git clone https://github.com/gejyn14/kiwoom-cli.git
cd kiwoom-cli
pip install -e .
```

## 시작하기

```bash
# 1. 초기 설정 (키움 Open API에서 발급받은 appkey, secretkey 입력)
kiwoom config setup

# 2. 토큰 발급
kiwoom auth login

# 3. 사용
kiwoom stock info 005930
```

### 모의투자 vs 실거래

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

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

kiwoom config show          # 현재 설정 확인
```

모의투자는 KRX만 지원됩니다. 실거래 전환 후에는 `kiwoom auth login`으로 토큰을 재발급하세요.

### 환경변수 설정

`config.toml` 대신 환경변수로도 설정 가능합니다. 환경변수가 우선합니다.

```bash
export KIWOOM_APPKEY="your-app-key"
export KIWOOM_SECRETKEY="your-secret-key"
export KIWOOM_DOMAIN="prod"       # prod 또는 mock
export KIWOOM_ACCOUNT="1234567"   # 선택
```

Docker, CI, 클라우드 환경에서 `config setup` 없이 바로 사용 가능합니다.

## 명령어 구조

```
kiwoom [--format table|json|csv] [--no-color]
├── config      설정 (setup / show / domain)
├── auth        인증 (login / logout / status)
├── stock       종목 조회 (info / orderbook / chart / compare ...)
├── account     계좌 조회 (balance / deposit / returns / pnl ...)
├── order       주문 (buy / sell / modify / cancel / credit / gold)
├── market      시장 정보 (rank / sector / theme / etf / elw / gold)
├── stream      실시간 스트리밍 (quote / orderbook / order / vi ...)
├── dashboard   대시보드 (계좌 + 거래량 상위 한눈에)
└── api         Raw API 호출
```

---

## stock - 종목 조회

```bash
kiwoom stock info 005930              # 기본정보 (PER, PBR, 시가총액 등)
kiwoom stock price 005930             # 현재가 한 줄
kiwoom stock orderbook 005930         # 10단계 호가창
kiwoom stock daily 005930             # 일별 시세
kiwoom stock daily 005930 --type week # 주별 시세
kiwoom stock exec 005930              # 체결정보
kiwoom stock trader 005930            # 거래원
kiwoom stock foreign 005930           # 외국인 매매동향
kiwoom stock institution 005930       # 기관 매매동향
kiwoom stock short 005930 --from 20260101 --to 20260330  # 공매도 추이
kiwoom stock search --market kospi     # 코스피 종목 리스트
kiwoom stock watchlist "005930|000660" # 관심종목
```

### 차트

```bash
kiwoom stock chart tick 005930 --range 1        # 틱
kiwoom stock chart minute 005930 --interval 5    # 5분봉
kiwoom stock chart day 005930 --base-date 20260301   # 일봉
kiwoom stock chart week 005930 --base-date 20260301  # 주봉
kiwoom stock chart month 005930 --base-date 20260301 # 월봉
kiwoom stock chart year 005930 --base-date 20260301  # 년봉
```

### 투자자/분석

```bash
kiwoom stock investor daily-trade --from 20260301 --to 20260330
kiwoom stock investor by-stock 005930 --date 20260301
kiwoom stock investor program-top
kiwoom stock analysis vi-trigger
kiwoom stock analysis per-rank --type low-per
kiwoom stock lending trend
kiwoom stock credit trend 005930 --date 20260301 --type loan
```

<details>
<summary>전체 stock 하위 명령어</summary>

| 명령 | 설명 |
|------|------|
| `info` | 종목 기본정보 |
| `price` | 현재가 한 줄 |
| `detail` | 종목정보 상세 |
| `orderbook` | 10단계 호가창 |
| `daily` | 일/주/월별 시세 |
| `timeprice` | 시분 시세 |
| `daily-price` | 일별주가 |
| `after-hours` | 시간외단일가 |
| `quote-info` | 시세표성정보 |
| `exec` | 체결정보 |
| `trader` | 거래원 |
| `today-exec` | 당일/전일 체결 |
| `today-volume` | 당일/전일 체결량 |
| `tick-strength` | 체결강도 시간별 |
| `daily-strength` | 체결강도 일별 |
| `foreign` | 외국인 매매동향 |
| `institution` | 기관 매매동향 |
| `short` | 공매도 추이 |
| `search` | 종목 리스트/검색 |
| `watchlist` | 관심종목 |
| `brokers` | 회원사 리스트 |
| `chart *` | 틱/분봉/일봉/주봉/월봉/년봉, 투자자별 차트 |
| `investor *` | 기관매매, 투자자별매매, 프로그램매매 등 10개 |
| `analysis *` | 거래상세, 거래량갱신, 매물대, PER, VI, 증권사 등 10개 |
| `lending *` | 대차거래 추이/상위/종목별/내역 |
| `credit *` | 신용매매동향, 신용융자 가능 |

</details>

---

## account - 계좌 조회

```bash
kiwoom account list                # 계좌번호
kiwoom account balance             # 잔고 + 보유종목 + 손익
kiwoom account deposit             # 예수금
kiwoom account asset               # 추정자산
kiwoom account today               # 당일현황
kiwoom account returns summary     # 수익률
kiwoom account pnl today 005930    # 당일 실현손익
kiwoom account orders pending      # 미체결 주문
kiwoom account orders executed     # 체결 내역
kiwoom account holdings eval       # 잔고내역
kiwoom account orderable amount 005930 --side buy --price 70000
```

<details>
<summary>전체 account 하위 명령어</summary>

| 그룹 | 명령 | 설명 |
|------|------|------|
| - | `list` | 계좌번호 조회 |
| - | `balance` | 계좌 평가현황 |
| - | `deposit` | 예수금 상세 |
| - | `asset` | 추정자산 |
| - | `today` | 당일현황 |
| - | `margin-detail` | 증거금 세부내역 |
| `returns` | `summary` | 계좌 수익률 |
| `returns` | `daily-balance` | 일별 잔고수익률 |
| `returns` | `daily-detail` | 일별 수익률 상세 |
| `returns` | `daily-asset` | 일별 예탁자산 |
| `pnl` | `today` | 당일 실현손익 |
| `pnl` | `by-date` | 일자별 실현손익 |
| `pnl` | `by-period` | 기간별 실현손익 |
| `pnl` | `daily` | 일자별 실현손익 |
| `orders` | `pending` | 미체결 주문 |
| `orders` | `executed` | 체결 내역 |
| `orders` | `detail` | 주문체결 상세 |
| `orders` | `status` | 주문체결 현황 |
| `orders` | `split-detail` | 분할주문 상세 |
| `holdings` | `eval` | 계좌평가 잔고 |
| `holdings` | `settled` | 체결잔고 |
| `holdings` | `next-settle` | 익일결제예정 |
| `orderable` | `amount` | 주문가능 금액 |
| `orderable` | `margin-qty` | 증거금율별 수량 |
| `orderable` | `credit-qty` | 신용보증금율별 수량 |
| `history` | `transactions` | 위탁종합 거래내역 |
| `history` | `journal` | 당일 매매일지 |

</details>

---

## order - 주문

모든 주문에 `--confirm` 필수.

```bash
# 주식
kiwoom order buy 005930 10 --type market --confirm          # 시장가 매수
kiwoom order buy 005930 10 --price 70000 --type limit --confirm  # 지정가 매수
kiwoom order sell 005930 10 --type market --confirm         # 매도
kiwoom order modify 0000139 005930 1 70000 --confirm        # 정정
kiwoom order cancel 0000140 005930 --confirm                # 취소

# 신용
kiwoom order credit buy 005930 10 --type market --confirm
kiwoom order credit sell 005930 10 --type market --confirm

# 금현물
kiwoom order gold buy M04020000 1 --type market --confirm
kiwoom order gold balance --confirm    # 잔고
kiwoom order gold pending --confirm   # 미체결

# 조건검색
kiwoom order condition list
kiwoom order condition search 001 --confirm
```

주문유형: `limit` `market` `conditional` `after-hours` `pre-market` `single` `best` `first` `ioc` `market-ioc` `best-ioc` `fok` `market-fok` `best-fok` `stop` `mid` `mid-ioc` `mid-fok`

---

## market - 시장 정보

### 순위

```bash
kiwoom market rank volume           # 거래량 상위
kiwoom market rank amount           # 거래대금 상위
kiwoom market rank change           # 등락률 상위
kiwoom market rank surge            # 가격 급등락
kiwoom market rank hot              # 실시간 조회 순위
kiwoom market rank limit            # 상하한가
kiwoom market rank foreign-period   # 외인 기간별 매매
kiwoom market rank foreign-inst     # 외국인/기관 매매
```

<details>
<summary>전체 rank 명령어 (28개)</summary>

`volume` `prev-volume` `amount` `change` `expected-change` `surge` `hot` `limit` `new-highlow` `near-highlow` `volume-surge` `orderbook-top` `orderbook-surge` `balance-rate-surge` `credit-ratio` `foreign-period` `foreign-consecutive` `foreign-exhaust` `foreign-broker` `foreign-inst` `investor-top` `broker-by-stock` `broker-top` `major-trader` `net-buyer` `top-exit` `same-net-trade` `afterhours-change`

</details>

### 업종 / 테마 / ETF / ELW / 금현물 / 프로그램

```bash
kiwoom market sector current 001        # 업종 현재가
kiwoom market sector index              # 전업종 지수
kiwoom market sector chart day 001 --date 20260301

kiwoom market theme groups              # 테마 그룹
kiwoom market theme stocks THEMA001     # 테마 구성종목

kiwoom market etf all                   # ETF 전체 시세
kiwoom market etf info 069500           # ETF 종목정보

kiwoom market elw detail 580001         # ELW 상세정보
kiwoom market elw search                # ELW 조건검색

kiwoom market gold price                # 금현물 시세
kiwoom market gold orderbook            # 금현물 호가

kiwoom market program time-trend --date 20260301
kiwoom market program stock-daily 005930
```

---

## stream - 실시간 스트리밍

WebSocket 실시간 시세. Ctrl+C로 종료.

```bash
kiwoom stream quote 005930              # 체결 실시간
kiwoom stream orderbook 005930          # 호가 실시간
kiwoom stream order                     # 주문체결 (계좌)
kiwoom stream balance                   # 잔고 변동 (계좌)
kiwoom stream vi 005930                 # VI 발동/해제
kiwoom stream multi 005930              # 체결+호가 동시
kiwoom stream quote 005930 000660 035420  # 복수 종목
kiwoom stream custom 0B,0D 005930       # 타입 직접 지정
kiwoom stream types                     # 타입 코드 목록
```

| 코드 | 명령 | 설명 |
|------|------|------|
| 00 | `order` | 주문체결 |
| 04 | `balance` | 잔고 |
| 0A | `price` | 주식기세 |
| 0B | `quote` | 주식체결 |
| 0C | `best-bid` | 우선호가 |
| 0D | `orderbook` | 호가잔량 |
| 0E | `after-hours` | 시간외호가 |
| 0F | `trader` | 당일거래원 |
| 0G | `etf-nav` | ETF NAV |
| 0H | `expected` | 예상체결 |
| 0I | `gold` | 국제금환산 |
| 0J | `sector-index` | 업종지수 |
| 0U | `sector-change` | 업종등락 |
| 0g | `stock-info` | 종목정보 |
| 0m | `elw-theory` | ELW 이론가 |
| 0s | `market-time` | 장시작시간 |
| 0u | `elw-indicator` | ELW 지표 |
| 0w | `program` | 프로그램매매 |
| 1h | `vi` | VI발동/해제 |

---

## Raw API

```bash
kiwoom api ka10001 '{"stk_cd":"005930"}'        # 테이블 출력
kiwoom api ka10001 '{"stk_cd":"005930"}' --raw   # JSON 원본
```

---

## dashboard - 대시보드

```bash
kiwoom dashboard                        # 계좌 요약 + 거래량 상위 한눈에
```

## 종목 비교

```bash
kiwoom stock compare 005930 000660      # 삼성전자 vs SK하이닉스
kiwoom stock compare 005930 000660 035420  # 3종목 비교
kiwoom -f json stock compare 005930 000660  # JSON 출력
```

---

## 출력 형식

모든 명령에 `-f` / `--format` 옵션 사용 가능:

```bash
kiwoom stock info 005930                # 기본: Rich 테이블
kiwoom -f json stock info 005930        # JSON (파이핑, AI 에이전트용)
kiwoom -f csv stock daily 005930        # CSV (엑셀, 데이터 분석용)
kiwoom --no-color stock info 005930     # 색상 없이 (파일 저장용)
```

```bash
# jq로 필터링
kiwoom -f json market rank volume | jq '.[].stk_nm'

# CSV를 파일로 저장
kiwoom -f csv stock daily 005930 > samsung_daily.csv
```

## Shell 자동완성

```bash
# Bash
eval "$(_KIWOOM_COMPLETE=bash_source kiwoom)"

# Zsh
eval "$(_KIWOOM_COMPLETE=zsh_source kiwoom)"

# Fish
eval (env _KIWOOM_COMPLETE=fish_source kiwoom)
```

## Exit Codes

| 코드 | 의미 |
|------|------|
| 0 | 성공 |
| 1 | 입력 오류 (잘못된 인자) |
| 2 | API/네트워크 오류 |
| 3 | 인증 필요 (토큰 만료) |

## 참고

| 항목 | 값 |
|------|------|
| 설정 파일 | `~/.kiwoom/config.toml` |
| 토큰 파일 | `~/.kiwoom/token` |
| 운영 도메인 | `https://api.kiwoom.com` |
| 모의투자 도메인 | `https://mockapi.kiwoom.com` |
| WebSocket | `wss://api.kiwoom.com:10000` |

- `kiwoom <명령> --help`로 상세 옵션 확인
- 모의투자 먼저 테스트: `kiwoom config domain mock`
- 연속조회(페이지네이션) 자동 처리
- 종목코드 6자리: `005930` (삼성전자)
- 금현물: `M04020000` (1kg), `M04020100` (미니 100g)

## License

MIT
