ibkr-api-skill

TWS API（ib_async）または Client Portal REST API を使用して、Roth IRA、個人ブローカレッジ、事業用口座にわたるポートフォリオ照会、取引執行、マルチアカウント管理のための Interactive Brokers（IBKR）連携を構築および管理します。

<quick_start>

1. インストール: pip install ib_async
2. ポート 7497（ペーパー）または 7496（ライブ）で IB Gateway を起動
3. 接続: ib = IB(); await ib.connectAsync('127.0.0.1', 7497, clientId=1)
4. 照会: positions = ib.positions() / summary = await ib.accountSummaryAsync() </quick_start>

<success_criteria>

• API 接続が確立され、認証されている
• リンクされたすべての口座にわたるポートフォリオのポジションと残高が取得されている
• 書き込み操作に IRA の制限が適用されている
• 認証情報が安全に保存されている（ハードコードされていない） </success_criteria>

クイック判断: どの API を使うか？

基準	TWS API（推奨）	Client Portal REST API
最適な用途	自動取引、ポートフォリオ管理	Web ダッシュボード、軽度の利用
認証	TWS/IB Gateway 経由のローカルログイン	OAuth 2.0 JWT
パフォーマンス	非同期、低レイテンシ、高スループット	REST、低速
データ品質	ティックバイティックが利用可能	Level 1 のみ
マルチアカウント	すべての口座に同時アクセス	リクエストごと
インフラストラクチャ	ローカル Java アプリ（ポート 7496/7497）	HTTPS REST 呼び出し
Python ライブラリ	ib_async（推奨）	requests + OAuth
コスト	無料	無料

デフォルトの推奨: すべてのプログラムによる作業には、ib_async ライブラリ経由の TWS API を使用します。

口座アーキテクチャ

Tim の構成: Roth IRA + 個人ブローカレッジ + THK Enterprises（将来の事業用口座）

• すべてが単一の IBKR ユーザー名/パスワードの下にリンクされています
• 単一の API セッションでリンクされたすべての口座にアクセスできます
• reqLinkedAccounts() を使用して口座 ID を列挙します
• 注文発注ごとに口座 ID を指定します
• マーケットデータのサブスクリプションは、リンクされたすべての口座にわたって一度だけ課金されます
• ユーザー名ごとにアクティブなセッションは 1 つ — 別の場所で接続すると現在のセッションが閉じられます

IRA 固有の制限（重要）

制限	影響
空売り不可	placeOrder() は売り注文を拒否します
信用取引による借入不可	現金のみ（借入残高なし）
外貨借入不可	先に FX 取引を執行する必要があります
先物証拠金が 2 倍	ポジションサイジングに影響します
MLP/UBTI 禁止	IRA の注文フローからこれらを除外します
出金は USD のみ	参考情報

コア API 操作

読み取り操作（安全 — すべての口座タイプで使用可能）

# Key TWS API functions for portfolio queries
reqLinkedAccounts()        # List all account IDs
reqAccountSummary()        # Balances, buying power, equity (all accounts)
reqPositions()             # Current positions (up to 50 sub-accounts)
reqPositionsMulti()        # Per-account positions (>50 sub-accounts)
reqAccountUpdates()        # Stream account + position data (single account)
reqMktData()               # Real-time Level 1 market data
reqHistoricalData()        # Historical price data

書き込み操作（注意して使用 — IRA の制限を遵守）

placeOrder(account_id, contract, order)  # Place order on specific account
cancelOrder(order_id)                     # Cancel pending order
reqGlobalCancel()                         # Cancel all open orders

Client Portal REST エンドポイント（代替）

GET  /iserver/accounts                        # List accounts
GET  /iserver/account/{id}/positions          # Positions
GET  /iserver/account/{id}/summary            # Balances
POST /iserver/account/{id}/orders             # Place order
GET  /market/candle                           # Historical candles

Python ライブラリ: ib_async

インストール: pip install ib_async

代替手段ではなく ib_async を選ぶ理由:

• ib_insync のモダンな後継（オリジナル作者のプロジェクトを継続）
• ネイティブの asyncio サポート
• IBKR バイナリプロトコルを内部で実装（公式 ibapi は不要）
• 活発にメンテナンスされている（GitHub: ib-api-reloaded/ib_async）

代替手段（ib_async が要件を満たさない場合のみ使用）:

• ib_insync — レガシー、安定しているが 2024 年初頭以降メンテナンスされていない
• ibapi — 公式 IBKR ライブラリ、扱いにくいイベントループ

リファレンス: 接続パターン

以下については reference/connection-patterns.md を参照してください:

• IB Gateway のセットアップと構成
• 接続/再接続の処理
• セッションタイムアウトの管理（CP API では 6 分ごとの ping）
• マルチアカウントの照会パターン
• エラー処理とレート制限の管理

