kiwoom-cli 0.1.0__py3-none-any.whl

kiwoom_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Kiwoom Securities REST API CLI."""
+
+__version__ = "0.1.0"

kiwoom_cli/api_spec.py

@@ -0,0 +1,229 @@
+"""API specification registry.
+
+Maps API IDs to their URL paths. All APIs use POST and share URLs
+differentiated by the `api-id` header.
+"""
+
+from __future__ import annotations
+
+# API ID -> (url_path, description_ko)
+API_REGISTRY: dict[str, tuple[str, str]] = {
+    # === OAuth ===
+    "au10001": ("/oauth2/token", "접근토큰 발급"),
+    "au10002": ("/oauth2/revoke", "접근토큰폐기"),
+    # === 계좌 (Account) ===
+    "ka00001": ("/api/dostk/acnt", "계좌번호조회"),
+    "ka01690": ("/api/dostk/acnt", "일별잔고수익률"),
+    "ka10072": ("/api/dostk/acnt", "일자별종목별실현손익요청_일자"),
+    "ka10073": ("/api/dostk/acnt", "일자별종목별실현손익요청_기간"),
+    "ka10074": ("/api/dostk/acnt", "일자별실현손익요청"),
+    "ka10075": ("/api/dostk/acnt", "미체결요청"),
+    "ka10076": ("/api/dostk/acnt", "체결요청"),
+    "ka10077": ("/api/dostk/acnt", "당일실현손익상세요청"),
+    "ka10085": ("/api/dostk/acnt", "계좌수익률요청"),
+    "ka10088": ("/api/dostk/acnt", "미체결 분할주문 상세"),
+    "ka10170": ("/api/dostk/acnt", "당일매매일지요청"),
+    "kt00001": ("/api/dostk/acnt", "예수금상세현황요청"),
+    "kt00002": ("/api/dostk/acnt", "일별추정예탁자산현황요청"),
+    "kt00003": ("/api/dostk/acnt", "추정자산조회요청"),
+    "kt00004": ("/api/dostk/acnt", "계좌평가현황요청"),
+    "kt00005": ("/api/dostk/acnt", "체결잔고요청"),
+    "kt00007": ("/api/dostk/acnt", "계좌별주문체결내역상세요청"),
+    "kt00008": ("/api/dostk/acnt", "계좌별익일결제예정내역요청"),
+    "kt00009": ("/api/dostk/acnt", "계좌별주문체결현황요청"),
+    "kt00010": ("/api/dostk/acnt", "주문인출가능금액요청"),
+    "kt00011": ("/api/dostk/acnt", "증거금율별주문가능수량조회요청"),
+    "kt00012": ("/api/dostk/acnt", "신용보증금율별주문가능수량조회요청"),
+    "kt00013": ("/api/dostk/acnt", "증거금세부내역조회요청"),
+    "kt00015": ("/api/dostk/acnt", "위탁종합거래내역요청"),
+    "kt00016": ("/api/dostk/acnt", "일별계좌수익률상세현황요청"),
+    "kt00017": ("/api/dostk/acnt", "계좌별당일현황요청"),
+    "kt00018": ("/api/dostk/acnt", "계좌평가잔고내역요청"),
+    "kt50020": ("/api/dostk/acnt", "금현물 잔고확인"),
+    "kt50021": ("/api/dostk/acnt", "금현물 예수금"),
+    "kt50030": ("/api/dostk/acnt", "금현물 주문체결전체조회"),
+    "kt50031": ("/api/dostk/acnt", "금현물 주문체결조회"),
+    "kt50032": ("/api/dostk/acnt", "금현물 거래내역조회"),
+    "kt50075": ("/api/dostk/acnt", "금현물 미체결조회"),
+    # === 종목정보 (Stock Info) ===
+    "ka00198": ("/api/dostk/stkinfo", "실시간종목조회순위"),
+    "ka10001": ("/api/dostk/stkinfo", "주식기본정보요청"),
+    "ka10002": ("/api/dostk/stkinfo", "주식거래원요청"),
+    "ka10003": ("/api/dostk/stkinfo", "체결정보요청"),
+    "ka10013": ("/api/dostk/stkinfo", "신용매매동향요청"),
+    "ka10015": ("/api/dostk/stkinfo", "일별거래상세요청"),
+    "ka10016": ("/api/dostk/stkinfo", "신고저가요청"),
+    "ka10017": ("/api/dostk/stkinfo", "상하한가요청"),
+    "ka10018": ("/api/dostk/stkinfo", "고저가근접요청"),
+    "ka10019": ("/api/dostk/stkinfo", "가격급등락요청"),
+    "ka10024": ("/api/dostk/stkinfo", "거래량갱신요청"),
+    "ka10025": ("/api/dostk/stkinfo", "매물대집중요청"),
+    "ka10026": ("/api/dostk/stkinfo", "고저PER요청"),
+    "ka10028": ("/api/dostk/stkinfo", "시가대비등락률요청"),
+    "ka10043": ("/api/dostk/stkinfo", "거래원매물대분석요청"),
+    "ka10052": ("/api/dostk/stkinfo", "거래원순간거래량요청"),
+    "ka10054": ("/api/dostk/stkinfo", "변동성완화장치발동종목요청"),
+    "ka10055": ("/api/dostk/stkinfo", "당일전일체결량요청"),
+    "ka10058": ("/api/dostk/stkinfo", "투자자별일별매매종목요청"),
+    "ka10059": ("/api/dostk/stkinfo", "종목별투자자기관별요청"),
+    "ka10061": ("/api/dostk/stkinfo", "종목별투자자기관별합계요청"),
+    "ka10084": ("/api/dostk/stkinfo", "당일전일체결요청"),
+    "ka10095": ("/api/dostk/stkinfo", "관심종목정보요청"),
+    "ka10099": ("/api/dostk/stkinfo", "종목정보 리스트"),
+    "ka10100": ("/api/dostk/stkinfo", "종목정보 조회"),
+    "ka10101": ("/api/dostk/stkinfo", "업종코드 리스트"),
+    "ka10102": ("/api/dostk/stkinfo", "회원사 리스트"),
+    "ka90003": ("/api/dostk/stkinfo", "프로그램순매수상위50요청"),
+    "ka90004": ("/api/dostk/stkinfo", "종목별프로그램매매현황요청"),
+    "kt20016": ("/api/dostk/stkinfo", "신용융자 가능종목요청"),
+    "kt20017": ("/api/dostk/stkinfo", "신용융자 가능문의"),
+    # === 시세 (Market Conditions) ===
+    "ka10004": ("/api/dostk/mrkcond", "주식호가요청"),
+    "ka10005": ("/api/dostk/mrkcond", "주식일주월시분요청"),
+    "ka10006": ("/api/dostk/mrkcond", "주식시분요청"),
+    "ka10007": ("/api/dostk/mrkcond", "시세표성정보요청"),
+    "ka10011": ("/api/dostk/mrkcond", "신주인수권전체시세요청"),
+    "ka10044": ("/api/dostk/mrkcond", "일별기관매매종목요청"),
+    "ka10045": ("/api/dostk/mrkcond", "종목별기관매매추이요청"),
+    "ka10046": ("/api/dostk/mrkcond", "체결강도추이시간별요청"),
+    "ka10047": ("/api/dostk/mrkcond", "체결강도추이일별요청"),
+    "ka10063": ("/api/dostk/mrkcond", "장중투자자별매매요청"),
+    "ka10066": ("/api/dostk/mrkcond", "장마감후투자자별매매요청"),
+    "ka10078": ("/api/dostk/mrkcond", "증권사별종목매매동향요청"),
+    "ka10086": ("/api/dostk/mrkcond", "일별주가요청"),
+    "ka10087": ("/api/dostk/mrkcond", "시간외단일가요청"),
+    "ka50010": ("/api/dostk/mrkcond", "금현물체결추이"),
+    "ka50012": ("/api/dostk/mrkcond", "금현물일별추이"),
+    "ka50087": ("/api/dostk/mrkcond", "금현물예상체결"),
+    "ka50100": ("/api/dostk/mrkcond", "금현물 시세정보"),
+    "ka50101": ("/api/dostk/mrkcond", "금현물 호가"),
+    "ka90005": ("/api/dostk/mrkcond", "프로그램매매추이요청 시간대별"),
+    "ka90006": ("/api/dostk/mrkcond", "프로그램매매차익잔고추이요청"),
+    "ka90007": ("/api/dostk/mrkcond", "프로그램매매누적추이요청"),
+    "ka90008": ("/api/dostk/mrkcond", "종목시간별프로그램매매추이요청"),
+    "ka90010": ("/api/dostk/mrkcond", "프로그램매매추이요청 일자별"),
+    "ka90013": ("/api/dostk/mrkcond", "종목일별프로그램매매추이요청"),
+    # === 주문 (Orders) ===
+    "kt10000": ("/api/dostk/ordr", "주식 매수주문"),
+    "kt10001": ("/api/dostk/ordr", "주식 매도주문"),
+    "kt10002": ("/api/dostk/ordr", "주식 정정주문"),
+    "kt10003": ("/api/dostk/ordr", "주식 취소주문"),
+    "kt50000": ("/api/dostk/ordr", "금현물 매수주문"),
+    "kt50001": ("/api/dostk/ordr", "금현물 매도주문"),
+    "kt50002": ("/api/dostk/ordr", "금현물 정정주문"),
+    "kt50003": ("/api/dostk/ordr", "금현물 취소주문"),
+    # === 신용주문 (Credit Orders) ===
+    "kt10006": ("/api/dostk/crdordr", "신용 매수주문"),
+    "kt10007": ("/api/dostk/crdordr", "신용 매도주문"),
+    "kt10008": ("/api/dostk/crdordr", "신용 정정주문"),
+    "kt10009": ("/api/dostk/crdordr", "신용 취소주문"),
+    # === 차트 (Charts) ===
+    "ka10060": ("/api/dostk/chart", "종목별투자자기관별차트요청"),
+    "ka10064": ("/api/dostk/chart", "장중투자자별매매차트요청"),
+    "ka10079": ("/api/dostk/chart", "주식틱차트조회요청"),
+    "ka10080": ("/api/dostk/chart", "주식분봉차트조회요청"),
+    "ka10081": ("/api/dostk/chart", "주식일봉차트조회요청"),
+    "ka10082": ("/api/dostk/chart", "주식주봉차트조회요청"),
+    "ka10083": ("/api/dostk/chart", "주식월봉차트조회요청"),
+    "ka10094": ("/api/dostk/chart", "주식년봉차트조회요청"),
+    "ka20004": ("/api/dostk/chart", "업종틱차트조회요청"),
+    "ka20005": ("/api/dostk/chart", "업종분봉조회요청"),
+    "ka20006": ("/api/dostk/chart", "업종일봉조회요청"),
+    "ka20007": ("/api/dostk/chart", "업종주봉조회요청"),
+    "ka20008": ("/api/dostk/chart", "업종월봉조회요청"),
+    "ka20019": ("/api/dostk/chart", "업종년봉조회요청"),
+    "ka50079": ("/api/dostk/chart", "금현물틱차트조회요청"),
+    "ka50080": ("/api/dostk/chart", "금현물분봉차트조회요청"),
+    "ka50081": ("/api/dostk/chart", "금현물일봉차트조회요청"),
+    "ka50082": ("/api/dostk/chart", "금현물주봉차트조회요청"),
+    "ka50083": ("/api/dostk/chart", "금현물월봉차트조회요청"),
+    "ka50091": ("/api/dostk/chart", "금현물당일틱차트조회요청"),
+    "ka50092": ("/api/dostk/chart", "금현물당일분봉차트조회요청"),
+    # === 순위정보 (Rankings) ===
+    "ka10020": ("/api/dostk/rkinfo", "호가잔량상위요청"),
+    "ka10021": ("/api/dostk/rkinfo", "호가잔량급증요청"),
+    "ka10022": ("/api/dostk/rkinfo", "잔량율급증요청"),
+    "ka10023": ("/api/dostk/rkinfo", "거래량급증요청"),
+    "ka10027": ("/api/dostk/rkinfo", "전일대비등락률상위요청"),
+    "ka10029": ("/api/dostk/rkinfo", "예상체결등락률상위요청"),
+    "ka10030": ("/api/dostk/rkinfo", "당일거래량상위요청"),
+    "ka10031": ("/api/dostk/rkinfo", "전일거래량상위요청"),
+    "ka10032": ("/api/dostk/rkinfo", "거래대금상위요청"),
+    "ka10033": ("/api/dostk/rkinfo", "신용비율상위요청"),
+    "ka10034": ("/api/dostk/rkinfo", "외인기간별매매상위요청"),
+    "ka10035": ("/api/dostk/rkinfo", "외인연속순매매상위요청"),
+    "ka10036": ("/api/dostk/rkinfo", "외인한도소진율증가상위"),
+    "ka10037": ("/api/dostk/rkinfo", "외국계창구매매상위요청"),
+    "ka10038": ("/api/dostk/rkinfo", "종목별증권사순위요청"),
+    "ka10039": ("/api/dostk/rkinfo", "증권사별매매상위요청"),
+    "ka10040": ("/api/dostk/rkinfo", "당일주요거래원요청"),
+    "ka10042": ("/api/dostk/rkinfo", "순매수거래원순위요청"),
+    "ka10053": ("/api/dostk/rkinfo", "당일상위이탈원요청"),
+    "ka10062": ("/api/dostk/rkinfo", "동일순매매순위요청"),
+    "ka10065": ("/api/dostk/rkinfo", "장중투자자별매매상위요청"),
+    "ka10098": ("/api/dostk/rkinfo", "시간외단일가등락율순위요청"),
+    "ka90009": ("/api/dostk/rkinfo", "외국인기관매매상위요청"),
+    # === 기관/외국인 (Foreign/Institutional) ===
+    "ka10008": ("/api/dostk/frgnistt", "주식외국인종목별매매동향"),
+    "ka10009": ("/api/dostk/frgnistt", "주식기관요청"),
+    "ka10131": ("/api/dostk/frgnistt", "기관외국인연속매매현황요청"),
+    "ka52301": ("/api/dostk/frgnistt", "금현물투자자현황"),
+    # === 업종 (Sector) ===
+    "ka10010": ("/api/dostk/sect", "업종프로그램요청"),
+    "ka10051": ("/api/dostk/sect", "업종별투자자순매수요청"),
+    "ka20001": ("/api/dostk/sect", "업종현재가요청"),
+    "ka20002": ("/api/dostk/sect", "업종별주가요청"),
+    "ka20003": ("/api/dostk/sect", "전업종지수요청"),
+    "ka20009": ("/api/dostk/sect", "업종현재가일별요청"),
+    # === ELW ===
+    "ka10048": ("/api/dostk/elw", "ELW일별민감도지표요청"),
+    "ka10050": ("/api/dostk/elw", "ELW민감도지표요청"),
+    "ka30001": ("/api/dostk/elw", "ELW가격급등락요청"),
+    "ka30002": ("/api/dostk/elw", "거래원별ELW순매매상위요청"),
+    "ka30003": ("/api/dostk/elw", "ELWLP보유일별추이요청"),
+    "ka30004": ("/api/dostk/elw", "ELW괴리율요청"),
+    "ka30005": ("/api/dostk/elw", "ELW조건검색요청"),
+    "ka30009": ("/api/dostk/elw", "ELW등락율순위요청"),
+    "ka30010": ("/api/dostk/elw", "ELW잔량순위요청"),
+    "ka30011": ("/api/dostk/elw", "ELW근접율요청"),
+    "ka30012": ("/api/dostk/elw", "ELW종목상세정보요청"),
+    # === ETF ===
+    "ka40001": ("/api/dostk/etf", "ETF수익율요청"),
+    "ka40002": ("/api/dostk/etf", "ETF종목정보요청"),
+    "ka40003": ("/api/dostk/etf", "ETF일별추이요청"),
+    "ka40004": ("/api/dostk/etf", "ETF전체시세요청"),
+    "ka40006": ("/api/dostk/etf", "ETF시간대별추이요청"),
+    "ka40007": ("/api/dostk/etf", "ETF시간대별체결요청"),
+    "ka40008": ("/api/dostk/etf", "ETF일자별체결요청"),
+    "ka40009": ("/api/dostk/etf", "ETF시간대별체결요청"),
+    "ka40010": ("/api/dostk/etf", "ETF시간대별추이요청"),
+    # === 공매도 (Short Selling) ===
+    "ka10014": ("/api/dostk/shsa", "공매도추이요청"),
+    # === 대차거래 (Securities Lending) ===
+    "ka10068": ("/api/dostk/slb", "대차거래추이요청"),
+    "ka10069": ("/api/dostk/slb", "대차거래상위10종목요청"),
+    "ka20068": ("/api/dostk/slb", "대차거래추이요청(종목별)"),
+    "ka90012": ("/api/dostk/slb", "대차거래내역요청"),
+    # === 테마 (Theme) ===
+    "ka90001": ("/api/dostk/thme", "테마그룹별요청"),
+    "ka90002": ("/api/dostk/thme", "테마구성종목요청"),
+    # === 조건검색 (Condition Search) / WebSocket ===
+    "ka10171": ("/api/dostk/websocket", "조건검색 목록조회"),
+    "ka10172": ("/api/dostk/websocket", "조건검색 요청 일반"),
+    "ka10173": ("/api/dostk/websocket", "조건검색 요청 실시간"),
+    "ka10174": ("/api/dostk/websocket", "조건검색 실시간 해제"),
+}
+
+
+def get_url(api_id: str) -> str:
+    entry = API_REGISTRY.get(api_id)
+    if entry is None:
+        raise ValueError(f"Unknown API ID: {api_id}")
+    return entry[0]
+
+
+def get_description(api_id: str) -> str:
+    entry = API_REGISTRY.get(api_id)
+    if entry is None:
+        return api_id
+    return entry[1]

kiwoom_cli/auth.py

@@ -0,0 +1,30 @@
+"""OAuth token management for Kiwoom REST API.
+
+Tokens are stored in ~/.kiwoom/token and loaded automatically by the client.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import config
+
+TOKEN_FILE = config.CONFIG_DIR / "token"
+
+
+def save_token(token: str) -> None:
+    config.ensure_config_dir()
+    TOKEN_FILE.write_text(token)
+    TOKEN_FILE.chmod(0o600)
+
+
+def load_token() -> str | None:
+    if TOKEN_FILE.exists():
+        t = TOKEN_FILE.read_text().strip()
+        return t if t else None
+    return None
+
+
+def delete_token() -> None:
+    if TOKEN_FILE.exists():
+        TOKEN_FILE.unlink()

