KIS-Agent — 韓国投資証券 OpenAPI、いまや pip ひとつで

韓国投資証券の OpenAPI を使おうとして公式ドキュメントを開いたものの、すぐ閉じてしまったことがある方のために作りました。
認証トークン管理、Rate Limit の様子見、stck_prpr のようなフィールド名の解読、100件ページネーションのループ――これを毎回自分で書くのが本当に正しいのかと思い、ラッパーとしてまとめました。

何ができるのか
ターミナルから直接:

kis price 005930           # サムスン電子の現在値  
kis balance --holdings     # 口座残高 + 保有銘柄  
kis overseas NAS AAPL      # ナスダック AAPL

コードから:

agent = Agent(app_key=..., app_secret=..., account_no=...)  
price = agent.get_stock_price("005930")  
agent.order_stock_cash("buy", "005930", "03", "1", "0")  # 成行買い

LLM エージェントツールとして:
JSON 出力 + kis schema の型探索により、GPT/Claude のツールコールにそのままつなげられます。

主な解決ポイント

フィールド名の自動変換 — stck_prpr → currentPrice。公式レスポンスをそのまま受け取る必要はありません
Rate Limiting 内蔵 — 実測ベースで 18 RPS / 900 RPM。落ちてから調整する必要なし
キャッシュ — 同一リクエストの繰り返し時に API 呼び出しを 80〜95% 削減
100件制限を回避 — get_daily_price_all() で全期間を自動収集
96個の TypedDict モデル — IDE の自動補完、型チェッカーがすべて動作

対応範囲
国内 (KOSPI/KOSDAQ/NXT) ・海外 9取引所 (NASDAQ, NYSE, 東京、上海、香港、ベトナム など) ・国内外の先物オプション ・WebSocket リアルタイムストリーミング ・投資家/プログラム売買/証券会社別の動向分析

個人トレーディングの自動化を目的に作っているため、実運用で実際によく使うものを中心に実装しています。公式 API にあるのに抜けている機能は、issue を残していただければ追加します。