regulatory-reporting

监管报告

状态：占位内容 —— 此技能概述了加密货币税务和监管报告方面的计划功能。所有生成的输出都必须由合格的税务专业人士审核后才能提交。此技能中的任何内容均不构成税务或法律建议。

概述

跟踪并生成加密货币交易活动所需的监管报告。涵盖美国联邦表格（IRS Form 8949、Schedule D）、FinCEN 境外账户报告（FBAR）、各州特定的加密货币义务、大额交易标记以及截止日期跟踪。

加密货币税务报告复杂且不断变化。规则经常变更，各司法管辖区采用的成本基础计算方法各不相同，而 DeFi 活动（兑换、LP 仓位、空投、质押奖励）在现行指南下的处理方式也不明确。此技能提供了一个结构化框架，可将交易数据整理为监管机构预期的格式，但每份申报都必须由税务专业人士审核。

免责声明

警告：此技能仅用于提供信息和教育，不构成税务、法律或财务建议。加密货币税法复杂、因司法管辖区而异，且变化迅速。在将此技能的任何输出用于实际税务申报之前，你必须咨询具备加密货币专业知识的合格税务专业人士（CPA、EA 或税务律师）。税务报告中的错误可能导致罚款、利息和法律后果。作者不对任何人使用本材料承担任何责任。

当前状态

此技能目前仍是占位内容。所提供的代码和参考资料只是用于演示数据结构和基本计算的起点，尚未根据当前 IRS 指南或任何州税务机关的要求进行验证。

目前已有

• 根据交易数据生成基本的 Form 8949 项目（参见 scripts/form_8949_generator.py）
• 监管要求概述（参见 references/planned_features.md）
• 使用示例交易数据的演示模式

计划功能

• 完整生成 IRS Form 8949 和 Schedule D PDF
• 外国交易所账户金额超过 $10,000 时生成 FinCEN FBAR
• 检测各州特定的报告要求并提供模板
• 跟踪报告门槛并提供截止日期日历
• 标记大额交易（$10,000 及以上的现金等价交易）
• 境外账户报告要求（FATCA Form 8938）
• 检测并调整洗售（如适用）
• 选择成本基础计算方法（FIFO、LIFO、Specific ID、HIFO）
• 对 DeFi 特定事件进行分类（兑换、LP 进入/退出、质押、空投）
• 输出符合 IRS 要求的实际 CSV/PDF 表格数据

前置条件

# No external dependencies for the demo script
python scripts/form_8949_generator.py --demo

要用于生产环境，还需要以下内容：

uv pip install pandas reportlab  # PDF generation

关键概念

IRS Form 8949 — 资本资产出售和处置

Form 8949 用于报告每笔资本资产出售或处置。对于加密货币，每次交易、兑换或支出事件都属于应税处置。主要字段：

列	描述
(a)	财产描述（例如，“2.5 BTC”）
(b)	取得日期
(c)	出售或处置日期
(d)	收入（以 USD 计的售价）
(e)	成本或其他基础
(f)	调整代码（例如，洗售代码 W）
(g)	调整金额
(h)	盈亏（d 减 e，再按 g 调整）

交易分为第一部分（短期，持有一年或更短）和第二部分（长期，持有超过一年）。

Schedule D — 资本利得和损失

Schedule D 汇总 Form 8949 中的总额：

• 第 1b/8b 行：Form 8949 第一部分/第二部分中的总额（成本基础已向 IRS 报告）
• 第 1c/8c 行：成本基础未向 IRS 报告的总额
• 第 7/15 行：短期/长期资本净利得或损失
• 第 16 行：合并后的净利得或损失

FinCEN FBAR（FinCEN Form 114）

如果日历年内任何时候境外金融账户的合计价值超过 $10,000，则必须申报。存放在境外交易所的加密货币（例如非美国实体使用的 Binance）可能会触发此项要求，不过 IRS 关于加密货币账户是否属于“境外金融账户”的指引仍在不断演变。

• 申报截止日期：4 月 15 日（自动延期至 10 月 15 日）
• 未申报罚款：非故意违规最高罚款 $12,500；故意违规最高罚款 $100,000 或账户余额的 50%

大额交易报告

