tax-liability-tracking

税务负债跟踪

专为活跃的 Solana 交易者打造的实时税务负债分析。跟踪部分卖出时按比例分摊的成本基础，将已实现收益与未实现收益分类，预测季度纳税义务，并提供可反馈至交易决策的税务信号。

为什么这很重要

活跃的加密货币交易者每年会产生数百笔应税事件。如果没有实时跟踪：

• 直到年末，你都不知道实际的税后盈亏
• 部分卖出（“回本后用剩余筹码获利”的操作）会造成成本基础混乱
• 短期与长期的分类会使你的实际税率相差 15-20%
• 你可能未察觉税损收割的时机窗口已经关闭
• 季度预缴税款只能靠猜测

此技能会在你的交易活动中同步维护税务台账，让每项决策都考虑其税务影响。

核心概念

部分卖出的比例成本基础

这是最关键的概念。卖出部分持仓时，成本基础会按比例分摊，而不会变为零并留给剩余代币。

示例 — 积累／“回本后用剩余筹码获利”的操作：

1. 买入：以每枚 $1.00 的价格买入 1,000 枚代币。总成本基础 = $1,000。
2. 部分卖出：以每枚 $1.25 的价格卖出 800 枚。所得 = $1,000。
3. 实际情况：
   • 卖出的 800 枚代币按比例分摊的成本基础 = 800 x $1.00 = $800
   • 此次卖出的已实现收益 = $1,000 - $800 = $200
   • 剩余 200 枚代币保留的成本基础 = 200 x $1.00 = $200
   • 剩余代币并非“免费”——它们仍保留原来的单位成本

常见错误：将部分卖出记录为“已收回本金，剩余成本基础 = $0”。这会低估部分卖出时的已实现收益，并高估最终卖出剩余代币时的收益。无论采用哪种记录方式，应缴税额总计相同，但纳税时间和分类（短期与长期）可能会有显著差异。

收益分类

分类	持有期限	美国联邦税率（2024）
短期资本收益	< 1 年	普通所得税率（10-37%）
长期资本收益	>= 1 年	0%、15% 或 20%

每个税务批次都会记录自己的取得日期。部分卖出会按照你的会计方法（FIFO、LIFO 或特定识别法）指定的顺序扣减批次。

以 SOL 计价的交易与 USD 报告

Solana 交易者通常以 SOL 为单位进行思考，但美国的纳税义务以 USD 计价。每笔应税事件都需要：

1. 取得时的 SOL 价格 — 用于确定 USD 成本基础
2. 处置时的 SOL 价格 — 用于确定 USD 所得
3. 两次事件时的代币 SOL 价格 — 通过 SOL/USD 汇率换算为 USD

此技能会跟踪每笔事件时间戳对应的 SOL/USD 汇率，以计算以 USD 计价的收益。

已实现与未实现收益

• 已实现：持仓已全部或部分平仓。已发生应税事件。
• 未实现：持仓仍未平仓。尚未发生应税事件，但如果你计划在年末前平仓，它会计入预估税务负债。

税后盈亏视图会同时显示两者，并按当前预估税率标记未实现收益。

功能

税务批次跟踪

• 将买入、卖出和代币兑换代币的交易记录为应税事件
• 按批次维护成本基础和取得日期
• 支持 FIFO、LIFO 和特定识别会计方法
• 按比例分摊成本基础，处理部分卖出

收益分类引擎

• 将每笔已实现收益分类为短期或长期
• 跟踪每个未平仓批次距离长期门槛还剩多少天
• 标记接近 1 年持有期限的持仓

季度税务预测

• 使用累进税率档估算联邦税务负债
• 纳入州税估算（可配置税率）
• 预测 Q1-Q4 的预缴税款金额
• 按季度跟踪累计已实现收益

税务感知型交易信号

• 长期持有期限提醒：“持仓将在 N 天后达到长期持有期限”
• 获利了结成本：“在此处获利了结将产生 $X 的短期税务负担”
• 亏损收割：“你有 $X 的未实现亏损可供收割”
• 时机价值：“现在卖出而非等待 30 天，可节省 $X 税款”
• 洗售警告：“在 30 天内重新买入可能触发洗售规则”

税后盈亏视图

• 在标准交易盈亏旁显示预估税后盈亏
• 按持仓细分税前和税后回报
• 显示年初至今累计税务负担

前提条件

• Python 3.10+
• 核心跟踪功能无外部依赖（仅使用标准库）
• 用于准确换算为 USD 的历史 SOL/USD 价格
• 结构化格式的交易历史（时间戳、方向、代币、数量、价格）

