open-trading-api：把韓國投資證券 Open API 拆成 LLM 可讀的樣本庫

它解決的是導航問題，不是交易問題

韓國投資證券的 Open API 本身涵蓋 국내주식、국내채권、국내선물옵션、해외주식、해외선물옵션、ELW、ETF/ETN 七個商品類別，每個類別底下又有為數不少的端點。對第一次接觸的人來說，真正的門檻往往不是簽名演算法，而是不知道某個功能對應哪個路徑、參數叫什麼、回傳長什麼樣。這個儲存庫的定位就是把這些端點拆成可以逐一打開來看的檔案。README 開頭寫得很直白：샘플 코드는 한국투자증권 Open API(KIS Developers)를 연동하는 예시입니다，並且強調僅供參考、可能隨時更新、造成的損害該公司不負責。

目標讀者寫得很清楚，三類：第一次使用 KIS Open API 的 Python 開發者、已有使用經驗但想學結構的人、以及想用 LLM 程式代理來做종목 검색、시세 분석、자동매매的人。第三類是這個儲存庫相對於同類範例庫最明顯的差異點，整個目錄切法都是繞著「讓模型能沿著路徑找到單一功能」在設計。

如果你的需求只是查一檔股票的目前價位，這裡的樣本足夠；如果你期待的是拿來就能跑的自動交易系統，README 從第一段就在降低這個期待。

examples_llm 與 examples_user 是兩套不同的切法

同一個商品類別在這個儲存庫裡有兩份樣本，切法完全相反。

examples_llm 走功能粒度。以 국내채권 為例，路徑是 examples_llm/domestic_bond/inquire_price/，裡面放兩個檔案：inquire_price.py 是單一功能的呼叫，chk_inquire_price.py 是驗證結果的測試執行檔。每個 API 功能各自一個資料夾，這個結構的用意是讓模型不需要讀完整份文件，只要被指向某個資料夾就能拿到最小可呼叫單元。

examples_user 走商品粒度。同一個 국내채권 底下是 domestic_bond_functions.py（該類別所有 REST 函式的集合）、domestic_bond_examples.py（使用範例）、以及對應的 websocket 版本 domestic_bond_functions_ws.py 與 domestic_bond_examples_ws.py。對人類讀者來說，這種切法更接近實際開發時「我這個商品要用到哪些功能」的思路。

兩套並存不是冗餘。它承認了兩種消費者的檢索方式不同：模型偏好窄而深的單一功能，人偏好寬而整合的類別檔。這種雙軌設計在 API 範例庫裡並不常見，代價是同一段邏輯要維護兩份，README 也明說樣本會持續更新，兩邊同步的成本落在維護方身上。

認證、環境切換與 kis_devlp.yaml

認證邏輯集中在 kis_auth.py，兩個目錄各有一份。README 列出它負責四件事：접근토큰 발급 및 관리、API 호출 공통 함수、실전투자/모의투자 환경 전환、웹소켓 연결 설정。模擬與實戰切換被當成認證層的職責，這點值得留意，因為它意味著環境是透過設定而非程式分支來決定，寫錯設定的後果直接反映在真實帳戶上。

設定檔是 kis_devlp.yaml，預設讀取路徑為 ~/KIS/config/kis_devlp.yaml。README 建議的做法是把專案根目錄的 kis_devlp.yaml 複製過去再改：

mkdir -p ~/KIS/config cp kis_devlp.yaml ~/KIS/config/

要換路徑就改 kis_auth.py 裡的 config_root。金鑰的取得流程不在儲存庫內，README 指向 apiportal.koreainvestment.com，步驟是先開立帳戶並連結 ID、在官網或 App 申請 Open API 服務、取得 App Key 與 App Secret，而且模擬投資與實戰投資要各自準備一組。

環境需求寫得很明確：Python 3.11 以上，並建議使用 uv。安裝指令是 uv sync，uv 本身的安裝在 Windows 用 PowerShell 的 irm 腳本、macOS/Linux 用 curl 腳本。這裡沒有列出任何依賴套件清單，實際裝了什麼要自己看 pyproject.toml 與 uv.lock。

strategy_builder 與 backtester 之間的那個 YAML

除了樣本程式，儲存庫還附了一條 전략 설계 → 백테스팅 → 주문 실행 的管線。分工是：strategy_builder 負責設計策略並產生 BUY/SELL/HOLD 訊號，backtester 負責用歷史資料驗證與參數最佳化，兩者之間靠 .kis.yaml 這個自訂格式交換。README 的流程圖畫得很清楚，strategy_builder 匯出 .kis.yaml 給 backtester，驗證完再回到 strategy_builder，最後才把訊號送進 KIS Open API。

strategy_builder 的說明是 80 個技術指標、10 個預設策略。這 10 個策略在兩個子專案裡是同一份定義，README 逐一列出：골든크로스、모멘텀、52주 신고가、연속 상승/하락、이격도、돌파 실패、강한 종가、변동성 확장、평균회귀、추세 필터，並標註各自屬於 추세추종、돌파매매、역추세、손절、모멘텀 哪一類。

backtester 的技術選擇值得注意：README 寫明它是 Docker 기반 QuantConnect Lean，輸出 HTML 報告。這代表回測能力不是自己實作的，而是包了一層 Lean，好處是策略邏輯可以複用成熟的回測引擎，代價是你多了一個 Docker 依賴，而且 .kis.yaml 到 Lean 之間的轉換層是這個專案自己維護的部分，格式細節要看 strategy_builder/README.md 與 backtester/README.md 的 .kis.yaml 포맷 章節。

