---
title: "Concentrated-position liquidation optimizer (multi-year, tax-aware)"
method: POST
path: "/v1/tax/liquidation-schedule"
tags: ["Tax"]
---

# Concentrated-position liquidation optimizer (multi-year, tax-aware)

`POST /v1/tax/liquidation-schedule`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/tax/liquidation-schedule`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Schedules the year-by-year sale of a large low-basis position (founder/inherited stock, long-vested RSUs) to diversify without one huge capital-gains / NIIT hit. Each year it realizes gain up to a chosen objective — fill the 15% LTCG bracket, stay under the §1411 NIIT threshold, or a fixed annual cap — pricing the 0/15/20 + NIIT tax incrementally through the tax engine (so it matches the tax harness, incl. a $0-income founder whose gain alone crosses the NIIT threshold). Returns the per-year schedule, years to diversify, and a lump-sum comparison with the tax saved by spreading. Deterministic; not tax advice.

## Request body

- LiquidationScheduleRequest
  - `tax_year` 2025 | 2026, required
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
  - `market_value` number, required: Current value of the concentrated position.
  - `cost_basis` number, required: Total cost basis (must be <= market_value; gain = market − basis).
  - `other_ordinary_income` number: AGI-level ordinary income (drives the LTCG stacking position).
  - `other_ltcg` number: Other long-term gains already realized (stack below this position).
  - `objective` 'target_bracket' | 'niit_cap' | 'max_annual_gain', required: Yearly gain target: fill the 15% LTCG bracket, stay under the NIIT threshold, or a fixed cap.
  - `max_annual_gain` number: Required when objective = max_annual_gain.
  - `growth_rate` number: Annual appreciation of the remaining position.
  - `horizon_years` integer, required
  - `state_tax_rate` number: Optional flat state rate on realized gains.

## Response `200`

The multi-year sale schedule + lump-sum comparison

- LiquidationScheduleResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` LiquidationScheduleRequest
    - `tax_year` 2025 | 2026, required
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
    - `market_value` number, required: Current value of the concentrated position.
    - `cost_basis` number, required: Total cost basis (must be <= market_value; gain = market − basis).
    - `other_ordinary_income` number: AGI-level ordinary income (drives the LTCG stacking position).
    - `other_ltcg` number: Other long-term gains already realized (stack below this position).
    - `objective` 'target_bracket' | 'niit_cap' | 'max_annual_gain', required: Yearly gain target: fill the 15% LTCG bracket, stay under the NIIT threshold, or a fixed cap.
    - `max_annual_gain` number: Required when objective = max_annual_gain.
    - `growth_rate` number: Annual appreciation of the remaining position.
    - `horizon_years` integer, required
    - `state_tax_rate` number: Optional flat state rate on realized gains.
  - `result` object
    - `schedule` object[]: One entry per year until the position is sold or the horizon ends.
      - `year` integer
      - `start_value` number
      - `sold` number: Market value sold this year.
      - `gain` number: Long-term gain realized.
      - `ltcg_tax` number: 0/15/20 federal tax on the gain.
      - `niit` number: §1411 NIIT on the gain.
      - `state_tax` number
      - `total_tax` number
      - `after_tax_proceeds` number
      - `remaining_value` number
    - `years_to_diversify` integer: Year the position is fully sold (0 if not within the horizon).
    - `fully_liquidated` boolean
    - `total_gain_realized` number
    - `total_tax` number
    - `total_after_tax_proceeds` number
    - `lump_sum` object: The alternative — sell everything now.
      - `gain` number
      - `ltcg_tax` number
      - `niit` number
      - `state_tax` number
      - `total_tax` number
      - `after_tax_proceeds` number
      - `tax_saved_by_spreading` number: Lump-sum total tax minus the schedule's total tax.
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)