open-trading-api：韩国投资证券官方 API 的 Python 样例仓库，以及它新加的 LLM 与策略工具链
Korea Investment & Securities Open API Github
秒懂
- 它是什么？
- 这个仓库不是 SDK，而是韩国投资证券（KIS）Open API 的官方样例代码集合，最近扩展出 examples_llm、strategy_builder、backtester 和 MCP 四条支线。核心判断：它省掉的是摸索接口参数的时间，不省掉的是账户风险与接口变更风险。
- 适合谁用？
- 适合已经或计划开通韩国投资证券账户、需要用 Python 对接 KIS Open API 的开发者，尤其是想让 LLM 代理去检索单接口调用方式的场景；不适合只想拿一个封装好的 pip 包、不愿读样例代码的人，也不适合把它当成交易系统骨架的人，README 明确写了样例代码可能随时更新且公司不承担因使用样例造成的损失。动手前先确认三件事：能否拿到 실전투자 与 모의투자 两套 앱키，Python 版本是否达到 3.11，以及 ~/KIS/config/kis_devlp.yaml 这个默认路径在你的部署环境里是否可写。
- 能商用吗？
- 未经许可不能。GitHub 在这个仓库里没有找到许可证文件；没有许可证，默认即「保留所有权利」：你可以阅读代码，但不能复用。使用前请看看 README，或先征得作者同意。
- 还在维护吗？
- 在维护。仓库最近一次提交在 21 天前。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是找参数的问题，不是写策略的问题
KIS Open API 的接口数量按商品线铺开：국내주식、국내채권、국내선물옵션、해외주식、해외선물옵션、ELW、ETF/ETN，每条线下又有行情、下单、余额等不同端点。真正消耗时间的往往不是业务逻辑，而是搞清某个端点该传哪些字段、返回体长什么样。这个仓库的定位就在这里：README 第一段直接写明，样例代码是“연동하는 예시”，为了减轻客户开发负担而提供参考。
目标读者被 README 分成三类：第一次用 KIS Open API 的 Python 开发者、已有使用者中想参考代码结构的人、以及想用 LLM 代码代理去做종목 검색、시세 분석、자동매매 的人。第三类是这份材料里最值得注意的变化，因为仓库为此专门提供了 llms.txt，并单独拆出 examples_llm 目录。换句话说，它假设读者可能是 ChatGPT 或 Claude，而不只是人。
需要说清楚的是边界：这不是一个发布到 PyPI 的客户端库，仓库里没有 SDK 式的统一入口类。你拿到的是可复制、可修改的调用样例，接口契约本身由 KIS 的 API 门户定义，仓库只是它的镜像与示范。
两套样例目录的分工：examples_llm 按接口切，examples_user 按商品切
同一个仓库里放了两份并行样例，切分逻辑不同，这是它最实用的设计。
examples_llm 按单个 API 功能建独立文件夹，每个文件夹里两个文件：inquire_price.py 这样的一行调用文件，以及 chk_inquire_price.py 这样的结果校验文件。README 的说法是，这样切是为了让 LLM 容易检索到相关代码。对检索型代理来说，目录名即语义，一个文件夹对应一个端点，命中率确实比读一个几千行的聚合文件高。
examples_user 则按商品聚合：domestic_bond_functions.py 放该类别所有 REST 函数，domestic_bond_examples.py 放用法示例，WebSocket 版本另起 domestic_bond_functions_ws.py 与 domestic_bond_examples_ws.py。这是给人读的组织方式，你要写 국내주식 的完整流程时，翻一个文件就够。
代价是重复。同一套接口在 examples_llm 与 examples_user 里各维护一份，认证逻辑 kis_auth.py 也是两边各有一个副本。仓库用 legacy/ 目录保留旧样例，说明历史上样例发生过整体换代。读代码时如果发现两份实现不一致，优先以你实际要跑的那一份为准，不要默认它们同步。
认证与配置：kis_devlp.yaml 的默认路径是个要留意的前提
认证相关功能集中在 kis_auth.py：접근토큰 발급与管理、API 调用公共函数、실전투자/모의투자 环境切换、WebSocket 连接设置。examples_llm 与 examples_user 各自带一份。
配置走 kis_devlp.yaml。README 给出的默认路径是 ~/KIS/config/kis_devlp.yaml，并建议把仓库根目录的这份文件复制过去再改。给出的命令是 mkdir -p ~/KIS/config 与 cp kis_devlp.yaml ~/KIS/config/。如果不想用这个路径，README 说可以改 kis_auth.py 里的 config_root 值。
这里有两个实际约束值得提前想。第一，默认路径在用户主目录下，容器化或 CI 环境里要么挂载卷，要么改 config_root，否则认证文件找不到。第二，README 要求准备모의투자 与 실전투자 两套 앱키，也就是说配置里至少要能区分两套凭据，切换环境不是改一个布尔值那么简单。
凭据获取的流程 README 也列了：先在韩国投资证券开户并连接 ID，再通过官网或 App 申请 Open API 服务，然后拿到 앱키 与 앱시크릿。这一步在仓库之外完成，仓库不提供任何绕过方式。
环境搭建：Python 3.11 起，uv sync 一步装依赖
README 对环境的要求写得很明确：Python 3.11 以上，推荐用 uv 管理依赖。依赖清单在 pyproject.toml，锁文件是 uv.lock，两者都在仓库根目录，说明这是一个用 uv 管理的项目而不是散装的 requirements.txt。
安装 uv 的命令 README 给了三行：Windows 用 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"，macOS/Linux 用 curl -LsSf https://astral.sh/uv/install.sh | sh，然后用 uv --version 确认。之后是 git clone https://github.com/koreainvestment/open-trading-api、cd open-trading-api、uv sync。
注意 uv.lock 的存在意味着依赖版本被锁住了。这对复现样例行为是好事，但也意味着如果你的项目本身有自己的依赖树，把这里的版本直接搬过去可能冲突。更稳的做法是只把样例当参考，在自己的项目里按需引入，而不是把整个仓库当依赖源。
仓库根目录还列了 stocks_info/ 存放종목정보 참고 데이터，以及 docs/convention.md 作为编码规范。后者对想给仓库提 PR 的人有用，对只想调用接口的人可以跳过。
strategy_builder 与 backtester：靠 .kis.yaml 串起来的两段管道
这是仓库里最新的部分，README 用一张 mermaid 图描述流程：strategy_builder 导出 .kis.yaml 给 backtester，backtester 验证完成后回到 strategy_builder，最终由 strategy_builder 向 KIS Open API 发出 BUY/SELL/HOLD 信号。
strategy_builder 的 README 声称有 80 个技术指标、10 个预设策略，产出 BUY/SELL/HOLD 信号，并且提供可视化 UI 来设计策略。backtester 基于 Docker 化的 QuantConnect Lean，产出 HTML 报告，支持参数优化。两者都支持同一份 10 个预设策略清单，README 逐条列了出来：골든크로스、모멘텀、52주 신고가、연속 상승/하락、이격도、돌파 실패、강한 종가、변동성 확장、평균회귀、추세 필터。
.kis.yaml 是这两个组件之间的契约。README 说格式细节在 strategy_builder/README.md 与 backtester/README.md 的对应小节里，主 README 没有展开。这意味着如果你要自己生成或解析这个格式，得去翻子目录文档，主文档给的信息到此为止。
把回测引擎选成 QuantConnect Lean 是个有分量的决定。好处是策略表达能力和报告能力不用自己造；代价是引入 Docker 依赖，而且 Lean 有自己的策略模型，.kis.yaml 到 Lean 策略之间必然有一层转换，这层转换的行为在主 README 里看不到。
MCP 与 llms.txt：面向代理的接口，但边界由代理自己把握
仓库提供了 llms.txt，README 的开头就把它放在显眼位置，说明目的是让 ChatGPT、Claude 等 LLM 与 AI 代理更容易浏览这个仓库。MCP/ 目录则被描述为 KIS Code Assistant 加 Trading MCP，指向 MCP/README.MD。
这个方向的意图很清楚：让代理自己去找某个端点怎么调，而不是人去翻目录。examples_llm 的目录结构正是为这种检索服务的。
但这里有个必须点明的落差。仓库给代理提供的是调用样例，不是调用护栏。样例里包含下单类接口，代理如果直接照抄执行，风险由使用者承担。README 在开头用一段注意事项划了责任：样例可能不另行通知就更新，因使用样例所制程序造成的损失公司不负责。这段话放在最前面不是客套，它是这个仓库法律与运维边界的正式表述。
所以 MCP 这条线更适合做检索与代码生成，把它直接接到实盘下单路径上，需要你自己加确认环节，仓库不提供。
什么时候它不合适：没有许可证信息，也没有发布版本
从仓库元数据看，许可证一栏是未知，也没有检索到任何 release。这两点合起来意味着：你无法从仓库层面确认代码的使用授权范围，也无法通过版本号锁定一个稳定快照。README 自己也说样例代码可能不另行通知持续更新。
对个人研究这通常不是问题，对要把样例代码嵌入商业产品或受审计环境的团队，这就是必须先解决的前置问题。授权问题需要直接联系韩国投资证券或查阅 API 门户条款，仓库本身给不出答案。
另一类不合适的情形是把它当交易框架用。仓库提供的是样例、策略设计器、回测器和 MCP 连接，没有仓位管理、风控限额、订单状态机、断线重连后的持仓对账这些实盘必需件。WebSocket 样例能连上行情，但连接断了之后怎么恢复，样例层面不涉及。
还有一点：样例是韩文注释与韩文命名的目录结构，函数名和字段名也以韩文业务概念为主。对不熟悉韩国市场术语的开发者，理解 국내선물옵션 与 해외선물옵션 的差别、이격도 这类指标的含义，本身就是额外成本。
替代路线：自己封装客户端，还是继续用官方样例
Python 生态里存在社区维护的 KIS Open API 封装库，它们把认证、限流、重试、类型定义收进一个可 import 的包，用 pip 安装即可，接口以 Python 类和方法的形式暴露。这个仓库走的是相反的路：不封装，只示范。
差别体现在三处。第一，升级方式。社区库通过版本号发布变更，你可以锁版本；这个仓库的样例是持续更新的文件，你复制走之后就和上游脱钩，上游改了字段你不会有通知。第二，覆盖范围。社区库通常只覆盖作者用到的接口子集；这个仓库按商品线把 국내주식、국내채권、국내선물옵션、해외주식、해외선물옵션、ELW、ETF/ETN 都列了目录，覆盖面由官方决定。第三，正确性来源。社区库的正确性靠使用者和测试；这个仓库的正确性靠官方，但 README 明确不承诺。
实际选择往往不是二选一。用这个仓库确认字段与调用顺序，把确认过的部分固化进自己的封装层，是这个仓库最自然的用法。它的 examples_user 目录本来就是按这个思路组织的：函数文件加示例文件，你拿走的是函数，不是框架。
编辑结论
适合已经或计划开通韩国投资证券账户、需要用 Python 对接 KIS Open API 的开发者，尤其是想让 LLM 代理去检索单接口调用方式的场景；不适合只想拿一个封装好的 pip 包、不愿读样例代码的人，也不适合把它当成交易系统骨架的人，README 明确写了样例代码可能随时更新且公司不承担因使用样例造成的损失。动手前先确认三件事：能否拿到 실전투자 与 모의투자 两套 앱키，Python 版本是否达到 3.11，以及 ~/KIS/config/kis_devlp.yaml 这个默认路径在你的部署环境里是否可写。
社区笔记