Tax-Loss Harvesting Simulator

Why this Data Set exists

Direct indexing has gone from boutique service to default offering at every major wealth platform in three years. The algorithms underneath are not commodities. The differences in TLH yield from one implementation to another can compound to 100+ basis points of after-tax return — the difference between a competitive product and an also-ran. But validating the algorithms requires test data with structural properties most synthetic data products skip: lot-level cost basis with realistic acquisition-date distributions, holdings that mathematically produce wash-sale conflicts at the right frequency, QSBS-eligible positions with actual gross-asset-test history, and household-level coordination across taxable and tax-deferred accounts.

Without this kind of fixture data, TLH algorithm development happens in a vacuum. You can't backtest. You can't reproduce a customer's reported issue. You can't run regression tests against a known-good baseline. The Tax-Loss Harvesting Simulator is the canonical fixture for this work.

Use Cases

Who uses this Data Set

What's inside

The 350 households span ten archetypes selected for taxable-account complexity: tech workers with vesting RSUs, dual-income professionals with brokerage accounts, peak earners with concentrated positions, HNW investors with multi-firm engagements, FIRE achievers with tax-aware withdrawal sequencing, real estate investors, and crypto-heavy investors whose digital-asset cost basis interacts with traditional brokerage holdings.

Every household has lot-level taxable-account holdings: each lot carries its acquisition date, original cost basis, current market value, holding-period status (short-term vs. long-term), and unrealized gain/loss. Cost-basis method is recorded per lot (specific-ID is the dominant choice in this corpus, since it's the method required for sophisticated TLH). Wash-sale flags pre-populate where applicable — both intra-account and cross-account (the disallowed-loss case where a buyer triggers wash-sale by repurchasing in their IRA). Holding-period bucketing is structured for fast filter access. QSBS-eligible positions include the Section 1202 attestation chain: original issuance date, gross-asset-test history at issuance, holding-period satisfaction, and any stacking via non-grantor trusts.

The Data Set ships as JSON, CSV, and Parquet (Parquet is recommended for analytical work over the lot-level data — there are roughly 8,000 lots across the corpus, so Parquet's columnar layout makes ad-hoc queries fast). The WealthSynth Methodology PDF documents the lot-generation methodology, the calibration of unrealized-loss frequency against realistic market conditions, and the specific structural patterns each archetype is designed to exercise.

Preview a sample household

A redacted summary of one household from this Data Set — names, employers, exact balances, and metro area are stripped. Ages are bucketed, income and net worth are reported as bands. The full record (and all 350 like it) ships in the ZIP.

Technical Highlights

Sample Schema Fields

{
  "accounts.taxable.lots[].acquisition_date": <value>,
  "accounts.taxable.lots[].cost_basis": <value>,
  "accounts.taxable.lots[].unrealized_pnl": <value>,
  "taxes.wash_sale_flags": <value>,
  "taxes.qsbs_attestation": <value>
}

Sample queries

households.flatMap(h =>
  h.accounts.taxable.lots.filter(lot =>
    lot.unrealized_pnl < 0 &&
    !h.taxes.wash_sale_flags.some(wf =>
      wf.symbol === lot.symbol &&
      Math.abs(wf.window_days) <= 30)
  )
)

households.flatMap(h =>
  h.equity_comp.qsbs_attestation
    .filter(p => p.years_held >= 4 && p.years_held < 5)
)

households.flatMap(h =>
  h.accounts.taxable.lots.filter(lot => {
    const days = daysBetween(lot.acquisition_date, today());
    return days >= 305 && days < 365 && lot.unrealized_pnl > 0;
  })
)

households.map(h => {
  const harvestable = h.accounts.taxable.lots
    .filter(l => l.unrealized_pnl < 0 &&
                 !isWashSaleConflicted(l, h))
    .reduce((s, l) => s + Math.abs(l.unrealized_pnl), 0);
  const realizedGains = h.taxes.realized_gains_ytd;
  const cap = realizedGains + 3000;
  return { id: h.id, tlh_yield: Math.min(harvestable, cap) };
})

Edge cases modeled

Tax-loss-harvesting algorithms break on edge cases, not happy-path lots. The corpus is built to exercise the specific structural traps that show up in production — the ones that surface only at year-end on the 1099 and that engineering teams report as urgent bugs in January. Below is the enumeration: every case is grep-able in the household record at the field path shown, and the corpus-rate column reports the calibrated frequency across the 350 households.

Frequencies are calibrated against a 'normal' equity-market environment, not a stress year. The Methodology PDF documents the parameterized re-pricing approach for shifting the corpus into a stress regime (2008, 2022, etc.) and the corresponding edge-case frequency shifts. For each row, the field path is grep-able in the household JSON; regression-test fixtures should exercise every case at least once.

Methodology

Each household's taxable-account holdings are generated against archetype-specific portfolio profiles (RSU-heavy tech workers carry concentrated single-stock positions; HNW investors carry diversified multi-fund portfolios; crypto-heavy households carry significant digital-asset cost-basis structures). Lot acquisition dates are sampled to produce realistic holding-period distributions, including the tail of long-held positions with embedded gains. Unrealized loss frequency is calibrated to a 'normal' market environment — about 18% of lots show net unrealized losses at the corpus snapshot date, in line with typical equity volatility. Wash-sale conflicts are seeded at archetype-realistic rates: dual-account households (taxable + IRA at same firm) produce more cross-account conflicts than single-account households. QSBS attestation chains are generated with full Section 1202 traceability — original issuance, gross-asset-test history, and any stacking trust structures. The corpus passes the WealthSynth consistency validator (cost basis reconciles, wash-sale flags are mathematically consistent with the lot graph, QSBS attestation is internally complete) and the LLM-as-judge gate. Annual refresh re-runs against current-year market levels and any updated tax-rate parameters.

Included Archetypes (10)

Frequently asked questions