Where does the next dollar go?
The most-asked question in personal finance, as three calls: the ordering
(/v1/savings-waterfall), the account type
(/v1/roth-vs-traditional), and — if there's debt — the payoff
plan (/v1/debt-payoff).
1 · The waterfall
A 40-year-old with $120k compensation and $30,000/year to save: capture the match, then HSA, then IRA (the engine checks the MAGI phase-outs and picks the Roth route), then back to the 401(k).
curl -X POST https://api.numeratica.com/v1/savings-waterfall \
-H "Authorization: Bearer nmr_sk_test_xxx" \
-H "Content-Type: application/json" \
-d '{
"tax_year": 2026, "age": 40, "filing_status": "single",
"magi": 90000, "compensation": 120000,
"annual_savings": 30000, "hsa_coverage": "family",
"employer_match_rate": 0.5, "employer_match_cap_pct": 0.06
}'{
"result_id": "savingswf_6ec65325caf9a45c",
"engine_version": "savings-waterfall-1.0.0",
"result": {
"steps": [
{ "order": 1, "account": "401k_match", "amount": 7200,
"rationale": "capture the full employer match — an immediate, guaranteed return" },
{ "order": 2, "account": "hsa", "amount": 8750,
"rationale": "triple tax advantage; unused funds roll over and invest" },
{ "order": 3, "account": "ira", "amount": 7500,
"note": "roth route: roth_direct" }, /* MAGI-checked */
{ "order": 4, "account": "401k_remainder", "amount": 6550, "limit": 17300 },
{ "order": 5, "account": "taxable", "amount": 0 }
],
"employer_match_captured": 3600,
"full_match_captured": true,
"unused_tax_advantaged_room": 10750,
"roth_route": "roth_direct"
},
"disclaimer": "Calculation engine output for informational purposes only; not financial advice."
}All $30,000 lands tax-advantaged, the full $3,600 match is captured, and there's still $10,750 of unused room — the "give yourself a raise" line every advisor looks for. The limits and phase-outs are the live IRS tables, not hardcoded guesses.
2 · Roth or traditional — with the subtlety
The naive rule says: retirement rate (22%) below today's (24%) → traditional. The engine
disagrees — Roth wins by $3,020 on a $7,000/year, 30-year contribution
(result_id rothvtrad_5b5a18db496d374e). Why: the traditional
route's tax savings get invested in a taxable account, and the drag on that side
account costs more than the 2-point rate gap saves. The response includes the
breakeven_retirement_rate — 21.5% here — so
the "it depends" has a number.
3 · If there's debt: avalanche vs snowball
Three debts, $900/month budget: both strategies finish in 34 months;
avalanche (rate order) saves $243 of interest over snowball (balance
order), and the response schedules every payoff month (result_id
debtpayoff_f38d1f7454af1edd). Honest framing for a client: if
the quick win of killing the store card in month 10 keeps someone on plan, $243 is a cheap
price for it. Whether the extra $900 belongs here at all is
/v1/debt-vs-invest's question.
4 · Render it
The waterfall, as the card a savings app would show.
<div style="font-family:-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif;color:#1a2230;max-width:600px">
<div style="font-size:14px;color:#5b6675;margin-bottom:8px">$30,000/yr of savings, routed · 2026 limits, MAGI-checked</div>
<div style="display:grid;grid-template-columns:150px 1fr 80px;gap:6px;font-size:13px;align-items:center">
<div>1 · 401(k) to match</div><div style="background:#e8edf8;border-radius:4px"><div style="width:24%;background:#16a34a;height:16px;border-radius:4px"></div></div><div style="text-align:right">$7,200</div>
<div>2 · HSA (family)</div><div style="background:#e8edf8;border-radius:4px"><div style="width:29%;background:#1d4ed8;height:16px;border-radius:4px"></div></div><div style="text-align:right">$8,750</div>
<div>3 · Roth IRA</div><div style="background:#e8edf8;border-radius:4px"><div style="width:25%;background:#1d4ed8;height:16px;border-radius:4px"></div></div><div style="text-align:right">$7,500</div>
<div>4 · 401(k) rest</div><div style="background:#e8edf8;border-radius:4px"><div style="width:22%;background:#1d4ed8;height:16px;border-radius:4px"></div></div><div style="text-align:right">$6,550</div>
<div>5 · Taxable</div><div style="background:#e8edf8;border-radius:4px"></div><div style="text-align:right">$0</div>
</div>
<div style="margin-top:12px;border:1px solid #16a34a;background:#f0fdf4;border-radius:10px;padding:12px;display:flex;justify-content:space-between;align-items:baseline">
<div><strong>Full match captured</strong> (+$3,600 employer) · all 100% tax-advantaged</div>
<div style="font-size:14px;color:#16a34a;font-weight:600">$10,750 room left</div>
</div>
<div style="color:#5b6675;font-size:12px;margin-top:6px">result_id savingswf_6ec65325caf9a45c · not financial advice</div>
</div>
Related: will it be enough? (Monte Carlo), the down-payment question, and the benefits elections that decide steps 1 and 2.