ib-trades-history

IB の取引履歴

Interactive Brokers から取引の約定履歴を取得します。

IB の接続

TWS または IB Gateway をローカルで起動し、API を有効にしておく必要があります。

• ペーパートレード — ポート 7497
• ライブトレード — ポート 7496
• IB_PORT 環境変数 — --port を省略した場合のデフォルトポートです（例：Gateway コンテナの場合は IB_PORT=4001）。優先順位：--port フラグ > IB_PORT > 組み込みのデフォルト値。シェルまたは .env ファイルに設定してください。

ポートのフォールバック： 設定されたポートへの接続に失敗した場合、もう一方のポートで自動的に再試行します。 再試行に成功した場合は、どちらの口座タイプ（ライブ／ペーパー）が機能したかをメモリに保存し、このセッションおよび今後のセッションにおけるすべての IB スキルの呼び出しで再利用します。ユーザーがもう一方の口座を明示的に要求するまで、この設定を保持します。 どちらのポートでも接続できない場合は、TWS または IB Gateway が起動しており、API アクセスが有効になっているかユーザーに確認してもらってください。

約 7 日を超える全取引履歴を取得するには、ユーザーは Flex Web Service トークンと、IBKR Account Management で事前に設定した Trade クエリが必要です。

手順

注： uv がインストールされていない場合、または pyproject.toml が見つからない場合は、以下のすべてのコマンドで uv run python を python に置き換えてください。

# Recent trades (last ~7 days via API)
uv run python .claude/skills/ib-trades-history/scripts/trades.py --all-accounts

# Filter by symbol
uv run python .claude/skills/ib-trades-history/scripts/trades.py --all-accounts --symbol AAPL

# Full history via FlexReport
uv run python .claude/skills/ib-trades-history/scripts/trades.py --all-accounts --flex-token YOUR_TOKEN --flex-query-id YOUR_QUERY_ID

# Custom date range (FlexReport)
uv run python .claude/skills/ib-trades-history/scripts/trades.py --all-accounts --flex-token TOKEN --flex-query-id QID --start-date 2025-01-01 --end-date 2025-12-31

# Multiple queries (e.g., one per year to exceed 365-day limit)
uv run python .claude/skills/ib-trades-history/scripts/trades.py --all-accounts --flex-token TOKEN --flex-query-id QID_2025 --flex-query-id QID_2026 --start-date 2025-01-01 --end-date 2026-12-31

# From local FlexReport XML files (no TWS/Gateway needed)
uv run python .claude/skills/ib-trades-history/scripts/trades.py --file trades_2024.xml --file trades_2025.xml --symbol TSLA

# Mix files with date filtering
uv run python .claude/skills/ib-trades-history/scripts/trades.py --file exports/2025.xml --start-date 2025-06-01 --end-date 2025-12-31

# Group option fills into vertical spreads (credit, width, max risk, capture %, RoR)
uv run python .claude/skills/ib-trades-history/scripts/trades.py --file exports/2026.xml --symbol NDX --group-spreads

引数

• --port - IB ポート（デフォルト：ペーパートレードの場合は 7497）
• --account - フィルター対象の特定の口座 ID
• --all-accounts - 管理対象のすべての口座の取引を取得
• --symbol - 銘柄で取引をフィルター（例：AAPL）
• --start-date - 開始日（YYYY-MM-DD 形式。デフォルト：現在の年の 1 月 1 日）
• --end-date - 終了日（YYYY-MM-DD 形式。デフォルト：今日）
• --flex-token - FlexReport トークン（長期間の履歴を取得）
• --flex-query-id - FlexReport クエリ ID（繰り返し指定可能 — 異なる期間を対象とする複数のクエリを統合する場合は、複数指定してください）
• --file - ローカルの FlexReport XML ファイルのパス（繰り返し指定可能 — 複数のファイルを統合する場合は、複数指定してください）。TWS／Gateway は不要です
• --group-spreads - 約定をレッグに統合し、それらを組み合わせてバーティカル・スプレッドにします。FlexReport ソースのみ

デフォルトの動作（フラグなし）：ライブ API から最初の管理対象口座の取引を取得します。 特定の口座をユーザーが指定していない限り、必ず --all-accounts を使用してください。

