QuantCalc Retirement Engine

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.

{
  "type": "object",
  "properties": {
    "current_age": {
      "type": "integer",
      "description": "Current age of the primary person."
    },
    "retirement_age": {
      "type": "integer",
      "description": "Age work income stops. Defaults to current age."
    },
    "life_expectancy": {
      "type": "integer",
      "description": "Age the plan must last until. Default 92."
    },
    "current_savings": {
      "type": "number",
      "description": "Total invested portfolio today, in dollars."
    },
    "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)."
    },
    "monthly_contribution": {
      "type": "number",
      "description": "Monthly savings until retirement. Default 0."
    },
    "social_security": {
      "type": "number",
      "description": "Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden."
    },
    "ss_start_age": {
      "type": "integer",
      "description": "Age Social Security starts. Default 67."
    },
    "pension": {
      "type": "number",
      "description": "Yearly pension income. Default 0."
    },
    "pension_start_age": {
      "type": "integer",
      "description": "Age the pension starts. Default 65."
    },
    "inflation_rate": {
      "type": "number",
      "description": "Annual inflation as a percent, e.g. 2.5. Default 2.5."
    },
    "allocations": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "minItems": 5,
      "maxItems": 5,
      "description": "Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]."
    },
    "returns_source": {
      "type": "string",
      "description": "Which published return set to use (see list_return_assumption_sources). Default jpmorgan."
    },
    "return_model": {
      "type": "string",
      "enum": [
        "parametric",
        "bootstrap",
        "historical"
      ],
      "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."
    },
    "withdrawal_strategy": {
      "type": "string",
      "enum": [
        "fixed",
        "guyton-klinger",
        "vpw",
        "bucket"
      ],
      "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."
    },
    "bucket_years": {
      "type": "integer",
      "description": "Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10."
    },
    "spending_confidence": {
      "type": "integer",
      "enum": [
        75,
        80,
        85,
        90,
        95
      ],
      "description": "The success rate the 'sustainable spending' answer is solved at: the most this plan can spend each year and still succeed on at least this percentage of paths, with the same answer if every balance were 20% lower or higher today. One of 75, 80, 85, 90, 95. Default 90."
    }
  },
  "required": [
    "current_age",
    "current_savings",
    "annual_spending"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "current_age": {
      "type": "integer",
      "description": "Current age of the primary person."
    },
    "retirement_age": {
      "type": "integer",
      "description": "Age work income stops. Defaults to current age."
    },
    "life_expectancy": {
      "type": "integer",
      "description": "Age the plan must last until. Default 92."
    },
    "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."
    },
    "monthly_contribution": {
      "type": "number",
      "description": "Monthly savings until retirement. Default 0."
    },
    "social_security": {
      "type": "number",
      "description": "Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden."
    },
    "ss_start_age": {
      "type": "integer",
      "description": "Age Social Security starts. Default 67."
    },
    "pension": {
      "type": "number",
      "description": "Yearly pension income. Default 0."
    },
    "pension_start_age": {
      "type": "integer",
      "description": "Age the pension starts. Default 65."
    },
    "inflation_rate": {
      "type": "number",
      "description": "Annual inflation as a percent, e.g. 2.5. Default 2.5."
    },
    "allocations": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "minItems": 5,
      "maxItems": 5,
      "description": "Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]."
    },
    "returns_source": {
      "type": "string",
      "description": "Which published return set to use (see list_return_assumption_sources). Default jpmorgan."
    },
    "return_model": {
      "type": "string",
      "enum": [
        "parametric",
        "bootstrap",
        "historical"
      ],
      "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."
    },
    "withdrawal_strategy": {
      "type": "string",
      "enum": [
        "fixed",
        "guyton-klinger",
        "vpw",
        "bucket"
      ],
      "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."
    },
    "bucket_years": {
      "type": "integer",
      "description": "Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10."
    },
    "spending_confidence": {
      "type": "integer",
      "enum": [
        75,
        80,
        85,
        90,
        95
      ],
      "description": "The success rate the 'sustainable spending' answer is solved at: the most this plan can spend each year and still succeed on at least this percentage of paths, with the same answer if every balance were 20% lower or higher today. One of 75, 80, 85, 90, 95. Default 90."
    },
    "pension_type": {
      "type": "string",
      "enum": [
        "private",
        "public"
      ],
      "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."
    },
    "traditional_balance": {
      "type": "number",
      "description": "Pre-tax retirement accounts today (traditional IRA, 401(k), 403(b)), in dollars. 0 if none."
    },
    "roth_balance": {
      "type": "number",
      "description": "Roth IRA and Roth 401(k) balance today, in dollars. 0 if none."
    },
    "taxable_balance": {
      "type": "number",
      "description": "Taxable brokerage and savings today, in dollars. 0 if none. The three balances together are the portfolio."
    },
    "filing_status": {
      "type": "string",
      "enum": [
        "single",
        "mfj",
        "mfs",
        "hoh"
      ],
      "description": "Federal filing status: single, married filing jointly (mfj), married filing separately (mfs) or head of household (hoh)."
    },
    "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."
    },
    "move_state": {
      "type": "object",
      "description": "A planned move to another state: the household lives in `state` until the first day of `month` of `year`, then in move_state.state. The plan uses the old state's income tax before the move year, the new state's after it, and a part-year return in each in the move year (each state's own part-year rules, the year's income split by days). The result compares the lifetime state tax with the move against staying and against moving now. Needs `state`.",
      "properties": {
        "state": {
          "type": "string",
          "description": "Two-letter state moved to (or DC); not Washington."
        },
        "year": {
          "type": "integer",
          "description": "Calendar year of the move, 2026 to the plan's last year."
        },
        "month": {
          "type": "integer",
          "description": "Month of the move, 1-12 (the move on the 1st). Default 7. 1 = the whole move year in the new state."
        }
      },
      "required": [
        "state",
        "year"
      ]
    },
    "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."
    },
    "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."
    },
    "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."
    },
    "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."
    },
    "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."
    },
    "annual_qcd": {
      "type": "number",
      "description": "Yearly qualified charitable distribution from the traditional account, in today's dollars, counted against required minimum distributions. Default 0."
    },
    "roth_conversion": {
      "type": "object",
      "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.",
      "properties": {
        "annual_amount": {
          "type": "number",
          "description": "Dollars converted per year, today's dollars."
        },
        "start_age": {
          "type": "integer"
        },
        "end_age": {
          "type": "integer"
        }
      },
      "required": [
        "annual_amount",
        "start_age",
        "end_age"
      ]
    },
    "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."
    },
    "aca_marketplace": {
      "type": "object",
      "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.",
      "properties": {
        "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."
        },
        "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."
        },
        "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."
        },
        "cover_spouse": {
          "type": "boolean",
          "description": "Joint return: the spouse is on the plan too. Default true."
        }
      },
      "required": [
        "spending_includes_premium"
      ]
    },
    "itemized_deductions": {
      "type": "object",
      "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.",
      "properties": {
        "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."
        },
        "property_tax": {
          "type": "number",
          "description": "Real estate tax on the home per year."
        },
        "charitable_giving": {
          "type": "number",
          "description": "Cash gifts to charity per year, not counting QCDs."
        },
        "medical_expenses": {
          "type": "number",
          "description": "Unreimbursed medical and dental costs per year, before the 7.5% floor."
        }
      }
    },
    "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."
    },
    "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."
    },
    "dependents": {
      "type": "array",
      "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.",
      "items": {
        "type": "object",
        "properties": {
          "age": {
            "type": "integer"
          },
          "student": {
            "type": "boolean"
          },
          "disabled": {
            "type": "boolean"
          }
        },
        "required": [
          "age"
        ]
      }
    },
    "lifespan": {
      "type": "string",
      "enum": [
        "fixed",
        "stochastic"
      ],
      "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."
    },
    "annuity": {
      "type": "object",
      "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.",
      "properties": {
        "purchase_age": {
          "type": "integer",
          "description": "Age at purchase, in retirement."
        },
        "premium": {
          "type": "number",
          "description": "Single premium in today's dollars."
        },
        "source": {
          "type": "string",
          "enum": [
            "traditional",
            "taxable"
          ]
        },
        "payout_rate": {
          "type": "number",
          "description": "First year's payments as a percent of the premium (from a quote)."
        },
        "cola": {
          "type": "number",
          "description": "Fixed yearly increase of the payment in percent. Default 0."
        }
      },
      "required": [
        "purchase_age",
        "premium",
        "source",
        "payout_rate"
      ]
    },
    "spouse_split": {
      "type": "string",
      "enum": [
        "even",
        "filer",
        "spouse"
      ],
      "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."
    }
  },
  "required": [
    "current_age",
    "annual_spending",
    "traditional_balance",
    "roth_balance",
    "taxable_balance",
    "filing_status"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "current_age": {
      "type": "integer",
      "description": "Current age of the primary person."
    },
    "retirement_age": {
      "type": "integer",
      "description": "Age work income stops. Defaults to current age."
    },
    "life_expectancy": {
      "type": "integer",
      "description": "Age the plan must last until. Default 92."
    },
    "current_savings": {
      "type": "number",
      "description": "Total invested portfolio today, in dollars."
    },
    "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)."
    },
    "monthly_contribution": {
      "type": "number",
      "description": "Monthly savings until retirement. Default 0."
    },
    "social_security": {
      "type": "number",
      "description": "Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden."
    },
    "ss_start_age": {
      "type": "integer",
      "description": "Age Social Security starts. Default 67."
    },
    "pension": {
      "type": "number",
      "description": "Yearly pension income. Default 0."
    },
    "pension_start_age": {
      "type": "integer",
      "description": "Age the pension starts. Default 65."
    },
    "inflation_rate": {
      "type": "number",
      "description": "Annual inflation as a percent, e.g. 2.5. Default 2.5."
    },
    "allocations": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "minItems": 5,
      "maxItems": 5,
      "description": "Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]."
    },
    "returns_source": {
      "type": "string",
      "description": "Which published return set to use (see list_return_assumption_sources). Default jpmorgan."
    },
    "return_model": {
      "type": "string",
      "enum": [
        "parametric",
        "bootstrap",
        "historical"
      ],
      "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."
    },
    "withdrawal_strategy": {
      "type": "string",
      "enum": [
        "fixed",
        "guyton-klinger",
        "vpw",
        "bucket"
      ],
      "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."
    },
    "bucket_years": {
      "type": "integer",
      "description": "Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10."
    },
    "spending_confidence": {
      "type": "integer",
      "enum": [
        75,
        80,
        85,
        90,
        95
      ],
      "description": "The success rate the 'sustainable spending' answer is solved at: the most this plan can spend each year and still succeed on at least this percentage of paths, with the same answer if every balance were 20% lower or higher today. One of 75, 80, 85, 90, 95. Default 90."
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Source ids to compare. Defaults to all."
    }
  },
  "required": []
}

