---
title: "Asset location — minimize annual tax drag by placement"
method: POST
path: "/v1/tax/asset-location"
tags: ["Tax"]
---

# Asset location — minimize annual tax drag by placement

`POST /v1/tax/asset-location`

## Request

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

For each asset, the annual tax drag per dollar of holding it in a taxable account (tax on its yield — qualified at the LTCG rate, the rest ordinary — plus the LTCG tax on the appreciation realized via turnover), and a recommended placement that fills the tax-advantaged accounts with the highest-drag assets first. Returns the annual drag under that placement vs a pro-rata baseline. A transparent calculator (the caller can override), not a black-box optimizer; Roth and deferred are combined as the shelter (the choice between them is a separate rate decision). Deterministic; not tax advice.

## Request body

- AssetLocationRequest
  - `tax_year` integer, required: Supported tax year (2025 or 2026).
  - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
  - `taxable_income` number: Sets the marginal ordinary and LTCG rates.
  - `taxable_balance` number, required
  - `tax_advantaged_balance` number, required: Tax-deferred + Roth combined (the shelter).
  - `assets` object[], required: Holdings; must sum to taxable_balance + tax_advantaged_balance.
    - `name` string, required
    - `amount` number, required
    - `expected_return` number, required
    - `yield` number, required: Annual income yield (dividends/interest).
    - `qualified_pct` number: Fraction of yield taxed at the LTCG rate (rest ordinary).
    - `turnover` number: Fraction of appreciation realized as gains each year.

## Response `200`

Asset-location placement

- AssetLocationResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` AssetLocationRequest
    - `tax_year` integer, required: Supported tax year (2025 or 2026).
    - `filing_status` 'single' | 'mfj' | 'mfs' | 'hoh', required
    - `taxable_income` number: Sets the marginal ordinary and LTCG rates.
    - `taxable_balance` number, required
    - `tax_advantaged_balance` number, required: Tax-deferred + Roth combined (the shelter).
    - `assets` object[], required: Holdings; must sum to taxable_balance + tax_advantaged_balance.
      - `name` string, required
      - `amount` number, required
      - `expected_return` number, required
      - `yield` number, required: Annual income yield (dividends/interest).
      - `qualified_pct` number: Fraction of yield taxed at the LTCG rate (rest ordinary).
      - `turnover` number: Fraction of appreciation realized as gains each year.
  - `result` object
    - `marginal_rate` number
    - `ltcg_rate` number
    - `placements` object[]
      - `name` string
      - `drag_rate` number: Annual tax per dollar if held in a taxable account.
      - `taxable_amount` number
      - `tax_advantaged_amount` number
      - `recommendation` 'taxable' | 'tax_advantaged' | 'split'
    - `annual_drag_prorata` number: Drag if each asset were spread pro-rata across accounts.
    - `annual_drag_optimized` number: Drag under the recommended placement.
    - `annual_drag_saved` number
  - `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)