一个用于计算富途证券交易税务的 Python 工具，支持股票和期权交易的税务计算，使用移动加权平均算法计算成本基础。
公司解禁RSU股票的税务处理有特殊规定：
- 成本计算原则: RSU股票交易与普通股票交易合并计算，使用移动加权平均算法统一核算成本价
- 分红分离原则: 股票交易盈亏与股息分红分开计算，盈亏不能互相抵消
- 双重税务责任:
- 授予时: 按行权日收市价计算个人所得税（公司代扣代缴）
- 卖出时: 如卖出价格高于行权日收市价，差价部分需自行申报缴纳20%个人所得税
场景：2024年1月15日授予100股，行权日收市价$150
2024年2月10日普通买入100股@$160
2024年3月20日卖出150股@$180
计算：
- RSU授予成本: $150/股 × 100股 = $15000
- 普通买入成本: $160/股 × 100股 = $16000
- 移动加权平均成本: ($15000 + $16000) ÷ 200股 = $155/股
- 卖出150股盈利: ($180 - $155) × 150股 = $3750
脚本处理：
- 在futu_rsu_history.csv中记录授予($150)
- 系统将RSU与普通交易合并，按移动加权平均算法计算统一成本价
- 生成包含所有股票交易的综合税务报告
# 1. 创建虚拟环境
python3 -m venv venv
# 2. 激活虚拟环境
source venv/bin/activate
# 3. 安装依赖
pip install -r requirements.txt- 配置富途API → 2. 下载交易数据 → 3. 计算税务 → 4. 查看报告
下载地址在这个文档里 https://openapi.futunn.com/futu-api-doc/opend/opend-cmd.html
如果访问不了，记得翻墙切全局 非大陆 IP
可直接下载 MacOs 的 版本
这里以 MacOsGUI 版本为例，下载后解压缩，打开Futu_OpenD-GUI_9.4.5418_Mac，里面安装 DMG，然后默认登录，首次设备需短信验证
涉及美股滞纳金，汇率以当年最后一个工作日查询汇率 可以在官方汇率网站查询 如果 12.31 号不是工作日，则往前找最后一个工作日
http://m.safe.gov.cn/safe/rmbhlzjj/index.html#
# 下载股息和股息税数据（耗时可能需要约2小时）
python futu/download_cash_flow.py
默认股息流水路径是 data/futu_cash_flow.csv
特别说明
- 这个 csv 包含了默认 3 年前所有股息&股息税流水，打开 csv 文件自行过滤年份&货币统计每年股息
- 港股只有股息，没有股息税，
- 美股有点特殊，流水里包含有-10% 扣掉的股息税
# 步骤1: 下载交易数据
python futu/download_history_flow.py
# 步骤2: 计算税务并生成报告
python tax/stock_option_tax_calculator.py
# 步骤3: 查看生成的报告
ls 税务报告/如有公司解禁股票交易，必须在 data/ 目录下创建 futu_rsu_history.csv：
记录特殊说明
- 授予记录，也就是 buy 这条记录，所有券商，例如Futu 及中银国际都需要填写，没法通过 Api 获取
- 卖出记录，也就是 sell 这条记录，
- 如果是 Futu，无需填写，可通过脚本自动获取
- 其他券商卖出，例如中银国际则需要手动填写，没法通过 Api 获取
填写要求:
- 股票代码(非我司 查询 Futu 股票代号)： 固定 HK.00700，
- 数量及成交价格: 查询 公司解禁页面
- 买卖方向： 授予填 buy, 卖出则是 sell
- 结算币种：固定 HKD
- 合计手续费：富途卖出无需填写，可自动获取，中银国际需要自己填卖出
- 交易时间(参考, 你改日期就行)：2025/7/23 17:00
示例:
股票代码,数量,成交价格,买卖方向,结算币种,合计手续费,交易时间
HK.00700,100,150.00,buy,HKD,0.00,2024-01-15 09:30:00
HK.00700,50,180.00,sell,HKD,0.50,2024-03-20 14:30:00
HK.00700,50,175.00,sell,HKD,0.50,2024-04-10 11:15:00
注意 ：
- 在你所属公司授予记录里有所有包括中银及富途的授予记录，里面有授予日的成本价，我们计算增值盈利需要基于这个成本价 合并计算，否则就会出现
- 富途无法获取授予记录，但可以自动获取卖出记录及手续费
- 其他券商请手动登记买入及卖出记录 配置好后重新计算税务报告即可，无需重新下载数据
# 计算税务并生成报告
python tax/stock_option_tax_calculator.py
如果你是在本机运行，而且没有更改 FutuOpenD 端口，则忽略此环境配置
如果你不是本地运行 FutuOpenD，
记得添加 .env 文件，里面编辑，
FUTU_ADDRESS=127.0.0.1
FUTU_PORT=11111
FUTU_ENV=REAL
# 如果非本地连接，需配置RSA密钥路径
# FUTU_RSA=path/to/your/rsa/key
- 同年完整买卖交易
- 跨年部分卖出
- 当年买次年卖
- 复杂交易场景
⚠️ 仅卖出无买入（标记需人工核查）⚠️ 卖空股票（标记需人工核查）
- 期权做多/做空（同年/跨年）
- 期权到期处理（作废/获利）
- 复杂混合交易场景
- 100倍合约乘数自动处理
- 股票期权混合交易
- RSU解禁股票处理
- 多币种交易（USD/HKD）
- 无效数据容错处理
- 长桥平台（需额外配置）
- 轮证、涡轮、期货
- 公司解禁的期权（不了解）
- 安装富途OpenD网关并启动，确保本地11111端口可用
- 如需跨网非本地访问配置：参考富途OpenAPI文档设置私钥（需翻墙访问）
- 创建配置文件：在项目根目录新建
.env文件：
# 富途API配置
FUTU_ADDRESS=127.0.0.1
FUTU_PORT=11111
FUTU_ENV=REAL
# 如果非本地连接，需配置RSA密钥路径
# FUTU_RSA=path/to/your/rsa/key# 下载历史成交订单（耗时约10-30分钟）
python futu/download_history_flow.py
# 生成文件: data/futu_history.csv# 下载股息和股息税数据（耗时约2小时）
python futu/download_cash_flow.py
# 生成文件: data/futu_cash_flow.csv如有公司解禁股票交易，必须在 data/ 目录下创建 futu_rsu_history.csv：
股票代码,数量,成交价格,买卖方向,结算币种,合计手续费,交易时间
US.AAPL,100,150.00,buy,USD,0.00,2024-01-15 09:30:00
US.AAPL,50,180.00,sell,USD,0.50,2024-03-20 14:30:00
US.AAPL,50,175.00,sell,USD,0.50,2024-04-10 11:15:00
配置说明：
- buy记录: 使用行权日收市价，手续费填0
- sell记录: 使用实际卖出价格和手续费
- 数据来源: 授予价格查公司解禁页面，卖出记录需手动添加
- 计算逻辑: 系统将RSU交易与普通股票交易合并，使用移动加权平均算法统一计算成本价
# 使用默认配置计算税务
python tax/stock_option_tax_calculator.py
# 自定义输入输出路径
python tax/stock_option_tax_calculator.py --input data/my_trades.csv --output my_reports/# 运行测试用例验证算法正确性
python tax/test_calculator.py生成的报告位于 税务报告/ 目录：
2024_report.csv- 2024年度税务报告2023_report.csv- 2023年度税务报告- 按币种分别汇总年度盈亏
股票代码,数量,成交价格,买卖方向,结算币种,合计手续费,交易时间
US.AAPL,100,150.00,buy,USD,1.00,2024-01-15 09:30:00
US.AAPL240315C160000,1,5.50,sell,USD,0.65,2024-03-01 15:30:00
- 格式：
US.{股票代码}{到期日YYMMDD}{C/P}{行权价} - 示例：
US.AAPL240315C160000= 苹果2024年3月15日到期160美元看涨期权
- 买入时: 买入成本 = 价格 × 数量 + 手续费
- 平均成本: (原持仓成本 + 新买入成本) ÷ 总持仓数量
- 卖出时: 盈亏 = (卖出价格 × 数量 - 手续费) - (平均成本 × 数量)
买入100股@$10，手续费$1 → 总成本$1001，平均成本$10.01
买入200股@$15，手续费$2 → 总成本$3002，平均成本$13.34
卖出150股@$20，手续费$1.5 → 盈利$998.5，剩余150股@$13.34
项目包含15个完整测试场景，确保计算准确性：
| 场景类型 | 测试用例 | 验证重点 |
|---|---|---|
| 股票交易 | 01-05 | 同年交易、跨年交易、复杂场景 |
| 期权交易 | 06-13 | 做多做空、到期处理、复杂场景 |
| 综合场景 | 14-15 | 混合交易、异常数据处理 |
# 运行所有测试用例
python tax/test_calculator.py
# 查看测试结果
✅ 验证通过: 2024_report.csv 与 test_data_2024.csv 一致
🎉 所有测试用例均已通过！futu_tax_calculator/
├── 📂 data/ # 数据文件
│ ├── futu_history.csv # 标准化交易数据
│ ├── futu_cash_flow.csv # 股息现金流数据
│ └── futu_rsu_history.csv # RSU解禁数据（可选）
├── 📂 futu/ # 数据获取模块
│ ├── download_history_flow.py
│ └── download_cash_flow.py
├── 📂 tax/ # 税务计算模块
│ ├── stock_option_tax_calculator.py
│ └── test_calculator.py
├── 📂 test_data/ # 测试用例（15个场景）
├── 📂 税务报告/ # 生成的年度报告
├── requirements.txt # Python依赖
└── ReadMe.md # 项目文档
A: 确保FutuOpenD已启动，端口11111可用，检查.env配置文件
A: 期权自动乘以100倍合约乘数，无需手动调整
A: 盈利计入卖出年度，成本基础自动结转到下一年
A: 创建futu_rsu_history.csv文件，手动添加授予和卖出记录
A: 如需支持长桥平台，可参考 stock_tax_calculator 项目的实现方式
MIT License - 详见 LICENSE 文件
感谢 stock_tax_calculator 项目，为 Futu 拉取流水订单提供了启发。
-
download_history_flow.py: 批量下载交易订单，支持多账户和限流保护
- 连接管理：支持本地和远程富途OpenD网关
- 批量下载：按3个月为批次分段下载，避免API限制
- 费用查询：自动批量查询订单手续费信息
- 限流保护：内置请求频率限制器（30秒内最多9次请求）
-
download_cash_flow.py: 下载股息数据，自动识别USD/HKD股息和税费
- 股息识别：自动识别美股股息和股息税
- 港股支持：识别港股现金种子分红
- 去重处理：基于cashflow_id自动去除重复记录
-
stock_option_tax_calculator.py: 核心计算引擎，支持股票期权混合计算
- 移动加权平均：买入时更新平均成本，卖出时按平均成本计算盈亏
- 期权处理：支持做多/做空双向交易，100倍合约乘数计算
- 跨年处理：盈利计入卖出年度，成本基础正确结转
-
test_calculator.py: 自动化测试框架，15个场景验证计算准确性
- 用例发现：自动遍历test_data/下所有测试用例
- 结果对比：基于股票代码和时间创建唯一键进行匹配
- 测试验证：输出详细的通过/失败信息
- 期权处理: 100倍合约乘数，支持做多做空，自动处理到期
- 异常处理: 智能标记无买入记录、卖超持仓等异常情况
- 跨年处理: 盈利计入卖出年度，成本基础正确结转
- 重要提醒: 富途已退出大陆运营，文档地址需翻墙访问，IP不可为中国大陆
- 端口配置: 默认11111端口，可根据实际情况在.env中调整
- 跨网设置: 非本地连接需配置RSA密钥路径
- 查询限制: 只支持逐日查询，30秒内最多20次请求
- 识别规则:
- USD: cashflow_remark包含"SHARES DIVIDENDS"或"SHARES WITHHOLDING TAX"
- HKD: cashflow_type为"现金种子"
- 耗时预估: 查询2022-2024年数据约需2小时
- 手动配置: 需在data目录下创建futu_rsu_history.csv
- 数据来源: 公司解禁页面查看授予价格和记录
- 平台限制: 中银国际无API，需手动添加卖出记录