mcpField
T
tax-loss-harvesting

tax-loss-harvesting

github.com/agiprolabsその他456431 回インストール8 週間前に更新
リポジトリ

tax-loss-harvesting について

暗号資産ポートフォリオの損失確定機会を評価する Python スキルです。未実現損失の順位付け、コスト控除後の純便益の推定、ウォッシュセール確認や損失繰越の計画を支援しますが、税務助言ではありません。

主な機能

  1. 01未実現損失機会の順位付け
  2. 02コスト控除後の節税額の推定
  3. 03ウォッシュセールリスクの評価
  4. 04年間損失繰越の追跡
  5. 05年末の損失確定計画

活用シーン

  1. 01四半期ごとのポートフォリオ損失確認
  2. 02年末の損失確定計画
  3. 03長期保有期間に近いポジションの監視
  4. 04取引コストが損失確定益を上回るかの判定

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/agiprolabs/claude-trading-skills --skill tax-loss-harvesting

インストール後、Claude Code で/tax-loss-harvestingを入力して読み込まれたか確認します。

同梱ファイルreferences/planned_features.mdscripts/harvest_scanner.py

詳細

税務上の損失確定(Tax-Loss Harvesting)

暗号資産ポートフォリオ全体から、税務上の損失確定(TLH)の機会を特定し、スコアを付け、計画します。このスキルでは、未実現損失のランキング、純利益の計算、ウォッシュセール規則への準拠、年間の損失繰越額の追跡、年末の「使わなければ失効する」戦略を扱います。

免責事項: このスキルが提供するのは情報分析のみです。税務アドバイスではありません。税務規則は法域によって異なり、頻繁に変更されます。税務関連の取引を決定する前に、資格を持つ税務専門家に相談してください。

税務上の損失確定の仕組み

税務上の損失確定とは、実現した譲渡益と相殺し、当年の納税額を減らすために、意図的に投資損失を確定させる手法です。

基本的な仕組み
  1. ポートフォリオ内の未実現損失があるポジションを特定します。
  2. そのポジションを売却し、損失を確定します。
  3. 確定した損失を確定益と相殺して、課税所得を減らします。
  4. 市場エクスポージャーを維持するため、類似していても「実質的に同一」ではないポジションに再投資することもできます。
短期と長期
保有期間区分一般的な税率
< 1 年短期譲渡益/損失通常所得税率
>= 1 年長期譲渡益/損失優遇税率(0-20%)

短期損失はまず短期譲渡益と相殺され、長期損失はまず長期譲渡益と相殺されます。残った純損失は、他方の区分の譲渡益との相殺に充てられます。

年間損失控除の上限

純損失の合計が譲渡益の合計を上回る場合、超過分は年間3,000ドル(夫婦別申告の場合は1,500ドル)を上限として通常所得から控除できます。残った損失は、将来の課税年度に無期限で繰り越されます。

未実現損失のランキング

未実現損失は、すべて同じ価値があるわけではありません。このスキルでは、各機会を次の4つの観点からスコアリングします。

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. 相殺可能な譲渡益

確定した損失は、相殺できる確定益がある場合にのみ、すぐに役立ちます。次のような場合、機会のスコアを高くします。

  • 区分が一致する譲渡益がある(短期損失と短期譲渡益など)。
  • 損失額が相殺可能な譲渡益を大きく上回らない(3,000ドルの控除上限を超えると、限界的な節税効果が薄れるため)。
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
    )

純利益の計算

損失の確定には費用がかかります。取引コスト(スワップ手数料、スリッページ、ガス代)によって利益が減少します。

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日待ってから元のロットを売却する多額の資金が必要
暗号資産固有の考慮事項
  • IRSは、ウォッシュセール規則が暗号資産に適用されると明示的に判断していません(2025年時点)。ただし、適用範囲を拡大する法案が提案される可能性があります。
  • 慎重な税務計画のため、慎重な実務家は暗号資産にもウォッシュセール規則が適用されるものとして扱います。
  • 異なるトークン(例: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.mdTLHの仕組み、スコアリング式、ウォッシュセールとの関係、繰越ルール、年末戦略
scripts/harvest_scanner.pyデモ用スキャナー:機会をスコアリングし、損失確定計画を作成して純利益を計算

Important: このスキルは情報提供のみを目的とした分析ツールです。税務関連の判断はすべて、資格を有する税務専門家に確認してください。税法は管轄地域によって異なり、変更される場合があります。

コメント