---
title: "Get Cross Border Assumptions"
method: GET
path: "/api/tax/cross-border-assumptions"
tags: ["tax"]
---

# Get Cross Border Assumptions

`GET /api/tax/cross-border-assumptions`

## Request

- Base URL: `https://api.retirementlab.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.retirementlab.app/api/tax/cross-border-assumptions`
- Auth: none declared

Return active cross-border tax assumptions for a citizenship/residency pair.

The payload powers the scenario-results disclosure and the methodology
page's cross-border section. Wrapper-treatment rows come from the
cross-border assumption registry; the treaty-allocation field comes from
the TreatyProvisions metadata.

## Query parameters

- `citizenship` string, required
- `residency` string, required
- `tax_regime` string
- `wealth_tax_region` string

## Response `200`

Successful Response

- ActiveCrossBorderAssumptionsResponse: Active cross-border tax assumptions for a citizenship/residency pair. ``active`` indicates whether the disclosure should render at all — false when the pair does not produce a cross-border tax year (e.g. citizenship matches residency, or non-US citizenship which is out of scope for v1).
  - `citizenship_country` string, required
  - `residency_country` string, required
  - `active` boolean, required
  - `wrapper_assumptions` CrossBorderTaxAssumptionResponse[]
    - `assumption_id` string, required
    - `label` string, required
    - `citizenship_country` string, required
    - `residency_country` string, required
    - `wrapper_or_income_category` string, required
    - `taxable_component_basis` 'full_distribution' | 'earnings_only' | 'exempt', required
    - `local_tax_category` string, required
    - `confidence` 'high' | 'medium' | 'low', required
    - `source_urls` string[]
    - `last_verified` string
    - `caveat` string, required
    - `is_fallback` boolean
  - `treaty_provisions` TreatyProvisionsResponse
    - `citizenship` string, required
    - `residency` string, required
    - `social_security_taxable_by` 'citizenship' | 'residency' | 'both' | 'source_state', required
    - `public_pension_taxable_by` 'citizenship' | 'residency' | 'both' | 'source_state', required
    - `private_pension_taxable_by` 'citizenship' | 'residency' | 'both' | 'source_state', required
    - `traditional_ira_401k_withdrawal_taxable_by` 'citizenship' | 'residency' | 'both' | 'source_state', required
    - `roth_withdrawal_taxable_by` 'citizenship' | 'residency' | 'both' | 'source_state', required
    - `capital_gains_taxable_by` 'citizenship' | 'residency' | 'both' | 'source_state', required
    - `source_state_caveats` string[]
    - `source_citation` string, required
    - `last_verified` string, required
  - `fallback_assumption` CrossBorderTaxAssumptionResponse: One active cross-border tax assumption disclosed in scenario results.
    - `assumption_id` string, required
    - `label` string, required
    - `citizenship_country` string, required
    - `residency_country` string, required
    - `wrapper_or_income_category` string, required
    - `taxable_component_basis` 'full_distribution' | 'earnings_only' | 'exempt', required
    - `local_tax_category` string, required
    - `confidence` 'high' | 'medium' | 'low', required
    - `source_urls` string[]
    - `last_verified` string
    - `caveat` string, required
    - `is_fallback` boolean
  - `dual_tax_fallback` DualTaxFallbackMetadataResponse: Classification metadata for the dual-tax overlay's fallback posture on a US-citizen residency pair. ``treaty_status`` reflects whether the simulator's treaty matrix has an entry for the pair, ``residence_tax_model`` reflects the residency country's domestic tax model, and ``fallback_posture`` summarizes the simulator's simulation methodology given those facts.
    - `country` string, required
    - `treaty_status` 'explicit_treaty_matrix' | 'treaty_exists_not_encoded' | 'no_income_tax_treaty', required
    - `residence_tax_model` 'worldwide' | 'territorial' | 'remittance' | 'no_personal_income_tax' | 'special_regime_dependent' | 'unknown_or_conservative', required
    - `fallback_posture` 'standard_both_ftc' | 'conservative_both_ftc' | 'domestic_policy_primary' | 'conservative_assumption_only', required
    - `summary` string, required
    - `source_citation` string, required
    - `last_verified` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/retirementlab/apis/income-simulator-api.md) · [All operations](https://skmtc.dev/retirementlab/apis/income-simulator-api/llms.txt) · [OpenAPI document](https://skmtc.dev/retirementlab/apis/income-simulator-api/revisions/b0f00a0333fd?raw)