另外有一個 MCP/ 目錄，README 描述為 KIS Code Assistant 加 Trading MCP，也就是把這些能力接到 AI 工具上。這是整個儲存庫最貼近「LLM 自動化交易」敘事的部分，但提供資料裡只有一行目錄說明，沒有協定細節。

範例庫的三個實際邊界

第一個邊界是責任歸屬。README 的注意事項寫得很清楚：샘플 코드를 활용하여 제작한 고객님의 프로그램으로 인한 손해에 대해서는 당사에서 책임지지 않습니다。這不是客套話，而是這個專案性質的準確定義。它是券商提供的示範素材，不是有 SLA 的產品，沒有版本號、沒有 release、沒有相容性承諾，README 也說樣本會 별도의 공지 없이 지속적으로 업데이트될 수 있습니다。你如果照著某個 commit 寫好程式，之後儲存庫改了，你的程式不會有任何提示。

第二個邊界是它不處理交易系統本身該有的東西。提供的資料裡，目錄結構涵蓋的是 API 呼叫、策略訊號與回測，看不到部位管理、風控、斷線重連後的狀態復原、下單冪等這類議題的說明。websocket 有對應的 functions_ws.py 與 examples_ws.py，但內容細節不在資料中，無法判斷它對重連與訂閱恢復處理到什麼程度。

第三個邊界是依賴外部服務的形狀。整條管線的終點是 KIS Open API，起點是你在 apiportal 申請到的金鑰，中間的 backtester 還要 Docker。任何一環的環境沒備好，範例就跑不動，而 README 對這些前置條件的描述是清單式的，沒有疑難排解章節。

反過來說，如果你的目的只是理解某個端點怎麼呼叫，這些邊界都不構成阻礙，因為你本來就只需要讀一個資料夾。

什麼時候該改用別的方案

如果你的目標市場不是韓國，這個儲存庫沒有替代價值。它從頭到尾綁定 KIS Developers 的端點、認證與商品分類，換一家券商等於全部重寫。這種情況下你需要的是一套券商無關的抽象層，而不是某一家券商的範例。

如果你的目標是韓國市場但想要的是完整交易框架，可以對照的方向是直接用 QuantConnect Lean。這個儲存庫的 backtester 本身就是 Docker 기반 QuantConnect Lean，也就是說它已經承認回測這件事 Lean 做得比自製好。差別在於 Lean 是通用回測與執行框架，有自己的資料格式與 brokerage 介面，你要自己接上 KIS；這個儲存庫則是反過來，把 KIS 的呼叫範例準備好，再把 Lean 包進來當回測零件。選擇的關鍵是你想從哪一端開始：從券商 API 往上蓋，或從回測框架往下接。

還有一種情況是只需要下單、不需要策略。那 examples_llm 底下的單一功能資料夾就是最短路徑，strategy_builder 與 backtester 反而是多餘的重量，尤其 backtester 還拉進 Docker 與 Lean 兩層依賴。

這三種判斷都不需要跑過專案就能做，因為它們取決於你的目標市場與你想要的抽象層位置，而不是這個儲存庫的執行效能。

維護成本與授權要先自己查清楚

維護成本分兩塊。第一塊是上游變動：README 明說樣本會不定期更新，而這類券商 API 的端點與參數本來就會隨政策調整，所以任何基於範例改寫的程式都應該被當成需要定期對照上游的程式碼，而不是一次寫完就放著。第二塊是雙軌結構的同步：examples_llm 與 examples_user 是同一組功能的兩種切法，strategy_builder 與 backtester 又共用同一份 10 個預設策略的定義，維護方要讓這些保持一致，採用方則要意識到你在其中一邊看到的行為，另一邊未必同步。

依賴管理用 uv 與 uv.lock，這對重現環境是好事，鎖檔讓你知道當初裝了什麼版本。但這也意味著要升級就得動 uv.lock，而 README 沒有提供升級指引。

授權是這篇最需要保留的地方。提供的資料裡 License 欄位是 unknown，儲存庫本身也沒有在 README 中提及授權條款。這不代表沒有授權，只代表我無法從手上的材料確認。在把任何範例程式碼併入商業產品之前，這件事必須自己去儲存庫確認，包括根目錄是否有 LICENSE 檔案、以及 apiportal 的服務條款是否對程式碼使用另有約束。這不是法律意見，只是指出一個在提供的資料中確實空白的位置。

編輯結論

如果你要的是韓國投資證券 KIS Open API 的可執行範例，尤其是想讓 LLM 代理沿著單一功能資料夾去讀取呼叫方式，這個儲存庫的 examples_llm 結構確實比一般 API 文件好導航；如果你要的是一套自帶風控、部位管理與復原機制的下單系統，這裡沒有，README 也明講程式造成的損害由使用者自負。動手前先確認三件事：kis_devlp.yaml 是否已複製到 ~/KIS/config/ 並填入模擬與實戰兩組金鑰、你的 Python 是否達 3.11 以上、以及 backtester 需要的 Docker 環境是否可用。授權條款在提供的資料中未標示，採用前務必自行到儲存庫確認。

官方來源

1. Issues
2. koreainvestment/open-trading-api on GitHub
3. Project website
4. README