Returns the published capital market assumption sets the engine carries and which components each publisher provides (returns, volatilities, correlations).

{
  "type": "object",
  "properties": {}
}

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.

{
  "type": "object",
  "properties": {}
}

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.

{
  "type": "object",
  "properties": {
    "filing_status": {
      "type": "string",
      "enum": [
        "single",
        "mfj",
        "mfs",
        "hoh"
      ],
      "description": "2026 filing status: single, married filing jointly (mfj), married filing separately (mfs) or head of household (hoh)."
    },
    "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."
    },
    "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."
    },
    "spouse_age": {
      "type": "integer",
      "description": "Joint return only: the age the spouse reaches in 2026. Default: the same as age, stated in the result."
    },
    "spouse_birth_month": {
      "type": "integer",
      "description": "Joint return only: the spouse's birth month, 1-12, optional."
    },
    "wages": {
      "type": "number",
      "description": "The filer's 2026 wages (Form W-2 box 1). Default 0."
    },
    "spouse_wages": {
      "type": "number",
      "description": "Joint return only: the spouse's 2026 wages. 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."
    },
    "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."
    },
    "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."
    },
    "ira_distributions": {
      "type": "number",
      "description": "Taxable 2026 IRA, 401(k) and 403(b) distributions (not Roth conversions), the household's total. Default 0."
    },
    "roth_conversion": {
      "type": "number",
      "description": "Taxable amount converted to Roth in 2026, the household's total. Default 0."
    },
    "pension": {
      "type": "number",
      "description": "Taxable 2026 pension and annuity income, the household's total. Default 0."
    },
    "pension_type": {
      "type": "string",
      "enum": [
        "private",
        "public"
      ],
      "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": {
      "type": "string",
      "enum": [
        "even",
        "filer",
        "spouse",
        "custom"
      ],
      "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_ira_distributions": {
      "type": "number",
      "description": "spouse_split custom only: the spouse's part of ira_distributions."
    },
    "spouse_pension": {
      "type": "number",
      "description": "spouse_split custom only: the spouse's part of pension."
    },
    "spouse_roth_conversion": {
      "type": "number",
      "description": "spouse_split custom only: the spouse's part of roth_conversion."
    },
    "taxable_interest": {
      "type": "number",
      "description": "Taxable interest (Form 1040 line 2b). 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."
    },
    "ordinary_dividends": {
      "type": "number",
      "description": "Ordinary dividends, Form 1099-DIV box 1a (line 3b), including the qualified part. Default 0."
    },
    "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."
    },
    "capital_gain_distributions": {
      "type": "number",
      "description": "Capital gain distributions from funds (Form 1099-DIV box 2a). Default 0."
    },
    "short_term_gains": {
      "type": "number",
      "description": "2026 net short-term capital gain; negative for a net loss. Default 0."
    },
    "long_term_gains": {
      "type": "number",
      "description": "2026 net long-term capital gain; negative for a net loss. Default 0."
    },
    "capital_loss_carryover_short_term": {
      "type": "number",
      "description": "Short-term capital loss carried over from 2025, as a positive number. Default 0."
    },
    "capital_loss_carryover_long_term": {
      "type": "number",
      "description": "Long-term capital loss carried over from 2025, as a positive number. Default 0."
    },
    "other_ordinary_income": {
      "type": "number",
      "description": "Other ordinary income that is not investment income (Schedule 1). 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."
    },
    "real_estate_tax_paid": {
      "type": "number",
      "description": "Itemized deduction input: real estate tax paid in 2026. Default 0."
    },
    "mortgage_interest": {
      "type": "number",
      "description": "Itemized deduction input: home mortgage interest paid in 2026. Default 0."
    },
    "medical_expenses": {
      "type": "number",
      "description": "Itemized deduction input: medical and dental expenses paid in 2026, before the AGI floor. Default 0."
    },
    "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."
    },
    "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."
    },
    "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."
    },
    "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."
    },
    "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%."
    },
    "state_withholding": {
      "type": "number",
      "description": "State income tax withheld in 2026. Default 0."
    },
    "state_estimated_payments": {
      "type": "number",
      "description": "State estimated tax paid for 2026, the total. 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."
    }
  },
  "required": [
    "filing_status",
    "age",
    "state"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "current_age": {
      "type": "integer",
      "description": "Current age of the primary person."
    },
    "retirement_age": {
      "type": "integer",
      "description": "Age work income stops. Defaults to current age."
    },
    "life_expectancy": {
      "type": "integer",
      "description": "Age the plan must last until. Default 92."
    },
    "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."
    },
    "monthly_contribution": {
      "type": "number",
      "description": "Monthly savings until retirement. Default 0."
    },
    "social_security": {
      "type": "number",
      "description": "Yearly Social Security in today's dollars. Default 0 — and 0 is reported as an explicit assumption, not hidden."
    },
    "ss_start_age": {
      "type": "integer",
      "description": "Age Social Security starts. Default 67."
    },
    "pension": {
      "type": "number",
      "description": "Yearly pension income. Default 0."
    },
    "pension_start_age": {
      "type": "integer",
      "description": "Age the pension starts. Default 65."
    },
    "inflation_rate": {
      "type": "number",
      "description": "Annual inflation as a percent, e.g. 2.5. Default 2.5."
    },
    "allocations": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "minItems": 5,
      "maxItems": 5,
      "description": "Percentages summing to 100: [US stocks, international stocks, bonds, real estate, cash]. Default [60,10,25,5,0]."
    },
    "returns_source": {
      "type": "string",
      "description": "Which published return set to use (see list_return_assumption_sources). Default jpmorgan."
    },
    "return_model": {
      "type": "string",
      "enum": [
        "parametric",
        "bootstrap",
        "historical"
      ],
      "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."
    },
    "withdrawal_strategy": {
      "type": "string",
      "enum": [
        "fixed",
        "guyton-klinger",
        "vpw",
        "bucket"
      ],
      "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."
    },
    "bucket_years": {
      "type": "integer",
      "description": "Only with withdrawal_strategy bucket: years of spending held in the cash bucket, 1-10."
    },
    "spending_confidence": {
      "type": "integer",
      "enum": [
        75,
        80,
        85,
        90,
        95
      ],
      "description": "The success rate the 'sustainable spending' answer is solved at: the most this plan can spend each year and still succeed on at least this percentage of paths, with the same answer if every balance were 20% lower or higher today. One of 75, 80, 85, 90, 95. Default 90."
    },
    "pension_type": {
      "type": "string",
      "enum": [
        "private",
        "public"
      ],
      "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."
    },
    "traditional_balance": {
      "type": "number",
      "description": "Pre-tax retirement accounts today (traditional IRA, 401(k), 403(b)), in dollars. 0 if none."
    },
    "roth_balance": {
      "type": "number",
      "description": "Roth IRA and Roth 401(k) balance today, in dollars. 0 if none."
    },
    "taxable_balance": {
      "type": "number",
      "description": "Taxable brokerage and savings today, in dollars. 0 if none. The three balances together are the portfolio."
    },
    "filing_status": {
      "type": "string",
      "enum": [
        "single",
        "mfj",
        "mfs",
        "hoh"
      ],
      "description": "Federal filing status: single, married filing jointly (mfj), married filing separately (mfs) or head of household (hoh)."
    },
    "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."
    },
    "move_state": {
      "type": "object",
      "description": "A planned move to another state: the household lives in `state` until the first day of `month` of `year`, then in move_state.state. The plan uses the old state's income tax before the move year, the new state's after it, and a part-year return in each in the move year (each state's own part-year rules, the year's income split by days). The result compares the lifetime state tax with the move against staying and against moving now. Needs `state`.",
      "properties": {
        "state": {
          "type": "string",
          "description": "Two-letter state moved to (or DC); not Washington."
        },
        "year": {
          "type": "integer",
          "description": "Calendar year of the move, 2026 to the plan's last year."
        },
        "month": {
          "type": "integer",
          "description": "Month of the move, 1-12 (the move on the 1st). Default 7. 1 = the whole move year in the new state."
        }
      },
      "required": [
        "state",
        "year"
      ]
    },
    "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."
    },
    "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."
    },
    "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."
    },
    "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."
    },
    "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."
    },
    "annual_qcd": {
      "type": "number",
      "description": "Yearly qualified charitable distribution from the traditional account, in today's dollars, counted against required minimum distributions. Default 0."
    },
    "roth_conversion": {
      "type": "object",
      "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.",
      "properties": {
        "annual_amount": {
          "type": "number",
          "description": "Dollars converted per year, today's dollars."
        },
        "start_age": {
          "type": "integer"
        },
        "end_age": {
          "type": "integer"
        }
      },
      "required": [
        "annual_amount",
        "start_age",
        "end_age"
      ]
    },
    "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."
    },
    "aca_marketplace": {
      "type": "object",
      "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.",
      "properties": {
        "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."
        },
        "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."
        },
        "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."
        },
        "cover_spouse": {
          "type": "boolean",
          "description": "Joint return: the spouse is on the plan too. Default true."
        }
      },
      "required": [
        "spending_includes_premium"
      ]
    },
    "itemized_deductions": {
      "type": "object",
      "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.",
      "properties": {
        "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."
        },
        "property_tax": {
          "type": "number",
          "description": "Real estate tax on the home per year."
        },
        "charitable_giving": {
          "type": "number",
          "description": "Cash gifts to charity per year, not counting QCDs."
        },
        "medical_expenses": {
          "type": "number",
          "description": "Unreimbursed medical and dental costs per year, before the 7.5% floor."
        }
      }
    },
    "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."
    },
    "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."
    },
    "dependents": {
      "type": "array",
      "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.",
      "items": {
        "type": "object",
        "properties": {
          "age": {
            "type": "integer"
          },
          "student": {
            "type": "boolean"
          },
          "disabled": {
            "type": "boolean"
          }
        },
        "required": [
          "age"
        ]
      }
    },
    "lifespan": {
      "type": "string",
      "enum": [
        "fixed",
        "stochastic"
      ],
      "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."
    },
    "annuity": {
      "type": "object",
      "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.",
      "properties": {
        "purchase_age": {
          "type": "integer",
          "description": "Age at purchase, in retirement."
        },
        "premium": {
          "type": "number",
          "description": "Single premium in today's dollars."
        },
        "source": {
          "type": "string",
          "enum": [
            "traditional",
            "taxable"
          ]
        },
        "payout_rate": {
          "type": "number",
          "description": "First year's payments as a percent of the premium (from a quote)."
        },
        "cola": {
          "type": "number",
          "description": "Fixed yearly increase of the payment in percent. Default 0."
        }
      },
      "required": [
        "purchase_age",
        "premium",
        "source",
        "payout_rate"
      ]
    },
    "spouse_split": {
      "type": "string",
      "enum": [
        "even",
        "filer",
        "spouse"
      ],
      "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."
    },
    "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."
    }
  }
}

