tax-loss-harvest-scanner

税務上の損失確定スキャナー

目次

• 概要
• 入力仕様
• ウォッシュセールのルール
• ワークフロー
• 代替ペア
• 出力仕様
• ガードレール

概要

税務上の損失確定では、課税口座の損失を実現して利益（および年間最大 $3,000 の通常所得）と相殺しながら、世帯の経済的なポジションを変えません。売却代金で類似しているものの同一ではない有価証券を購入し、市場エクスポージャーを維持します。最も難しいのはウォッシュセールのルールです。損失を出して売却した場合、その前後30日以内に、配偶者のIRAを含む世帯内のいずれかの口座で実質的に同一の有価証券を購入すると、損失は認められません。

このスキルは課税口座をスキャンして損失確定の候補を探し、世帯内のすべての口座を対象にウォッシュセール期間を照合します。

入力仕様

呼び出し元は以下を指定します。

• taxable_holdings — 課税口座のロット。できればロット単位で指定します：{symbol, shares, cost_basis_cents, value_cents, acquisition_date}。ポジション単位の集計データしかない場合は、lot_resolution: aggregate を設定し、制約事項を記載します。
• all_account_transactions_60d — 過去60日間に世帯内のすべての口座（課税口座、401k、IRA、配偶者のIRA、HSA）で行われた、すべての買い、売り、配当再投資。ウォッシュセールの検出に使用します。
• planned_buys_30d（任意）— 配当再投資の予定、401k の拠出、自動入金など、今後30日以内に有価証券を購入する予定のもの。
• loss_threshold_cents — 対象とする含み損の最小額。既定値は 50000（$500）です。
• today — ISO 形式の日付。

ウォッシュセールのルール

IRS によると、損失を出して売却した有価証券を、売却日を中心とする61日間（売却日の前後30日間）に「実質的に同一」の有価証券と入れ替えると、ウォッシュセールが発生します。

このスキルでは、次のように扱います。

1. 同じティッカー。 常に実質的に同一とみなします。例外はありません。
2. 同じファンドファミリー、同じ指数。 VTI ↔ VFIAX ↔ FXAIX（異なるファンドファミリーの S&P 500／米国株式市場全体の連動ファンド）は、IRS の指針上、一般に同一とはみなされません。ただし、このスキルでは保守的に、同じ指数に連動する2つのファンドを実質的に同一とみなします。
3. 異なる指数で、似たエクスポージャー。 VTI（米国株式市場全体）↔ ITOT（別のファンドファミリーの米国株式市場全体）は、実質的に同一ではありません。これらは有効な TLH ペアです。
4. 世帯内のすべての口座が対象です。 配偶者のIRA、401k の自動購入、HSA の自動購入もすべて対象です。
5. 配当再投資。 30日間の対象期間内に行われる配当再投資は、ウォッシュセールを引き起こす購入に該当します。売却前に、損失確定の対象となる有価証券の DRIP を無効にしてください。

ワークフロー

TLH Scan Progress:
- [ ] Step 1: Filter taxable lots with unrealized loss >= loss_threshold
- [ ] Step 2: For each candidate, check 30-day backward wash-sale window
- [ ] Step 3: For each candidate, check 30-day forward planned-buys window
- [ ] Step 4: Identify substitute security (similar exposure, not identical)
- [ ] Step 5: Compute realized loss and tax savings estimate
- [ ] Step 6: Emit harvest proposals with explicit wash-sale guard
- [ ] Step 7: Surface candidates blocked by wash sale with the unblock date

ステップ1 — 損失による絞り込み

unrealized_loss_cents = value_cents − cost_basis_cents（負の値）です。|unrealized_loss_cents| ≥ loss_threshold_cents かつ unrealized_loss_cents < 0 のロットを残します。

ロット単位での判定ができない場合は、weighted_avg_cost_basis を使ってポジション単位で判定します。lot_resolution: aggregate を記録し、一部のロットには利益があり、ほかのロットには損失がある可能性があること、損失が出ているのは集計値のみであることを警告します。

ステップ2 — 過去の取引期間の確認

各候補銘柄について、all_account_transactions_60d の過去30日間を確認し、同一または実質的に同一の有価証券の買いがないか調べます。該当する買いがあれば、売却による損失の一部または全部がウォッシュセールとして扱われるため、直近の買いから30日後まで対象外とします。blocked_until: YYYY-MM-DD として表示します。

ステップ 3 — 今後の取引予定

同一または実質的に同一の証券について、planned_buys_30d を確認します。よくあるケース：

• 401k の給与天引き拠出で、2 週間ごとに S&P 500 インデックスファンドを購入する → 課税口座で S&P 500 を損失確定した場合、次回の 401k での購入によってウォッシュセールになります。
• 配当金の再投資が予定されている。
• 証券口座への毎月の自動入金。

対処方法：

• 401k の給与天引きの場合：可能であれば、1 サイクルだけ 401k で購入する資産クラスを変更します。それが難しい場合は、別の証券を損失確定します。
• DRIP の場合：売却の 1 日以上前に、損失確定対象の DRIP をオフにします。
• 自動入金の場合：入金を延期するか、入金先を変更します。