kiwoom_cli/client.py

@@ -0,0 +1,176 @@
+"""HTTP client for Kiwoom REST API.
+
+Handles authentication headers, pagination, and error handling.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+import httpx
+
+from . import auth, config
+from .api_spec import get_url
+from .output import err_console
+
+CONTENT_TYPE = "application/json;charset=UTF-8"
+
+
+class KiwoomAPIError(Exception):
+    def __init__(self, code: int, msg: str):
+        self.code = code
+        self.msg = msg
+        super().__init__(f"[{code}] {msg}")
+
+
+class KiwoomClient:
+    """Synchronous client for the Kiwoom REST API."""
+
+    def __init__(self, domain: str | None = None, token: str | None = None):
+        self.domain = domain or config.get_domain()
+        self.token = token or auth.load_token()
+        self._http = httpx.Client(
+            base_url=self.domain,
+            timeout=30.0,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def _headers(self, api_id: str, cont_yn: str = "", next_key: str = "") -> dict:
+        h = {
+            "content-type": CONTENT_TYPE,
+            "api-id": api_id,
+        }
+        if self.token:
+            h["authorization"] = f"Bearer {self.token}"
+        if cont_yn:
+            h["cont-yn"] = cont_yn
+        if next_key:
+            h["next-key"] = next_key
+        return h
+
+    def _should_spin(self) -> bool:
+        """Show spinner only for table format on a real terminal."""
+        if not err_console.is_terminal:
+            return False
+        ctx = click.get_current_context(silent=True)
+        if ctx and ctx.obj and ctx.obj.get("format") != "table":
+            return False
+        return True
+
+    def request(
+        self,
+        api_id: str,
+        body: dict[str, Any] | None = None,
+        *,
+        cont_yn: str = "",
+        next_key: str = "",
+    ) -> tuple[dict[str, Any], dict[str, str]]:
+        """Make a single API request. Returns (body_json, response_headers)."""
+        url_path = get_url(api_id)
+        headers = self._headers(api_id, cont_yn, next_key)
+        if self._should_spin():
+            with err_console.status("[dim]조회 중...[/]", spinner="dots"):
+                resp = self._http.post(url_path, headers=headers, json=body or {})
+        else:
+            resp = self._http.post(url_path, headers=headers, json=body or {})
+        resp.raise_for_status()
+        data = resp.json()
+
+        rc = data.get("return_code")
+        if rc is not None and rc != 0:
+            raise KiwoomAPIError(rc, data.get("return_msg", "Unknown error"))
+
+        resp_headers = {
+            "cont-yn": resp.headers.get("cont-yn", ""),
+            "next-key": resp.headers.get("next-key", ""),
+        }
+        return data, resp_headers
+
+    def request_all(
+        self,
+        api_id: str,
+        body: dict[str, Any] | None = None,
+        *,
+        max_pages: int = 10,
+    ) -> list[dict[str, Any]]:
+        """Auto-paginate through cont-yn/next-key. Returns list of all response bodies."""
+        results = []
+        cont_yn = ""
+        next_key = ""
+
+        for _ in range(max_pages):
+            data, headers = self.request(
+                api_id, body, cont_yn=cont_yn, next_key=next_key
+            )
+            results.append(data)
+
+            if headers.get("cont-yn") == "Y" and headers.get("next-key"):
+                cont_yn = headers["cont-yn"]
+                next_key = headers["next-key"]
+            else:
+                break
+
+        return results
+
+    def issue_token(self, appkey: str | None = None, secretkey: str | None = None) -> str:
+        """Issue an access token via au10001."""
+        ak = appkey or config.get_appkey()
+        sk = secretkey or config.get_secretkey()
+        if not ak or not sk:
+            raise click.ClickException(
+                "appkey/secretkey not set. Run: kiwoom config setup"
+            )
+
+        resp = self._http.post(
+            "/oauth2/token",
+            headers={"content-type": CONTENT_TYPE, "api-id": "au10001"},
+            json={
+                "grant_type": "client_credentials",
+                "appkey": ak,
+                "secretkey": sk,
+            },
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        rc = data.get("return_code")
+        if rc is not None and rc != 0:
+            raise KiwoomAPIError(rc, data.get("return_msg", "Token issue failed"))
+
+        token = data.get("token", "")
+        if not token:
+            # Some responses put it differently
+            for k in ("access_token", "token"):
+                if data.get(k):
+                    token = data[k]
+                    break
+
+        if token:
+            auth.save_token(token)
+            self.token = token
+        return token
+
+    def revoke_token(self) -> None:
+        """Revoke the current access token via au10002."""
+        ak = config.get_appkey()
+        sk = config.get_secretkey()
+        token = self.token or auth.load_token()
+        if not token:
+            raise click.ClickException("No token to revoke.")
+
+        self._http.post(
+            "/oauth2/revoke",
+            headers={"content-type": CONTENT_TYPE, "api-id": "au10002"},
+            json={"appkey": ak, "secretkey": sk, "token": token},
+        )
+        auth.delete_token()
+        self.token = None