Run RetireCrunch's full year-by-year Wealth Plan projection for a household. Models earned income, pensions, expenses, portfolio growth (accumulating, distributing, or accumulating until a switch year), mortgage amortization, optional property sale, and region-aware tax (US: federal brackets, standard and 65+ deductions as published by the IRS for 2026 and 2027 and indexed by inflation after that, plus state tax; other regions use a flat rate). Returns a compact summary with 5-year milestones by default, or the full annual array when yearly_detail=true.
View input schema
{
"type": "object",
"properties": {
"region": {
"default": "GENERIC",
"description": "Country regime — drives tax model (US uses bracket-based federal/state; others a flat rate).",
"type": "string",
"enum": [
"US",
"CH",
"GB",
"EU",
"JP",
"GENERIC"
]
},
"currency": {
"default": "USD",
"type": "string",
"enum": [
"USD",
"EUR",
"GBP",
"CHF",
"JPY",
"CAD",
"AUD",
"DKK"
]
},
"start_year": {
"type": "integer",
"minimum": 1900,
"maximum": 2200,
"description": "First year of the projection (typically the current year)."
},
"retirement_year": {
"type": "integer",
"minimum": 1900,
"maximum": 2200,
"description": "Year retirement begins."
},
"plan_horizon_years": {
"default": 50,
"description": "Total years to project from start_year.",
"type": "integer",
"minimum": 1,
"maximum": 80
},
"current_earned_income": {
"default": 0,
"description": "Annual gross earned income today.",
"type": "number",
"minimum": 0
},
"current_living_costs": {
"default": 0,
"description": "Annual general living expenses today.",
"type": "number",
"minimum": 0
},
"current_housing_expenses": {
"default": 0,
"description": "Annual housing expenses today.",
"type": "number",
"minimum": 0
},
"current_other_expenses": {
"default": 0,
"description": "Annual other expenses today.",
"type": "number",
"minimum": 0
},
"estimated_tax_rate": {
"default": 20,
"description": "Pre-retirement effective tax rate (%).",
"type": "number",
"minimum": 0,
"maximum": 60
},
"post_retirement_tax_rate": {
"default": 10,
"description": "Post-retirement effective tax rate (%).",
"type": "number",
"minimum": 0,
"maximum": 60
},
"current_liquidity": {
"default": 0,
"type": "number",
"minimum": 0
},
"current_investment_portfolio": {
"default": 0,
"type": "number",
"minimum": 0
},
"current_property": {
"default": 0,
"type": "number",
"minimum": 0
},
"current_mortgage": {
"default": 0,
"type": "number",
"minimum": 0
},
"inflation_rate": {
"default": 2,
"description": "Annual inflation %.",
"type": "number",
"minimum": 0,
"maximum": 20
},
"portfolio_return_rate": {
"default": 5,
"description": "Annual real portfolio return %.",
"type": "number",
"minimum": 0,
"maximum": 30
},
"portfolio_volatility": {
"default": 0,
"description": "Return std dev %; 0 = deterministic.",
"type": "number",
"minimum": 0,
"maximum": 50
},
"portfolio_return_mode": {
"description": "What the portfolio does with its return. 'accumulating': everything stays invested and compounds, nothing is paid out (shortfalls are drawn from cash, then the portfolio). 'distributing': pays out income_yield_rate % of its value every year from start_year as investment income; the rest stays invested. 'switch': accumulating until portfolio_switch_year, distributing from then on. If omitted: 'switch' when portfolio_switch_enabled is true (the legacy default), 'accumulating' when it is false.",
"type": "string",
"enum": [
"accumulating",
"distributing",
"switch"
]
},
"portfolio_switch_enabled": {
"default": true,
"description": "Legacy: prefer portfolio_return_mode. Only read when portfolio_return_mode is omitted.",
"type": "boolean"
},
"portfolio_switch_year": {
"description": "'switch' mode: first year the portfolio pays out. Defaults to retirement_year if omitted.",
"type": "integer",
"minimum": 1900,
"maximum": 2200
},
"income_yield_rate": {
"default": 3.5,
"description": "Annual payout % of the portfolio while distributing.",
"type": "number",
"minimum": 0,
"maximum": 20
},
"household_type": {
"default": "single",
"type": "string",
"enum": [
"single",
"couple"
]
},
"partner_early_death_years_before_end": {
"default": 5,
"type": "integer",
"minimum": 0,
"maximum": 10
},
"partner_survivor_expense_factor": {
"default": 0.7,
"type": "number",
"minimum": 0.3,
"maximum": 1
},
"property_sale_enabled": {
"default": false,
"type": "boolean"
},
"property_sale_year": {
"type": "integer",
"minimum": 1900,
"maximum": 2200
},
"property_sale_destination": {
"default": "liquidity",
"type": "string",
"enum": [
"liquidity",
"investmentPortfolio"
]
},
"yearly_detail": {
"default": false,
"description": "When true, include the full year-by-year array in the response. When false (default), return a compact summary plus 5-year milestones.",
"type": "boolean"
}
},
"required": [
"start_year",
"retirement_year"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}