Retirement Monte Carlo, tax-aware withdrawal and Roth-conversion plans, and a 2026 return estimate.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Runs the same plan against several published capital market assumption sets and returns the success rate and median outcome under each, showing how far the answer moves with the return forecast used. Every input is optional: omitted plan inputs use an illustrative plan (age 65, $1,000,000 saved, $40,000 a year spending) which the reply states in its first line.
Yearly pension income. Default 0.
Source ids to compare. Defaults to all.
Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0].
Current age of the primary person.
Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10.
How returns are generated. parametric (default): the forward-looking published assumptions. bootstrap: stationary block bootstrap of historical months. historical: replays real months from 1926 in order. The last two need a PRO licence; without one the engine runs parametric and the result says so.
Age Social Security starts. Default 67.
Annual inflation as a percent, e.g. 2.5. Default 2.5.
Age work income stops. Defaults to current age.
Which published return set to use (see list_return_assumption_sources). Default jpmorgan.
Planned yearly spending in today's dollars, before income tax (this tool runs the standard engine, which does not model tax).
Total invested portfolio today, in dollars.
Age the plan must last until. Default 92.
Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden.
Age the pension starts. Default 65.
Spending rule. fixed (default): the planned amount, inflation-adjusted, every year. guyton-klinger: guardrails that cut or raise spending as the portfolio moves. vpw: variable percentage withdrawal. bucket: a cash reserve of bucket_years of spending.
Monthly savings until retirement. Default 0.
Runs the same plan against several published capital market assumption sets and returns the success rate and median outcome under each, showing how far the answer moves with the return forecast used. Every input is optional: omitted plan inputs use an illustrative plan (age 65, $1,000,000 saved, $40,000 a year spending) which the reply states in its first line.
| Argument | Type | Description |
|---|---|---|
| pension | number | Yearly pension income. Default 0. |
| sources | array | Source ids to compare. Defaults to all. |
| allocations | array | Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]. |
| current_age | integer | Current age of the primary person. |
| bucket_years | integer | Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10. |
| return_model | string | How returns are generated. parametric (default): the forward-looking published assumptions. bootstrap: stationary block bootstrap of historical months. historical: replays real months from 1926 in order. The last two need a PRO licence; without one the engine runs parametric and the result says so. |
| ss_start_age | integer | Age Social Security starts. Default 67. |
| inflation_rate | number | Annual inflation as a percent, e.g. 2.5. Default 2.5. |
| retirement_age | integer | Age work income stops. Defaults to current age. |
| returns_source | string | Which published return set to use (see list_return_assumption_sources). Default jpmorgan. |
| annual_spending | number | Planned yearly spending in today's dollars, before income tax (this tool runs the standard engine, which does not model tax). |
| current_savings | number | Total invested portfolio today, in dollars. |
| life_expectancy | integer | Age the plan must last until. Default 92. |
| social_security | number | Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden. |
| pension_start_age | integer | Age the pension starts. Default 65. |
| withdrawal_strategy | string | Spending rule. fixed (default): the planned amount, inflation-adjusted, every year. guyton-klinger: guardrails that cut or raise spending as the portfolio moves. vpw: variable percentage withdrawal. bucket: a cash reserve of bucket_years of spending. |
| monthly_contribution | number | Monthly savings until retirement. Default 0. |
{
"type": "object",
"required": [],
"properties": {
"pension": {
"type": "number",
"description": "Yearly pension income. Default 0."
},
"sources": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source ids to compare. Defaults to all."
},
"allocations": {
"type": "array",
"items": {
"type": "number"
},
"maxItems": 5,
"minItems": 5,
"description": "Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]."
},
"current_age": {
"type": "integer",
"description": "Current age of the primary person."
},
"bucket_years": {
"type": "integer",
"description": "Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10."
},
"return_model": {
"enum": [
"parametric",
"bootstrap",
"historical"
],
"type": "string",
"description": "How returns are generated. parametric (default): the forward-looking published assumptions. bootstrap: stationary block bootstrap of historical months. historical: replays real months from 1926 in order. The last two need a PRO licence; without one the engine runs parametric and the result says so."
},
"ss_start_age": {
"type": "integer",
"description": "Age Social Security starts. Default 67."
},
"inflation_rate": {
"type": "number",
"description": "Annual inflation as a percent, e.g. 2.5. Default 2.5."
},
"retirement_age": {
"type": "integer",
"description": "Age work income stops. Defaults to current age."
},
"returns_source": {
"type": "string",
"description": "Which published return set to use (see list_return_assumption_sources). Default jpmorgan."
},
"annual_spending": {
"type": "number",
"description": "Planned yearly spending in today's dollars, before income tax (this tool runs the standard engine, which does not model tax)."
},
"current_savings": {
"type": "number",
"description": "Total invested portfolio today, in dollars."
},
"life_expectancy": {
"type": "integer",
"description": "Age the plan must last until. Default 92."
},
"social_security": {
"type": "number",
"description": "Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden."
},
"pension_start_age": {
"type": "integer",
"description": "Age the pension starts. Default 65."
},
"withdrawal_strategy": {
"enum": [
"fixed",
"guyton-klinger",
"vpw",
"bucket"
],
"type": "string",
"description": "Spending rule. fixed (default): the planned amount, inflation-adjusted, every year. guyton-klinger: guardrails that cut or raise spending as the portfolio moves. vpw: variable percentage withdrawal. bucket: a cash reserve of bucket_years of spending."
},
"monthly_contribution": {
"type": "number",
"description": "Monthly savings until retirement. Default 0."
}
}
}Estimates a household's 2026 federal and state income tax return from its 2026 income (wages, Social Security, IRA and 401(k) distributions, pensions, Roth conversions, interest, dividends, capital gains and losses), deductions, withholding and estimated payments, and returns the federal refund or amount owed, the state refund or amount owed, and both together; the main Form 1040 lines (total income, AGI, deduction, taxable income, tax, total tax) and the state's taxable income and tax; and every default assumed, the facts the state engine assumed, and what is not modelled. Computed by QuantCalc's federal and state tax APIs, the engines the website's 2026 Return Preview is checked against to the cent. Requires a connected QuantCalc PRO licence or Tax Season Pass; without one it returns no figures and names the free web calculator. An estimate, not a filed return and not tax advice.
| Argument | Type | Description |
|---|---|---|
| age* | integer | The age the filer reaches in 2026 (18-110). |
| state* | string | Two-letter state of residence for all of 2026, or DC. States with no income tax (e.g. TX, FL) return a state tax of 0. |
| wages | number | The filer's 2026 wages (Form W-2 box 1). Default 0. |
| pension | number | Taxable 2026 pension and annuity income, the household's total. Default 0. |
| spouse_age | integer | Joint return only: the age the spouse reaches in 2026. Default: the same as age, stated in the result. |
Returns what the QuantCalc engine models and what it deliberately leaves out, including the tax provisions that are out of scope, and links to the published methodology.
No arguments.
{
"type": "object",
"properties": {}
}Returns the published capital market assumption sets the engine carries and which components each publisher provides (returns, volatilities, correlations).
No arguments.
{
"type": "object",
"properties": {}
}Searches every Social Security claiming age from 62 (or today's age) to 70 for the household's tax-aware plan: each age's benefit is the given benefit restated by the SSA reduction and delayed-retirement-credit rules, and each age runs the full tax-aware plan on the same simulated markets as the plan's own age. The score of a path is the after-tax estate minus unfunded spending (today's dollars); the result gives each age's success rate and median paired difference against the plan, the best age, and the 10th-90th percentile range. Requires a connected QuantCalc PRO licence. Long searches return a job_id: call again with only job_id to fetch the result.
| Argument | Type | Description |
|---|---|---|
| state | string | Two-letter state of residence (or DC) for state income tax with that state's retirement-income rules. When absent the result states that no state tax was modelled. |
| job_id | string | Only to fetch a search a previous call started: the job_id it returned. With it, no other input is read. |
| annuity | object | Optional: a single-life immediate annuity bought at purchase_age with premium (today's dollars) from the traditional IRA (a qualified annuity: payments fully taxable) or the taxable account (non-qualified: each payment is tax-free up to the premium over the IRS Table V multiple until the premium is recovered). Payments start in the purchase year and stop at death. |
| pension | number | Yearly pension income. Default 0. |
| lifespan | string |
Runs a Monte Carlo retirement projection on the QuantCalc engine and returns the success rate, the ending-portfolio distribution, and the assumptions that produced them. The result states the return model that ran, the number of paths, and the income assumptions it used, including when there are none. Income tax is not modelled by this tool; run_tax_aware_projection models it.
| Argument | Type | Description |
|---|---|---|
| pension | number | Yearly pension income. Default 0. |
| allocations | array | Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]. |
| current_age* | integer | Current age of the primary person. |
| bucket_years | integer | Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10. |
| return_model | string | How returns are generated. parametric (default): the forward-looking published assumptions. bootstrap: stationary block bootstrap of historical months. historical: replays real months from 1926 in order. The last two need a PRO licence; without one the engine runs parametric and the result says so. |
| ss_start_age | integer | Age Social Security starts. Default 67. |
Runs the retirement projection with the household's accounts split by tax type and returns the withdrawal order and Roth-conversion programme the engine selected, its present-value advantage and range against drawing traditional first, and the after-tax success rate. Federal and state income tax (50 states and DC), Social Security taxability, required minimum distributions, Medicare IRMAA surcharges and the early-withdrawal penalty are paid from the portfolio year by year; spending is what the household keeps after tax. The result states every assumption it used, including the defaults for inputs that were not given, and what the engine does not model.
| Argument | Type | Description |
|---|---|---|
| state | string | Two-letter state of residence (or DC) for state income tax with that state's retirement-income rules. When absent the result states that no state tax was modelled. |
| annuity | object | Optional: a single-life immediate annuity bought at purchase_age with premium (today's dollars) from the traditional IRA (a qualified annuity: payments fully taxable) or the taxable account (non-qualified: each payment is tax-free up to the premium over the IRS Table V multiple until the premium is recovered). Payments start in the purchase year and stop at death. |
| pension | number | Yearly pension income. Default 0. |
| lifespan | string | fixed (default): the plan runs to its end age. stochastic: each path draws your death year from the SSA period life table and ends after it (the estate is held at its value at death; success = the money lasted while you were alive). Not on a joint return. |
| birth_month | integer | Filer's birth month, 1-12, optional. With it the 10% early-withdrawal tax applies only to the part of the year before 59 and a half; without it, through the year the filer reaches 59. |
| pension_type | string | Whether the pension is a private pension or a government (public) pension, for the state's retirement-income rules. Default private, stated in the result when a pension is given. |
| spouse_split | string | Joint return only: whose the IRA distributions, pension and Roth conversion are on the state return: even (half each), filer, spouse, or custom (the spouse's own amounts in spouse_ira_distributions, spouse_pension and spouse_roth_conversion, the rest the filer's). Arkansas, Delaware, Maryland, Minnesota, Missouri, North Dakota, Ohio and Virginia tax a couple by each spouse's own income, so there it can change the state tax; federal tax does not depend on it. Default even, stated in the result. |
| spouse_wages | number | Joint return only: the spouse's 2026 wages. Default 0. |
| filing_status* | string | 2026 filing status: single, married filing jointly (mfj), married filing separately (mfs) or head of household (hoh). |
| prior_year_agi | number | 2025 adjusted gross income, used with prior_year_tax: above $150,000 ($75,000 married filing separately) the prior-year safe harbor is 110%. |
| prior_year_tax | number | Total tax on the 2025 return. With it the underpayment penalty (Form 2210) is figured and subtracted; without it the penalty is not figured, stated in the result. |
| qualified_tips | number | Qualified tips included in the wages, deducted on Schedule 1-A (IRC 224, up to $25,000, phased out above $150,000 / $300,000 MAGI; none married filing separately). Not more than the wages. Default 0. |
| spouse_pension | number | spouse_split custom only: the spouse's part of pension. |
| charitable_cash | number | Cash gifts to charity in 2026. The engine figures the return with the standard deduction (with the 2026 deduction for non-itemizers' cash gifts) and with the itemized deductions given, and keeps the lower tax. Default 0. |
| long_term_gains | number | 2026 net long-term capital gain; negative for a net loss. Default 0. |
| roth_conversion | number | Taxable amount converted to Roth in 2026, the household's total. Default 0. |
| social_security | number | Gross 2026 Social Security benefits of the household (Form SSA-1099 box 5); the engine figures the taxable part. Default 0. |
| medical_expenses | number | Itemized deduction input: medical and dental expenses paid in 2026, before the AGI floor. Default 0. |
| short_term_gains | number | 2026 net short-term capital gain; negative for a net loss. Default 0. |
| taxable_interest | number | Taxable interest (Form 1040 line 2b). Default 0. |
| ira_distributions | number | Taxable 2026 IRA, 401(k) and 403(b) distributions (not Roth conversions), the household's total. Default 0. |
| mortgage_interest | number | Itemized deduction input: home mortgage interest paid in 2026. Default 0. |
| state_withholding | number | State income tax withheld in 2026. Default 0. |
| estimated_payments | array | The 2026 federal estimated tax payments, up to four installments in order (April, June, September, January). Default none. |
| ordinary_dividends | number | Ordinary dividends, Form 1099-DIV box 1a (line 3b), including the qualified part. Default 0. |
| qualified_overtime | number | Qualified overtime compensation included in the wages: the FLSA overtime premium only (the half in time-and-a-half), deducted on Schedule 1-A (IRC 225, up to $12,500, $25,000 joint, phased out above $150,000 / $300,000 MAGI; none married filing separately). Not more than the wages. Default 0. |
| spouse_birth_month | integer | Joint return only: the spouse's birth month, 1-12, optional. |
| federal_withholding | number | Federal income tax withheld in 2026 from wages, pensions, IRA distributions and Social Security. Default 0, stated in the result. |
| qualified_dividends | number | The qualified part of ordinary_dividends (box 1b, line 3a), taxed at the capital-gains rates; not more than ordinary_dividends. Default 0. |
| tax_exempt_interest | number | Tax-exempt (municipal bond) interest (line 2a): not taxed, but counts toward the taxable part of Social Security. Default 0. |
| marketplace_coverage | boolean | True if the household had Marketplace (ACA) health coverage in 2026: the premium tax credit is not reconciled by this estimate and the result says so. |
| real_estate_tax_paid | number | Itemized deduction input: real estate tax paid in 2026. Default 0. |
| other_ordinary_income | number | Other ordinary income that is not investment income (Schedule 1). Default 0. |
| spouse_roth_conversion | number | spouse_split custom only: the spouse's part of roth_conversion. |
| spouse_ira_distributions | number | spouse_split custom only: the spouse's part of ira_distributions. |
| state_estimated_payments | number | State estimated tax paid for 2026, the total. Default 0. |
| capital_gain_distributions | number | Capital gain distributions from funds (Form 1099-DIV box 2a). Default 0. |
| state_local_income_tax_paid | number | Itemized deduction input: state and local income tax paid in 2026 (Schedule A line 5a). Default 0. |
| capital_loss_carryover_long_term | number | Long-term capital loss carried over from 2025, as a positive number. Default 0. |
| capital_loss_carryover_short_term | number | Short-term capital loss carried over from 2025, as a positive number. Default 0. |
{
"type": "object",
"required": [
"filing_status",
"age",
"state"
],
"properties": {
"age": {
"type": "integer",
"description": "The age the filer reaches in 2026 (18-110)."
},
"state": {
"type": "string",
"description": "Two-letter state of residence for all of 2026, or DC. States with no income tax (e.g. TX, FL) return a state tax of 0."
},
"wages": {
"type": "number",
"description": "The filer's 2026 wages (Form W-2 box 1). Default 0."
},
"pension": {
"type": "number",
"description": "Taxable 2026 pension and annuity income, the household's total. Default 0."
},
"spouse_age": {
"type": "integer",
"description": "Joint return only: the age the spouse reaches in 2026. Default: the same as age, stated in the result."
},
"birth_month": {
"type": "integer",
"description": "Filer's birth month, 1-12, optional. With it the 10% early-withdrawal tax applies only to the part of the year before 59 and a half; without it, through the year the filer reaches 59."
},
"pension_type": {
"enum": [
"private",
"public"
],
"type": "string",
"description": "Whether the pension is a private pension or a government (public) pension, for the state's retirement-income rules. Default private, stated in the result when a pension is given."
},
"spouse_split": {
"enum": [
"even",
"filer",
"spouse",
"custom"
],
"type": "string",
"description": "Joint return only: whose the IRA distributions, pension and Roth conversion are on the state return: even (half each), filer, spouse, or custom (the spouse's own amounts in spouse_ira_distributions, spouse_pension and spouse_roth_conversion, the rest the filer's). Arkansas, Delaware, Maryland, Minnesota, Missouri, North Dakota, Ohio and Virginia tax a couple by each spouse's own income, so there it can change the state tax; federal tax does not depend on it. Default even, stated in the result."
},
"spouse_wages": {
"type": "number",
"description": "Joint return only: the spouse's 2026 wages. Default 0."
},
"filing_status": {
"enum": [
"single",
"mfj",
"mfs",
"hoh"
],
"type": "string",
"description": "2026 filing status: single, married filing jointly (mfj), married filing separately (mfs) or head of household (hoh)."
},
"prior_year_agi": {
"type": "number",
"description": "2025 adjusted gross income, used with prior_year_tax: above $150,000 ($75,000 married filing separately) the prior-year safe harbor is 110%."
},
"prior_year_tax": {
"type": "number",
"description": "Total tax on the 2025 return. With it the underpayment penalty (Form 2210) is figured and subtracted; without it the penalty is not figured, stated in the result."
},
"qualified_tips": {
"type": "number",
"description": "Qualified tips included in the wages, deducted on Schedule 1-A (IRC 224, up to $25,000, phased out above $150,000 / $300,000 MAGI; none married filing separately). Not more than the wages. Default 0."
},
"spouse_pension": {
"type": "number",
"description": "spouse_split custom only: the spouse's part of pension."
},
"charitable_cash": {
"type": "number",
"description": "Cash gifts to charity in 2026. The engine figures the return with the standard deduction (with the 2026 deduction for non-itemizers' cash gifts) and with the itemized deductions given, and keeps the lower tax. Default 0."
},
"long_term_gains": {
"type": "number",
"description": "2026 net long-term capital gain; negative for a net loss. Default 0."
},
"roth_conversion": {
"type": "number",
"description": "Taxable amount converted to Roth in 2026, the household's total. Default 0."
},
"social_security": {
"type": "number",
"description": "Gross 2026 Social Security benefits of the household (Form SSA-1099 box 5); the engine figures the taxable part. Default 0."
},
"medical_expenses": {
"type": "number",
"description": "Itemized deduction input: medical and dental expenses paid in 2026, before the AGI floor. Default 0."
},
"short_term_gains": {
"type": "number",
"description": "2026 net short-term capital gain; negative for a net loss. Default 0."
},
"taxable_interest": {
"type": "number",
"description": "Taxable interest (Form 1040 line 2b). Default 0."
},
"ira_distributions": {
"type": "number",
"description": "Taxable 2026 IRA, 401(k) and 403(b) distributions (not Roth conversions), the household's total. Default 0."
},
"mortgage_interest": {
"type": "number",
"description": "Itemized deduction input: home mortgage interest paid in 2026. Default 0."
},
"state_withholding": {
"type": "number",
"description": "State income tax withheld in 2026. Default 0."
},
"estimated_payments": {
"type": "array",
"items": {
"type": "number"
},
"maxItems": 4,
"description": "The 2026 federal estimated tax payments, up to four installments in order (April, June, September, January). Default none."
},
"ordinary_dividends": {
"type": "number",
"description": "Ordinary dividends, Form 1099-DIV box 1a (line 3b), including the qualified part. Default 0."
},
"qualified_overtime": {
"type": "number",
"description": "Qualified overtime compensation included in the wages: the FLSA overtime premium only (the half in time-and-a-half), deducted on Schedule 1-A (IRC 225, up to $12,500, $25,000 joint, phased out above $150,000 / $300,000 MAGI; none married filing separately). Not more than the wages. Default 0."
},
"spouse_birth_month": {
"type": "integer",
"description": "Joint return only: the spouse's birth month, 1-12, optional."
},
"federal_withholding": {
"type": "number",
"description": "Federal income tax withheld in 2026 from wages, pensions, IRA distributions and Social Security. Default 0, stated in the result."
},
"qualified_dividends": {
"type": "number",
"description": "The qualified part of ordinary_dividends (box 1b, line 3a), taxed at the capital-gains rates; not more than ordinary_dividends. Default 0."
},
"tax_exempt_interest": {
"type": "number",
"description": "Tax-exempt (municipal bond) interest (line 2a): not taxed, but counts toward the taxable part of Social Security. Default 0."
},
"marketplace_coverage": {
"type": "boolean",
"description": "True if the household had Marketplace (ACA) health coverage in 2026: the premium tax credit is not reconciled by this estimate and the result says so."
},
"real_estate_tax_paid": {
"type": "number",
"description": "Itemized deduction input: real estate tax paid in 2026. Default 0."
},
"other_ordinary_income": {
"type": "number",
"description": "Other ordinary income that is not investment income (Schedule 1). Default 0."
},
"spouse_roth_conversion": {
"type": "number",
"description": "spouse_split custom only: the spouse's part of roth_conversion."
},
"spouse_ira_distributions": {
"type": "number",
"description": "spouse_split custom only: the spouse's part of ira_distributions."
},
"state_estimated_payments": {
"type": "number",
"description": "State estimated tax paid for 2026, the total. Default 0."
},
"capital_gain_distributions": {
"type": "number",
"description": "Capital gain distributions from funds (Form 1099-DIV box 2a). Default 0."
},
"state_local_income_tax_paid": {
"type": "number",
"description": "Itemized deduction input: state and local income tax paid in 2026 (Schedule A line 5a). Default 0."
},
"capital_loss_carryover_long_term": {
"type": "number",
"description": "Long-term capital loss carried over from 2025, as a positive number. Default 0."
},
"capital_loss_carryover_short_term": {
"type": "number",
"description": "Short-term capital loss carried over from 2025, as a positive number. Default 0."
}
}
}| fixed (default): the plan runs to its end age. stochastic: each path draws your death year from the SSA period life table and ends after it (the estate is held at its value at death; success = the money lasted while you were alive). Not on a joint return. |
| ira_basis | number | Optional: your Form 8606 basis (nondeductible traditional IRA contributions not yet recovered); that share of each traditional withdrawal and conversion is tax-free. Not with a per-owner traditional balance. |
| annual_qcd | number | Yearly qualified charitable distribution from the traditional account, in today's dollars, counted against required minimum distributions. Default 0. |
| birth_year | integer | Year of birth, optional. Must match current_age: 2026 minus current_age, or 2025 minus current_age when this year's birthday is still to come (then every tax rule uses the age reached in each calendar year). Sets the RMD start age (73 if born 1951-1959, 75 if born 1960 or later). Default: 2026 minus current_age, stated in the result. |
| dependents | array | Optional: up to 8 people you claim, each {age (at the end of 2026; negative = born later), student, disabled}. Each retirement year counts the qualifying children that year for the child tax credit (under 17), the credit for other dependents and the earned income credit, and gives them to the state return. |
| spouse_age | integer | Spouse's current age, for married filing jointly: sets the second aged deduction and Medicare surcharge. Default: the same as current_age, stated in the result. |
| allocations | array | Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]. |
| birth_month | integer | Month of birth, 1-12, optional. Times the half-year rules: the early-withdrawal penalty ends at 59 and a half, charitable distributions start at 70 and a half, Medicare starts in the birthday month. Default: not given, stated in the result. |
| current_age | integer | Current age of the primary person. |
| bucket_years | integer | Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10. |
| pension_type | string | Whether the pension is private or a government (public) pension, which several states exempt from state income tax. Only affects the tax-aware tool. Default private, and the tax-aware result states it. |
| return_model | string | How returns are generated. parametric (default): the forward-looking published assumptions. bootstrap: stationary block bootstrap of historical months. historical: replays real months from 1926 in order. The last two need a PRO licence; without one the engine runs parametric and the result says so. |
| roth_balance | number | Roth IRA and Roth 401(k) balance today, in dollars. 0 if none. |
| spouse_split | string | Married filing jointly with a state: whose IRA withdrawals, pension and Roth conversions they are on the state return: even (half each), filer (all the filer's) or spouse (all the spouse's). Arkansas, Delaware, Maryland, Minnesota, Missouri, North Dakota, Ohio and Virginia tax a couple by each spouse's own income, so there it can change the state tax; federal tax does not depend on it. Default on a joint return with a state: even (the spouse's age is then needed; when spouse_age is not given it is current_age), stated in the result. Not used off a joint return or without a state. |
| ss_start_age | integer | Age Social Security starts. Default 67. |
| filing_status | string | Federal filing status: single, married filing jointly (mfj), married filing separately (mfs) or head of household (hoh). |
| inflation_rate | number | Annual inflation as a percent, e.g. 2.5. Default 2.5. |
| retirement_age | integer | Age work income stops. Defaults to current age. |
| returns_source | string | Which published return set to use (see list_return_assumption_sources). Default jpmorgan. |
| aca_marketplace | object | Optional: the household buys marketplace (ACA) health coverage in the retirement years before Medicare. Each path's premium tax credit is figured each year by the federal engine's Form 8962 at that path's own income (no credit above 400% of the poverty line; Medicaid below 138% in expansion states), and the premium after the credit is funded each year and counted by the withdrawal-order search. Needs state. |
| annual_spending | number | Planned yearly spending in today's dollars, after tax: what the household keeps. The engine withdraws enough each year to fund this plus that year's federal, state, Medicare-surcharge and penalty tax. |
| life_expectancy | integer | Age the plan must last until. Default 92. |
| roth_conversion | object | The household's own Roth-conversion plan: a fixed amount per year between two ages. When given, the engine applies it on every path and searches withdrawal orders around it instead of searching its own conversion programmes. |
| social_security | number | Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden. |
| taxable_balance | number | Taxable brokerage and savings today, in dollars. 0 if none. The three balances together are the portfolio. |
| cost_basis_ratio | number | Percentage of the taxable account that is cost basis, 0-100. Default 40, and the result says so when it is assumed. |
| pension_start_age | integer | Age the pension starts. Default 65. |
| medicare_start_age | integer | Age Medicare (and its IRMAA income surcharges) begins. Default 65. The year it begins is charged only for the months from the birthday month. |
| itemized_deductions | object | Optional Schedule A amounts, in today's dollars a year: each year the engine adds that year's own state and local income tax (capped with the property tax by the SALT limit), takes gifts over 0.5% of AGI and medical costs over 7.5% of AGI, and itemizes when that gives the lower tax; otherwise the standard deduction. They are deductions only, assumed to be inside annual_spending already. Mortgage interest stays fixed in dollars until its end year, property tax rises 3.5% a year, giving with inflation, medical costs with inflation. Do not include QCDs in charitable_giving. Default: none, stated in the result. |
| tax_exempt_interest | number | Yearly municipal-bond interest, which counts toward Social Security taxability and IRMAA income but is not itself taxed. Default 0. |
| traditional_balance | number | Pre-tax retirement accounts today (traditional IRA, 401(k), 403(b)), in dollars. 0 if none. |
| withdrawal_strategy | string | Spending rule. fixed (default): the planned amount, inflation-adjusted, every year. guyton-klinger: guardrails that cut or raise spending as the portfolio moves. vpw: variable percentage withdrawal. bucket: a cash reserve of bucket_years of spending. |
| monthly_contribution | number | Monthly savings until retirement. Default 0. |
| roth_contribution_basis | number | Optional: the part of roth_balance that is your own regular Roth IRA contributions (withdrawn first, tax-free). Giving it, roth_first_contribution_year or ira_basis turns on the Roth ordering and 5-year rules on Roth withdrawals (earnings before 59 1/2 or inside the 5-year clock are taxed, with the 10% additional tax before 59 1/2) and the Form 8606 pro-rata rule on traditional withdrawals and conversions. Default: all of roth_balance. |
| roth_first_contribution_year | integer | Optional: the first year you contributed to or converted into any Roth IRA (the 5-year clock), 1998-2026. Default: 2021 when roth_balance > 0. |
{
"type": "object",
"properties": {
"state": {
"type": "string",
"description": "Two-letter state of residence (or DC) for state income tax with that state's retirement-income rules. When absent the result states that no state tax was modelled."
},
"job_id": {
"type": "string",
"description": "Only to fetch a search a previous call started: the job_id it returned. With it, no other input is read."
},
"annuity": {
"type": "object",
"required": [
"purchase_age",
"premium",
"source",
"payout_rate"
],
"properties": {
"cola": {
"type": "number",
"description": "Fixed yearly increase of the payment in percent. Default 0."
},
"source": {
"enum": [
"traditional",
"taxable"
],
"type": "string"
},
"premium": {
"type": "number",
"description": "Single premium in today's dollars."
},
"payout_rate": {
"type": "number",
"description": "First year's payments as a percent of the premium (from a quote)."
},
"purchase_age": {
"type": "integer",
"description": "Age at purchase, in retirement."
}
},
"description": "Optional: a single-life immediate annuity bought at purchase_age with premium (today's dollars) from the traditional IRA (a qualified annuity: payments fully taxable) or the taxable account (non-qualified: each payment is tax-free up to the premium over the IRS Table V multiple until the premium is recovered). Payments start in the purchase year and stop at death."
},
"pension": {
"type": "number",
"description": "Yearly pension income. Default 0."
},
"lifespan": {
"enum": [
"fixed",
"stochastic"
],
"type": "string",
"description": "fixed (default): the plan runs to its end age. stochastic: each path draws your death year from the SSA period life table and ends after it (the estate is held at its value at death; success = the money lasted while you were alive). Not on a joint return."
},
"ira_basis": {
"type": "number",
"description": "Optional: your Form 8606 basis (nondeductible traditional IRA contributions not yet recovered); that share of each traditional withdrawal and conversion is tax-free. Not with a per-owner traditional balance."
},
"annual_qcd": {
"type": "number",
"description": "Yearly qualified charitable distribution from the traditional account, in today's dollars, counted against required minimum distributions. Default 0."
},
"birth_year": {
"type": "integer",
"description": "Year of birth, optional. Must match current_age: 2026 minus current_age, or 2025 minus current_age when this year's birthday is still to come (then every tax rule uses the age reached in each calendar year). Sets the RMD start age (73 if born 1951-1959, 75 if born 1960 or later). Default: 2026 minus current_age, stated in the result."
},
"dependents": {
"type": "array",
"items": {
"type": "object",
"required": [
"age"
],
"properties": {
"age": {
"type": "integer"
},
"student": {
"type": "boolean"
},
"disabled": {
"type": "boolean"
}
}
},
"description": "Optional: up to 8 people you claim, each {age (at the end of 2026; negative = born later), student, disabled}. Each retirement year counts the qualifying children that year for the child tax credit (under 17), the credit for other dependents and the earned income credit, and gives them to the state return."
},
"spouse_age": {
"type": "integer",
"description": "Spouse's current age, for married filing jointly: sets the second aged deduction and Medicare surcharge. Default: the same as current_age, stated in the result."
},
"allocations": {
"type": "array",
"items": {
"type": "number"
},
"maxItems": 5,
"minItems": 5,
"description": "Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]."
},
"birth_month": {
"type": "integer",
"description": "Month of birth, 1-12, optional. Times the half-year rules: the early-withdrawal penalty ends at 59 and a half, charitable distributions start at 70 and a half, Medicare starts in the birthday month. Default: not given, stated in the result."
},
"current_age": {
"type": "integer",
"description": "Current age of the primary person."
},
"bucket_years": {
"type": "integer",
"description": "Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10."
},
"pension_type": {
"enum": [
"private",
"public"
],
"type": "string",
"description": "Whether the pension is private or a government (public) pension, which several states exempt from state income tax. Only affects the tax-aware tool. Default private, and the tax-aware result states it."
},
"return_model": {
"enum": [
"parametric",
"bootstrap",
"historical"
],
"type": "string",
"description": "How returns are generated. parametric (default): the forward-looking published assumptions. bootstrap: stationary block bootstrap of historical months. historical: replays real months from 1926 in order. The last two need a PRO licence; without one the engine runs parametric and the result says so."
},
"roth_balance": {
"type": "number",
"description": "Roth IRA and Roth 401(k) balance today, in dollars. 0 if none."
},
"spouse_split": {
"enum": [
"even",
"filer",
"spouse"
],
"type": "string",
"description": "Married filing jointly with a state: whose IRA withdrawals, pension and Roth conversions they are on the state return: even (half each), filer (all the filer's) or spouse (all the spouse's). Arkansas, Delaware, Maryland, Minnesota, Missouri, North Dakota, Ohio and Virginia tax a couple by each spouse's own income, so there it can change the state tax; federal tax does not depend on it. Default on a joint return with a state: even (the spouse's age is then needed; when spouse_age is not given it is current_age), stated in the result. Not used off a joint return or without a state."
},
"ss_start_age": {
"type": "integer",
"description": "Age Social Security starts. Default 67."
},
"filing_status": {
"enum": [
"single",
"mfj",
"mfs",
"hoh"
],
"type": "string",
"description": "Federal filing status: single, married filing jointly (mfj), married filing separately (mfs) or head of household (hoh)."
},
"inflation_rate": {
"type": "number",
"description": "Annual inflation as a percent, e.g. 2.5. Default 2.5."
},
"retirement_age": {
"type": "integer",
"description": "Age work income stops. Defaults to current age."
},
"returns_source": {
"type": "string",
"description": "Which published return set to use (see list_return_assumption_sources). Default jpmorgan."
},
"aca_marketplace": {
"type": "object",
"required": [
"spending_includes_premium"
],
"properties": {
"cover_spouse": {
"type": "boolean",
"description": "Joint return: the spouse is on the plan too. Default true."
},
"household_size": {
"type": "integer",
"description": "Tax family size for the poverty line (you, a spouse on a joint return, dependents). Default 2 on a joint return, else 1."
},
"benchmark_premium": {
"type": "number",
"description": "The household's 2026 annual benchmark (second-lowest-cost silver) premium at its 2026 ages, from healthcare.gov or the state's marketplace. Default: the state-average model, stated in the result."
},
"spending_includes_premium": {
"type": "boolean",
"description": "Required. true: annual_spending already includes the full, unsubsidized benchmark premium (it is taken out and the premium after the credit paid instead); false: the premium after the credit is paid on top of annual_spending."
}
},
"description": "Optional: the household buys marketplace (ACA) health coverage in the retirement years before Medicare. Each path's premium tax credit is figured each year by the federal engine's Form 8962 at that path's own income (no credit above 400% of the poverty line; Medicaid below 138% in expansion states), and the premium after the credit is funded each year and counted by the withdrawal-order search. Needs state."
},
"annual_spending": {
"type": "number",
"description": "Planned yearly spending in today's dollars, after tax: what the household keeps. The engine withdraws enough each year to fund this plus that year's federal, state, Medicare-surcharge and penalty tax."
},
"life_expectancy": {
"type": "integer",
"description": "Age the plan must last until. Default 92."
},
"roth_conversion": {
"type": "object",
"required": [
"annual_amount",
"start_age",
"end_age"
],
"properties": {
"end_age": {
"type": "integer"
},
"start_age": {
"type": "integer"
},
"annual_amount": {
"type": "number",
"description": "Dollars converted per year, today's dollars."
}
},
"description": "The household's own Roth-conversion plan: a fixed amount per year between two ages. When given, the engine applies it on every path and searches withdrawal orders around it instead of searching its own conversion programmes."
},
"social_security": {
"type": "number",
"description": "Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden."
},
"taxable_balance": {
"type": "number",
"description": "Taxable brokerage and savings today, in dollars. 0 if none. The three balances together are the portfolio."
},
"cost_basis_ratio": {
"type": "number",
"description": "Percentage of the taxable account that is cost basis, 0-100. Default 40, and the result says so when it is assumed."
},
"pension_start_age": {
"type": "integer",
"description": "Age the pension starts. Default 65."
},
"medicare_start_age": {
"type": "integer",
"description": "Age Medicare (and its IRMAA income surcharges) begins. Default 65. The year it begins is charged only for the months from the birthday month."
},
"itemized_deductions": {
"type": "object",
"properties": {
"property_tax": {
"type": "number",
"description": "Real estate tax on the home per year."
},
"medical_expenses": {
"type": "number",
"description": "Unreimbursed medical and dental costs per year, before the 7.5% floor."
},
"charitable_giving": {
"type": "number",
"description": "Cash gifts to charity per year, not counting QCDs."
},
"mortgage_interest": {
"type": "number",
"description": "Deductible home mortgage interest per year."
},
"mortgage_interest_end_year": {
"type": "integer",
"description": "Last calendar year with mortgage interest. Default: every year."
}
},
"description": "Optional Schedule A amounts, in today's dollars a year: each year the engine adds that year's own state and local income tax (capped with the property tax by the SALT limit), takes gifts over 0.5% of AGI and medical costs over 7.5% of AGI, and itemizes when that gives the lower tax; otherwise the standard deduction. They are deductions only, assumed to be inside annual_spending already. Mortgage interest stays fixed in dollars until its end year, property tax rises 3.5% a year, giving with inflation, medical costs with inflation. Do not include QCDs in charitable_giving. Default: none, stated in the result."
},
"tax_exempt_interest": {
"type": "number",
"description": "Yearly municipal-bond interest, which counts toward Social Security taxability and IRMAA income but is not itself taxed. Default 0."
},
"traditional_balance": {
"type": "number",
"description": "Pre-tax retirement accounts today (traditional IRA, 401(k), 403(b)), in dollars. 0 if none."
},
"withdrawal_strategy": {
"enum": [
"fixed",
"guyton-klinger",
"vpw",
"bucket"
],
"type": "string",
"description": "Spending rule. fixed (default): the planned amount, inflation-adjusted, every year. guyton-klinger: guardrails that cut or raise spending as the portfolio moves. vpw: variable percentage withdrawal. bucket: a cash reserve of bucket_years of spending."
},
"monthly_contribution": {
"type": "number",
"description": "Monthly savings until retirement. Default 0."
},
"roth_contribution_basis": {
"type": "number",
"description": "Optional: the part of roth_balance that is your own regular Roth IRA contributions (withdrawn first, tax-free). Giving it, roth_first_contribution_year or ira_basis turns on the Roth ordering and 5-year rules on Roth withdrawals (earnings before 59 1/2 or inside the 5-year clock are taxed, with the 10% additional tax before 59 1/2) and the Form 8606 pro-rata rule on traditional withdrawals and conversions. Default: all of roth_balance."
},
"roth_first_contribution_year": {
"type": "integer",
"description": "Optional: the first year you contributed to or converted into any Roth IRA (the 5-year clock), 1998-2026. Default: 2021 when roth_balance > 0."
}
}
}| inflation_rate |
| number |
| Annual inflation as a percent, e.g. 2.5. Default 2.5. |
| retirement_age | integer | Age work income stops. Defaults to current age. |
| returns_source | string | Which published return set to use (see list_return_assumption_sources). Default jpmorgan. |
| annual_spending* | number | Planned yearly spending in today's dollars, before income tax (this tool runs the standard engine, which does not model tax). |
| current_savings* | number | Total invested portfolio today, in dollars. |
| life_expectancy | integer | Age the plan must last until. Default 92. |
| social_security | number | Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden. |
| pension_start_age | integer | Age the pension starts. Default 65. |
| withdrawal_strategy | string | Spending rule. fixed (default): the planned amount, inflation-adjusted, every year. guyton-klinger: guardrails that cut or raise spending as the portfolio moves. vpw: variable percentage withdrawal. bucket: a cash reserve of bucket_years of spending. |
| monthly_contribution | number | Monthly savings until retirement. Default 0. |
{
"type": "object",
"required": [
"current_age",
"current_savings",
"annual_spending"
],
"properties": {
"pension": {
"type": "number",
"description": "Yearly pension income. Default 0."
},
"allocations": {
"type": "array",
"items": {
"type": "number"
},
"maxItems": 5,
"minItems": 5,
"description": "Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]."
},
"current_age": {
"type": "integer",
"description": "Current age of the primary person."
},
"bucket_years": {
"type": "integer",
"description": "Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10."
},
"return_model": {
"enum": [
"parametric",
"bootstrap",
"historical"
],
"type": "string",
"description": "How returns are generated. parametric (default): the forward-looking published assumptions. bootstrap: stationary block bootstrap of historical months. historical: replays real months from 1926 in order. The last two need a PRO licence; without one the engine runs parametric and the result says so."
},
"ss_start_age": {
"type": "integer",
"description": "Age Social Security starts. Default 67."
},
"inflation_rate": {
"type": "number",
"description": "Annual inflation as a percent, e.g. 2.5. Default 2.5."
},
"retirement_age": {
"type": "integer",
"description": "Age work income stops. Defaults to current age."
},
"returns_source": {
"type": "string",
"description": "Which published return set to use (see list_return_assumption_sources). Default jpmorgan."
},
"annual_spending": {
"type": "number",
"description": "Planned yearly spending in today's dollars, before income tax (this tool runs the standard engine, which does not model tax)."
},
"current_savings": {
"type": "number",
"description": "Total invested portfolio today, in dollars."
},
"life_expectancy": {
"type": "integer",
"description": "Age the plan must last until. Default 92."
},
"social_security": {
"type": "number",
"description": "Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden."
},
"pension_start_age": {
"type": "integer",
"description": "Age the pension starts. Default 65."
},
"withdrawal_strategy": {
"enum": [
"fixed",
"guyton-klinger",
"vpw",
"bucket"
],
"type": "string",
"description": "Spending rule. fixed (default): the planned amount, inflation-adjusted, every year. guyton-klinger: guardrails that cut or raise spending as the portfolio moves. vpw: variable percentage withdrawal. bucket: a cash reserve of bucket_years of spending."
},
"monthly_contribution": {
"type": "number",
"description": "Monthly savings until retirement. Default 0."
}
}
}| ira_basis | number | Optional: your Form 8606 basis (nondeductible traditional IRA contributions not yet recovered); that share of each traditional withdrawal and conversion is tax-free. Not with a per-owner traditional balance. |
| annual_qcd | number | Yearly qualified charitable distribution from the traditional account, in today's dollars, counted against required minimum distributions. Default 0. |
| birth_year | integer | Year of birth, optional. Must match current_age: 2026 minus current_age, or 2025 minus current_age when this year's birthday is still to come (then every tax rule uses the age reached in each calendar year). Sets the RMD start age (73 if born 1951-1959, 75 if born 1960 or later). Default: 2026 minus current_age, stated in the result. |
| dependents | array | Optional: up to 8 people you claim, each {age (at the end of 2026; negative = born later), student, disabled}. Each retirement year counts the qualifying children that year for the child tax credit (under 17), the credit for other dependents and the earned income credit, and gives them to the state return. |
| spouse_age | integer | Spouse's current age, for married filing jointly: sets the second aged deduction and Medicare surcharge. Default: the same as current_age, stated in the result. |
| allocations | array | Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]. |
| birth_month | integer | Month of birth, 1-12, optional. Times the half-year rules: the early-withdrawal penalty ends at 59 and a half, charitable distributions start at 70 and a half, Medicare starts in the birthday month. Default: not given, stated in the result. |
| current_age* | integer | Current age of the primary person. |
| bucket_years | integer | Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10. |
| pension_type | string | Whether the pension is private or a government (public) pension, which several states exempt from state income tax. Only affects the tax-aware tool. Default private, and the tax-aware result states it. |
| return_model | string | How returns are generated. parametric (default): the forward-looking published assumptions. bootstrap: stationary block bootstrap of historical months. historical: replays real months from 1926 in order. The last two need a PRO licence; without one the engine runs parametric and the result says so. |
| roth_balance* | number | Roth IRA and Roth 401(k) balance today, in dollars. 0 if none. |
| spouse_split | string | Married filing jointly with a state: whose IRA withdrawals, pension and Roth conversions they are on the state return: even (half each), filer (all the filer's) or spouse (all the spouse's). Arkansas, Delaware, Maryland, Minnesota, Missouri, North Dakota, Ohio and Virginia tax a couple by each spouse's own income, so there it can change the state tax; federal tax does not depend on it. Default on a joint return with a state: even (the spouse's age is then needed; when spouse_age is not given it is current_age), stated in the result. Not used off a joint return or without a state. |
| ss_start_age | integer | Age Social Security starts. Default 67. |
| filing_status* | string | Federal filing status: single, married filing jointly (mfj), married filing separately (mfs) or head of household (hoh). |
| inflation_rate | number | Annual inflation as a percent, e.g. 2.5. Default 2.5. |
| retirement_age | integer | Age work income stops. Defaults to current age. |
| returns_source | string | Which published return set to use (see list_return_assumption_sources). Default jpmorgan. |
| aca_marketplace | object | Optional: the household buys marketplace (ACA) health coverage in the retirement years before Medicare. Each path's premium tax credit is figured each year by the federal engine's Form 8962 at that path's own income (no credit above 400% of the poverty line; Medicaid below 138% in expansion states), and the premium after the credit is funded each year and counted by the withdrawal-order search. Needs state. |
| annual_spending* | number | Planned yearly spending in today's dollars, after tax: what the household keeps. The engine withdraws enough each year to fund this plus that year's federal, state, Medicare-surcharge and penalty tax. |
| life_expectancy | integer | Age the plan must last until. Default 92. |
| roth_conversion | object | The household's own Roth-conversion plan: a fixed amount per year between two ages. When given, the engine applies it on every path and searches withdrawal orders around it instead of searching its own conversion programmes. |
| social_security | number | Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden. |
| taxable_balance* | number | Taxable brokerage and savings today, in dollars. 0 if none. The three balances together are the portfolio. |
| cost_basis_ratio | number | Percentage of the taxable account that is cost basis, 0-100. Default 40, and the result says so when it is assumed. |
| pension_start_age | integer | Age the pension starts. Default 65. |
| medicare_start_age | integer | Age Medicare (and its IRMAA income surcharges) begins. Default 65. The year it begins is charged only for the months from the birthday month. |
| itemized_deductions | object | Optional Schedule A amounts, in today's dollars a year: each year the engine adds that year's own state and local income tax (capped with the property tax by the SALT limit), takes gifts over 0.5% of AGI and medical costs over 7.5% of AGI, and itemizes when that gives the lower tax; otherwise the standard deduction. They are deductions only, assumed to be inside annual_spending already. Mortgage interest stays fixed in dollars until its end year, property tax rises 3.5% a year, giving with inflation, medical costs with inflation. Do not include QCDs in charitable_giving. Default: none, stated in the result. |
| tax_exempt_interest | number | Yearly municipal-bond interest, which counts toward Social Security taxability and IRMAA income but is not itself taxed. Default 0. |
| traditional_balance* | number | Pre-tax retirement accounts today (traditional IRA, 401(k), 403(b)), in dollars. 0 if none. |
| withdrawal_strategy | string | Spending rule. fixed (default): the planned amount, inflation-adjusted, every year. guyton-klinger: guardrails that cut or raise spending as the portfolio moves. vpw: variable percentage withdrawal. bucket: a cash reserve of bucket_years of spending. |
| monthly_contribution | number | Monthly savings until retirement. Default 0. |
| roth_contribution_basis | number | Optional: the part of roth_balance that is your own regular Roth IRA contributions (withdrawn first, tax-free). Giving it, roth_first_contribution_year or ira_basis turns on the Roth ordering and 5-year rules on Roth withdrawals (earnings before 59 1/2 or inside the 5-year clock are taxed, with the 10% additional tax before 59 1/2) and the Form 8606 pro-rata rule on traditional withdrawals and conversions. Default: all of roth_balance. |
| roth_first_contribution_year | integer | Optional: the first year you contributed to or converted into any Roth IRA (the 5-year clock), 1998-2026. Default: 2021 when roth_balance > 0. |
{
"type": "object",
"required": [
"current_age",
"annual_spending",
"traditional_balance",
"roth_balance",
"taxable_balance",
"filing_status"
],
"properties": {
"state": {
"type": "string",
"description": "Two-letter state of residence (or DC) for state income tax with that state's retirement-income rules. When absent the result states that no state tax was modelled."
},
"annuity": {
"type": "object",
"required": [
"purchase_age",
"premium",
"source",
"payout_rate"
],
"properties": {
"cola": {
"type": "number",
"description": "Fixed yearly increase of the payment in percent. Default 0."
},
"source": {
"enum": [
"traditional",
"taxable"
],
"type": "string"
},
"premium": {
"type": "number",
"description": "Single premium in today's dollars."
},
"payout_rate": {
"type": "number",
"description": "First year's payments as a percent of the premium (from a quote)."
},
"purchase_age": {
"type": "integer",
"description": "Age at purchase, in retirement."
}
},
"description": "Optional: a single-life immediate annuity bought at purchase_age with premium (today's dollars) from the traditional IRA (a qualified annuity: payments fully taxable) or the taxable account (non-qualified: each payment is tax-free up to the premium over the IRS Table V multiple until the premium is recovered). Payments start in the purchase year and stop at death."
},
"pension": {
"type": "number",
"description": "Yearly pension income. Default 0."
},
"lifespan": {
"enum": [
"fixed",
"stochastic"
],
"type": "string",
"description": "fixed (default): the plan runs to its end age. stochastic: each path draws your death year from the SSA period life table and ends after it (the estate is held at its value at death; success = the money lasted while you were alive). Not on a joint return."
},
"ira_basis": {
"type": "number",
"description": "Optional: your Form 8606 basis (nondeductible traditional IRA contributions not yet recovered); that share of each traditional withdrawal and conversion is tax-free. Not with a per-owner traditional balance."
},
"annual_qcd": {
"type": "number",
"description": "Yearly qualified charitable distribution from the traditional account, in today's dollars, counted against required minimum distributions. Default 0."
},
"birth_year": {
"type": "integer",
"description": "Year of birth, optional. Must match current_age: 2026 minus current_age, or 2025 minus current_age when this year's birthday is still to come (then every tax rule uses the age reached in each calendar year). Sets the RMD start age (73 if born 1951-1959, 75 if born 1960 or later). Default: 2026 minus current_age, stated in the result."
},
"dependents": {
"type": "array",
"items": {
"type": "object",
"required": [
"age"
],
"properties": {
"age": {
"type": "integer"
},
"student": {
"type": "boolean"
},
"disabled": {
"type": "boolean"
}
}
},
"description": "Optional: up to 8 people you claim, each {age (at the end of 2026; negative = born later), student, disabled}. Each retirement year counts the qualifying children that year for the child tax credit (under 17), the credit for other dependents and the earned income credit, and gives them to the state return."
},
"spouse_age": {
"type": "integer",
"description": "Spouse's current age, for married filing jointly: sets the second aged deduction and Medicare surcharge. Default: the same as current_age, stated in the result."
},
"allocations": {
"type": "array",
"items": {
"type": "number"
},
"maxItems": 5,
"minItems": 5,
"description": "Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]."
},
"birth_month": {
"type": "integer",
"description": "Month of birth, 1-12, optional. Times the half-year rules: the early-withdrawal penalty ends at 59 and a half, charitable distributions start at 70 and a half, Medicare starts in the birthday month. Default: not given, stated in the result."
},
"current_age": {
"type": "integer",
"description": "Current age of the primary person."
},
"bucket_years": {
"type": "integer",
"description": "Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10."
},
"pension_type": {
"enum": [
"private",
"public"
],
"type": "string",
"description": "Whether the pension is private or a government (public) pension, which several states exempt from state income tax. Only affects the tax-aware tool. Default private, and the tax-aware result states it."
},
"return_model": {
"enum": [
"parametric",
"bootstrap",
"historical"
],
"type": "string",
"description": "How returns are generated. parametric (default): the forward-looking published assumptions. bootstrap: stationary block bootstrap of historical months. historical: replays real months from 1926 in order. The last two need a PRO licence; without one the engine runs parametric and the result says so."
},
"roth_balance": {
"type": "number",
"description": "Roth IRA and Roth 401(k) balance today, in dollars. 0 if none."
},
"spouse_split": {
"enum": [
"even",
"filer",
"spouse"
],
"type": "string",
"description": "Married filing jointly with a state: whose IRA withdrawals, pension and Roth conversions they are on the state return: even (half each), filer (all the filer's) or spouse (all the spouse's). Arkansas, Delaware, Maryland, Minnesota, Missouri, North Dakota, Ohio and Virginia tax a couple by each spouse's own income, so there it can change the state tax; federal tax does not depend on it. Default on a joint return with a state: even (the spouse's age is then needed; when spouse_age is not given it is current_age), stated in the result. Not used off a joint return or without a state."
},
"ss_start_age": {
"type": "integer",
"description": "Age Social Security starts. Default 67."
},
"filing_status": {
"enum": [
"single",
"mfj",
"mfs",
"hoh"
],
"type": "string",
"description": "Federal filing status: single, married filing jointly (mfj), married filing separately (mfs) or head of household (hoh)."
},
"inflation_rate": {
"type": "number",
"description": "Annual inflation as a percent, e.g. 2.5. Default 2.5."
},
"retirement_age": {
"type": "integer",
"description": "Age work income stops. Defaults to current age."
},
"returns_source": {
"type": "string",
"description": "Which published return set to use (see list_return_assumption_sources). Default jpmorgan."
},
"aca_marketplace": {
"type": "object",
"required": [
"spending_includes_premium"
],
"properties": {
"cover_spouse": {
"type": "boolean",
"description": "Joint return: the spouse is on the plan too. Default true."
},
"household_size": {
"type": "integer",
"description": "Tax family size for the poverty line (you, a spouse on a joint return, dependents). Default 2 on a joint return, else 1."
},
"benchmark_premium": {
"type": "number",
"description": "The household's 2026 annual benchmark (second-lowest-cost silver) premium at its 2026 ages, from healthcare.gov or the state's marketplace. Default: the state-average model, stated in the result."
},
"spending_includes_premium": {
"type": "boolean",
"description": "Required. true: annual_spending already includes the full, unsubsidized benchmark premium (it is taken out and the premium after the credit paid instead); false: the premium after the credit is paid on top of annual_spending."
}
},
"description": "Optional: the household buys marketplace (ACA) health coverage in the retirement years before Medicare. Each path's premium tax credit is figured each year by the federal engine's Form 8962 at that path's own income (no credit above 400% of the poverty line; Medicaid below 138% in expansion states), and the premium after the credit is funded each year and counted by the withdrawal-order search. Needs state."
},
"annual_spending": {
"type": "number",
"description": "Planned yearly spending in today's dollars, after tax: what the household keeps. The engine withdraws enough each year to fund this plus that year's federal, state, Medicare-surcharge and penalty tax."
},
"life_expectancy": {
"type": "integer",
"description": "Age the plan must last until. Default 92."
},
"roth_conversion": {
"type": "object",
"required": [
"annual_amount",
"start_age",
"end_age"
],
"properties": {
"end_age": {
"type": "integer"
},
"start_age": {
"type": "integer"
},
"annual_amount": {
"type": "number",
"description": "Dollars converted per year, today's dollars."
}
},
"description": "The household's own Roth-conversion plan: a fixed amount per year between two ages. When given, the engine applies it on every path and searches withdrawal orders around it instead of searching its own conversion programmes."
},
"social_security": {
"type": "number",
"description": "Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden."
},
"taxable_balance": {
"type": "number",
"description": "Taxable brokerage and savings today, in dollars. 0 if none. The three balances together are the portfolio."
},
"cost_basis_ratio": {
"type": "number",
"description": "Percentage of the taxable account that is cost basis, 0-100. Default 40, and the result says so when it is assumed."
},
"pension_start_age": {
"type": "integer",
"description": "Age the pension starts. Default 65."
},
"medicare_start_age": {
"type": "integer",
"description": "Age Medicare (and its IRMAA income surcharges) begins. Default 65. The year it begins is charged only for the months from the birthday month."
},
"itemized_deductions": {
"type": "object",
"properties": {
"property_tax": {
"type": "number",
"description": "Real estate tax on the home per year."
},
"medical_expenses": {
"type": "number",
"description": "Unreimbursed medical and dental costs per year, before the 7.5% floor."
},
"charitable_giving": {
"type": "number",
"description": "Cash gifts to charity per year, not counting QCDs."
},
"mortgage_interest": {
"type": "number",
"description": "Deductible home mortgage interest per year."
},
"mortgage_interest_end_year": {
"type": "integer",
"description": "Last calendar year with mortgage interest. Default: every year."
}
},
"description": "Optional Schedule A amounts, in today's dollars a year: each year the engine adds that year's own state and local income tax (capped with the property tax by the SALT limit), takes gifts over 0.5% of AGI and medical costs over 7.5% of AGI, and itemizes when that gives the lower tax; otherwise the standard deduction. They are deductions only, assumed to be inside annual_spending already. Mortgage interest stays fixed in dollars until its end year, property tax rises 3.5% a year, giving with inflation, medical costs with inflation. Do not include QCDs in charitable_giving. Default: none, stated in the result."
},
"tax_exempt_interest": {
"type": "number",
"description": "Yearly municipal-bond interest, which counts toward Social Security taxability and IRMAA income but is not itself taxed. Default 0."
},
"traditional_balance": {
"type": "number",
"description": "Pre-tax retirement accounts today (traditional IRA, 401(k), 403(b)), in dollars. 0 if none."
},
"withdrawal_strategy": {
"enum": [
"fixed",
"guyton-klinger",
"vpw",
"bucket"
],
"type": "string",
"description": "Spending rule. fixed (default): the planned amount, inflation-adjusted, every year. guyton-klinger: guardrails that cut or raise spending as the portfolio moves. vpw: variable percentage withdrawal. bucket: a cash reserve of bucket_years of spending."
},
"monthly_contribution": {
"type": "number",
"description": "Monthly savings until retirement. Default 0."
},
"roth_contribution_basis": {
"type": "number",
"description": "Optional: the part of roth_balance that is your own regular Roth IRA contributions (withdrawn first, tax-free). Giving it, roth_first_contribution_year or ira_basis turns on the Roth ordering and 5-year rules on Roth withdrawals (earnings before 59 1/2 or inside the 5-year clock are taxed, with the 10% additional tax before 59 1/2) and the Form 8606 pro-rata rule on traditional withdrawals and conversions. Default: all of roth_balance."
},
"roth_first_contribution_year": {
"type": "integer",
"description": "Optional: the first year you contributed to or converted into any Roth IRA (the 5-year clock), 1998-2026. Default: 2021 when roth_balance > 0."
}
}
}