Figures one household's 2026 state income tax in all 50 states and DC from its income (Social Security, IRA and 401(k) withdrawals, a private or government pension, military retirement pay, wages, interest, dividends, long-term gains) and returns every jurisdiction ranked from the lowest tax to the highest, with each state's tax, its share of total income and, given current_state, the difference from the state the household lives in now; the federal tax, which is the same in every state; the lowest and highest states and how many charge $0; the county taxes included; and every default assumed and what is not modelled. Computed by QuantCalc's federal and state tax APIs (POST /api/state-tax/every-state), the engines the website's 'Your retirement tax in every state' page 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 page. Not tax advice.

{
  "type": "object",
  "properties": {
    "filing_status": {
      "type": "string",
      "enum": [
        "single",
        "mfj",
        "mfs",
        "hoh"
      ],
      "description": "2026 filing status: single, married filing jointly (mfj), married filing separately (mfs) or head of household (hoh)."
    },
    "age": {
      "type": "integer",
      "description": "The age the filer reaches in 2026 (18-110)."
    },
    "spouse_age": {
      "type": "integer",
      "description": "Joint return only: the age the spouse reaches in 2026. Default: the same as age, stated in the result."
    },
    "spouse_split": {
      "type": "string",
      "enum": [
        "even",
        "filer",
        "spouse"
      ],
      "description": "Joint return only: whose the IRA withdrawals, pension and wages are on the state return: even (half each), filer or spouse. 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."
    },
    "social_security": {
      "type": "number",
      "description": "Gross 2026 Social Security benefits of the household; the engine figures the taxable part. Default 0."
    },
    "ira_distributions": {
      "type": "number",
      "description": "Taxable 2026 IRA, 401(k) and 403(b) withdrawals, the household's total. Default 0."
    },
    "pension": {
      "type": "number",
      "description": "Taxable 2026 pension and annuity income, the household's total. Default 0."
    },
    "pension_type": {
      "type": "string",
      "enum": [
        "private",
        "public"
      ],
      "description": "Whether the pension is a private pension or a government (federal, state or local) pension, which many states tax differently. Default private, stated in the result when a pension is given."
    },
    "military_pension": {
      "type": "number",
      "description": "Taxable 2026 military retirement pay, the household's total (not in pension). Federally a taxable pension; each state applies its own military retirement rule (exempt, capped, age-tested or credited). On a joint return it follows spouse_split like the pension. Default 0."
    },
    "wages": {
      "type": "number",
      "description": "2026 wages of the household. Default 0."
    },
    "taxable_interest": {
      "type": "number",
      "description": "Taxable interest. Default 0."
    },
    "ordinary_dividends": {
      "type": "number",
      "description": "Ordinary dividends (Form 1099-DIV box 1a), including the qualified part. Default 0."
    },
    "qualified_dividends": {
      "type": "number",
      "description": "The qualified part of ordinary_dividends; not more than ordinary_dividends. Default 0."
    },
    "long_term_gains": {
      "type": "number",
      "description": "2026 net long-term capital gain (0 or more). Default 0."
    },
    "current_state": {
      "type": "string",
      "description": "Optional: two-letter code of the state the household lives in now (or DC). Adds each state's difference from it and its rank."
    }
  },
  "required": [
    "filing_status",
    "age"
  ]
}