---
title: "Pay down debt vs. invest the extra (paired Monte Carlo)"
method: POST
path: "/v1/debt-vs-invest"
tags: ["Utilities"]
---

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

`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`

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.

## Request body

- DebtInvestRequest
  - `annual_fee_rate` number, 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_balance` number, required
  - `loan_annual_rate` number, required
  - `loan_minimum_payment` number, required: Monthly.
  - `extra_monthly` number, required: Discretionary monthly amount to allocate.
  - `horizon_years` integer, required
  - `expected_return` number, required: Annual investment return (supply after-tax to compare a taxable account).
  - `return_volatility` number, required
  - `num_simulations` integer
  - `seed` integer: Optional; generated and echoed back.
  - `marginal_rate` number: For the after-tax debt rate (e.g. from /v1/tax/estimate).
  - `interest_deductible` boolean: Carry the debt at the after-tax rate (mortgage / student loan).

## Response `200`

Strategy comparison

- DebtInvestResponse
  - `result_id` string
  - `engine_version` string
  - `seed` integer
  - `inputs` DebtInvestRequest
    - `annual_fee_rate` number, 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_balance` number, required
    - `loan_annual_rate` number, required
    - `loan_minimum_payment` number, required: Monthly.
    - `extra_monthly` number, required: Discretionary monthly amount to allocate.
    - `horizon_years` integer, required
    - `expected_return` number, required: Annual investment return (supply after-tax to compare a taxable account).
    - `return_volatility` number, required
    - `num_simulations` integer
    - `seed` integer: Optional; generated and echoed back.
    - `marginal_rate` number: For the after-tax debt rate (e.g. from /v1/tax/estimate).
    - `interest_deductible` boolean: Carry the debt at the after-tax rate (mortgage / student loan).
  - `result` object
    - `after_tax_debt_rate` number: The guaranteed hurdle.
    - `payoff_months_avalanche` integer: Months to clear the debt under pay_debt.
    - `median_net_worth_pay_debt` number
    - `median_net_worth_invest` number
    - `median_advantage_pay_debt` number: median(pay_debt - invest); >0 favors paying debt.
    - `prob_invest_wins` number
    - `recommendation` 'pay_debt' | 'invest'
    - `net_worth_pay_debt` Percentiles
      - `p10` number
      - `p25` number
      - `p50` number
      - `p75` number
      - `p90` number
    - `net_worth_invest` Percentiles
      - `p10` number
      - `p25` number
      - `p50` number
      - `p75` number
      - `p90` number
    - `num_simulations` integer
    - `seed` integer
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)