kwcli 1.0.0__tar.gz → 1.0.3__tar.gz

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: kwcli
-Version: 1.0.0
+Version: 1.0.3
 Summary: Kiwoom OpenAPI toolkit
 License-File: LICENSE.md
 Requires-Python: >=3.13
@@ -11,19 +11,13 @@ Requires-Dist: requests>=2.33.1
 Requires-Dist: websockets>=15.0.1
 Description-Content-Type: text/markdown
 
-# Kiwoom CLI
+# 키움증권 CLI (Kiwoom CLI)
 
-`kiwoomcli`는 키움증권 OpenAPI를 위한 커맨드라인 클라이언트입니다. 터미널에서
-키움 OpenAPI 데이터를 조회하고, 인증 상태를 관리하며, 안전장치가 적용된 주문
-작업을 수행해야 하는 사람과 AI 에이전트를 위한 **탐색(discovery) 중심**의 운영
-도구입니다.
+`kiwoomcli`는 키움증권 OpenAPI를 위한 커맨드라인 클라이언트입니다. 터미널에서 키움 OpenAPI 데이터를 조회하고, 인증 상태를 관리하며, 안전장치가 적용된 주문 작업을 수행해야 하는 사람과 AI 에이전트를 위한 **탐색(discovery) 중심**의 운영 도구입니다.
 
 배포 패키지 이름은 `kwcli` 이며, 설치 후 사용하는 콘솔 명령은 `kiwoomcli` 입니다.
 
