koreainvestment/open-trading-api

**[关于我司提供的示例代码的注意事项]** - 示例代码是集成韩国投资证券 Open API（KIS Developers）的演示示例。旨在减轻您的开发负担，仅供参考。 - 示例代码可能会在不另行通知的情况下持续更新。 - 对于因使用示例代码开发的您的程序所造成的任何损失，我司概不负责。 # KIS Open API 示例代码仓库 (支持 LLM) ## 1. 制作意图及目标受众 ### 🎯 制作意图 本仓库旨在让 **ChatGPT、Claude 等 LLM（Large Language Model）** 自动化环境与 Python 开发者 **都能轻松理解并使用韩国投资证券（Korea Investment & Securities）的 Open API**，为此整理了这套示例代码合集。 - `examples_llm/`: 面向 LLM 的功能单元示例代码，使 LLM 能够轻松探索并调用单一 API 功能 - `examples_user/`: 面向用户的集成 API 调用示例代码，用户可利用其实现实际投资及自动化交易 - `strategy_builder/`: 通过可视化 UI 设计交易策略，并根据生成的信号执行买入/卖出 - `backtester/`: 使用历史数据验证所设计策略的回测引擎 [前往韩国投资证券 Open API 门户](https://apiportal.koreainvestment.com/) ### 👤 目标用户 - 首次使用韩国投资证券 Open API 的 Python 开发者 - 现有 Open API 用户中，需要改善代码及学习系统架构的用户 - 希望利用基于 LLM 的代码代理实现股票搜索、行情分析、自动化交易等功能的用户 ## 2. 文件夹结构及主要文件说明 ### 2.1. 文件夹结构 ``` # 项目结构 . ├── README.md # 프로젝트 설명서 ├── strategy_builder/ # 전략 설계 + 시그널 생성 엔진 ← New ├── backtester/ # 백테스팅 엔진 (QuantConnect Lean) ← New │ ├── docs/ │ └── convention.md # 코딩 컨벤션 가이드 ├── examples_llm/ # LLM용 샘플 코드 │ ├── kis_auth.py # 인증 공통 함수 │ ├── auth # 인증(토큰 발급) │ │ ├── auth_token # REST 접근토큰 발급 │ │ └── auth_ws_token # 웹소켓 접속키 발급 │ ├── domestic_bond # 국내채권 │ │ └── inquire_price # API 단일 기능별 폴더 │ │ ├── inquire_price.py # 한줄 호출 파일 (예: 채권 가격 조회) │ │ └── chk_inquire_price.py # 테스트 파일 (예: 채권 가격 조회 결과 검증) │ ├── domestic_futureoption # 국내선물옵션 │ ├── domestic_stock # 국내주식 │ ├── elw # ELW │ ├── etfetn # ETF/ETN │ ├── overseas_futureoption # 해외선물옵션 │ └── overseas_stock # 해외주식 ├── examples_user/ # user용 실제 사용 예제 │ ├── kis_auth.py # 인증 공통 함수 │ ├── auth # 인증(토큰 발급) │ │ ├── auth_functions.py # 인증 함수 모음 │ │ └── auth_examples.py # 인증 실행 예제 │ ├── domestic_bond # 국내채권 │ │ ├── domestic_bond_functions.py # (REST) 통합 함수 파일 (모든 API 함수 모음) │ │ ├── domestic_bond_examples.py # (REST) 실행 예제 파일 (함수 사용법) │ │ ├── domestic_bond_functions_ws.py # (Websocket) 통합 함수 파일 │ │ └── domestic_bond_examples_ws.py # (Websocket) 실행 예제 파일 │ ├── domestic_futureoption # 국내선물옵션 │ ├── domestic_stock # 국내주식 │ ├── elw # ELW │ ├── etfetn # ETF/ETN │ ├── overseas_futureoption # 해외선물옵션 │ └── overseas_stock # 해외주식 ├── legacy/ # 구 샘플코드 보관 ├── stocks_info/ # 종목정보파일 참고 데이터 ├── kis_devlp.yaml # API 설정 파일 (개인정보 입력 필요) ├── pyproject.toml # (uv)프로젝트 의존성 관리 └── uv.lock # (uv)의존성 락 파일 ``` ### 2.2. 支持的主要 API 类别 - 以下类别及文件夹结构同样适用于 examples_llm/ 和 examples_user/ 文件夹。 | 类别 | 说明 | 文件夹名 | | --- | --- | --- | | 认证 | 发放访问令牌、发放 WebSocket 接入密钥 | `auth` | | 国内股票 | 国内股票行情、订单、余额等 | `domestic_stock` | | 国内债券 | 国内债券行情、订单等 | `domestic_bond` | | 国内期货期权 | 国内衍生品相关 | `domestic_futureoption` | | 海外股票 | 海外股票行情、订单等 | `overseas_stock` | | 海外期货期权 | 海外衍生品相关 | `overseas_futureoption` | | ELW | ELW 行情 API | `elw` | | ETF/ETN | ETF、ETN 行情 API | `etfetn` | ### 2.3. 主要文件说明 ### `examples_llm/` - 面向 LLM 的功能单元示例代码 **各 API 独立文件夹结构**：将单一 API 功能分离至独立文件夹，以便 LLM 轻松探索相关代码 - **单行调用文件**：`[函数名].py` – 调用单一功能的最小化代码 (例如: `inquire_price.py`) - **测试文件**：`chk_[函数名].py` – 验证调用结果的测试运行代码 (例如: `chk_inquire_price.py`) ### `examples_user/` - 面向用户的集成示例代码 **各类别独立文件夹结构**：整合每个类别（产品）的所有功能，方便用户轻松探索并运行示例代码 - **集成函数文件**：`[类别]_functions.py` - 整合了该类别所有 API 功能的函数合集 - **运行示例文件**：`[类别]_examples.py` - 基于实际使用案例的运行代码 - **WebSocket 集成函数文件及运行示例文件**：`[类别]_functions_ws.py`, `[类别]_examples_ws.py` ### `kis_auth.py` - 认证及公共功能 - 访问令牌发放及管理 - API 调用公共函数 - 支持实盘/模拟投资环境切换 - 提供 WebSocket 连接设置功能 ### 2.4. AI 交易工具 除示例代码外，还提供了利用 Open API 实现的 **策略设计 → 回测 → 订单执行** pipeline。 ``` graph LR SB[strategy_builder] -->|".kis.yaml"| BT[backtester] BT -->|"검증 완료"| SB SB -->|"BUY/SELL/HOLD"| KIS[KIS Open API] ``` | 目录 | 作用 | 详情 | |----------|------|------| | `strategy_builder/` | 策略设计 + 信号生成 | 80个技术指标，10个预设策略，BUY/SELL/HOLD 信号 ([README](strategy_builder/README.md)) | | `backtester/` | 历史回测 + 参数优化 | 基于 Docker 的 QuantConnect Lean，HTML 报告 ([README](backtester/README.md)) | | `MCP/` | AI 工具连接 | KIS Code Assistant + Trading MCP ([README](MCP/README.MD)) | #### 10个预设策略 `strategy_builder` 和 `backtester` 双方均提供支持。 | # | 策略名 | 类型 | 简要说明 | |---|--------|------|-----------| | 01 | 金交叉 | 趋势跟随 | 短期移动平均线向上突破长期移动平均线时买入 | | 02 | 动量 | 趋势跟随 | 买入近 N 日收益率较高的标的 | | 03 | 52周新高 | 突破交易 | 收盘价刷新 52 周最高价时买入 | | 04 | 连续上涨/下跌 | 趋势跟随 | 连续 N 日收盘价上涨时买入，连续 N 日下跌时卖出 | | 05 | 乖离率 | 逆势 | 根据收盘价/移动平均线比率判断过热（卖出）或低迷（买入） | | 06 | 突破失败 | 止损 | 突破前高后再次回落时止损 | | 07 | 强势收盘 | 动量 | 收盘价在当日最高价附近报收时买入 | | 08 | 波动率扩张 | 突破交易 | 波动率收敛后急剧上涨时买入 | | 09 | 均值回归 | 逆势 | 价格大幅偏离均值时向反方向交易 | | 10 | 趋势过滤器 | 趋势跟随 | 在长期移动平均线上方上涨时买入 | #### .kis.yaml — 共享策略格式 在 `strategy_builder` 中设计的策略导出为 `.kis.yaml` 后，可直接在 `backtester` 中导入进行回测。 格式详情请参考 [strategy_builder/README.md](strategy_builder/README.md#kisyaml-포맷) 或 [backtester/README.md](backtester/README.md#kisyaml-포맷)。 ## 3. 前置环境配置指南 ### 3.1. Python 环境要求 - 需要 **Python 3.11 及以上版本** - 推荐使用 **uv** **包管理器** （快速且便捷的依赖管理） ### 3.2. uv 安装方法 - 为简化配置，推荐使用 uv ``` # Windows (PowerShell) powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # 安装确认 uv --version # uv 0.x.x ... -> 安装完成 ``` ### 3.3. 项目克隆及环境配置 ``` # 克隆仓库 git clone https://github.com/koreainvestment/open-trading-api cd open-trading-api # 使用 uv 安装依赖 - 一行搞定 uv sync ``` ### 3.4. KIS Open API 申请及设置 🍀 [前往服务申请指南](https://apiportal.koreainvestment.com/about-howto) 1. 韩国投资证券 **开户及关联 ID** 2. 在韩国投资证券官网或 App 中申请 **Open API 服务** 3. 获取 **App Key**, **App Secret** 4. 分别准备 **模拟投资** 及 **实盘投资** 的 App Key ### 3.5. kis_devlp.yaml 设置 - 为配置您的账户信息，需修改 `kis_devlp.yaml` 文件。 - 默认路径为 `~/KIS/config/kis_devlp.yaml`。如果文件夹不存在，请先创建。 - 建议将项目根目录下的 `kis_devlp.yaml` 复制到 `~/KIS/config/` 后再进行修改。 - 如果想要更改路径，只需修改 `kis_auth.py` 中的 `config_root` 值即可。 ``` # 创建设置文件夹并复制文件 mkdir -p ~/KIS/config cp kis_devlp.yaml ~/KIS/config/ ``` 1. 打开 `~/KIS/config/kis_devlp.yaml` 文件 2. 输入 **App Key 和 App Secret** 信息 3. 输入 **HTS ID** 信息 4. 输入 **账号** 信息 (区分前 8 位和后 2 位) 5. **保存** 后关闭 ``` # 实盘交易 my_app: "여기에 실전투자 앱키 입력" my_sec: "여기에 실전투자 앱시크릿 입력" # 模拟交易 paper_app: "여기에 모의투자 앱키 입력" paper_sec: "여기에 모의투자 앱시크릿 입력" # HTS ID（KIS Developers 客户 ID） - 用于成交通知、查看我的条件列表等。 my_htsid: "사용자 HTS ID" # 账号前 8 位 my_acct_stock: "증권계좌 8자리" my_acct_future: "선물옵션계좌 8자리" my_paper_stock: "모의투자 증권계좌 8자리" my_paper_future: "모의투자 선물옵션계좌 8자리" # 账号后 2 位 my_prod: "01" # 종합계좌 # my_prod: "03" # 国内期货期权账号 # my_prod: "08" # 海外期货期权账号 # my_prod: "22" # 个人养老金账号 # my_prod: "29" # 退休养老金账号 # User-Agent（建议使用默认值，无需更改） my_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" ``` ### 3.6. 运行文件内的认证设置检查 - 请在需要运行的文件中检查或修改认证相关设置。若要使用国内股票全部功能，请查看 `domestic_stock/domestic_stock_examples.py` 文件。 如下方所示修改 ka.auth() 函数的 svr, product 参数，即可在实盘环境(prod)下使用委托账户(-01)进行交易测试。 ``` import kis_auth as ka # 实盘交易认证 ka.auth(svr="prod", product="01") # 모의투자: svr="vps" ``` ### 3.7. 策略构建器 / 回测器环境配置 (可选) 若需使用策略设计及回测功能，需进行额外配置。 | 项目 | 安装 | 用途 | |------|------|------| | Node.js 18+ | [nodejs.org](https://nodejs.org/) | strategy_builder, backtester 前端 | | Docker Desktop | [docker.com](https://www.docker.com/products/docker-desktop) | backtester (Lean 引擎) | ## 4. 示例代码运行 ### 4.1. 示例代码运行 - **以 examples_user 为标准** ``` # 国内股票示例代码运行 (examples_user/domestic_stock/) uv run python domestic_stock_examples.py # REST 방식 uv run python domestic_stock_examples_ws.py # Websocket 방식 ``` 因为 domestic_stock_examples.py 包含了多个函数，请仅保留您要使用的函数，注释掉其余部分，修改输入值后再进行调用。 - **以 examples_llm 为标准** ``` # 国内股票 > 股票当前价行情示例代码运行 (examples_llm/domestic_stock/inquire_price/) uv run python chk_inquire_price.py ``` examples_llm 中各功能的独立运行文件 (chk_*.py) 已分离，非常适合在仅测试特定功能时使用。 ### 4.2. 示例代码样本 (examples_user) ``` # REST API 调用示例 - domestic_stock_examples.py import sys import logging import pandas as pd sys.path.extend(['..', '.']) import kis_auth as ka from domestic_stock_functions import * # logging 设置 logging.basicConfig(level=logging.INFO, format='%(levelname)s - %(message)s') logger = logging.getLogger(__name__) # 认证 ka.auth() trenv = ka.getTREnv() # 查询三星电子当前价行情 result = inquire_price(env_dv="real", fid_cond_mrkt_div_code="J", fid_input_iscd="005930") print(result) ``` ``` # WebSocket 调用示例 - domestic_stock_examples_ws.py import sys import logging import pandas as pd sys.path.extend(['..', '.']) import kis_auth as ka from domestic_stock_functions_ws import * # logging 设置 logging.basicConfig(level=logging.INFO, format='%(levelname)s - %(message)s') logger = logging.getLogger(__name__) # 认证 ka.auth() ka.auth_ws() trenv = ka.getTREnv() # WebSocket 声明 kws = ka.KISWebSocket(api_url="/tryitout") # 订阅三星电子、SK海力士实时报价 kws.subscribe(request=asking_price_krx, data=["005930", "000660"]) ``` ### 4.3. 策略构建器 / 回测器运行 ``` # Strategy Builder (策略设计 + signal) cd strategy_builder ./start.sh # Backtester (backtesting) cd backtester ./start.sh ``` 详细的运行方法请参考各目录下的 README： - [strategy_builder/README.md](strategy_builder/README.md) - [backtester/README.md](backtester/README.md) ## 5. 问题排查指南 ### 令牌错误时 ``` import kis_auth as ka # Token 重新签发 - 每分钟签发 1 次。 ka.auth(svr="prod") # 또는 "vps" ``` ### 配置文件错误时 - 检查 `kis_devlp.yaml` 文件中的 App Key、App Secret 是否正确 - 检查账号格式是否匹配 (前 8 位 + 后 2 位) - 如果在使用实时行情 (WebSocket) 时出现 'No close frame received' 错误，请检查您在 `kis_devlp.yaml` 中输入的 HTS ID 是否准确 ### 依赖错误时 ``` # 重新安装依赖 uv sync --reinstall ``` ### Docker 错误 (backtester) ``` docker info # Docker Desktop 실행 상태 확인 docker images | grep lean # Lean 이미지 확인 (첫 실행 시 자동 다운로드) ``` ### 超出每秒交易请求数限制 (`EGW00201`) 模拟投资账户的 REST API 调用限制较低。 单一查询没有问题，但如果是像参数优化这样需要大量连续调用的场景，建议使用实盘投资账户。 # 📧 咨询事项 - 请随时在 [💬 韩国投资证券 Open API 聊天机器人](https://chatgpt.com/g/g-68b920ee7afc8191858d3dc05d429571-hangugtujajeunggweon-open-api-seobiseu-gpts) 中提问您遇到的疑惑。

标签：API SDK, LLM集成, MITM代理, Python, 回测系统, 无后门, 自动交易, 证券交易, 请求拦截, 逆向工具, 量化交易