Retirement

Run a Monte Carlo retirement projection

Simulates many market paths to estimate the probability that a plan's money lasts to the planning horizon, plus the distribution of ending balances. Deterministic: the same inputs and seed always return the same result and result_id.

post/v1/retirement/monte-carlo

Request

  • Base URL: https://api.numeratica.com
  • URL: https://api.numeratica.com/v1/retirement/monte-carlo
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

current_ageinteger required
retirement_ageinteger required

Must be >= current_age.

end_ageinteger required

Planning horizon; must be > retirement_age.

current_balancenumber required
annual_contributionnumber required

Nominal contribution per year while working.

annual_spendingnumber required

Annual withdrawal in today's dollars; inflated over time.

expected_returnnumber

Arithmetic mean nominal annual return (> -1, <= 1). Required unless glide_path is given.

return_volatilitynumber

Stddev of nominal annual return (0–1). Required unless glide_path is given.

inflationnumber

Annual inflation (> -1, <= 1).

num_simulationsinteger
annual_fee_ratenumber double

All-in annual cost drag as a decimal (0.01 = 1%): advisory fee plus fund expense ratios. Applied as a reduction to the expected return each year, so it compounds inside the return distribution rather than acting as a separate withdrawal. Omitted or 0 means projections are GROSS of fees, which is the historical behaviour and leaves result_id unchanged. Costs matter: on the example above a 1% fee moves success probability by roughly 14 points.

seedinteger

Optional RNG seed. If omitted, one is generated and returned so the run can be reproduced.

rebalanceboolean

For the assets path: annual rebalancing to target weights (true, the default) vs buy-and-hold drift (false). Ignored without assets.

Example request

{
  "current_age": 40,
  "retirement_age": 65,
  "end_age": 95,
  "current_balance": 250000,
  "annual_contribution": 20000,
  "annual_spending": 70000,
  "expected_return": 0.06,
  "return_volatility": 0.12,
  "inflation": 0.025,
  "num_simulations": 10000,
  "annual_fee_rate": 0.01,
  "seed": 12345,
  "glide_path": [
    {
      "age": 40,
      "expected_return": 0.09,
      "return_volatility": 0.18
    }
  ],
  "assets": [
    {
      "class": "us-equity",
      "weight": 0.6,
      "expected_return": 0.08,
      "return_volatility": 0.18
    }
  ],
  "correlations": [
    [
      1,
      0.2
    ],
    [
      0.2,
      1
    ]
  ],
  "guaranteed_income": [
    {
      "annual_amount": 40000,
      "start_age": 67
    }
  ]
}

Response

Projection result

result_idstring

Deterministic id for this run (hash of inputs + seed + engine version).

engine_versionstring
seedinteger
noticesstring[]

Optional advisories about how the request was handled — e.g. a free-tier key that omitted num_simulations is told the count was defaulted to the cap. Absent when there's nothing to flag.

disclaimerstring

Example response

{
  "result_id": "mc_1a2b3c4d5e6f7a8b",
  "engine_version": "montecarlo-1.0.0",
  "seed": 12345,
  "inputs": {
    "current_age": 40,
    "retirement_age": 65,
    "end_age": 95,
    "current_balance": 250000,
    "annual_contribution": 20000,
    "annual_spending": 70000,
    "expected_return": 0.06,
    "return_volatility": 0.12,
    "inflation": 0.025,
    "num_simulations": 10000,
    "annual_fee_rate": 0.01,
    "seed": 12345,
    "glide_path": [
      {
        "age": 40,
        "expected_return": 0.09,
        "return_volatility": 0.18
      }
    ],
    "assets": [
      {
        "class": "us-equity",
        "weight": 0.6,
        "expected_return": 0.08,
        "return_volatility": 0.18
      }
    ],
    "correlations": [
      [
        1,
        0.2
      ],
      [
        0.2,
        1
      ]
    ],
    "guaranteed_income": [
      {
        "annual_amount": 40000,
        "start_age": 67
      }
    ]
  },
  "result": {
    "success_probability": 0.89,
    "median_ending_balance": 13100000,
    "num_simulations": 10000
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.