tax-loss-harvesting

税损收割

识别、评估并规划加密货币投资组合中的税损收割（TLH）机会。此技能涵盖未实现亏损排名、净收益计算、洗售合规、年度亏损结转跟踪，以及年末“用掉，否则作废”策略。

**免责声明：**此技能仅提供信息分析，并非税务建议。不同司法管辖区的税务规则各不相同，且经常变化。在做出任何与税务相关的交易决策之前，请咨询合格的税务专业人士。

税损收割的运作方式

税损收割是指有意实现投资亏损，以抵消已实现的资本利得，从而降低本年度的纳税义务。

核心机制

1. 识别投资组合中存在未实现亏损的持仓。
2. 卖出这些持仓以实现亏损。
3. 抵消已实现的利得，用收割的亏损降低应税收入。
4. 可选地重新买入类似（但并非“实质相同”）的持仓，以维持市场敞口。

短期与长期

持有期限	分类	典型税率
< 1 年	短期资本利得/亏损	普通收入税率
>= 1 年	长期资本利得/亏损	优惠税率（0-20%）

短期亏损优先抵消短期利得；长期亏损优先抵消长期利得。剩余净亏损可跨类别抵消另一类利得。

年度亏损抵扣限额

如果净亏损总额超过利得总额，超出的部分每年最多可抵扣 $3,000 的普通收入（夫妻分别申报时为 $1,500）。任何剩余亏损都可以无限期结转至未来纳税年度。

未实现亏损排名

并非所有未实现亏损都同样值得收割。此技能会从四个维度为每个机会评分：

1. 亏损金额

金额较大的美元亏损可带来更多税务节省。原始亏损是当前市值与成本基础之间的差额。

unrealized_loss = current_value - cost_basis  # negative when loss
tax_savings = abs(unrealized_loss) * marginal_tax_rate

2. 距离长期持有期限的天数

接近持有满 1 年的仓位值得特别关注：

• 如果即将达到长期持有期限，现在收割会锁定为短期亏损（可抵消税率较高的短期利得）。
• 如果已属于长期持有，亏损可抵消长期利得（享受较低税率带来的优惠）。

days_held = (today - acquisition_date).days
days_to_long_term = max(0, 365 - days_held)

距离长期持有期限剩余天数越少，越需要紧急评估，因为一旦超过 365 天，短期亏损就会变成价值较低的长期亏损。

3. 洗售风险（相关性评分）

IRS 的洗售规则禁止在出售前后 30 天内买入“实质相同”的证券并申报亏损。在加密货币领域，该规则的确切适用方式仍在演变，但审慎的规划会避免在 61 天洗售窗口内重新买入相同代币（前 30 天 + 卖出日 + 后 30 天）。

相关性评分：如果你持有（或计划重新买入）与收割资产高度相关的仓位，洗售风险就会增加。评分如下：

wash_sale_risk = 1.0  # if same token re-entry planned within 30 days
wash_sale_risk = correlation_coefficient  # if correlated substitute held
wash_sale_risk = 0.0  # if no re-entry or uncorrelated substitute

洗售风险越高，机会的有效得分越低。

4. 可供抵消的利得

只有在存在已实现利得可供抵消时，收割的亏损才可立即发挥作用。以下情况应给予更高评分：

• 存在同类型利得（短期亏损对短期利得）。
• 亏损金额不会大幅超过可抵消的利得（超过 $3K 抵扣上限后的边际收益会递减）。

offset_efficiency = min(1.0, available_matching_gains / abs(unrealized_loss))

综合评分

def tlh_score(
    unrealized_loss: float,
    days_to_long_term: int,
    wash_sale_risk: float,
    offset_efficiency: float,
    weights: dict | None = None,
) -> float:
    w = weights or {
        "magnitude": 0.35,
        "urgency": 0.25,
        "wash_safety": 0.20,
        "offset_match": 0.20,
    }
    magnitude_score = min(abs(unrealized_loss) / 10_000, 1.0)
    urgency_score = max(0, 1.0 - days_to_long_term / 365)
    wash_safety_score = 1.0 - wash_sale_risk
    return (
        w["magnitude"] * magnitude_score
        + w["urgency"] * urgency_score
        + w["wash_safety"] * wash_safety_score
        + w["offset_match"] * offset_efficiency
    )

净收益计算

收割亏损并非没有成本。交易成本（兑换费、滑点、Gas 费）会降低收益。

def net_benefit(
    unrealized_loss: float,
    marginal_tax_rate: float,
    transaction_cost: float,
    re_entry_cost: float = 0.0,
) -> float:
    """Compute net dollar benefit of harvesting a loss.

    Args:
        unrealized_loss: Negative number representing the loss.
        marginal_tax_rate: Applicable tax rate (0.0 to 1.0).
        transaction_cost: Cost to execute the sell (fees + slippage).
        re_entry_cost: Cost to re-enter a substitute position.

    Returns:
        Net benefit in dollars. Positive means harvesting is worthwhile.
    """
    tax_savings = abs(unrealized_loss) * marginal_tax_rate
    total_costs = transaction_cost + re_entry_cost
    return tax_savings - total_costs

经验法则：只有当 net_benefit > 0 且有明显收益时，才进行收割。金额很小的亏损不值得承担交易成本和操作复杂性。

年末“用掉或作废”

临近 12 月 31 日时，评估是否应加快亏损收割：