快速开始

from tax_tracker import TaxTracker, Trade

tracker = TaxTracker(
    accounting_method="fifo",
    federal_bracket=0.32,   # Your marginal federal rate
    state_rate=0.05,        # Your state income tax rate
    long_term_rate=0.15,    # Your long-term capital gains rate
)

# Record the accumulate/house-money play
tracker.add_trade(Trade(
    timestamp="2025-06-15T10:00:00Z",
    side="buy",
    token="BONK",
    amount=1_000_000,
    price_usd=0.00002,      # Per-token price in USD
    total_usd=20.00,
))

tracker.add_trade(Trade(
    timestamp="2025-07-20T14:30:00Z",
    side="sell",
    token="BONK",
    amount=800_000,          # Sell 80% to recover capital
    price_usd=0.000025,
    total_usd=20.00,
))

# Check what happened
summary = tracker.position_summary("BONK")
print(f"Realized gain: ${summary.realized_gain:.2f}")
# Realized gain: $4.00  (sold 800k at $0.000025 = $20, basis = $16, gain = $4)

print(f"Remaining basis: ${summary.remaining_cost_basis:.2f}")
# Remaining basis: $4.00  (200k tokens x $0.00002 = $4)

print(f"Classification: {summary.gain_type}")
# Classification: short-term  (held ~35 days)

# Tax-aware signals
signals = tracker.get_signals("BONK", current_price_usd=0.00003)
for signal in signals:
    print(f"  [{signal.type}] {signal.message}")
# [long_term_countdown] Position crosses long-term threshold in 330 days
# [profit_taking_cost] Taking full profit triggers $2.80 short-term liability

使用场景

1. 日内交易者税务跟踪

跟踪数百笔每日交易，这些交易全部属于短期交易。重点关注季度预估缴税的准确性和累计税务负担。

2. 使用本金回收策略的波段交易者

部分卖出以收回本金，让剩余持仓继续持有。按比例计算成本基础，确保两部分都能得到正确跟踪。

3. 长期持有者监控

跟踪即将达到 1 年长期持有期限的持仓。当现在卖出与等待 N 天会改变税务分类时，系统会发出提醒。

4. 税务亏损收割

找出存在未实现亏损的持仓。收割亏损以抵消收益，同时留意洗售规则。

5. 年末税务规划

预测剩余的季度税务负担，并在 Dec 31 前找出优化机会。

6. 多代币投资组合

同时跟踪数十种代币的成本基础和收益，并提供按代币和汇总视图。

会计方法

FIFO（先进先出）

卖出时优先消耗最早买入的批次。这是大多数交易者的默认方法。如果你长期持续买入，通常会产生更多长期收益。

LIFO（后进先出）

卖出时优先消耗最新买入的批次。如果近期买入价格较高，这种方法可以减少短期收益。

特定识别法

选择要卖出的批次。此方法为税务优化提供最大灵活性，但需要仔细记录。必须在交易前选择，不能事后选择。

与交易工作流集成

Trade Signal → Tax-Aware Filter → Execute/Defer Decision
                    │
                    ├─ "Short-term gain: $X liability"
                    ├─ "Long-term in N days — consider waiting"
                    ├─ "Loss harvest opportunity: $X offset"
                    └─ "Net after-tax profit: $Y"

税务感知型筛选器不会阻止交易，而是提供信息，帮助交易者在充分了解情况后决定交易时机。

文件

参考资料

• references/planned_features.md — 详细功能列表、附带计算示例的按比例成本基础计算方法、收益分类规则、季度预估方法

脚本

• scripts/tax_tracker.py — 演示实现，包含按比例计算成本基础、收益分类、税务感知型信号和季度预测。运行时添加 --demo 可查看一个累积买入／回收本金场景的示例。

限制

• 仅支持美国联邦和州税务规则（暂不支持国际税务）
• 不处理质押奖励、空投或 DeFi 收益等收入事件（计划支持）
• 会标记洗售规则，但不会自动强制执行
• 根据 IRS 指引，将代币之间的兑换视为一次卖出和一次买入（两项应税事件）
• 不会生成正式税表（仅用于跟踪和规划）

免责声明

此技能生成的税务计算结果仅用于信息跟踪。加密货币税法复杂且不断变化。提交申报前，应由合格的税务专业人士核实所有税务数据。此技能不构成税务建议。请咨询 CPA 或税务律师，获取针对你具体情况的指导。