リファレンス: 取引パターン

以下については reference/trading-patterns.md を参照してください:

• 注文タイプ（成行、指値、逆指値、ブラケット、IB アルゴ）
• IRA セーフな注文検証
• マルチアカウントの注文ルーティング
• 口座タイプを考慮したポジションサイジング
• ギリシャ指標を考慮したオプション注文フロー

インフラストラクチャ要件

1. IB Gateway（軽量）または TWS（フル UI）をローカルで実行
2. Java 8+ がインストールされていること
3. TWS/Gateway の設定で API が有効化されていること
4. ポート: 7496（ライブ）/ 7497（ペーパートレーディング）
5. 認証情報: OS の資格情報マネージャーに保存する（ハードコードは絶対にしない）

セキュリティのベストプラクティス

• IB Gateway は localhost 上でのみ実行する（インターネットに公開しない）
• トレーディングが不要な場合は、ポートフォリオ照会に読み取り専用ログインを使用する
• 認証情報は macOS キーチェーン / Linux secret-service に保存する
• セッションタイムアウトの処理を実装する
• 注文を出す前にマーケットデータのサブスクリプションを検証する
• すべての注文試行をアカウント ID + タイムスタンプとともにログに記録する

コスト構造

項目	コスト
API アクセス	無料
マーケットデータ	取引所ごとのサブスクリプションで月額 $5〜50
取引手数料	標準の IBKR 料率（資産によって異なる）
口座最低額	口座あたり $500
推定合計	最低合計で約 $1,500、データに月額 $15〜50

Trading-Signals スキルとの統合

このスキルは trading-signals-skill を補完します：

• trading-signals → シグナルの生成、コンフルエンススコア、レジーム検出
• ibkr-api → 取引の執行、ポジションの照会、アカウントの管理
• パイプライン: シグナル生成 → ポジションサイジング → IRA 検証 → 注文執行

IBKR MCP サーバー（インストール済み）

ArjunDivecha/ibkr-mcp-server がインストールおよび設定済みです：

• 場所: ~/Desktop/tk_projects/ibkr-mcp-server/
• Claude Code: ~/.claude.json に追加済み（ユーザースコープ）
• Claude Desktop: claude_desktop_config.json に追加済み
• モード: ペーパートレーディング（ポート 7497）、ライブトレーディングは無効
• 安全性: 注文上限 1,000 株、確認必須

利用可能な MCP ツール

ツール	目的	アカウント種別
get_portfolio	ポジション + 損益	すべてのアカウント
get_account_summary	残高、証拠金、買付余力	すべてのアカウント
switch_account	Roth IRA / Personal / THK の切り替え	マルチアカウント
get_market_data	リアルタイム気配値	該当なし
get_historical_data	過去の OHLCV	該当なし
place_order	安全チェック付きの注文	すべて（IRA の制限を適用）
check_shortable_shares	空売り可能株数	Personal/Business のみ
get_margin_requirements	証券ごとの証拠金要件	Personal/Business のみ
get_borrow_rates	空売りの借株コスト	Personal/Business のみ
short_selling_analysis	空売り分析の完全パッケージ	Personal/Business のみ
get_connection_status	IB Gateway のヘルスチェック	該当なし

有効化するには

1. IB Gateway を起動 → ポート 7497（ペーパー）または 7496（ライブ）
2. API を有効化: Config → API → Settings → 「ActiveX and Socket Clients」
3. 信頼済み IP に 127.0.0.1 を追加
4. Claude Code / Claude Desktop を再起動

その他のコミュニティ MCP サーバー

• code-rabi/interactive-brokers-mcp — Client Portal REST API
• xiao81/IBKR-MCP-Server — TWS API に特化
• Hellek1/ib-mcp — ib_async 経由の読み取り専用（最も安全）

マルチブローカー集約

IBKR + Robinhood をまたぐ統合ビューのために：

• SnapTrade MCP（dangelov/mcp-snaptrade） — 読み取り専用アグリゲーター、15 以上の証券会社、OAuth ベース（安全）
• Alpaca MCP（公式） — 本番対応の MCP を備えた代替ブローカー
• フォールバックとして Robinhood からの手動 CSV インポート（ToS に準拠）

集約パターンについては reference/multi-broker-strategy.md を参照してください。

Emit Outcome Sidecar

最後のステップとして、~/.claude/skill-analytics/last-outcome-ibkr-api-skill.json に書き込みます：

{"ts":"[UTC ISO8601]","skill":"ibkr-api-skill","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"queries_executed":[n],"positions_analyzed":[n],"accounts_checked":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

一部のステージが失敗しても結果が生成された場合は、ステータスに「partial」を使用してください。出力がまったく生成されなかった場合にのみ「error」を使用してください。