koreainvestment/open-trading-api を採用前に読む: サンプルコード集とバックテスターの境界
Korea Investment & Securities Open API Github
ひと目でわかる
- これは何？
- 韓国投資証券のOpen APIをPythonから呼ぶためのサンプルコード集であり、LLM向けの機能単位サンプルと人間向けの統合サンプルが同居する。戦略設計からバックテストまでのパイプラインも同梱されるが、まず確認すべきはサンプルの位置づけとライセンスの不在である。
- 誰に向いている？
- 韓国投資証券のAPIをこれから触るPython開発者、とくにLLMエージェントにAPI呼び出しを探索させたい人にとって、examples_llm の機能単位フォルダ構成は出発点として合理的である。逆に、サンプルをそのまま本番の自動売買に載せたい人には向かない。
- 商用利用できる？
- 許可なしにはできません。GitHub はこのリポジトリにライセンスファイルを見つけていません。ライセンスがなければ、原則としてすべての権利が留保され、コードを読むことはできても再利用はできません。使う前に README を確認するか、作者に問い合わせてください。
- 今もメンテナンスされている？
- されています。最後のコミットは 21 日前です。
- 何の言語で書かれている？
- 主に Python です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
このリポジトリが埋めるのは「API仕様」と「動くコード」の間の溝
韓国投資証券のOpen APIは、ポータルに仕様が並んでいる。だが仕様書から実際にトークンを取り、相場を引き、注文を出すまでの配線は利用者側の作業になる。このリポジトリはその配線をPythonのサンプルとして配っている。対象は、韓国投資証券のOpen APIを初めて使うPython開発者、既存の利用者でコード構成を見直したい人、そしてLLMベースのコードエージェントに銘柄検索や自動売買を組み立てさせたい人だとREADMEは説明している。つまり純粋なライブラリではなく、参照実装の集合体である。READMEの冒頭には「샘플 코드는 한국투자증권 Open API(KIS Developers)를 연동하는 예시입니다」とあり、顧客の開発負担を減らすための参考提供だと位置づけられている。この一文が、このリポジトリをどう扱うべきかをほぼ決めている。
examples_llm と examples_user は同じAPIを別の粒度で切っている
ディレクトリは二系統に分かれる。examples_llm はAPI単機能ごとに独立したフォルダを切り、その中に「한줄 호출 파일」として [関数名].py、検証用に chk_[関数名].py を置く。たとえば domestic_bond/inquire_price の下に inquire_price.py と chk_inquire_price.py が並ぶ形で、READMEはこれを 채권 가격 조회 の例として挙げている。LLMが探索するとき、候補となるファイルが一つに絞られる構造だ。
examples_user は逆で、カテゴリ単位に統合する。domestic_bond なら domestic_bond_functions.py にそのカテゴリのAPI関数をまとめ、domestic_bond_examples.py に使い方を示す。WebSocketは domestic_bond_functions_ws.py と domestic_bond_examples_ws.py に分かれる。カテゴリは auth、domestic_stock、domestic_bond、domestic_futureoption、overseas_stock、overseas_futureoption、elw、etfetn の8つで、両フォルダに同じ分類が適用される。人間が読むなら functions と examples の対、LLMに探させるなら機能単位フォルダ、という使い分けが想定されている。
認証は kis_auth.py と kis_devlp.yaml の二点に集約される
共通の認証処理は examples_llm/kis_auth.py と examples_user/kis_auth.py が担う。READMEによれば、アクセスティッカー発行と管理、API呼び出しの共通関数、実投資とモック投資の環境切替、WebSocket接続設定がここに入る。認証そのものは auth フォルダに分かれ、REST用の auth_token とWebSocket用の auth_ws_token が置かれる。
設定値は kis_devlp.yaml に書く。既定の探索先は ~/KIS/config/kis_devlp.yaml で、フォルダがなければ作成する必要がある。READMEが示す手順は次のとおり。
mkdir -p ~/KIS/config cp kis_devlp.yaml ~/KIS/config/
ルートの kis_devlp.yaml をコピーしてから編集する流れを推奨している。探索先を変えたい場合は kis_auth.py の config_root を書き換える。アプリキーとアプリシークレットは、実投資用とモック投資用をそれぞれ用意するようREADMEは求めている。ここで注意したいのは、設定ファイルがホームディレクトリ配下に置かれる設計だ。リポジトリをcloneしただけでは認証情報が読まれず、cp を忘れると原因の分かりにくい失敗になる。
strategy_builder と backtester は .kis.yaml でつながる
サンプルコード以外に、戦略設計からバックテスト、注文実行までのパイプラインが同梱される。READMEのmermaid図では、strategy_builder が .kis.yaml を出力し、backtester がそれを受け取り、検証結果を strategy_builder に返し、最終的に BUY/SELL/HOLD が KIS Open API に渡る流れが描かれている。
strategy_builder は80個の技術指標、10個のプリセット戦略、BUY/SELL/HOLDシグナルを扱うとされ、비주얼 UI で戦略を設計する。backtester は Docker ベースの QuantConnect Lean を使い、HTMLレポートを出す。プリセットは 골든크로스、모멘텀、52주 신고가、연속 상승/하락、이격도、돌파 실패、강한 종가、변동성 확장、평균회귀、추세 필터 の10種で、strategy_builder と backtester の両方で同一のものが使えるとREADMEは述べている。加えて MCP/ ディレクトリがあり、KIS Code Assistant と Trading MCP を提供する。
ここで読者は二つの問いを持つはずだ。QuantConnect Lean を Docker で動かす前提は、手元の環境でどれだけの準備を要求するのか。そして、このバックテスターが扱うデータの範囲はどこまでか。READMEからは後者を判断できない。
サンプルであることと、ライセンスが書かれていないこと
READMEは「샘플 코드는 별도의 공지 없이 지속적으로 업데이트될 수 있습니다」と明記し、サンプルを使って作ったプログラムによる損害について会社が責任を負わないとしている。自動売買の文脈でこの一文は重い。動くコードが置いてあることと、そのコードを本番の注文経路に置いてよいことは別である。
もう一点、提供されたリポジトリ情報ではライセンスが unknown となっている。READMEにもライセンス表記は見当たらない。サンプルコードを社内プロダクトに取り込む、あるいは改変して再配布する場合、この不在は無視できない。法的助言はここではできないが、採用を検討する組織は、コードを取り込む前に権利関係を確認する必要がある。ライセンスが明示されていない公開リポジトリからのコード流用は、技術的な問題ではなく手続きの問題として先に片付けるべきものだ。
同様に、サンプルが継続的に更新されうるという宣言は、逆に言えば互換性が固定されないということでもある。examples_llm の関数単位ファイルを自分のコードにコピーして育てるなら、上流の変更を追う負担は利用者側にある。
代替として何を選ぶか: 自作クライアントか、Leanに寄せるか
このリポジトリの代替は二方向ある。一つは、韓国投資証券のAPI仕様を読みながら薄いクライアントを自分で書くこと。サンプルを読む手間は増えるが、依存するファイルが自分の管理下に入り、READMEが予告する「予告なしの更新」に振り回されない。認証とレート制限の扱いを自分で決められる点は、注文系の処理では利点になる。
もう一つは、バックテスト部分を QuantConnect Lean 側に寄せること。このリポジトリの backtester はそもそも Docker ベースの Lean を使うとREADMEに書かれている。ならば戦略の検証をLeanの作法で書き、KISへの発注だけをこのリポジトリのサンプルから取る、という分割も成立する。strategy_builder の비주얼 UI と .kis.yaml という共有フォーマットを捨てることになるが、検証環境を一つのツールチェーンに統一できる。どちらが良いかは、戦略をUIで組みたいか、コードで書きたいかで決まる。
導入前に潰しておくべき三つの確認
第一に、Python 3.11以上とuvが前提になる。READMEは uv sync を「한줄로 끝」と表現し、pyproject.toml と uv.lock をリポジトリに置いている。既存のプロジェクトがpipとrequirements.txtで回っているなら、仮想環境を分けてから uv sync を試すのが安全だ。
第二に、モック投資と実投資のアプリキーを両方用意できるか。READMEの手順は、계좌 개설、Open API 서비스 신청、앱키と앱시크릿 발급、そして 모의투자와 실전투자 각각のキー準備、という順に並ぶ。実投資用のキーしか持たない状態でサンプルを走らせるのは避けたい。
第三に、backtester を動かすなら Docker と QuantConnect Lean を受け入れる覚悟があるか。HTMLレポートが出るという記述はあるが、必要なデータの入手方法や実行時間についてはREADMEから読み取れない。ここは実際に手を動かすまで分からない領域だと正直に言っておく。サンプルの位置づけ、ライセンスの不在、設定ファイルがホームディレクトリにあること。この三点を確認せずに使い始めると、後から効いてくる。
編集部の結論
韓国投資証券のAPIをこれから触るPython開発者、とくにLLMエージェントにAPI呼び出しを探索させたい人にとって、examples_llm の機能単位フォルダ構成は出発点として合理的である。逆に、サンプルをそのまま本番の自動売買に載せたい人には向かない。README自身が「샘플 코드는 별도의 공지 없이 지속적으로 업데이트될 수 있습니다」と述べ、プログラムによる損害の責任を負わないと明記している。採用判断の前に、リポジトリにライセンス表記が見当たらない点と、kis_devlp.yaml の config_root が既定で ~/KIS/config を指す点を確認し、モック投資用と実投資用のアプリキーをそれぞれ用意できるかを先に確かめてほしい。
コミュニティノート