IBKR Finance Analysis

Interactive Brokers (IBKR) Flex Query 数据分析 CLI。这个版本面向 AI 和脚本调用：非交互、默认 JSON 输出、stdout 只放结果。

功能

• 通过 IBKR Flex API 同步全量历史数据
• 按 365 天窗口从新到旧拉取，遇到无可用报表后停止
• 保存最新全量快照索引，启动时自动加载最新数据
• 输出账户总览、周期盈亏、持仓、交易、股息、股息退税和佣金
• 股息退税基于 Cash Transactions 和 Statement of Funds 中已入账的真实现金流水识别

配置

复制配置示例文件：

cp config.example.toml config.toml

编辑 config.toml，填入 IBKR Flex API 信息：

token = "your_personal_access_token_here"
account_id = "U1234567"
data_dir = "./data"

[queries]
trades = "your_query_id_here"

account_id 用于输出中标识账户。它是可选字段；如果不配置，程序会从 Flex Query 返回的 XML 中读取账户 ID。

IBKR Flex Query

推荐创建一个覆盖分析所需数据的 XML query。

基础配置：

配置项	值
时间范围	Last 365 Calendar Days
输出格式	XML
Date Format	yyyy-MM-dd
Time Format	HH:mm:ss TimeZone
Date/Time Separator	;

建议勾选的 Sections：

• Cash Report
• Cash Transactions
• Statement of Funds
• Open Positions
• Trades
• Transfers

Cash Transactions 建议至少包含：

• Dividends
• Payment in Lieu of Dividends
• Withholding Tax
• Deposits & Withdrawals

使用

统一使用 Go module 入口：

go run . <command>

不要使用 go run *.go，因为 shell 会把 *_test.go 也传给 go run。

给 AI 或脚本集成时，推荐先构建二进制，避免 go run 在非零退出码时额外向 stderr 输出 exit status 1：

go build -o ibkr .
./ibkr summary

命令

go run . sync
go run . summary
go run . pnl --period month
go run . positions
go run . trades --limit 50 --symbol SCHD
go run . dividends
go run . tax-refunds
go run . commissions
go run . snapshot

全局参数：

go run . --pretty summary

pnl --period 支持：

• month
• 1m
• 6m
• ytd
• 1y
• all

输出格式

成功：

{
  "ok": true,
  "command": "summary",
  "account_id": "U1234567",
  "as_of": "20260525",
  "data": {}
}

失败：

{
  "ok": false,
  "command": "summary",
  "error": {
    "code": "NO_DATA",
    "message": "无可用数据，请先执行 sync"
  }
}

数据口径

• 账户总览的持仓和现金使用最新报表窗口的快照。
• 已实现盈亏按 FIFO 计算，并归属到真实平仓日期。
• pnl 里的 income = 已实现盈亏 + 净股息收入 + 股息退税。
• 周期盈亏分析不计算未实现变化；当前未实现盈亏只在 summary 和 positions 中展示。
• 股息退税只统计已经出现在 Cash Transactions 或 Statement of Funds 中的真实到账记录。
• Tax Receivables 显示为待收税款，它是报表里的待收项目，不等同于已经到账的退税。

项目结构

.
├── main.go             # 程序入口和数据同步
├── cli.go              # CLI 命令和 JSON 输出
├── config.go           # 配置加载
├── flex/               # IBKR Flex API 客户端和 XML 类型
├── analysis/           # 数据分析模块
└── data/               # 本地 XML 数据和快照索引