-> **키움증권 공식 프로젝트**
-> 본 프로젝트는 **키움증권(Kiwoom Securities)이 공식적으로 제공·관리**하는 도구입니다.
-> PyPI 패키지 [`kwcli`](https://pypi.org/project/kwcli/)는 키움증권이 게시한 공식 배포본입니다.
-> 키움 REST API 공식 포털: <https://openapi.kiwoom.com> (API 가이드: <https://openapi.kiwoom.com/guide/apiguide>)
+> **키움증권 공식 프로젝트** 본 프로젝트는 **키움증권(Kiwoom Securities)이 공식적으로 제공·관리**하는 도구입니다. PyPI 패키지 [`kwcli`](https://pypi.org/project/kwcli/)는 키움증권이 게시한 공식 배포본입니다. 키움 REST API 공식 포털: <https://openapi.kiwoom.com> (API 가이드: <https://openapi.kiwoom.com/guide/apiguide>)
 
 ## 설치
 
@@ -43,9 +37,7 @@ kiwoomcli setup
 
 ## 빠른 시작
 
-일상적인 흐름은 **먼저 탐색하고, 그다음 명령 하나를 실행**하는 것입니다. 어떤
-명령이든 `-h`를 붙이면 실시간으로 매핑된 계약 정보(요약 / 동작 / 예시 / OpenAPI
-매핑)를 볼 수 있습니다.
+일상적인 흐름은 **먼저 탐색하고, 그다음 명령 하나를 실행**하는 것입니다. 어떤 명령이든 `-h`를 붙이면 실시간으로 매핑된 계약 정보(요약 / 동작 / 예시 / OpenAPI 매핑)를 볼 수 있습니다.
 
 ```sh
 kiwoomcli setup                                   # 온보딩: 별칭, demo/real, 키, 검증
@@ -60,19 +52,9 @@ kiwoomcli domestic orders buy --code 005930 --qty 1 --price 70000 --order-type l
 
 ## 인증과 프로필
 
-- `kiwoomcli setup`은 온보딩 초기화 명령입니다. 환경 사전 점검(OS 자격 증명
-  저장소 사용 가능 여부와 PATH 모호성 경고)을 수행하고, 계정 별칭을 만들며,
-  `demo`/`real`을 선택하고, App Key / Secret을 저장한 뒤, 안전한 읽기 전용
-  호출로 검증하고, 현재 프로필을 지정한 다음 준비 상태 요약을 출력합니다.
-  비대화형 셸에서는 멈추지 않고 안내 메시지와 함께 실패합니다(`--mode` 전달).
-- `kiwoomcli doctor`는 읽기 전용 진단 명령입니다. 어떤 인증 컨텍스트가
-  선택됐는지(우선순위 `--profile`/`KIWOOM_PROFILE` > `--mode`/`KIWOOM_MODE` >
-  현재 프로필), 프로필별 자격 증명/토큰 상태, 권장 조치를 보여줍니다.
-- `--profile NAME`은 저장된 계정 별칭(OS 자격 증명 저장소의 App Key / Secret)을
-  사용합니다. `--mode demo|real`은 저장된 별칭을 쓰지 않으며, mode 단독 실행에는
-  환경변수가 필요합니다. 이때 환경변수 이름은 모드별로 다릅니다 —
-  `real`은 `APP_KEY` / `APP_SECRET`, `demo`는 `APP_KEY_MOCK` / `APP_SECRET_MOCK`.
-  자격 증명이 없을 때는 진입 방식에 맞는 해결책을 함께 안내합니다.
+- `kiwoomcli setup`은 온보딩 초기화 명령입니다. 환경을 먼저 점검(OS 자격 증명 저장소 사용 가능 여부, PATH 중복 경고)한 뒤, 계정 별칭 입력 → `demo`/`real` 선택 → App Key/Secret 저장 → 안전한 읽기 전용 호출로 검증 → 현재 프로필 지정 순서로 진행하고, 마지막에 준비 상태 요약을 보여줍니다. 비대화형 셸에서는 멈추지 않고 안내 메시지와 함께 실패합니다(`--mode` 전달).
+- `kiwoomcli doctor`는 읽기 전용 진단 명령입니다. 어떤 인증 컨텍스트가 선택됐는지(우선순위 `--profile`/`KIWOOM_PROFILE` > `--mode`/`KIWOOM_MODE` > 현재 프로필), 프로필별 자격 증명/토큰 상태, 권장 조치를 보여줍니다.
+- `--profile NAME`은 저장된 계정 별칭(OS 자격 증명 저장소의 App Key / Secret)을 사용합니다. `--mode demo|real`은 저장된 별칭을 쓰지 않으며, mode 단독 실행에는 환경변수가 필요합니다. 이때 환경변수 이름은 모드별로 다릅니다 — `real`은 `APP_KEY` / `APP_SECRET`, `demo`는 `APP_KEY_MOCK` / `APP_SECRET_MOCK`. 자격 증명이 없을 때는 진입 방식에 맞는 해결책을 함께 안내합니다.
 
 자주 쓰는 인증 명령:
 
@@ -88,13 +70,10 @@ 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 clear`는 비밀 정보만 삭제합니다(기본은 토큰 캐시, `--all`을 주면 OS에 저장된 App Key / Secret까지). 별칭 등록 자체는 유지됩니다.
+- `auth remove <alias>`는 계정을 완전히 등록 해제합니다(프로필 항목, 토큰 캐시, 저장된 자격 증명 모두).
 - `auth revoke`는 서버에서 현재 토큰을 폐기하고 로컬 토큰 캐시도 삭제합니다.
-- `auth export`는 저장된 App Key/Secret을 화면에 출력하지 않고 `.env` 파일로
-  내보냅니다. 비대화형 환경에서는 `--yes`가 필요합니다.
+- `auth export`는 저장된 App Key/Secret을 화면에 출력하지 않고 `.env` 파일로 내보냅니다. 비대화형 환경에서는 `--yes`가 필요합니다.
 
 ## 명령 그룹
 
@@ -107,8 +86,7 @@ kiwoomcli spec groups [--format pretty|json|yaml]
 kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
 ```
 
-국내 리소스 명령은 주제별 그룹으로 나뉩니다. 대표 예시는 아래와 같습니다(어떤
-명령이든 `-h`를 붙이면 전체 옵션 계약을 볼 수 있습니다).
+국내 리소스 명령은 주제별 그룹으로 나뉩니다. 대표 예시는 아래와 같습니다(어떤 명령이든 `-h`를 붙이면 전체 옵션 계약을 볼 수 있습니다).
 
 | 그룹 | 예시 |
 | --- | --- |
@@ -144,13 +122,9 @@ kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
 | `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` 출력으로 확인하세요.
+전체 API 337개(OAuth 2, 국내주식 206, 미국주식 129)가 로컬 스펙과 CLI 맵에 포함됩니다. 정확한 옵션은 각 명령의 `-h` 출력으로 확인하세요.
 
-미국주식 `--exchange` 값의 대소문자는 명령별 API 계약을 따릅니다. 종목·시세·
-호가·캔들·계좌·스트림은 `AMEX|NASDAQ|NYSE`, 순위는
-`all|nyse|nasdaq|amex`, 업종의 `period-returns`는
-`ALL|NYSE|AMEX|NASDAQ`을 사용합니다. 항상 해당 명령의 `-h`를 확인하세요.
+미국주식 `--exchange` 값의 대소문자는 명령별 API 계약을 따릅니다. 종목·시세· 호가·캔들·계좌·스트림은 `AMEX|NASDAQ|NYSE`, 순위는 `all|nyse|nasdaq|amex`, 업종의 `period-returns`는 `ALL|NYSE|AMEX|NASDAQ`을 사용합니다. 항상 해당 명령의 `-h`를 확인하세요.
 
 ## 출력 형식
 
@@ -167,34 +141,25 @@ kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
 - `json`은 에이전트가 파싱하기 좋은 한 줄 압축 출력입니다.
 - `jsonl`은 한 줄에 JSON 레코드 하나씩 출력합니다(목록 행이나 스트림에 유용).
 - `yaml`은 YAML 형식으로 출력합니다.
-- `--pages`는 REST 연속조회 페이지 수입니다. 기본값은 1이며, 0은 서버가
-  제공하는 모든 페이지를 조회합니다. `spec` 명령에는 적용되지 않습니다.
+- `--pages`는 REST 연속조회 페이지 수입니다. 기본값은 1이며, 0은 서버가 제공하는 모든 페이지를 조회합니다. `spec` 명령에는 적용되지 않습니다.
 - REST 명령의 `--named`는 응답 필드 코드를 스펙의 한글명으로 변환합니다.
 
-안전장치가 적용된 계좌/주문 조회와 스트림에서는 출력 계층이 계좌 식별자를
-마스킹합니다. 다만 주문번호(`ord_no`, `orig_ord_no` 등)는 `orders modify`/`cancel`
-에 필요하므로 **마스킹하지 않습니다**. 마스킹은 `pretty`, `json`, `jsonl`, `yaml`
-전반에서 동일하게 적용됩니다.
+안전장치가 적용된 계좌/주문 조회와 스트림에서는 출력 계층이 계좌 식별자를 마스킹합니다. 다만 주문번호(`ord_no`, `orig_ord_no` 등)는 `orders modify`/`cancel` 에 필요하므로 **마스킹하지 않습니다**. 마스킹은 `pretty`, `json`, `jsonl`, `yaml` 전반에서 동일하게 적용됩니다.
 
 ## 스트리밍 (WebSocket)
 
-스트림 명령은 포그라운드에서 실행되며 키움 서버 메시지를 출력합니다. 유한한
-실행을 원하면 `--count`/`--duration`을 사용하세요.
+스트림 명령은 포그라운드에서 실행되며 키움 서버 메시지를 출력합니다. 유한한 실행을 원하면 `--count`/`--duration`을 사용하세요.
 
 ```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` 프레임 FID를
-  변환합니다. 알 수 없는 FID는 `unknown` 아래에 보존됩니다.
+- `--count`는 `REAL` 데이터 메시지만 셉니다. `REG`/`REMOVE`/`SYSTEM`은 제어 메시지입니다.
+- `--check`는 유한한 등록/수집을 수행하며, `REAL` 틱이 오지 않아도 정상 종료합니다.
+- 스트림 명령의 `--named`는 키움 스펙 기반 내장 스키마로 `REAL` 프레임 FID를 변환합니다. 알 수 없는 FID는 `unknown` 아래에 보존됩니다.
 
-장시간 구독을 저장하려면 파일로 출력하고 OS 도구로 프로세스를 백그라운드로
-돌리세요(CLI는 자체 작업 관리자를 제공하지 않습니다).
+장시간 구독을 저장하려면 파일로 출력하고 OS 도구로 프로세스를 백그라운드로 돌리세요(CLI는 자체 작업 관리자를 제공하지 않습니다).
 
 ```sh
 # 계속 수신하며 이벤트를 파일에 추가 기록
@@ -207,30 +172,21 @@ nohup kiwoomcli domestic streams trades --codes 005930,000660 --watch --output t
 Start-Process kiwoomcli -ArgumentList 'domestic streams trades --codes 005930,000660 --watch --output trades.jsonl'
 ```
 
-조건검색식의 생성과 수정은 키움 영웅문 HTS에서 합니다. CLI는 HTS에 이미 저장된
-조건식을 목록 조회, 선택, 조회, 구독, 해제만 합니다.
+조건검색식의 생성과 수정은 키움 영웅문 HTS에서 합니다. CLI는 HTS에 이미 저장된 조건식을 목록 조회, 선택, 조회, 구독, 해제만 합니다.
 
 ## 주문 안전장치
 
-국내·미국주식 주문 쓰기 명령(`orders buy/sell/modify/cancel`,
-`credit-*`, `gold-*`)과 미국주식 환전 신청(`overseas exchange request`)에는
-안전장치가 적용됩니다.
+국내·미국주식 주문 쓰기 명령(`orders buy/sell/modify/cancel`, `credit-*`, `gold-*`)과 미국주식 환전 신청(`overseas exchange request`)에는 안전장치가 적용됩니다.
 
-- `--confirm`이 없으면 짧은 미전송 주문 요약을 출력하고 주문 API를 호출하지
-  않습니다.
+- `--confirm`이 없으면 짧은 미전송 주문 요약을 출력하고 주문 API를 호출하지 않습니다.
 - `--confirm`이 있으면 실제 엔드포인트로 전송합니다.
-- `overseas exchange request`도 `--confirm`이 없으면 미전송 환전 확인만
-  출력하며, `--confirm`이 있어야 실제 환전 API를 호출합니다.
-- 주문 유형별 가격 규칙은 전송 경로 이전에 검증됩니다. 예를 들어
-  `--order-type limit`에는 `--price`가 필요하고, `--order-type market`에는
-  `--price`를 넣으면 안 됩니다. 잘못된 주문 식별자는 전송 전에 보고됩니다.
-- 주문 쓰기는 `--profile`/`--mode`로 인증 대상을 선택합니다. 먼저 데모(모의투자)
-  서버에서 검증하세요.
+- `overseas exchange request`도 `--confirm`이 없으면 미전송 환전 확인만 출력하며, `--confirm`이 있어야 실제 환전 API를 호출합니다.
+- 주문 유형별 가격 규칙은 전송 경로 이전에 검증됩니다. 예를 들어 `--order-type limit`에는 `--price`가 필요하고, `--order-type market`에는 `--price`를 넣으면 안 됩니다. 잘못된 주문 식별자는 전송 전에 보고됩니다.
+- 주문 쓰기는 `--profile`/`--mode`로 인증 대상을 선택합니다. 먼저 데모(모의투자) 서버에서 검증하세요.
 
 ## 용어
 
-안정적인 사용자 대상 옵션 이름이 키움 원본 필드명을 숨깁니다. 구체적인 코드
-종류는 명령 맥락에 따라 결정됩니다.
+각 옵션 이름은 키움 원본 필드명 대신 안정적인 사용자 대상 이름으로 노출됩니다. 구체적으로 어떤 코드를 넣어야 하는지는 명령마다 다릅니다.
 
 | 개념 | 옵션 | 예시 |
 | --- | --- | --- |
@@ -253,7 +209,16 @@ Start-Process kiwoomcli -ArgumentList 'domestic streams trades --codes 005930,00
 ## 안전 유의사항
 
 - 개발과 검증 단계에서는 `demo` 모드를 우선 사용하세요.
-- 자격 증명, 토큰, 계좌번호, 정제되지 않은 실제 호출 출력은 절대 로그로 남기거나
-  커밋하지 마세요.
-- 자격 증명·네트워크·계좌 안전 제약으로 실제 호출이 막히면, CLI는 결과를
-  지어내지 않고 차단됨/미실행으로 보고합니다.
+- 자격 증명, 토큰, 계좌번호, 정제되지 않은 실제 호출 출력은 절대 로그로 남기거나 커밋하지 마세요.
+- 자격 증명·네트워크·계좌 안전 제약으로 실제 호출이 막히면, CLI는 결과를 지어내지 않고 차단됨/미실행으로 보고합니다.
+
+## 알려진 제약
+
+- 국내 주문 취소(`domestic orders cancel`)는 `--qty`로 수량 일부만 취소할 수 있지만, 해외 주문 취소(`overseas orders cancel`)는 **전량만** 가능합니다. 해외 주문 정정(`overseas orders modify`)은 수량은 바꿀 수 없고 **가격만** 바꿀 수 있습니다(원주문이 STOP 주문이면 `--stop-price` 필수).
+- `domestic orders list-open`의 `--exchange`는 주문용 값인 `SOR`을 받지 않습니다 — `ALL`로 조회하세요. `overseas accounts open-orders`는 `--exchange`를 `--code` 없이 받지 않습니다(서버 제약) — 종목을 지정하지 않는 미체결 조회는 거래소 없이 전체로 조회하세요.
+- 너무 짧은 간격으로 연속 조회하면 유량 제한(429) 오류가 날 수 있습니다. 반복 호출에는 간격을 두세요.
+- 모의투자(demo) 계좌에서는 환율 조회, 주문가능금액 조회가 거절됩니다(실전 계좌에서만 가능).
+- 계좌마다 거래할 수 있는 시장이 다를 수 있습니다. 해당 계좌가 다루지 않는 시장은 주문이 거절되거나 조회 결과가 오류 없이 빈 목록으로 돌아올 수 있으므로, 결과가 비어 있다면 먼저 `--profile`/`--mode`로 선택한 계좌를 확인하세요. 장 운영 시간이 아닐 때 국내 주문을 시도하면 이와는 다른 이유(장 종료)로 거절됩니다.
+- 현재가 조회(`domestic quotes price`) 응답에는 전일대비 값이 직접 포함되어 있지 않습니다 — 현재가와 전일 종가의 차이로 직접 계산해야 합니다.
+- `auth list`/`auth status`는 `--format json`을 지원하지 않고 사람이 읽는 텍스트만 출력합니다.
+- 일부 계좌 조회 명령(`accounts valuation`/`accounts holdings`)에는 `--named`가 없어, 응답 필드가 키움 원본 코드로 나옵니다.

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

@@ -1,16 +1,10 @@
-# Kiwoom CLI
+# 키움증권 CLI (Kiwoom CLI)
 
-`kiwoomcli`는 키움증권 OpenAPI를 위한 커맨드라인 클라이언트입니다. 터미널에서
-키움 OpenAPI 데이터를 조회하고, 인증 상태를 관리하며, 안전장치가 적용된 주문
-작업을 수행해야 하는 사람과 AI 에이전트를 위한 **탐색(discovery) 중심**의 운영
-도구입니다.
+`kiwoomcli`는 키움증권 OpenAPI를 위한 커맨드라인 클라이언트입니다. 터미널에서 키움 OpenAPI 데이터를 조회하고, 인증 상태를 관리하며, 안전장치가 적용된 주문 작업을 수행해야 하는 사람과 AI 에이전트를 위한 **탐색(discovery) 중심**의 운영 도구입니다.
 
 배포 패키지 이름은 `kwcli` 이며, 설치 후 사용하는 콘솔 명령은 `kiwoomcli` 입니다.
 
-> **키움증권 공식 프로젝트**
-> 본 프로젝트는 **키움증권(Kiwoom Securities)이 공식적으로 제공·관리**하는 도구입니다.
-> PyPI 패키지 [`kwcli`](https://pypi.org/project/kwcli/)는 키움증권이 게시한 공식 배포본입니다.
-> 키움 REST API 공식 포털: <https://openapi.kiwoom.com> (API 가이드: <https://openapi.kiwoom.com/guide/apiguide>)
+> **키움증권 공식 프로젝트** 본 프로젝트는 **키움증권(Kiwoom Securities)이 공식적으로 제공·관리**하는 도구입니다. PyPI 패키지 [`kwcli`](https://pypi.org/project/kwcli/)는 키움증권이 게시한 공식 배포본입니다. 키움 REST API 공식 포털: <https://openapi.kiwoom.com> (API 가이드: <https://openapi.kiwoom.com/guide/apiguide>)
 
 ## 설치
 
@@ -30,9 +24,7 @@ kiwoomcli setup
 
 ## 빠른 시작
 
-일상적인 흐름은 **먼저 탐색하고, 그다음 명령 하나를 실행**하는 것입니다. 어떤
-명령이든 `-h`를 붙이면 실시간으로 매핑된 계약 정보(요약 / 동작 / 예시 / OpenAPI
-매핑)를 볼 수 있습니다.
+일상적인 흐름은 **먼저 탐색하고, 그다음 명령 하나를 실행**하는 것입니다. 어떤 명령이든 `-h`를 붙이면 실시간으로 매핑된 계약 정보(요약 / 동작 / 예시 / OpenAPI 매핑)를 볼 수 있습니다.
 
 ```sh
 kiwoomcli setup                                   # 온보딩: 별칭, demo/real, 키, 검증
@@ -47,19 +39,9 @@ kiwoomcli domestic orders buy --code 005930 --qty 1 --price 70000 --order-type l
 
 ## 인증과 프로필
 
-- `kiwoomcli setup`은 온보딩 초기화 명령입니다. 환경 사전 점검(OS 자격 증명
-  저장소 사용 가능 여부와 PATH 모호성 경고)을 수행하고, 계정 별칭을 만들며,
-  `demo`/`real`을 선택하고, App Key / Secret을 저장한 뒤, 안전한 읽기 전용
-  호출로 검증하고, 현재 프로필을 지정한 다음 준비 상태 요약을 출력합니다.
-  비대화형 셸에서는 멈추지 않고 안내 메시지와 함께 실패합니다(`--mode` 전달).
-- `kiwoomcli doctor`는 읽기 전용 진단 명령입니다. 어떤 인증 컨텍스트가
-  선택됐는지(우선순위 `--profile`/`KIWOOM_PROFILE` > `--mode`/`KIWOOM_MODE` >
-  현재 프로필), 프로필별 자격 증명/토큰 상태, 권장 조치를 보여줍니다.
-- `--profile NAME`은 저장된 계정 별칭(OS 자격 증명 저장소의 App Key / Secret)을
-  사용합니다. `--mode demo|real`은 저장된 별칭을 쓰지 않으며, mode 단독 실행에는
-  환경변수가 필요합니다. 이때 환경변수 이름은 모드별로 다릅니다 —
-  `real`은 `APP_KEY` / `APP_SECRET`, `demo`는 `APP_KEY_MOCK` / `APP_SECRET_MOCK`.
-  자격 증명이 없을 때는 진입 방식에 맞는 해결책을 함께 안내합니다.
+- `kiwoomcli setup`은 온보딩 초기화 명령입니다. 환경을 먼저 점검(OS 자격 증명 저장소 사용 가능 여부, PATH 중복 경고)한 뒤, 계정 별칭 입력 → `demo`/`real` 선택 → App Key/Secret 저장 → 안전한 읽기 전용 호출로 검증 → 현재 프로필 지정 순서로 진행하고, 마지막에 준비 상태 요약을 보여줍니다. 비대화형 셸에서는 멈추지 않고 안내 메시지와 함께 실패합니다(`--mode` 전달).
+- `kiwoomcli doctor`는 읽기 전용 진단 명령입니다. 어떤 인증 컨텍스트가 선택됐는지(우선순위 `--profile`/`KIWOOM_PROFILE` > `--mode`/`KIWOOM_MODE` > 현재 프로필), 프로필별 자격 증명/토큰 상태, 권장 조치를 보여줍니다.
+- `--profile NAME`은 저장된 계정 별칭(OS 자격 증명 저장소의 App Key / Secret)을 사용합니다. `--mode demo|real`은 저장된 별칭을 쓰지 않으며, mode 단독 실행에는 환경변수가 필요합니다. 이때 환경변수 이름은 모드별로 다릅니다 — `real`은 `APP_KEY` / `APP_SECRET`, `demo`는 `APP_KEY_MOCK` / `APP_SECRET_MOCK`. 자격 증명이 없을 때는 진입 방식에 맞는 해결책을 함께 안내합니다.
 
 자주 쓰는 인증 명령:
 
@@ -75,13 +57,10 @@ 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 clear`는 비밀 정보만 삭제합니다(기본은 토큰 캐시, `--all`을 주면 OS에 저장된 App Key / Secret까지). 별칭 등록 자체는 유지됩니다.
+- `auth remove <alias>`는 계정을 완전히 등록 해제합니다(프로필 항목, 토큰 캐시, 저장된 자격 증명 모두).
 - `auth revoke`는 서버에서 현재 토큰을 폐기하고 로컬 토큰 캐시도 삭제합니다.
-- `auth export`는 저장된 App Key/Secret을 화면에 출력하지 않고 `.env` 파일로
-  내보냅니다. 비대화형 환경에서는 `--yes`가 필요합니다.
+- `auth export`는 저장된 App Key/Secret을 화면에 출력하지 않고 `.env` 파일로 내보냅니다. 비대화형 환경에서는 `--yes`가 필요합니다.
 
 ## 명령 그룹
 
@@ -94,8 +73,7 @@ kiwoomcli spec groups [--format pretty|json|yaml]
 kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
 ```
 
-국내 리소스 명령은 주제별 그룹으로 나뉩니다. 대표 예시는 아래와 같습니다(어떤
-명령이든 `-h`를 붙이면 전체 옵션 계약을 볼 수 있습니다).
+국내 리소스 명령은 주제별 그룹으로 나뉩니다. 대표 예시는 아래와 같습니다(어떤 명령이든 `-h`를 붙이면 전체 옵션 계약을 볼 수 있습니다).
 
 | 그룹 | 예시 |
 | --- | --- |
@@ -131,13 +109,9 @@ kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
 | `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` 출력으로 확인하세요.
+전체 API 337개(OAuth 2, 국내주식 206, 미국주식 129)가 로컬 스펙과 CLI 맵에 포함됩니다. 정확한 옵션은 각 명령의 `-h` 출력으로 확인하세요.
 
-미국주식 `--exchange` 값의 대소문자는 명령별 API 계약을 따릅니다. 종목·시세·
-호가·캔들·계좌·스트림은 `AMEX|NASDAQ|NYSE`, 순위는
-`all|nyse|nasdaq|amex`, 업종의 `period-returns`는
-`ALL|NYSE|AMEX|NASDAQ`을 사용합니다. 항상 해당 명령의 `-h`를 확인하세요.
+미국주식 `--exchange` 값의 대소문자는 명령별 API 계약을 따릅니다. 종목·시세· 호가·캔들·계좌·스트림은 `AMEX|NASDAQ|NYSE`, 순위는 `all|nyse|nasdaq|amex`, 업종의 `period-returns`는 `ALL|NYSE|AMEX|NASDAQ`을 사용합니다. 항상 해당 명령의 `-h`를 확인하세요.
 
 ## 출력 형식
 
@@ -154,34 +128,25 @@ kiwoomcli spec apis [--group <text>] [--limit N] [--format pretty|json|yaml]
 - `json`은 에이전트가 파싱하기 좋은 한 줄 압축 출력입니다.
 - `jsonl`은 한 줄에 JSON 레코드 하나씩 출력합니다(목록 행이나 스트림에 유용).
 - `yaml`은 YAML 형식으로 출력합니다.
-- `--pages`는 REST 연속조회 페이지 수입니다. 기본값은 1이며, 0은 서버가
-  제공하는 모든 페이지를 조회합니다. `spec` 명령에는 적용되지 않습니다.
+- `--pages`는 REST 연속조회 페이지 수입니다. 기본값은 1이며, 0은 서버가 제공하는 모든 페이지를 조회합니다. `spec` 명령에는 적용되지 않습니다.
 - REST 명령의 `--named`는 응답 필드 코드를 스펙의 한글명으로 변환합니다.
 
-안전장치가 적용된 계좌/주문 조회와 스트림에서는 출력 계층이 계좌 식별자를
-마스킹합니다. 다만 주문번호(`ord_no`, `orig_ord_no` 등)는 `orders modify`/`cancel`
-에 필요하므로 **마스킹하지 않습니다**. 마스킹은 `pretty`, `json`, `jsonl`, `yaml`
-전반에서 동일하게 적용됩니다.
+안전장치가 적용된 계좌/주문 조회와 스트림에서는 출력 계층이 계좌 식별자를 마스킹합니다. 다만 주문번호(`ord_no`, `orig_ord_no` 등)는 `orders modify`/`cancel` 에 필요하므로 **마스킹하지 않습니다**. 마스킹은 `pretty`, `json`, `jsonl`, `yaml` 전반에서 동일하게 적용됩니다.
 
 ## 스트리밍 (WebSocket)
 
-스트림 명령은 포그라운드에서 실행되며 키움 서버 메시지를 출력합니다. 유한한
-실행을 원하면 `--count`/`--duration`을 사용하세요.
+스트림 명령은 포그라운드에서 실행되며 키움 서버 메시지를 출력합니다. 유한한 실행을 원하면 `--count`/`--duration`을 사용하세요.
 
 ```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` 프레임 FID를
-  변환합니다. 알 수 없는 FID는 `unknown` 아래에 보존됩니다.
+- `--count`는 `REAL` 데이터 메시지만 셉니다. `REG`/`REMOVE`/`SYSTEM`은 제어 메시지입니다.
+- `--check`는 유한한 등록/수집을 수행하며, `REAL` 틱이 오지 않아도 정상 종료합니다.
+- 스트림 명령의 `--named`는 키움 스펙 기반 내장 스키마로 `REAL` 프레임 FID를 변환합니다. 알 수 없는 FID는 `unknown` 아래에 보존됩니다.
 
-장시간 구독을 저장하려면 파일로 출력하고 OS 도구로 프로세스를 백그라운드로
-돌리세요(CLI는 자체 작업 관리자를 제공하지 않습니다).
+장시간 구독을 저장하려면 파일로 출력하고 OS 도구로 프로세스를 백그라운드로 돌리세요(CLI는 자체 작업 관리자를 제공하지 않습니다).
 
 ```sh
 # 계속 수신하며 이벤트를 파일에 추가 기록
@@ -194,30 +159,21 @@ nohup kiwoomcli domestic streams trades --codes 005930,000660 --watch --output t
 Start-Process kiwoomcli -ArgumentList 'domestic streams trades --codes 005930,000660 --watch --output trades.jsonl'
 ```
 
-조건검색식의 생성과 수정은 키움 영웅문 HTS에서 합니다. CLI는 HTS에 이미 저장된
-조건식을 목록 조회, 선택, 조회, 구독, 해제만 합니다.
+조건검색식의 생성과 수정은 키움 영웅문 HTS에서 합니다. CLI는 HTS에 이미 저장된 조건식을 목록 조회, 선택, 조회, 구독, 해제만 합니다.
 
 ## 주문 안전장치
 
-국내·미국주식 주문 쓰기 명령(`orders buy/sell/modify/cancel`,
-`credit-*`, `gold-*`)과 미국주식 환전 신청(`overseas exchange request`)에는
-안전장치가 적용됩니다.
+국내·미국주식 주문 쓰기 명령(`orders buy/sell/modify/cancel`, `credit-*`, `gold-*`)과 미국주식 환전 신청(`overseas exchange request`)에는 안전장치가 적용됩니다.
 
-- `--confirm`이 없으면 짧은 미전송 주문 요약을 출력하고 주문 API를 호출하지
-  않습니다.
+- `--confirm`이 없으면 짧은 미전송 주문 요약을 출력하고 주문 API를 호출하지 않습니다.
 - `--confirm`이 있으면 실제 엔드포인트로 전송합니다.
-- `overseas exchange request`도 `--confirm`이 없으면 미전송 환전 확인만
-  출력하며, `--confirm`이 있어야 실제 환전 API를 호출합니다.
-- 주문 유형별 가격 규칙은 전송 경로 이전에 검증됩니다. 예를 들어
-  `--order-type limit`에는 `--price`가 필요하고, `--order-type market`에는
-  `--price`를 넣으면 안 됩니다. 잘못된 주문 식별자는 전송 전에 보고됩니다.
-- 주문 쓰기는 `--profile`/`--mode`로 인증 대상을 선택합니다. 먼저 데모(모의투자)
-  서버에서 검증하세요.
+- `overseas exchange request`도 `--confirm`이 없으면 미전송 환전 확인만 출력하며, `--confirm`이 있어야 실제 환전 API를 호출합니다.
+- 주문 유형별 가격 규칙은 전송 경로 이전에 검증됩니다. 예를 들어 `--order-type limit`에는 `--price`가 필요하고, `--order-type market`에는 `--price`를 넣으면 안 됩니다. 잘못된 주문 식별자는 전송 전에 보고됩니다.
+- 주문 쓰기는 `--profile`/`--mode`로 인증 대상을 선택합니다. 먼저 데모(모의투자) 서버에서 검증하세요.
 
 ## 용어
 
-안정적인 사용자 대상 옵션 이름이 키움 원본 필드명을 숨깁니다. 구체적인 코드
-종류는 명령 맥락에 따라 결정됩니다.
+각 옵션 이름은 키움 원본 필드명 대신 안정적인 사용자 대상 이름으로 노출됩니다. 구체적으로 어떤 코드를 넣어야 하는지는 명령마다 다릅니다.
 
 | 개념 | 옵션 | 예시 |
 | --- | --- | --- |
@@ -240,7 +196,16 @@ Start-Process kiwoomcli -ArgumentList 'domestic streams trades --codes 005930,00
 ## 안전 유의사항
 
 - 개발과 검증 단계에서는 `demo` 모드를 우선 사용하세요.
-- 자격 증명, 토큰, 계좌번호, 정제되지 않은 실제 호출 출력은 절대 로그로 남기거나
-  커밋하지 마세요.
-- 자격 증명·네트워크·계좌 안전 제약으로 실제 호출이 막히면, CLI는 결과를
-  지어내지 않고 차단됨/미실행으로 보고합니다.
+- 자격 증명, 토큰, 계좌번호, 정제되지 않은 실제 호출 출력은 절대 로그로 남기거나 커밋하지 마세요.
+- 자격 증명·네트워크·계좌 안전 제약으로 실제 호출이 막히면, CLI는 결과를 지어내지 않고 차단됨/미실행으로 보고합니다.
+
+## 알려진 제약
+
+- 국내 주문 취소(`domestic orders cancel`)는 `--qty`로 수량 일부만 취소할 수 있지만, 해외 주문 취소(`overseas orders cancel`)는 **전량만** 가능합니다. 해외 주문 정정(`overseas orders modify`)은 수량은 바꿀 수 없고 **가격만** 바꿀 수 있습니다(원주문이 STOP 주문이면 `--stop-price` 필수).
+- `domestic orders list-open`의 `--exchange`는 주문용 값인 `SOR`을 받지 않습니다 — `ALL`로 조회하세요. `overseas accounts open-orders`는 `--exchange`를 `--code` 없이 받지 않습니다(서버 제약) — 종목을 지정하지 않는 미체결 조회는 거래소 없이 전체로 조회하세요.
+- 너무 짧은 간격으로 연속 조회하면 유량 제한(429) 오류가 날 수 있습니다. 반복 호출에는 간격을 두세요.
+- 모의투자(demo) 계좌에서는 환율 조회, 주문가능금액 조회가 거절됩니다(실전 계좌에서만 가능).
+- 계좌마다 거래할 수 있는 시장이 다를 수 있습니다. 해당 계좌가 다루지 않는 시장은 주문이 거절되거나 조회 결과가 오류 없이 빈 목록으로 돌아올 수 있으므로, 결과가 비어 있다면 먼저 `--profile`/`--mode`로 선택한 계좌를 확인하세요. 장 운영 시간이 아닐 때 국내 주문을 시도하면 이와는 다른 이유(장 종료)로 거절됩니다.
+- 현재가 조회(`domestic quotes price`) 응답에는 전일대비 값이 직접 포함되어 있지 않습니다 — 현재가와 전일 종가의 차이로 직접 계산해야 합니다.
+- `auth list`/`auth status`는 `--format json`을 지원하지 않고 사람이 읽는 텍스트만 출력합니다.
+- 일부 계좌 조회 명령(`accounts valuation`/`accounts holdings`)에는 `--named`가 없어, 응답 필드가 키움 원본 코드로 나옵니다.

{kwcli-1.0.0 → kwcli-1.0.3}/kiwoom/core/auth.py

@@ -328,8 +328,19 @@ class KiwoomAuth:
 
     @staticmethod
     def _credential_fingerprint(credentials: CredentialSet) -> str:
-        raw = f"{credentials.appkey}:{credentials.secretkey}".encode("utf-8")
-        return hashlib.sha256(raw).hexdigest()
+        return credential_fingerprint(credentials)
+
+
+def credential_fingerprint(credentials: CredentialSet) -> str:
+    """Non-reversible identity of an appkey/secret pair.
+
+    Stored beside a cached token so a token issued for one key pair is never
+    reused after the credentials change (`_load_valid_token`), and used by the
+    runtime to seed a pre-issued token (`KIWOOM_ACCESS_TOKEN`) with the
+    fingerprint the auth object will check it against.
+    """
+    raw = f"{credentials.appkey}:{credentials.secretkey}".encode("utf-8")
+    return hashlib.sha256(raw).hexdigest()
 
 
 def _safe_json(response: requests.Response) -> dict:

{kwcli-1.0.0 → kwcli-1.0.3}/kiwoom/core/client.py

@@ -6,10 +6,11 @@ import requests
 
 from kiwoom.core.auth import KiwoomAuth, get_base_url
 from kiwoom.core.errors import (
-    AUTH_RETRY_RETURN_CODES,
     AuthenticationError,
     HTTPRequestError,
+    auth_retry_code,
     normalize_return_code,
+    raise_for_error_code,
 )
 from kiwoom.core.types import Continuation, KiwoomResponse
 
@@ -81,7 +82,9 @@ class KiwoomClient:
             }
 
         return_code = normalize_return_code(data.get("return_code"))
-        if return_code in AUTH_RETRY_RETURN_CODES and retry_on_auth_failure:
+        # 키움은 만료/무효 토큰을 top-level return_code=8005로도, return_code=3 +
+        # return_msg "[8005:...]"로도 돌려준다 — 어느 쪽이든 한 번 재발급 후 재시도.
+        if retry_on_auth_failure and auth_retry_code(return_code, data.get("return_msg")) is not None:
             self.auth.recover_from_auth_failure()
             return self.request(
                 api_id=resolved_api_id,
@@ -97,6 +100,14 @@ class KiwoomClient:
             if return_code not in (None, 0):
                 message = f"{message} (return_code={data['return_code']})"
             raise HTTPRequestError(response.status_code, message)
+
+        # 키움은 업무 오류도 HTTP 200으로 내려보내고 실패 여부는 본문 return_code에만 담는다.
+        if return_code not in (None, 0):
+            raise_for_error_code(
+                return_code,
+                str(data.get("return_msg") or "API 요청에 실패했습니다."),
+            )
+
         return _build_response(data, response.headers)
 
     def fetch_page(

{kwcli-1.0.0 → kwcli-1.0.3}/kiwoom/core/errors.py

@@ -1,9 +1,31 @@
+import re
 from pathlib import Path
 
 # Kiwoom auth-expiry return codes that warrant a one-shot credential
 # recovery + retry (shared by the REST client and the WebSocket client).
 AUTH_RETRY_RETURN_CODES = frozenset({8005, 8031, 8103})
 
+# Kiwoom often reports a generic top-level ``return_code`` (e.g. 3 = "인증에
+# 실패했습니다") and puts the specific code inside ``return_msg`` as
+# ``[8005:Token이 유효하지 않습니다]`` (REST) or ``CODE=8005`` (WebSocket).
+_EMBEDDED_CODE_RE = re.compile(r"\[(\d{3,5}):|CODE=(\d{3,5})")
+
+
+def embedded_return_code(return_msg: object) -> int | None:
+    """Return the specific code embedded in a Kiwoom ``return_msg``, if any."""
+    match = _EMBEDDED_CODE_RE.search(str(return_msg or ""))
+    if match is None:
+        return None
+    return int(match.group(1) or match.group(2))
+
+
+def auth_retry_code(return_code: int | None, return_msg: object) -> int | None:
+    """The auth-expiry code (top-level or embedded) that warrants recovery, else None."""
+    if return_code in AUTH_RETRY_RETURN_CODES:
+        return return_code
+    embedded = embedded_return_code(return_msg)
+    return embedded if embedded in AUTH_RETRY_RETURN_CODES else None
+
 
 def normalize_return_code(value: object) -> int | None:
     """Normalize a Kiwoom ``return_code`` payload value.
@@ -137,6 +159,13 @@ class DeviceAuthenticationError(AuthenticationError):
         self.return_msg = return_msg
 
 
+class DemoUnsupportedError(APIError):
+    """Raised when the API exists but is not served in demo (모의투자) mode."""
+
+    def __init__(self, return_code: int, return_msg: str):
+        super().__init__(return_code, f"모의투자에서 지원하지 않는 API입니다. ({return_msg})")
+
+
 INPUT_VALIDATION_CODES = {
     1501,
     1504,
@@ -151,15 +180,35 @@ INPUT_VALIDATION_CODES = {
     1687,
     8020,
 }
-RATE_LIMIT_CODES = {1700}
-SYMBOL_NOT_FOUND_CODES = {1901, 1902}
+RATE_LIMIT_CODES = {1700, 1701, 1702}
+SYMBOL_NOT_FOUND_CODES = {1901, 1902, 1903}
 INVALID_CREDENTIAL_CODES = {8001, 8002, 8011, 8012}
 INVALID_TOKEN_CODES = {8003, 8005, 8006, 8009, 8015, 8016}
 MODE_MISMATCH_CODES = {8030, 8031}
 DEVICE_AUTH_CODES = {8010, 8040, 8050, 8103}
+DEMO_UNSUPPORTED_CODES = {8104}
+
+
+_CLASSIFIED_CODES = (
+    INPUT_VALIDATION_CODES
+    | RATE_LIMIT_CODES
+    | SYMBOL_NOT_FOUND_CODES
+    | INVALID_CREDENTIAL_CODES
+    | INVALID_TOKEN_CODES
+    | MODE_MISMATCH_CODES
+    | DEVICE_AUTH_CODES
+    | DEMO_UNSUPPORTED_CODES
+)
 
 
 def raise_for_error_code(return_code: int, return_msg: str) -> None:
+    # A generic top-level code (3, 5, ...) with a specific code embedded in the
+    # message is classified by the embedded code, so callers get the same
+    # error class either way; the message keeps Kiwoom's original text.
+    if return_code not in _CLASSIFIED_CODES:
+        embedded = embedded_return_code(return_msg)
+        if embedded in _CLASSIFIED_CODES:
+            return_code = embedded
     if return_code in INPUT_VALIDATION_CODES:
         raise InputValidationError(return_code, return_msg)
     if return_code in RATE_LIMIT_CODES:
@@ -174,4 +223,8 @@ def raise_for_error_code(return_code: int, return_msg: str) -> None:
         raise ModeMismatchError(return_code, return_msg)
     if return_code in DEVICE_AUTH_CODES:
         raise DeviceAuthenticationError(return_code, return_msg)
+    if return_code in DEMO_UNSUPPORTED_CODES:
+        raise DemoUnsupportedError(return_code, return_msg)
+    # 1999(예기치 못한 오류)·8200(법인 미지원)처럼 분류해도 대응이 달라지지 않는 코드는
+    # 원문 메시지를 그대로 노출하는 APIError로 남긴다.
     raise APIError(return_code, return_msg)