Utilities

Pay down debt vs. invest the extra (paired Monte Carlo)

Holds the monthly budget constant and compares two strategies over a horizon: throw the whole budget at the debt then invest the freed budget (pay_debt), or pay only the minimum and invest the extra (invest). Both see the same market path each month, so the difference reflects strategy, not luck. The guaranteed hurdle is the debt's after-tax rate (reduced by the marginal rate when the interest is deductible). Returns each strategy's net-worth distribution, the probability investing wins, and a recommendation. Deterministic given a seed.

post/v1/debt-vs-invest

Request

  • Base URL: https://api.numeratica.com
  • URL: https://api.numeratica.com/v1/debt-vs-invest
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

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. Omitted or 0 means the projection is GROSS of fees, which leaves result_id unchanged. Costs compound: a 1% load moves long-horizon outcomes by a large margin (see the Concepts page).

loan_balancenumber required
loan_annual_ratenumber required
loan_minimum_paymentnumber required

Monthly.

extra_monthlynumber required

Discretionary monthly amount to allocate.

horizon_yearsinteger required
expected_returnnumber required

Annual investment return (supply after-tax to compare a taxable account).

return_volatilitynumber required
num_simulationsinteger
seedinteger

Optional; generated and echoed back.

marginal_ratenumber

For the after-tax debt rate (e.g. from /v1/tax/estimate).

interest_deductibleboolean

Carry the debt at the after-tax rate (mortgage / student loan).

Example request

{
  "annual_fee_rate": 0.01,
  "loan_balance": 30000,
  "loan_annual_rate": 0.18,
  "loan_minimum_payment": 350,
  "extra_monthly": 500,
  "horizon_years": 15,
  "expected_return": 0.06,
  "return_volatility": 0.15
}

Response

Strategy comparison

result_idstring
engine_versionstring
seedinteger
disclaimerstring

Example response

{
  "result_id": "dvi_1a2b3c4d5e6f7a8b",
  "engine_version": "debt-vs-invest-1.0.0",
  "inputs": {
    "annual_fee_rate": 0.01,
    "loan_balance": 30000,
    "loan_annual_rate": 0.18,
    "loan_minimum_payment": 350,
    "extra_monthly": 500,
    "horizon_years": 15,
    "expected_return": 0.06,
    "return_volatility": 0.15
  }
}

Changes

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