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."
    }
  },
  "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."
    },
    "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."
    },
    "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."
    },
    "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."
    }
  },
  "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.

{
  "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."
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Source ids to compare. Defaults to all."
    }
  },
  "required": [
    "current_age",
    "current_savings",
    "annual_spending"
  ]
}

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": {}
}