收到 $10,000 或以上现金的企业（根据近期指引，其中可能包括加密货币）必须在 15 天内提交 IRS Form 8300。个人交易者通常无需提交 Form 8300，但交易所可能会报告大额交易。

快速开始

"""Generate Form 8949 line items from trade history."""
from dataclasses import dataclass
from datetime import date
from decimal import Decimal

@dataclass
class Trade:
    asset: str
    quantity: Decimal
    date_acquired: date
    date_sold: date
    proceeds_usd: Decimal
    cost_basis_usd: Decimal

def classify_holding_period(trade: Trade) -> str:
    """Return 'short-term' or 'long-term' based on holding period."""
    holding_days = (trade.date_sold - trade.date_acquired).days
    return "short-term" if holding_days <= 365 else "long-term"

def compute_gain_loss(trade: Trade) -> Decimal:
    """Compute capital gain or loss for a single trade."""
    return trade.proceeds_usd - trade.cost_basis_usd

# Example
trade = Trade(
    asset="SOL",
    quantity=Decimal("10"),
    date_acquired=date(2025, 1, 15),
    date_sold=date(2025, 8, 20),
    proceeds_usd=Decimal("2500.00"),
    cost_basis_usd=Decimal("1800.00"),
)
gain = compute_gain_loss(trade)
period = classify_holding_period(trade)
print(f"{trade.asset}: {period} gain of ${gain}")
# SOL: short-term gain of $700.00

使用场景

1. 年终报税准备 — 从交易所导出交易历史，生成 Form 8949 明细，计算 Schedule D 总额，并将整理好的数据交给税务专业人士。

2. 季度预缴税跟踪 — 监控全年累计已实现收益，以估算季度预缴税款（IRS Form 1040-ES）。

3. FBAR 门槛监控 — 跟踪境外交易所账户的合计余额，判断是否需要申报 FBAR。

4. 审计准备 — 保存所有资产处置的整理记录及成本基础证明，以备 IRS 查询。

5. 多州申报 — 在交易所在州有额外要求时，识别各州特定的加密货币申报义务。

文件

参考资料

• references/planned_features.md — 法规要求概览、Form 8949/Schedule D 字段说明、FBAR 门槛、各州要求摘要及申报截止日期

脚本

• scripts/form_8949_generator.py — 根据交易数据生成基础 Form 8949 明细的工具，支持 --demo 模式；无外部依赖

局限性

• 不构成法律或税务建议。 这是软件工具，不是税务专业人士。
• 侧重美国。 不涵盖国际税务义务。
• 规则仍在演变。 加密货币税务指引经常变化；此技能可能未反映 IRS 最新通知或裁定。
• 尚未对 DeFi 分类。 尚未处理复杂的 DeFi 事件（LP 头寸、收益耕作、弹性供应代币）。
• 无法确定洗售规则是否适用。 洗售规则是否适用于加密货币尚无定论；此技能会标记潜在洗售，但无法作出确定判断。
• 成本基础方法有限。 示例中仅实现 FIFO；计划支持 LIFO、HIFO 和 Specific ID。

申报截止日期（美国联邦）

表格	截止日期	延期
Form 8949 / Schedule D	4 月 15 日	10 月 15 日（需提交 Form 4868）
FinCEN FBAR（Form 114）	4 月 15 日	10 月 15 日（自动延期）
Form 8300	交易后 15 天	无
FATCA Form 8938	随纳税申报表提交	随纳税申报表延期
1040-ES（季度）	4 月 15 日、6 月 15 日、9 月 15 日、1 月 15 日	无

贡献

这是一个仍有很大扩展空间的占位技能。欢迎在以下方面贡献：

• 更多成本基础方法（LIFO、HIFO、Specific ID）
• DeFi 事件分类（LP 进入/退出、质押、空投、跨链桥接）
• 各州特定要求数据库
• 洗售检测算法
• PDF 表格生成（兼容 IRS 的输出）
• 国际税务管辖区支持
• 与交易所 API 导出格式集成

所有贡献都必须包含适当的免责声明，且不得提供具体税务建议。贡献指南请参阅项目的 CLAUDE.md。

相关技能

• portfolio-analytics — 投资组合绩效跟踪，为税务申报提供数据
• trade-journal — 交易记录，可作为 Form 8949 的源数据