View input schema
{
"type": "object",
"properties": {
"filing": {
"type": "string",
"enum": [
"single",
"married"
],
"description": "Tax filing status. Default 'single'. 'married' = one joint return (both spouses assumed the same age)."
},
"age": {
"type": "integer",
"minimum": 18,
"maximum": 90,
"description": "Your age this year. The plan starts now (conversions can begin this year)."
},
"end_age": {
"type": "integer",
"maximum": 110,
"description": "Plan until this age (default 90; horizon at most 70 years)."
},
"balances": {
"type": "object",
"additionalProperties": false,
"description": "Current household balances, dollars. Omitted = 0; at least one must be above 0.",
"properties": {
"traditional": {
"type": "number",
"minimum": 0,
"description": "Traditional IRA / 401(k) (pre-tax) balance: the money that can be converted."
},
"roth": {
"type": "number",
"minimum": 0,
"description": "Roth IRA / 401(k) balance."
},
"roth_penalty_free": {
"type": "number",
"minimum": 0,
"description": "Of the Roth balance, the part that can be withdrawn penalty-free before 59.5 (contributions and conversions at least 5 years old). Default 0; cannot exceed 'roth'."
},
"brokerage": {
"type": "number",
"minimum": 0,
"description": "Taxable brokerage and cash."
},
"brokerage_gain_long_term": {
"type": "number",
"minimum": 0,
"description": "Unrealized LONG-term gain inside the brokerage balance."
},
"brokerage_gain_short_term": {
"type": "number",
"minimum": 0,
"description": "Unrealized SHORT-term gain inside the brokerage balance (long + short cannot exceed the balance)."
}
}
},
"spending_per_year": {
"type": "number",
"minimum": 0,
"maximum": 5000000,
"description": "Yearly spending the plan must fund, today's dollars, before income tax. Required unless find_max_spending is true."
},
"spending_start_age": {
"type": "integer",
"description": "Age spending begins (default: now)."
},
"spending_end_age": {
"type": "integer",
"description": "Age spending ends (default: end of plan)."
},
"find_max_spending": {
"type": "boolean",
"description": "Instead of fixed spending, solve for the highest constant yearly spending the accounts can fund, ending near $0. Default false."
},
"social_security": {
"type": "object",
"additionalProperties": false,
"description": "Expected Social Security (household). Omitted = none.",
"properties": {
"annual": {
"type": "number",
"minimum": 0,
"description": "Yearly benefit in today's dollars."
},
"start_age": {
"type": "integer",
"minimum": 62,
"maximum": 70,
"description": "Age benefits start. Default 70."
},
"taxable_pct": {
"type": "number",
"minimum": 0,
"maximum": 85,
"description": "Share of benefits taxed as ordinary income, whole percent. Default 85."
}
}
},
"other_income": {
"type": "object",
"additionalProperties": false,
"description": "Other steady ordinary income (pension, rental, part-time pay), today's dollars. Omitted = none.",
"properties": {
"annual": {
"type": "number",
"minimum": 0,
"maximum": 5000000,
"description": "Yearly amount."
},
"start_age": {
"type": "integer",
"description": "First age it is received (default: now)."
},
"end_age": {
"type": "integer",
"description": "Last age it is received (default: end of plan)."
}
}
},
"assumptions": {
"type": "object",
"additionalProperties": false,
"description": "Modeling assumptions; the defaults (same as the web tool) are reported back.",
"properties": {
"real_return_pct": {
"type": "number",
"minimum": -5,
"maximum": 15,
"description": "Investment return above inflation, whole percent. Default 5."
},
"retirement_tax_rate_pct": {
"type": "number",
"minimum": 0,
"maximum": 60,
"description": "Income tax rate applied to leftover traditional money at the end of the plan (heirs' or your own). Default 24."
},
"terminal_ltcg_pct": {
"type": "number",
"minimum": 0,
"maximum": 40,
"description": "Capital-gains rate on leftover brokerage gain at the end. Default 15."
},
"ltcg_pct": {
"type": "number",
"minimum": 0,
"maximum": 40,
"description": "Flat capital-gains rate on gains realized during the plan. Default 15."
}
}
},
"advanced": {
"type": "object",
"additionalProperties": false,
"description": "Advanced layers, all OFF by default exactly like the web tool. IRMAA and NIIT make the solve a MILP (a few seconds longer; each solve is capped at 5 s, best plan found is returned).",
"properties": {
"irmaa": {
"type": "boolean",
"description": "Model the Medicare Part B/D income surcharge (IRMAA) so conversions can avoid or accept tiers. Default false."
},
"niit": {
"type": "boolean",
"description": "Model the 3.8% Net Investment Income Tax. Default false."
},
"state": {
"type": "object",
"additionalProperties": false,
"description": "State income tax. Default: none (0%).",
"properties": {
"code": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"description": "Two-letter state code (e.g. 'KS'): uses that state's real 2026 brackets, standard deduction and credit."
},
"flat_rate_pct": {
"type": "number",
"minimum": 0,
"maximum": 20,
"description": "Flat state rate, whole percent. Without 'code' it is the whole state model; with 'code' it only overrides the end-of-plan rate (default: the state's top rate)."
},
"exempts_social_security": {
"type": "boolean",
"description": "The state does not tax Social Security. Default false."
},
"retirement_exclusion": {
"type": "number",
"minimum": 0,
"description": "Yearly cap on IRA distributions the state excludes, dollars. Default 0."
}
}
}
}
}
},
"required": [
"age",
"balances"
],
"additionalProperties": false
}