---
title: "Multi-year capital-gains plan: realize a long-term gain all at once vs spread it evenly across N years, with the federal tax for each path (2026 0/15/20% long-term bands + the 3.8% NIIT) and the tax saved by spreading — the signed record an investor or agent uses to pick when to realize gains."
method: POST
path: "/v1/reports/capital-gains-scenario"
tags: ["Investing"]
---

# Multi-year capital-gains plan: realize a long-term gain all at once vs spread it evenly across N years, with the federal tax for each path (2026 0/15/20% long-term bands + the 3.8% NIIT) and the tax saved by spreading — the signed record an investor or agent uses to pick when to realize gains.

`POST /v1/reports/capital-gains-scenario`

## Request

- Base URL: `` (relative, and it does not resolve against the document’s source URL)
- URL: `/v1/reports/capital-gains-scenario`
- Auth: none declared

Multi-year capital-gains plan: realize a long-term gain all at once vs spread it evenly across N years, with the federal tax for each path (2026 0/15/20% long-term bands + the 3.8% NIIT) and the tax saved by spreading — the signed record an investor or agent uses to pick when to realize gains.

Payment: x402 ($1.00 USDC on eip155:8453). Call unpaid to receive an HTTP 402 with requirements, then retry with the PAYMENT-SIGNATURE header. Method: compares computeCapitalGainsTax(full gain in year 1) vs the sum of computeCapitalGainsTax(gain/N) across N years at the same ordinary income; savings = allAtOnce.totalTax - Σ spread

## Request body

- object
  - `filingStatus` 'single' | 'mfj' | 'hoh' | 'mfs'
  - `ordinaryTaxableIncome` number
  - `totalLongTermGain` number, required
  - `spreadYears` number

## Response `200`

Verified result + provenance (formula, sources, reproducible SHA-256 hash).

## Other responses

- `400`: Invalid input (no charge) — body echoes the JSON Schema.
- `402`: Payment required — PAYMENT-REQUIRED header carries the x402 accepts[] quote.

---

[API](https://skmtc.dev/x402toll/apis/tollbooth-verified-calculators-for-ai-agents.md) · [All operations](https://skmtc.dev/x402toll/apis/tollbooth-verified-calculators-for-ai-agents/llms.txt) · [OpenAPI document](https://skmtc.dev/x402toll/apis/tollbooth-verified-calculators-for-ai-agents/revisions/60cb70a3e1a5?raw)