kwcli 0.1.0__tar.gz → 1.0.0__tar.gz

{kwcli-0.1.0 → kwcli-1.0.0}/LICENSE.md

@@ -33,4 +33,3 @@ All rights reserved. (모든 권리 보유)
    본 라이선스는 대한민국 법률에 따라 해석되며, 분쟁 발생 시 회사 본점
    소재지를 관할하는 법원을 제1심 관할 법원으로 합니다.
 
-문의: [키움증권 OpenAPI 담당 부서 / 연락처]

{kwcli-0.1.0 → kwcli-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kwcli
-Version: 0.1.0
+Version: 1.0.0
 Summary: Kiwoom OpenAPI toolkit
 License-File: LICENSE.md
 Requires-Python: >=3.13
@@ -18,16 +18,21 @@ Description-Content-Type: text/markdown
 작업을 수행해야 하는 사람과 AI 에이전트를 위한 **탐색(discovery) 중심**의 운영
 도구입니다.
 
-설치 후 사용하는 콘솔 명령은 `kiwoomcli` 입니다.
+배포 패키지 이름은 `kwcli` 이며, 설치 후 사용하는 콘솔 명령은 `kiwoomcli` 입니다.
+
+> **키움증권 공식 프로젝트**
+> 본 프로젝트는 **키움증권(Kiwoom Securities)이 공식적으로 제공·관리**하는 도구입니다.
+> PyPI 패키지 [`kwcli`](https://pypi.org/project/kwcli/)는 키움증권이 게시한 공식 배포본입니다.
+> 키움 REST API 공식 포털: <https://openapi.kiwoom.com> (API 가이드: <https://openapi.kiwoom.com/guide/apiguide>)
 
 ## 설치
 
 ```sh
-uv tool install kiwoomcli
+uv tool install kwcli
 # 또는
-pipx install kiwoomcli
+pipx install kwcli
 # 또는
-pip install kiwoomcli
+pip install kwcli
 ```
 
 설치한 뒤 계정과 자격 증명을 초기화합니다.
@@ -47,6 +52,7 @@ kiwoomcli setup                                   # 온보딩: 별칭, demo/real
 kiwoomcli spec search "체결"                       # 필요한 API/명령 찾기
 kiwoomcli domestic stocks info --code 005930 -h   # 매핑된 계약 확인
 kiwoomcli domestic stocks info --code 005930 --format json
+kiwoomcli overseas stocks info --exchange NASDAQ --code AAPL --format json
 kiwoomcli domestic orders buy --code 005930 --qty 1 --price 70000 --order-type limit --confirm
 ```
 
@@ -64,8 +70,9 @@ kiwoomcli domestic orders buy --code 005930 --qty 1 --price 70000 --order-type l
   현재 프로필), 프로필별 자격 증명/토큰 상태, 권장 조치를 보여줍니다.
 - `--profile NAME`은 저장된 계정 별칭(OS 자격 증명 저장소의 App Key / Secret)을
   사용합니다. `--mode demo|real`은 저장된 별칭을 쓰지 않으며, mode 단독 실행에는
-  `APP_KEY` / `APP_SECRET` 환경변수가 필요합니다. 자격 증명이 없을 때는 진입
-  방식에 맞는 해결책을 함께 안내합니다.
+  환경변수가 필요합니다. 이때 환경변수 이름은 모드별로 다릅니다 —
+  `real`은 `APP_KEY` / `APP_SECRET`, `demo`는 `APP_KEY_MOCK` / `APP_SECRET_MOCK`.
+  자격 증명이 없을 때는 진입 방식에 맞는 해결책을 함께 안내합니다.
 
 자주 쓰는 인증 명령:
 
@@ -75,14 +82,19 @@ kiwoomcli auth list
 kiwoomcli auth switch <alias>
 kiwoomcli auth status [--profile NAME | --mode demo|real]
 kiwoomcli auth refresh [--profile NAME | --mode demo|real]
+kiwoomcli auth revoke [--profile NAME | --mode demo|real]
 kiwoomcli auth clear [--profile NAME | --mode demo|real] [--all]
 kiwoomcli auth remove <alias>
+kiwoomcli auth export [--profile NAME | --mode demo|real] [--dir DIR] [--yes]
 ```
 
 - `auth clear`는 비밀 정보만 삭제합니다(기본은 토큰 캐시, `--all`을 주면 OS에
   저장된 App Key / Secret까지). 별칭 등록 자체는 유지됩니다.
 - `auth remove <alias>`는 계정을 완전히 등록 해제합니다(프로필 항목, 토큰 캐시,
   저장된 자격 증명 모두).
+- `auth revoke`는 서버에서 현재 토큰을 폐기하고 로컬 토큰 캐시도 삭제합니다.
+- `auth export`는 저장된 App Key/Secret을 화면에 출력하지 않고 `.env` 파일로
+  내보냅니다. 비대화형 환경에서는 `--yes`가 필요합니다.
 
 ## 명령 그룹
 
@@ -111,11 +123,35 @@ kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
 | `investors` | `kiwoomcli domestic investors by-stock --code 005930` |
 | `short-selling` | `kiwoomcli domestic short-selling trend --code 005930 --from 20260101 --to 20260529` |
 | `securities-lending` | `kiwoomcli domestic securities-lending by-stock --code 005930` |
-| `themes` | `kiwoomcli domestic themes by-stock --code 005930 --exchange KRX` |
+| `themes` | `kiwoomcli domestic themes by-stock --code <테마그룹코드> --exchange KRX` |
 | `accounts` | `kiwoomcli domestic accounts holdings --basis total --exchange KRX` |
 | `orders` | `kiwoomcli domestic orders list-open --stock-scope all --side all --exchange ALL` |
 | `streams` | `kiwoomcli domestic streams trades --code 005930 --count 1` |
 
+미국주식 리소스는 `overseas` 아래에서 제공합니다.
+
+| 그룹 | 예시 |
+| --- | --- |
+| `stocks` | `kiwoomcli overseas stocks info --exchange NASDAQ --code AAPL` |
+| `quotes` | `kiwoomcli overseas quotes info --exchange NASDAQ --code AAPL` |
+| `orderbooks` | `kiwoomcli overseas orderbooks list --exchange NASDAQ --code AAPL` |
+| `candles` | `kiwoomcli overseas candles stock-daily --exchange NASDAQ --code AAPL` |
+| `rankings` | `kiwoomcli overseas rankings today-volume-top --exchange nasdaq` |
+| `sectors` | `kiwoomcli overseas sectors period-returns --exchange NASDAQ` |
+| `investment-info` | `kiwoomcli overseas investment-info research --kind stock` |
+| `accounts` | `kiwoomcli overseas accounts balance --exchange NASDAQ` |
+| `orders` | `kiwoomcli overseas orders orderable-quantity --exchange NASDAQ --code AAPL --price 150` |
+| `exchange` | `kiwoomcli overseas exchange rate --direction krw-to-usd` |
+| `streams` | `kiwoomcli overseas streams trades --exchange NASDAQ --code AAPL --count 1` |
+
+전체 API 337개(OAuth 2, 국내주식 206, 미국주식 129)가 로컬 스펙과 CLI
+맵에 포함됩니다. 정확한 옵션은 각 명령의 `-h` 출력으로 확인하세요.
+
+미국주식 `--exchange` 값의 대소문자는 명령별 API 계약을 따릅니다. 종목·시세·
+호가·캔들·계좌·스트림은 `AMEX|NASDAQ|NYSE`, 순위는
+`all|nyse|nasdaq|amex`, 업종의 `period-returns`는
+`ALL|NYSE|AMEX|NASDAQ`을 사용합니다. 항상 해당 명령의 `-h`를 확인하세요.
+
 ## 출력 형식
 
 도메인 명령은 `--format`과 프로필/모드 선택자를 받습니다.
@@ -124,12 +160,16 @@ kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
 --format pretty|json|jsonl|yaml
 --profile NAME
 --mode demo|real
+--pages N
 ```
 
 - `pretty`(기본값)는 사람이 읽기 좋은 들여쓰기 형식입니다.
 - `json`은 에이전트가 파싱하기 좋은 한 줄 압축 출력입니다.
 - `jsonl`은 한 줄에 JSON 레코드 하나씩 출력합니다(목록 행이나 스트림에 유용).
 - `yaml`은 YAML 형식으로 출력합니다.
+- `--pages`는 REST 연속조회 페이지 수입니다. 기본값은 1이며, 0은 서버가
+  제공하는 모든 페이지를 조회합니다. `spec` 명령에는 적용되지 않습니다.
+- REST 명령의 `--named`는 응답 필드 코드를 스펙의 한글명으로 변환합니다.
 
 안전장치가 적용된 계좌/주문 조회와 스트림에서는 출력 계층이 계좌 식별자를
 마스킹합니다. 다만 주문번호(`ord_no`, `orig_ord_no` 등)는 `orders modify`/`cancel`
@@ -143,13 +183,14 @@ kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
 
 ```sh
 kiwoomcli domestic streams trades --code 005930 --count 1 --named --format json
+kiwoomcli overseas streams trades --exchange NASDAQ --code AAPL --count 1 --named --format json
 ```
 
 - `--count`는 `REAL` 데이터 메시지만 셉니다. `REG`/`REMOVE`/`SYSTEM`은 제어
   메시지입니다.
 - `--check`는 유한한 등록/수집을 수행하며, `REAL` 틱이 오지 않아도 정상 종료
   합니다.
-- `--named`는 패키지에 포함된 키움 스펙 기반 내장 스키마로 `REAL` 프레임을
+- 스트림 명령의 `--named`는 키움 스펙 기반 내장 스키마로 `REAL` 프레임 FID를
   변환합니다. 알 수 없는 FID는 `unknown` 아래에 보존됩니다.
 
 장시간 구독을 저장하려면 파일로 출력하고 OS 도구로 프로세스를 백그라운드로
@@ -171,12 +212,15 @@ Start-Process kiwoomcli -ArgumentList 'domestic streams trades --codes 005930,00
 
 ## 주문 안전장치
 
-주문 쓰기 명령(`orders buy/sell/modify/cancel`, `credit-*`, `gold-*`)에는
+국내·미국주식 주문 쓰기 명령(`orders buy/sell/modify/cancel`,
+`credit-*`, `gold-*`)과 미국주식 환전 신청(`overseas exchange request`)에는
 안전장치가 적용됩니다.
 
 - `--confirm`이 없으면 짧은 미전송 주문 요약을 출력하고 주문 API를 호출하지
   않습니다.
 - `--confirm`이 있으면 실제 엔드포인트로 전송합니다.
+- `overseas exchange request`도 `--confirm`이 없으면 미전송 환전 확인만
+  출력하며, `--confirm`이 있어야 실제 환전 API를 호출합니다.
 - 주문 유형별 가격 규칙은 전송 경로 이전에 검증됩니다. 예를 들어
   `--order-type limit`에는 `--price`가 필요하고, `--order-type market`에는
   `--price`를 넣으면 안 됩니다. 잘못된 주문 식별자는 전송 전에 보고됩니다.
@@ -190,13 +234,13 @@ Start-Process kiwoomcli -ArgumentList 'domestic streams trades --codes 005930,00
 
 | 개념 | 옵션 | 예시 |
 | --- | --- | --- |
-| 종목/주식/업종/ETF/ELW 코드 | `--code`, `-c` | `--code 005930` |
+| 종목/주식/업종/ETF/ELW 코드 | `--code` | `--code 005930` |
 | 인증 프로필 | `--profile` | `--profile demo-main` |
 | 실행 모드 | `--mode` | `--mode demo` |
 | 시장/거래소 선택 | `--market` | `--market kospi` |
 | 수량 | `--qty` | `--qty 10` |
 | 가격 | `--price` | `--price 70000` |
-| 매수/매도 구분 | `--side` | `--side buy` |
+| 매수/매도 구분 | `--side` | 명령별 값은 `-h`에서 확인 |
 | 주문 유형 | `--order-type` | `--order-type limit` |
 | 주문 식별자 | `--order-id` | `--order-id 123` |
 | 시작 / 종료 일자 | `--from` / `--to` | `--from 20260101 --to 20260529` |

{kwcli-0.1.0 → kwcli-1.0.0}/README.md

@@ -5,16 +5,21 @@
 작업을 수행해야 하는 사람과 AI 에이전트를 위한 **탐색(discovery) 중심**의 운영
 도구입니다.
 
-설치 후 사용하는 콘솔 명령은 `kiwoomcli` 입니다.
+배포 패키지 이름은 `kwcli` 이며, 설치 후 사용하는 콘솔 명령은 `kiwoomcli` 입니다.
+
+> **키움증권 공식 프로젝트**
+> 본 프로젝트는 **키움증권(Kiwoom Securities)이 공식적으로 제공·관리**하는 도구입니다.
+> PyPI 패키지 [`kwcli`](https://pypi.org/project/kwcli/)는 키움증권이 게시한 공식 배포본입니다.
+> 키움 REST API 공식 포털: <https://openapi.kiwoom.com> (API 가이드: <https://openapi.kiwoom.com/guide/apiguide>)
 
 ## 설치
 
 ```sh
-uv tool install kiwoomcli
+uv tool install kwcli
 # 또는
-pipx install kiwoomcli
+pipx install kwcli
 # 또는
-pip install kiwoomcli
+pip install kwcli
 ```
 
 설치한 뒤 계정과 자격 증명을 초기화합니다.
@@ -34,6 +39,7 @@ kiwoomcli setup                                   # 온보딩: 별칭, demo/real
 kiwoomcli spec search "체결"                       # 필요한 API/명령 찾기
 kiwoomcli domestic stocks info --code 005930 -h   # 매핑된 계약 확인
 kiwoomcli domestic stocks info --code 005930 --format json
+kiwoomcli overseas stocks info --exchange NASDAQ --code AAPL --format json
 kiwoomcli domestic orders buy --code 005930 --qty 1 --price 70000 --order-type limit --confirm
 ```
 
@@ -51,8 +57,9 @@ kiwoomcli domestic orders buy --code 005930 --qty 1 --price 70000 --order-type l
   현재 프로필), 프로필별 자격 증명/토큰 상태, 권장 조치를 보여줍니다.
 - `--profile NAME`은 저장된 계정 별칭(OS 자격 증명 저장소의 App Key / Secret)을
   사용합니다. `--mode demo|real`은 저장된 별칭을 쓰지 않으며, mode 단독 실행에는
-  `APP_KEY` / `APP_SECRET` 환경변수가 필요합니다. 자격 증명이 없을 때는 진입
-  방식에 맞는 해결책을 함께 안내합니다.
+  환경변수가 필요합니다. 이때 환경변수 이름은 모드별로 다릅니다 —
+  `real`은 `APP_KEY` / `APP_SECRET`, `demo`는 `APP_KEY_MOCK` / `APP_SECRET_MOCK`.
+  자격 증명이 없을 때는 진입 방식에 맞는 해결책을 함께 안내합니다.
 
 자주 쓰는 인증 명령:
 
@@ -62,14 +69,19 @@ kiwoomcli auth list
 kiwoomcli auth switch <alias>
 kiwoomcli auth status [--profile NAME | --mode demo|real]
 kiwoomcli auth refresh [--profile NAME | --mode demo|real]
+kiwoomcli auth revoke [--profile NAME | --mode demo|real]
 kiwoomcli auth clear [--profile NAME | --mode demo|real] [--all]
 kiwoomcli auth remove <alias>
+kiwoomcli auth export [--profile NAME | --mode demo|real] [--dir DIR] [--yes]
 ```
 
 - `auth clear`는 비밀 정보만 삭제합니다(기본은 토큰 캐시, `--all`을 주면 OS에
   저장된 App Key / Secret까지). 별칭 등록 자체는 유지됩니다.
 - `auth remove <alias>`는 계정을 완전히 등록 해제합니다(프로필 항목, 토큰 캐시,
   저장된 자격 증명 모두).
+- `auth revoke`는 서버에서 현재 토큰을 폐기하고 로컬 토큰 캐시도 삭제합니다.
+- `auth export`는 저장된 App Key/Secret을 화면에 출력하지 않고 `.env` 파일로
+  내보냅니다. 비대화형 환경에서는 `--yes`가 필요합니다.
 
 ## 명령 그룹
 
@@ -98,11 +110,35 @@ kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
 | `investors` | `kiwoomcli domestic investors by-stock --code 005930` |
 | `short-selling` | `kiwoomcli domestic short-selling trend --code 005930 --from 20260101 --to 20260529` |
 | `securities-lending` | `kiwoomcli domestic securities-lending by-stock --code 005930` |
-| `themes` | `kiwoomcli domestic themes by-stock --code 005930 --exchange KRX` |
+| `themes` | `kiwoomcli domestic themes by-stock --code <테마그룹코드> --exchange KRX` |
 | `accounts` | `kiwoomcli domestic accounts holdings --basis total --exchange KRX` |
 | `orders` | `kiwoomcli domestic orders list-open --stock-scope all --side all --exchange ALL` |
 | `streams` | `kiwoomcli domestic streams trades --code 005930 --count 1` |
 
+미국주식 리소스는 `overseas` 아래에서 제공합니다.
+
+| 그룹 | 예시 |
+| --- | --- |
+| `stocks` | `kiwoomcli overseas stocks info --exchange NASDAQ --code AAPL` |
+| `quotes` | `kiwoomcli overseas quotes info --exchange NASDAQ --code AAPL` |
+| `orderbooks` | `kiwoomcli overseas orderbooks list --exchange NASDAQ --code AAPL` |
+| `candles` | `kiwoomcli overseas candles stock-daily --exchange NASDAQ --code AAPL` |
+| `rankings` | `kiwoomcli overseas rankings today-volume-top --exchange nasdaq` |
+| `sectors` | `kiwoomcli overseas sectors period-returns --exchange NASDAQ` |
+| `investment-info` | `kiwoomcli overseas investment-info research --kind stock` |
+| `accounts` | `kiwoomcli overseas accounts balance --exchange NASDAQ` |
+| `orders` | `kiwoomcli overseas orders orderable-quantity --exchange NASDAQ --code AAPL --price 150` |
+| `exchange` | `kiwoomcli overseas exchange rate --direction krw-to-usd` |
+| `streams` | `kiwoomcli overseas streams trades --exchange NASDAQ --code AAPL --count 1` |
+
+전체 API 337개(OAuth 2, 국내주식 206, 미국주식 129)가 로컬 스펙과 CLI
+맵에 포함됩니다. 정확한 옵션은 각 명령의 `-h` 출력으로 확인하세요.
+
+미국주식 `--exchange` 값의 대소문자는 명령별 API 계약을 따릅니다. 종목·시세·
+호가·캔들·계좌·스트림은 `AMEX|NASDAQ|NYSE`, 순위는
+`all|nyse|nasdaq|amex`, 업종의 `period-returns`는
+`ALL|NYSE|AMEX|NASDAQ`을 사용합니다. 항상 해당 명령의 `-h`를 확인하세요.
+
 ## 출력 형식
 
 도메인 명령은 `--format`과 프로필/모드 선택자를 받습니다.
@@ -111,12 +147,16 @@ kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
 --format pretty|json|jsonl|yaml
 --profile NAME
 --mode demo|real
+--pages N
 ```
 
 - `pretty`(기본값)는 사람이 읽기 좋은 들여쓰기 형식입니다.
 - `json`은 에이전트가 파싱하기 좋은 한 줄 압축 출력입니다.
 - `jsonl`은 한 줄에 JSON 레코드 하나씩 출력합니다(목록 행이나 스트림에 유용).
 - `yaml`은 YAML 형식으로 출력합니다.
+- `--pages`는 REST 연속조회 페이지 수입니다. 기본값은 1이며, 0은 서버가
+  제공하는 모든 페이지를 조회합니다. `spec` 명령에는 적용되지 않습니다.
+- REST 명령의 `--named`는 응답 필드 코드를 스펙의 한글명으로 변환합니다.
 
 안전장치가 적용된 계좌/주문 조회와 스트림에서는 출력 계층이 계좌 식별자를
 마스킹합니다. 다만 주문번호(`ord_no`, `orig_ord_no` 등)는 `orders modify`/`cancel`
@@ -130,13 +170,14 @@ kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
 
 ```sh
 kiwoomcli domestic streams trades --code 005930 --count 1 --named --format json
+kiwoomcli overseas streams trades --exchange NASDAQ --code AAPL --count 1 --named --format json
 ```
 
 - `--count`는 `REAL` 데이터 메시지만 셉니다. `REG`/`REMOVE`/`SYSTEM`은 제어
   메시지입니다.
 - `--check`는 유한한 등록/수집을 수행하며, `REAL` 틱이 오지 않아도 정상 종료
   합니다.
-- `--named`는 패키지에 포함된 키움 스펙 기반 내장 스키마로 `REAL` 프레임을
+- 스트림 명령의 `--named`는 키움 스펙 기반 내장 스키마로 `REAL` 프레임 FID를
   변환합니다. 알 수 없는 FID는 `unknown` 아래에 보존됩니다.
 
 장시간 구독을 저장하려면 파일로 출력하고 OS 도구로 프로세스를 백그라운드로
@@ -158,12 +199,15 @@ Start-Process kiwoomcli -ArgumentList 'domestic streams trades --codes 005930,00
 
 ## 주문 안전장치
 
-주문 쓰기 명령(`orders buy/sell/modify/cancel`, `credit-*`, `gold-*`)에는
+국내·미국주식 주문 쓰기 명령(`orders buy/sell/modify/cancel`,
+`credit-*`, `gold-*`)과 미국주식 환전 신청(`overseas exchange request`)에는
 안전장치가 적용됩니다.
 
 - `--confirm`이 없으면 짧은 미전송 주문 요약을 출력하고 주문 API를 호출하지
   않습니다.
 - `--confirm`이 있으면 실제 엔드포인트로 전송합니다.
+- `overseas exchange request`도 `--confirm`이 없으면 미전송 환전 확인만
+  출력하며, `--confirm`이 있어야 실제 환전 API를 호출합니다.
 - 주문 유형별 가격 규칙은 전송 경로 이전에 검증됩니다. 예를 들어
   `--order-type limit`에는 `--price`가 필요하고, `--order-type market`에는
   `--price`를 넣으면 안 됩니다. 잘못된 주문 식별자는 전송 전에 보고됩니다.
@@ -177,13 +221,13 @@ Start-Process kiwoomcli -ArgumentList 'domestic streams trades --codes 005930,00
 
 | 개념 | 옵션 | 예시 |
 | --- | --- | --- |
-| 종목/주식/업종/ETF/ELW 코드 | `--code`, `-c` | `--code 005930` |
+| 종목/주식/업종/ETF/ELW 코드 | `--code` | `--code 005930` |
 | 인증 프로필 | `--profile` | `--profile demo-main` |
 | 실행 모드 | `--mode` | `--mode demo` |
 | 시장/거래소 선택 | `--market` | `--market kospi` |
 | 수량 | `--qty` | `--qty 10` |
 | 가격 | `--price` | `--price 70000` |
-| 매수/매도 구분 | `--side` | `--side buy` |
+| 매수/매도 구분 | `--side` | 명령별 값은 `-h`에서 확인 |
 | 주문 유형 | `--order-type` | `--order-type limit` |
 | 주문 식별자 | `--order-id` | `--order-id 123` |
 | 시작 / 종료 일자 | `--from` / `--to` | `--from 20260101 --to 20260529` |