1. 汇总年初至今已实现的收益（包括短期和长期收益）。
2. 找出可抵消这些收益的未实现亏损。
3. 优先处理可抵消同类型收益的亏损（短期亏损抵消短期收益，税率差异最大）。
4. 检查 3,000 美元的超额限额：如果净亏损已超过收益 3,000 美元，今年进一步收割不会带来即时税务收益（但结转的亏损仍有价值）。
5. 考虑结算时间：确保交易在年末前结算。

洗售合规

61 天窗口期

洗售规则适用于以下时间范围内买入的实质相同证券：

• 卖出前 30 天（追溯适用的洗售）
• 卖出当天
• 卖出后 30 天

如果触发该规则，不允许扣除的亏损会计入替代股份的成本基础，从而递延（而非消除）税务收益。

合规策略

策略	说明	权衡
等待 31 天	卖出后等待 31 天再买入	市场敞口空档
替代资产	卖出后立即买入相关但不相同的资产	跟踪误差
不重新买入	卖出后不再持有	错失上涨收益
加倍买入	买入额外股份，等待 31 天后卖出原始批次	资金占用较大

加密货币的特定注意事项

• 截至 2025 年，IRS 尚未明确裁定洗售规则是否适用于加密货币。不过，拟议中的立法可能会将其纳入。
• 为采取审慎的规划方式，从业者通常将加密货币视为受洗售规则约束。
• 不同代币（例如 SOL 与 ETH）通常被认为并非相同资产。
• 同一代币的封装版本（例如 SOL 与 wSOL）可能被认为实质相同。

年度亏损结转跟踪

def compute_carryforward(
    realized_gains_st: float,
    realized_gains_lt: float,
    realized_losses_st: float,
    realized_losses_lt: float,
    prior_carryforward: float = 0.0,
    annual_deduction_limit: float = 3_000.0,
) -> dict:
    """Compute net tax position and carryforward.

    Returns dict with keys:
        net_st, net_lt, total_net,
        deduction_used, carryforward
    """
    net_st = realized_gains_st + realized_losses_st  # losses are negative
    net_lt = realized_gains_lt + realized_losses_lt
    total_net = net_st + net_lt - prior_carryforward

    if total_net >= 0:
        return {
            "net_st": net_st, "net_lt": net_lt,
            "total_net": total_net, "deduction_used": 0.0,
            "carryforward": 0.0,
        }

    excess_loss = abs(total_net)
    deduction_used = min(excess_loss, annual_deduction_limit)
    carryforward = max(0, excess_loss - annual_deduction_limit)
    return {
        "net_st": net_st, "net_lt": net_lt,
        "total_net": total_net,
        "deduction_used": deduction_used,
        "carryforward": carryforward,
    }

前提条件

• Python 3.10+
• 核心计算无需外部依赖
• 投资组合数据：成本基础、取得日期、每个批次的当前市值
• 税务参数：边际税率、申报身份、此前结转的亏损

功能

功能	说明
机会扫描	找出所有存在未实现亏损的持仓
多因素评分	按亏损金额、紧迫程度、洗售安全性、抵消匹配度排序
净收益分析	比较节税额与交易成本
洗售跟踪	标记处于 61 天窗口期内的持仓
结转计算器	跟踪年度 3,000 美元限额和亏损结转
年末规划	优先处理 12 月 31 日前的亏损收割
收割计划输出	生成可执行计划，其中包含卖出指令和重新买入日期

快速入门

from datetime import date

# Define a portfolio position
position = {
    "symbol": "TOKEN-A",
    "cost_basis": 10_000.0,
    "current_value": 6_500.0,
    "acquisition_date": date(2025, 8, 15),
    "quantity": 500.0,
}

unrealized_loss = position["current_value"] - position["cost_basis"]  # -3500
days_held = (date.today() - position["acquisition_date"]).days
days_to_lt = max(0, 365 - days_held)

# Score the opportunity
score = tlh_score(
    unrealized_loss=unrealized_loss,
    days_to_long_term=days_to_lt,
    wash_sale_risk=0.0,
    offset_efficiency=0.8,
)
print(f"TLH score: {score:.3f}")

# Calculate net benefit
benefit = net_benefit(
    unrealized_loss=unrealized_loss,
    marginal_tax_rate=0.35,
    transaction_cost=15.0,
    re_entry_cost=15.0,
)
print(f"Net benefit: ${benefit:.2f}")

使用场景

1. 季度投资组合审查：扫描所有持仓，按综合评分排列亏损收割机会。
2. 年末税务规划：根据年初至今的收益／亏损总额，确定 12 月 31 日前最适合收割的持仓组合。
3. 持续监控：标记即将达到长期持有门槛的持仓，在收割短期亏损变得紧迫时发出提醒。
4. 结转管理：跟踪多年的亏损结转余额，并预测何时可将其全部用完。
5. 交易成本分析：根据当前费用情况，确定值得收割的最低亏损金额。

文件

文件	说明
references/planned_features.md	TLH 机制、评分公式、洗售规则的影响、结转规则、年末策略
scripts/harvest_scanner.py	演示扫描器：为机会评分、生成收割计划、计算净收益

**重要提示：**此技能仅提供用于参考的分析工具。所有税务相关决策都应由合格的税务专业人士审查。各司法管辖区的税法不尽相同，且可能发生变化。