ib-trades-history

IB 交易历史

从 Interactive Brokers 获取成交记录。

IB 连接

必须在本地运行 TWS 或 IB Gateway，并启用 API：

• 模拟交易 — 端口 7497
• 实盘交易 — 端口 7496
• IB_PORT 环境变量 — 未指定 --port 时使用的默认端口（例如，Gateway 容器可设置为 IB_PORT=4001）。优先级：--port 标志 > IB_PORT > 内置默认值。在 shell 或 .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（可重复 — 传入多个 ID 可合并跨不同时间段的查询）
• --file - 本地 FlexReport XML 文件路径（可重复 — 传入多个文件即可合并）。无需 TWS/Gateway
• --group-spreads - 将成交合并为各个腿，并配对为垂直价差。仅适用于 FlexReport 数据源

默认行为（未指定标志）：从实时 API 获取第一个受管理账户的交易。 除非用户要求指定账户，否则始终使用 --all-accounts。

如果环境变量或 .env 中已设置 IB_FLEX_TOKEN／IB_FLEX_QUERY_ID（参见 env.template），则可省略 --flex-token／--flex-query-id。标志的优先级高于环境变量。

数据源

场景	数据源	日期范围
未指定 flex 参数	reqExecutionsAsync	仅限当前会话
--flex-token + --flex-query-id	FlexReport（Web）	按查询配置
--file	file（本地 XML）	完整文件内容

使用实时 API 时，输出中会包含 data_limitation 警告。

实时 API 只返回当前 TWS 会话的数据，尽管 API 文档暗示范围约为“7 天”——周末或查询任何前一日的数据时，它都会返回 0 笔成交，看起来与“没有交易”完全相同。设置 ExecutionFilter.time 也无法扩大范围。要获取今天之前的数据，请使用 FlexReport。Web 服务还受到严格的速率限制（“Statement could not be generated at this time” = 请求受限；大约每个查询每 10–15 分钟只能生成一次）；要查询较长时间范围，建议通过 --file 手动导出 XML。

价差分组（--group-spreads）

将原始成交转化为交易级视图：一个分配到五家交易所的 10 手订单算作一条腿，其开仓腿和 平仓腿合起来算作一个价差。

需要 openCloseIndicator 字段，该字段仅由 FlexReport 数据源提供。在实时 API 路径 中，输出会将 spread_grouping.supported = false，并附上原因，而不会猜测哪些成交是开仓、 哪些是平仓。

腿按 (account, symbol, expiry, right) 作为键 — 有意不包含交易日期，因此在一个交易日 开仓、下一个交易日结算的价差仍会保留其平仓腿。

任何无法明确判定为双行权价垂直价差的交易，都会连同原因保留在 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 是已实现盈亏除以最大风险。 对于铁鹰式价差，两侧价差会作为单独的价差处理 — 将它们的 max_risk 相加会高估实际风险， 因为到期时最多只有一侧会亏损。

如果未连接，请说明 TWS/Gateway 需要处于运行状态。

依赖项

• ib-async