IB_FLEX_TOKEN／IB_FLEX_QUERY_ID が環境変数または .env に設定されている場合（env.template を参照）、--flex-token／--flex-query-id は省略できます。フラグは環境変数より優先されます。

データソース

シナリオ	ソース	日付範囲
Flex 関連の引数なし	reqExecutionsAsync	現在のセッションのみ
--flex-token + --flex-query-id	FlexReport（ウェブ）	クエリで設定した範囲
--file	file（ローカル XML）	ファイル全体の内容

ライブ API を使用する場合、出力には data_limitation の警告が含まれます。

**API のドキュメントには「約 7 日」と記載されていますが、ライブ API が返すのは現在の TWS セッションのデータのみです。**週末や前日以前を対象に取得すると約定数は 0 になり、「取引なし」と同じように見えます。ExecutionFilter.time を設定しても取得範囲は広がりません。今日より前のデータを取得する場合は、FlexReport を使用してください。ウェブサービスには非常に厳しいレート制限があります（「Statement could not be generated at this time」は制限中を意味し、概ねクエリごとに 10～15 分に 1 回の生成が可能です）。長期間を遡って取得する場合は、--file で手動エクスポートした XML を優先してください。

スプレッドのグループ化（--group-spreads）

約定データをトレード単位のビューに変換します。5つの取引所に分けて発注した10枚の注文は1つのレッグとなり、オープンレッグとクローズレッグは1つのスプレッドになります。

openCloseIndicator フィールドが必要です。このフィールドを提供するのは FlexReport ソースのみ です。ライブ API 経由の場合は、どの約定がオープンでどれがクローズかを推測せず、理由とともに spread_grouping.supported = false を出力します。

レッグは (account, symbol, expiry, right) をキーにします。意図的に取引日は含めていないため、あるセッションでオープンし、翌日に決済されたスプレッドもクローズレッグが維持されます。

明確な2ストライクのバーティカルではないものは、すべて ungrouped_legs に残し、spread_grouping.warnings に理由を記載します。不適切なスプレッドに無理に当てはめることはありません。対象には、ロール、レシオスプレッド、同一満期・権利種別の複数のバーティカル、単独レッグ、未決済のポジション、対象期間より前にオープンしたポジションのクローズが含まれます。

spread_grouping.reconciled は、スプレッドの損益とグループ化されていない損益の合計が、約定全体の損益と一致することを示します。レポートを信頼する前に、この値を確認してください。

出力

次の内容を含む JSON を返します。

• connected - 接続に成功したかどうか
• source - 使用したデータソース（reqExecutionsAsync または FlexReport）
• filters - 適用したフィルター（日付、銘柄、口座）
• data_limitation - API の日付制限に関する警告（ライブ API の使用時のみ）
• execution_count - 返された約定の合計数
• executions - 個々のトレード約定の一覧
• summary - 銘柄ごとの集計統計（買い、売り、手数料、実現損益）

--group-spreads を指定した場合は、さらに次の内容を含みます。

• legs / leg_count - 部分約定を注文単位にまとめたもの
• spreads / spread_count - ペアになったバーティカル。それぞれに type（Bear call / Bull put / Bull call / Bear put）、short_strike、long_strike、width、lots、credit、 max_credit、max_risk、entry_date / entry_time、exit_date / exit_time、 realizedPnL、commission、netPnL、capture_pct、return_on_risk_pct、 settled_at_expiry、same_day が含まれます
• ungrouped_legs - 明確なバーティカルではないレッグ（空でない場合のみ）
• spread_grouping - supported、warnings、ungrouped_leg_count と、 reconciled / execution_pnl / spread_pnl / ungrouped_pnl の検算結果

max_risk は、リスクが限定されたバーティカルを前提としています。計算式は (width − credit) × lots × multiplier です。 capture_pct は、最大クレジットに対する実現損益の割合です。return_on_risk_pct は、最大リスクに対する実現損益の割合です。アイアンコンドルでは2つのウィングが別々のスプレッドになります。満期時に損失が発生するのは片側のみのため、両者の max_risk を合計すると、実際のエクスポージャーを過大評価します。

接続されていない場合は、TWS/Gateway の起動が必要であることを説明してください。

依存関係

• ib-async