kispilot 0.1.2__tar.gz → 0.2.0__tar.gz

kispilot-0.2.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: kispilot
+Version: 0.2.0
+Summary: 한국투자증권 Open API를 AI 에이전트(MCP)와 웹 콘솔에서 쓰기 위한 도구 모음 (비공식)
+Author: Dong-Ju An
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dongju923/kispilot
+Project-URL: Repository, https://github.com/dongju923/kispilot
+Project-URL: Issues, https://github.com/dongju923/kispilot/issues
+Project-URL: Changelog, https://github.com/dongju923/kispilot/releases
+Keywords: kis,korea-investment,한국투자증권,mcp,trading,backtest,claude,agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: Korean
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: keyring>=25
+Requires-Dist: platformdirs>=4
+Requires-Dist: pandas>=2.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: yfinance>=0.2.40
+Requires-Dist: starlette>=0.37
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: websockets>=12
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: mcp<3,>=2.2
+Dynamic: license-file
+
+# KISPilot
+
+한국투자증권 Open API를 **AI 에이전트(MCP)** 와 **웹 콘솔**에서 쓰기 위한 도구 모음입니다.
+
+> **비공식 프로젝트입니다.** 한국투자증권과 관계가 없으며, 한국투자증권이 만들거나 검증하지 않았습니다.
+> 이 소프트웨어는 투자 조언이 아니며, 주문·백테스트 결과로 생긴 손실에 대해 책임지지 않습니다 (MIT 라이선스, 무보증).
+> 실전 계좌로 쓰기 전에 모의투자로 충분히 확인하세요.
+
+## 할 수 있는 것
+
+- **조회** — 시세·호가·체결, 투자자·수급, 재무, 순위, 업종·지수, ETF, 계좌 잔고·손익 (KIS API 80여 개)
+- **선물·옵션** — KOSPI200 선물·옵션(미니·위클리 포함) 주간·야간 전광판, 실시간 호가·체결, 차트
+- **주문** — 현금·신용·예약 주문, 정정·취소 (에이전트는 모의투자가 기본, 실전은 2단계 확인)
+- **차트** — 1분~년봉, 이동평균·볼린저·일목균형표 등 지표, 보조 차트 30여 종
+- **백테스트** — 기본 전략 11종 + 지표 157개로 만드는 커스텀 전략, 여러 전략 비교, 여러 종목 포트폴리오
+- **실시간** — KIS 웹소켓 체결·호가 (웹 콘솔)
+
+## 빠른 시작
+
+Python 3.11 이상이 필요합니다.
+
+**1. 설치**
+
+```bash
+uv tool install kispilot      # 또는: pipx install kispilot / pip install kispilot
+```
+
+**2. 키 등록 (처음 한 번)** — [KIS Developers](https://apiportal.koreainvestment.com)에서 앱키·앱시크릿을 발급받은 뒤:
+
+```bash
+kispilot setup        # 실전 / 모의투자 / 둘 다 선택 → 앱키·시크릿·계좌 입력
+```
+
+앱키는 OS 키체인에 저장됩니다. **키를 AI 채팅창에 붙여넣지 마세요.**
+
+**3. 쓰는 방법 고르기**
+
+| 이렇게 쓰려면 | 실행 |
+|---|---|
+| 웹 화면에서 직접 보기 | `kispilot ui` → http://127.0.0.1:8000 |
+| Claude 등 AI 에이전트에게 맡기기 | `kispilot install claude-desktop` (Claude Code · Cursor · VS Code · Gemini CLI · Codex 도 지원) 후 앱 다시 시작 |
+
+## 안내 문서
+
+| 문서 | 이럴 때 보세요 |
+|---|---|
+| [설치 · 키 등록](https://github.com/dongju923/kispilot/blob/main/docs/install.md) | 업데이트·삭제, 소스 설치, 서버처럼 키체인이 없는 환경, 데이터 저장 위치 |
+| [웹 콘솔](https://github.com/dongju923/kispilot/blob/main/docs/web-console.md) | 화면마다 무엇을 볼 수 있는지, 다른 기기에서 접속하기 |
+| [선물 · 옵션](https://github.com/dongju923/kispilot/blob/main/docs/futures-options.md) | KOSPI200 선물·옵션 전광판, 주간/야간, 알아 둘 점 |
+| [AI 에이전트 (MCP)](https://github.com/dongju923/kispilot/blob/main/docs/mcp.md) | 클라이언트별 등록, 도구·프롬프트 목록, 직접 설정, 주문 안전장치 |
+
+버전별 변경 내용은 [Releases](https://github.com/dongju923/kispilot/releases) 에 있습니다.
+
+## 데이터 출처 · 참고
+
+- [한국투자증권 Open API](https://apiportal.koreainvestment.com) — 모든 시세·계좌·주문 기능은 이 API 를 호출합니다.
+- [yfinance](https://github.com/ranaroussi/yfinance) — 주식 과거 일봉·분봉 (Yahoo Finance, 개인적·연구 목적 이용 권장). 최근 거래일은 KIS API로 보강
+- [TradingView Lightweight Charts](https://github.com/tradingview/lightweight-charts) — 차트 (Apache-2.0)
+- [koreainvestment/open-trading-api](https://github.com/koreainvestment/open-trading-api) — 백테스트 기본 전략 구성(프리셋 종류)과 종목 마스터 파일 형식(필드 폭·열 이름)을 참고했습니다.
+
+## 라이선스
+
+[MIT](https://github.com/dongju923/kispilot/blob/main/LICENSE)

kispilot-0.2.0/README.md

@@ -0,0 +1,63 @@
+# KISPilot
+
+한국투자증권 Open API를 **AI 에이전트(MCP)** 와 **웹 콘솔**에서 쓰기 위한 도구 모음입니다.
+
+> **비공식 프로젝트입니다.** 한국투자증권과 관계가 없으며, 한국투자증권이 만들거나 검증하지 않았습니다.
+> 이 소프트웨어는 투자 조언이 아니며, 주문·백테스트 결과로 생긴 손실에 대해 책임지지 않습니다 (MIT 라이선스, 무보증).
+> 실전 계좌로 쓰기 전에 모의투자로 충분히 확인하세요.
+
+## 할 수 있는 것
+
+- **조회** — 시세·호가·체결, 투자자·수급, 재무, 순위, 업종·지수, ETF, 계좌 잔고·손익 (KIS API 80여 개)
+- **선물·옵션** — KOSPI200 선물·옵션(미니·위클리 포함) 주간·야간 전광판, 실시간 호가·체결, 차트
+- **주문** — 현금·신용·예약 주문, 정정·취소 (에이전트는 모의투자가 기본, 실전은 2단계 확인)
+- **차트** — 1분~년봉, 이동평균·볼린저·일목균형표 등 지표, 보조 차트 30여 종
+- **백테스트** — 기본 전략 11종 + 지표 157개로 만드는 커스텀 전략, 여러 전략 비교, 여러 종목 포트폴리오
+- **실시간** — KIS 웹소켓 체결·호가 (웹 콘솔)
+
+## 빠른 시작
+
+Python 3.11 이상이 필요합니다.
+
+**1. 설치**
+
+```bash
+uv tool install kispilot      # 또는: pipx install kispilot / pip install kispilot
+```
+
+**2. 키 등록 (처음 한 번)** — [KIS Developers](https://apiportal.koreainvestment.com)에서 앱키·앱시크릿을 발급받은 뒤:
+
+```bash
+kispilot setup        # 실전 / 모의투자 / 둘 다 선택 → 앱키·시크릿·계좌 입력
+```
+
+앱키는 OS 키체인에 저장됩니다. **키를 AI 채팅창에 붙여넣지 마세요.**
+
+**3. 쓰는 방법 고르기**
+
+| 이렇게 쓰려면 | 실행 |
+|---|---|
+| 웹 화면에서 직접 보기 | `kispilot ui` → http://127.0.0.1:8000 |
+| Claude 등 AI 에이전트에게 맡기기 | `kispilot install claude-desktop` (Claude Code · Cursor · VS Code · Gemini CLI · Codex 도 지원) 후 앱 다시 시작 |
+
+## 안내 문서
+
+| 문서 | 이럴 때 보세요 |
+|---|---|
+| [설치 · 키 등록](https://github.com/dongju923/kispilot/blob/main/docs/install.md) | 업데이트·삭제, 소스 설치, 서버처럼 키체인이 없는 환경, 데이터 저장 위치 |
+| [웹 콘솔](https://github.com/dongju923/kispilot/blob/main/docs/web-console.md) | 화면마다 무엇을 볼 수 있는지, 다른 기기에서 접속하기 |
+| [선물 · 옵션](https://github.com/dongju923/kispilot/blob/main/docs/futures-options.md) | KOSPI200 선물·옵션 전광판, 주간/야간, 알아 둘 점 |
+| [AI 에이전트 (MCP)](https://github.com/dongju923/kispilot/blob/main/docs/mcp.md) | 클라이언트별 등록, 도구·프롬프트 목록, 직접 설정, 주문 안전장치 |
+
+버전별 변경 내용은 [Releases](https://github.com/dongju923/kispilot/releases) 에 있습니다.
+
+## 데이터 출처 · 참고
+
+- [한국투자증권 Open API](https://apiportal.koreainvestment.com) — 모든 시세·계좌·주문 기능은 이 API 를 호출합니다.
+- [yfinance](https://github.com/ranaroussi/yfinance) — 주식 과거 일봉·분봉 (Yahoo Finance, 개인적·연구 목적 이용 권장). 최근 거래일은 KIS API로 보강
+- [TradingView Lightweight Charts](https://github.com/tradingview/lightweight-charts) — 차트 (Apache-2.0)
+- [koreainvestment/open-trading-api](https://github.com/koreainvestment/open-trading-api) — 백테스트 기본 전략 구성(프리셋 종류)과 종목 마스터 파일 형식(필드 폭·열 이름)을 참고했습니다.
+
+## 라이선스
+
+[MIT](https://github.com/dongju923/kispilot/blob/main/LICENSE)

{kispilot-0.1.2 → kispilot-0.2.0}/src/kispilot/__init__.py

@@ -1,3 +1,3 @@
 """KISPilot — 한국투자증권 Open API 를 AI 에이전트(MCP)와 웹 콘솔에서 쓰기 위한 도구 모음 (비공식)."""
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"

kispilot-0.2.0/src/kispilot/api/data/_mst.py

@@ -0,0 +1,44 @@
+"""마스터(.mst) 고정 폭 파일 파싱 공통부 — 종목 마스터는 앞부분(코드·이름) + 뒤쪽 고정 폭 필드로 이뤄진다."""
+from __future__ import annotations
+
+import csv
+import io
+from pathlib import Path
+from typing import Optional
+
+import pandas as pd
+
+
+def parse_stock_mst(path: Path, tail_len: int, name_col: str, widths: list[int], columns: list[str]) -> pd.DataFrame:
+    """한 줄 = [단축코드 9][표준코드 12][한글명 …][고정 폭 필드 tail_len] (cp949)."""
+    head, tail = [], []
+    with open(path, encoding="cp949") as f:
+        for row in f:
+            front = row[: len(row) - tail_len]
+            head.append((front[0:9].rstrip(), front[9:21].rstrip(), front[21:].strip()))
+            tail.append(row[-tail_len:])
+    df1 = pd.DataFrame(head, columns=["단축코드", "표준코드", name_col])
+    df2 = pd.read_fwf(io.StringIO("".join(tail)), widths=widths, names=columns)
+    return pd.merge(df1, df2, how="outer", left_index=True, right_index=True)
+
+
+def parse_fixed_bytes_mst(path: Path, fields: list[tuple[str, int, Optional[int]]]) -> pd.DataFrame:
+    """필드 위치가 cp949 바이트 기준으로 고정된 마스터. fields = [(열 이름, 시작, 끝)], 끝이 None 이면 줄 끝까지.
+
+    한글이 2바이트라 문자열로 디코딩한 뒤 문자 위치로 자르면 한글 이름이 있는 줄마다 뒤 필드가 밀린다.
+    그래서 줄을 바이트로 읽어 자른 뒤 필드마다 디코딩한다.
+    """
+    rows = []
+    with open(path, "rb") as f:
+        for line in f:
+            line = line.rstrip(b"\r\n")
+            if line.strip():
+                rows.append([line[a:b].decode("cp949").strip() for _, a, b in fields])
+    return pd.DataFrame(rows, columns=[name for name, _, _ in fields])
+
+
+def parse_pipe_mst(path: Path, columns: list[str]) -> pd.DataFrame:
+    """'|' 로 나뉜 마스터. 코드 앞자리 0 이 사라지지 않게 모든 값을 문자열로 읽는다."""
+    df = pd.read_csv(path, sep="|", header=None, names=columns, dtype=str, encoding="cp949",
+                     keep_default_na=False, quoting=csv.QUOTE_NONE)
+    return df.apply(lambda col: col.str.strip())

kispilot-0.2.0/src/kispilot/api/data/index_fo.py

@@ -0,0 +1,22 @@
+"""지수선물옵션 종목 마스터(fo_idx_code_mts.mst) 파싱. 내려받기·갱신은 master.py 가 한다.
+
+한 줄 = '|' 로 나뉜 9개 필드 (cp949). 예:
+    5|B01612610|KR4B016C6108|C 202612   610.0|2|00610.00| |2001|KOSPI200
+
+열 이름은 한국투자증권 open-trading-api 의 stocks_info/domestic_index_future_code.py 예제를 따른다
+(예제 열 이름 앞 공백은 뺐다). https://github.com/koreainvestment/open-trading-api
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+from kispilot.api.data._mst import parse_pipe_mst
+
+COLUMNS = ["상품종류", "단축코드", "표준코드", "한글종목명", "ATM구분",
+           "행사가", "월물구분코드", "기초자산단축코드", "기초자산명"]
+
+
+def parse(mst: Path) -> pd.DataFrame:
+    return parse_pipe_mst(mst, COLUMNS)

{kispilot-0.1.2 → kispilot-0.2.0}/src/kispilot/api/data/master.py

@@ -1,7 +1,9 @@
 """KIS 종목·업종 마스터 파일 — 내려받기, 하루 한 번 갱신, 검색.
 
 한투가 매일 갱신하는 마스터(.mst.zip)를 받아 CSV 로 바꿔 사용자 데이터 폴더에 둔다.
-    <데이터 폴더>/data/kospi_code.csv · kosdaq_code.csv · idxcode.csv
+    <데이터 폴더>/data/kospi_code.csv · kosdaq_code.csv · idxcode.csv        (주식 · 업종)
+    <데이터 폴더>/data/fo_idx_code_mts.csv                                    (지수선물옵션 — 주간)
+    <데이터 폴더>/data/fo_cme_code.csv · fo_eurex_code.csv                    (KOSPI200 야간선물 · KRX연계 야간옵션)
 
 갱신 규칙
     - 하루에 한 번. 하루의 경계는 오전 7시 (장 시작 전 갱신분을 받도록).
@@ -21,14 +23,14 @@ import time
 import zipfile
 from datetime import datetime, timedelta
 from pathlib import Path
-from typing import Callable, Literal
+from typing import Callable, Literal, get_args
 
 import pandas as pd
 import requests
 
 from kispilot.paths import data_dir
 
-Kind = Literal["kospi", "kosdaq", "sector"]
+Kind = Literal["kospi", "kosdaq", "sector", "index_fo", "night_future", "night_option"]
 
 _BASE_URL = "https://new.real.download.dws.co.kr/common/master/"
 _DAY_STARTS_AT = 7          # 이 시각(로컬) 이전에 받은 파일은 하루 지난 것으로 본다
@@ -37,11 +39,14 @@ _log = logging.getLogger("kispilot.master")
 
 
 def _parsers() -> dict[str, tuple[str, str, Callable[[Path], pd.DataFrame]]]:
-    from kispilot.api.data import kosdaq, kospi, sector
+    from kispilot.api.data import index_fo, kosdaq, kospi, night_future, night_option, sector
     return {
         "kospi": ("kospi_code.mst.zip", "kospi_code.csv", kospi.parse),
         "kosdaq": ("kosdaq_code.mst.zip", "kosdaq_code.csv", kosdaq.parse),
         "sector": ("idxcode.mst.zip", "idxcode.csv", sector.parse),
+        "index_fo": ("fo_idx_code_mts.mst.zip", "fo_idx_code_mts.csv", index_fo.parse),
+        "night_future": ("fo_cme_code.mst.zip", "fo_cme_code.csv", night_future.parse),
+        "night_option": ("fo_eurex_code.mst.zip", "fo_eurex_code.csv", night_option.parse),
     }
 
 
@@ -86,7 +91,7 @@ def refresh(kind: Kind) -> Path:
 
 _cache: dict[str, tuple[datetime, pd.DataFrame]] = {}
 _fail_until: dict[str, float] = {}
-_locks = {k: threading.Lock() for k in ("kospi", "kosdaq", "sector")}
+_locks = {k: threading.Lock() for k in get_args(Kind)}
 
 
 def load(kind: Kind) -> pd.DataFrame:

kispilot-0.2.0/src/kispilot/api/data/night_future.py

@@ -0,0 +1,33 @@
+"""KOSPI200 야간선물 종목 마스터(fo_cme_code.mst) 파싱. 내려받기·갱신은 master.py 가 한다.
+
+예전 CME 연계 야간선물 자리라 파일 이름에 cme 가 남아 있다.
+한 줄 = cp949 바이트 기준 고정 폭 (121바이트). 예:
+    1A01612   KR4A016C0004F 202612          …          00000.0012001     KOSPI200
+
+열 이름은 한국투자증권 open-trading-api 의 stocks_info/domestic_cme_future_code.py 예제를 따른다.
+예제의 row[63:72] 는 행사가(8)에 월물구분코드(1)까지 붙여 읽고 기초자산 코드도 한 칸 밀려 있어,
+야간옵션 마스터(night_option.py)와 같은 꼬리 배치로 고쳐 잡았다.
+https://github.com/koreainvestment/open-trading-api
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+from kispilot.api.data._mst import parse_fixed_bytes_mst
+
+FIELDS = [
+    ("상품종류", 0, 1),
+    ("단축코드", 1, 10),
+    ("표준코드", 10, 22),
+    ("한글종목명", 22, 63),
+    ("행사가", 63, 71),
+    ("월물구분코드", 71, 72),
+    ("기초자산단축코드", 72, 81),
+    ("기초자산명", 81, None),
+]
+
+
+def parse(mst: Path) -> pd.DataFrame:
+    return parse_fixed_bytes_mst(mst, FIELDS)

kispilot-0.2.0/src/kispilot/api/data/night_option.py

@@ -0,0 +1,33 @@
+"""KRX연계 야간옵션 종목 마스터(fo_eurex_code.mst) 파싱. 내려받기·갱신은 master.py 가 한다.
+
+예전 Eurex 연계 야간옵션 자리라 파일 이름에 eurex 가 남아 있다.
+한 줄 = cp949 바이트 기준 고정 폭 (121바이트). 예:
+    5B01610745KR4B016A7454C 202610   745.0          …          200745.00 2001     KOSPI200
+
+필드 위치·열 이름은 한국투자증권 open-trading-api 의 stocks_info/domestic_eurex_option_code.py 예제를 따르되,
+예제는 문자 위치로 자른 뒤 lstrip() 으로 어긋남을 메꾸므로 여기서는 바이트 위치로 고쳐 잡았다.
+월물구분코드 자리(바이트 71)는 옵션이라 비어 있어 뺐다.
+https://github.com/koreainvestment/open-trading-api
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+from kispilot.api.data._mst import parse_fixed_bytes_mst
+
+FIELDS = [
+    ("상품종류", 0, 1),
+    ("단축코드", 1, 10),
+    ("표준코드", 10, 22),
+    ("한글종목명", 22, 59),
+    ("ATM구분", 62, 63),
+    ("행사가", 63, 71),
+    ("기초자산단축코드", 72, 81),
+    ("기초자산명", 81, None),
+]
+
+
+def parse(mst: Path) -> pd.DataFrame:
+    return parse_fixed_bytes_mst(mst, FIELDS)

kispilot-0.2.0/src/kispilot/api/futureoption/__init__.py

@@ -0,0 +1,19 @@
+"""국내선물옵션(주간 · 야간) API 모음.
+
+    from kispilot.api.futureoption import (
+        inquire_price, inquire_asking_price,
+        inquire_daily_fuopchartprice, inquire_time_fuopchartprice,
+    )
+"""
+
+from .futureoption_inquire_price import inquire_price
+from .futureoption_inquire_asking_price import inquire_asking_price
+from .futureoption_inquire_daily_fuopchartprice import inquire_daily_fuopchartprice
+from .futureoption_inquire_time_fuopchartprice import inquire_time_fuopchartprice
+
+__all__ = [
+    "inquire_price",
+    "inquire_asking_price",
+    "inquire_daily_fuopchartprice",
+    "inquire_time_fuopchartprice",
+]

kispilot-0.2.0/src/kispilot/api/futureoption/futureoption_inquire_asking_price.py

@@ -0,0 +1,142 @@
+# 선물옵션 시세호가[v1_국내선물-007]
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+from kispilot.api.config import DOMAIN, REAL_APPKEY, REAL_APP_SECRET, PAPER_APPKEY, PAPER_APP_SECRET
+from kispilot.api.oauth.kis_token import load_token
+from kispilot.api.utils.http_session import get_session
+
+URL = "/uapi/domestic-futureoption/v1/quotations/inquire-asking-price"
+# ※ 실시간 데이터가 필요하면 웹소켓 API를 이용할 것.
+
+_TR_ID = "FHMIF10010000"  # 실전/모의 동일
+
+
+# ── DataClass 정의 ──────────────────────────────────────────
+
+@dataclass
+class ResponseBodyOutput1:
+    hts_kor_isnm: Optional[str] = None                      # HTS 한글 종목명
+    futs_prpr: Optional[str] = None                         # 선물 현재가
+    prdy_vrss_sign: Optional[str] = None                    # 전일 대비 부호 (1 상한, 2 상승, 3 보합, 4 하한, 5 하락)
+    futs_prdy_vrss: Optional[str] = None                    # 선물 전일 대비
+    futs_prdy_ctrt: Optional[str] = None                    # 선물 전일 대비율
+    acml_vol: Optional[str] = None                          # 누적 거래량
+    futs_prdy_clpr: Optional[str] = None                    # 선물 전일 종가
+    futs_shrn_iscd: Optional[str] = None                    # 선물 단축 종목코드
+
+
+@dataclass
+class ResponseBodyOutput2:
+    futs_askp1: Optional[str] = None                        # 선물 매도호가1
+    futs_askp2: Optional[str] = None                        # 선물 매도호가2
+    futs_askp3: Optional[str] = None                        # 선물 매도호가3
+    futs_askp4: Optional[str] = None                        # 선물 매도호가4
+    futs_askp5: Optional[str] = None                        # 선물 매도호가5
+    futs_bidp1: Optional[str] = None                        # 선물 매수호가1
+    futs_bidp2: Optional[str] = None                        # 선물 매수호가2
+    futs_bidp3: Optional[str] = None                        # 선물 매수호가3
+    futs_bidp4: Optional[str] = None                        # 선물 매수호가4
+    futs_bidp5: Optional[str] = None                        # 선물 매수호가5
+    askp_rsqn1: Optional[str] = None                        # 매도호가 잔량1
+    askp_rsqn2: Optional[str] = None                        # 매도호가 잔량2
+    askp_rsqn3: Optional[str] = None                        # 매도호가 잔량3
+    askp_rsqn4: Optional[str] = None                        # 매도호가 잔량4
+    askp_rsqn5: Optional[str] = None                        # 매도호가 잔량5
+    bidp_rsqn1: Optional[str] = None                        # 매수호가 잔량1
+    bidp_rsqn2: Optional[str] = None                        # 매수호가 잔량2
+    bidp_rsqn3: Optional[str] = None                        # 매수호가 잔량3
+    bidp_rsqn4: Optional[str] = None                        # 매수호가 잔량4
+    bidp_rsqn5: Optional[str] = None                        # 매수호가 잔량5
+    askp_csnu1: Optional[str] = None                        # 매도호가 건수1
+    askp_csnu2: Optional[str] = None                        # 매도호가 건수2
+    askp_csnu3: Optional[str] = None                        # 매도호가 건수3
+    askp_csnu4: Optional[str] = None                        # 매도호가 건수4
+    askp_csnu5: Optional[str] = None                        # 매도호가 건수5
+    bidp_csnu1: Optional[str] = None                        # 매수호가 건수1
+    bidp_csnu2: Optional[str] = None                        # 매수호가 건수2
+    bidp_csnu3: Optional[str] = None                        # 매수호가 건수3
+    bidp_csnu4: Optional[str] = None                        # 매수호가 건수4
+    bidp_csnu5: Optional[str] = None                        # 매수호가 건수5
+    total_askp_rsqn: Optional[str] = None                   # 총 매도호가 잔량
+    total_bidp_rsqn: Optional[str] = None                   # 총 매수호가 잔량
+    total_askp_csnu: Optional[str] = None                   # 총 매도호가 건수
+    total_bidp_csnu: Optional[str] = None                   # 총 매수호가 건수
+    aspr_acpt_hour: Optional[str] = None                    # 호가 접수 시간 (HHMMSS)
+
+
+@dataclass
+class ResponseBody:
+    rt_cd: str                          # 성공 실패 여부
+    msg_cd: str                         # 응답코드
+    msg1: str                           # 응답메세지
+    output1: ResponseBodyOutput1        # 시세 요약
+    output2: ResponseBodyOutput2        # 매도/매수 5단계 호가 (문서는 배열이라 하지만 실제 응답은 객체 하나)
+
+
+# ── 요청 함수 ───────────────────────────────────────────────
+
+def inquire_asking_price(
+    code: str,
+    market_div: Literal["F", "O", "JF", "JO", "CF", "CM", "EU"],
+    mode: Literal["real", "paper"] = "real",
+) -> ResponseBody:
+    """선물옵션 시세호가(매도/매수 5단계 호가·잔량·건수)를 조회한다.
+
+    Args:
+        code: 입력 종목코드(FID_INPUT_ISCD), 선물옵션 단축코드(ex A01612 KOSPI200 선물 2026년 12월물).
+        market_div: 조건 시장 분류 코드(FID_COND_MRKT_DIV_CODE). F:지수선물, O:지수옵션, JF:주식선물,
+            JO:주식옵션, CF:상품선물(금·국채·달러), CM:야간선물, EU:야간옵션.
+        mode: "real"(실전투자) 또는 "paper"(모의투자). 기본값 "real".
+
+    Returns:
+        rt_cd/msg_cd/msg1과 시세 요약(output1), 매도/매수 호가(output2)를 담은 ResponseBody.
+    """
+    token = load_token(mode)
+    if mode == "real":
+        app_key, app_secret = REAL_APPKEY, REAL_APP_SECRET
+    else:
+        app_key, app_secret = PAPER_APPKEY, PAPER_APP_SECRET
+
+    headers = {
+        "content-type": "application/json; charset=utf-8",
+        "authorization": f"Bearer {token}",
+        "appkey": app_key,
+        "appsecret": app_secret,
+        "tr_id": _TR_ID,
+        "custtype": "P",
+    }
+    params = {
+        "FID_COND_MRKT_DIV_CODE": market_div,
+        "FID_INPUT_ISCD": code,
+    }
+    response = get_session().get(DOMAIN[mode] + URL, headers=headers, params=params, timeout=10)
+    raw = response.json()
+
+    # 에러 응답(rt_cd != "0")은 output1/output2 키가 없거나 null일 수 있어 안전 파싱.
+    fields1 = set(ResponseBodyOutput1.__dataclass_fields__)
+    raw_output1 = raw.get("output1") or {}
+    output1 = ResponseBodyOutput1(**{k: v for k, v in raw_output1.items() if k in fields1})
+
+    fields2 = set(ResponseBodyOutput2.__dataclass_fields__)
+    raw_output2 = raw.get("output2") or {}
+    output2 = ResponseBodyOutput2(**{k: v for k, v in raw_output2.items() if k in fields2})
+
+    return ResponseBody(
+        rt_cd=raw.get("rt_cd", ""),
+        msg_cd=raw.get("msg_cd", ""),
+        msg1=raw.get("msg1", ""),
+        output1=output1,
+        output2=output2,
+    )
+
+
+# ── 실행 ────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    result = inquire_asking_price(code="A01612", market_div="F")
+    if result.rt_cd != "0":
+        print(f"조회 실패: {result.msg_cd} - {result.msg1}")
+    else:
+        print(result.output1)
+        print(result.output2)