ステップ 4 — 代替ペア

市場エクスポージャーを維持できる代替銘柄を選びます。このスキルにはデフォルトの対応関係が含まれています（代替ペアを参照）。代替銘柄は以下の条件を満たす必要があります。

• 類似しているものの、異なるインデックスに連動している。
• 代替先の口座で購入できる。
• 経費率が低い（理想的には 0.10% 以下）。

ステップ 5 — 節税額の見積もり

tax_savings_cents ≈ |realized_loss_cents| × marginal_rate。限界税率はユーザーから提供されるか、通常所得の相殺には 3,000 ドルまで 24%、長期キャピタルゲインの相殺には 15% がデフォルトで適用されます。両方の金額を提示します。

ステップ 6 — 提案の出力

各提案には以下を含めます。

• 売却側：口座、銘柄、ロット、株数、実現損失。
• 購入側：口座、代替銘柄、株数、金額。
• ウォッシュセールの確認：前後 30 日間に該当する取引がないことを確認済み。
• 節税額の見積もり。
• DRIP の無効化手順（該当する場合）。

ステップ 7 — ブロックされた候補

ブロックされた損失については、ユーザーが候補を損失確定できる日付を把握できるよう、unblock_date を含む blocked[] リストを出力します。

代替ペア

妥当な初期候補（スキルはこれらを確定的なものではなく、提案として出力します）：

売却	購入する代替銘柄	理由
VTI（米国株式市場全体）	ITOT（米国株式市場全体、iShares）	異なる運用会社で、エクスポージャーが類似
VOO（S&P 500）	VTI（米国株式市場全体）	異なるインデックス
VXUS（米国以外の国際株式全体）	IXUS（米国以外の国際株式全体、iShares）	異なる運用会社
BND（米国総合債券）	AGG（米国総合債券、iShares）	異なる運用会社で、エクスポージャーは同じ — 境界的な組み合わせのため、SCHZ のような少し異なるインデックスを優先
IEFA（先進国の米国以外の株式）	VEA（先進国株式）	異なる運用会社
FXAIX（Fidelity S&P 500）	FSKAX（Fidelity 全米株式市場）	異なるインデックス

代替銘柄は常に提案として明示してください。ユーザーが、自身の投資方針に照らして適切かどうかを確認します。

出力仕様

{
  "as_of": "2026-04-25",
  "candidates_total": 5,
  "harvest_proposals": [
    {
      "id": "tlh_20260425_001",
      "sell": {
        "account_id": "acc_inv_fid_001",
        "symbol": "VTI",
        "lots": [
          { "acquisition_date": "2024-09-12", "shares": 35, "cost_basis_cents": 985250, "value_cents": 935500 }
        ],
        "realized_loss_cents": -49750
      },
      "buy": {
        "account_id": "acc_inv_fid_001",
        "symbol": "ITOT",
        "shares": 38,
        "value_cents": 935500,
        "rationale": "Substantially similar exposure to VTI, different index family — not substantially identical per common interpretation"
      },
      "wash_sale_check": {
        "backward_30d_clear": true,
        "forward_30d_clear": false,
        "blockers": [
          { "type": "401k_payroll_buy", "symbol_substantially_identical": "FSKAX", "buy_date": "2026-05-02" }
        ],
        "remediation": "Change 401k allocation away from FSKAX for the 2026-05-02 cycle, or harvest a different security"
      },
      "tax_savings_estimate_cents": 11940,
      "drip_disable_required": true,
      "status": "remediation_required"
    }
  ],
  "blocked": [
    {
      "symbol": "VXUS",
      "reason": "spouse_ira_buy_within_30d",
      "unblock_date": "2026-05-12"
    }
  ],
  "warnings": []
}

ガードレール

• 家計内のすべての口座を横断してウォッシュセールを確認します。 配偶者の IRA も対象です。401k の自動購入も対象です。DRIP も対象です。
• ロット単位での解決を優先します。 集計データしかない場合は信頼度を下げ、警告を提示します。
• 代替銘柄は提案です。 IRS はすべてのインデックスの組み合わせについて「実質的に同一」の基準を明確に定義していないため、ユーザー自身の解釈に基づき、該当しないことを確認する必要があります。
• 売却前に DRIP を無効にします。 損失確定対象の証券で DRIP が有効になっている場合、次回の配当によって損失がウォッシュセールになります。
• 口座の種類を考慮せずに組み合わせないでください。 課税口座で損失確定した証券を、401k で同じ証券を購入して置き換えることはできません。これもウォッシュセールになります。
• 年初来の実現損失を追跡します。 累計額を提示してください。通常所得を相殺するための純実現損失がユーザーに 3,000 ドルある場合、それ以上の損失確定は翌年以降に繰り越されます（引き続き有用ですが、限界的なメリットは小さくなります）。
• 絶対に実行しないでください。 提案のみです。