Refinance Break-Even Analysis
calculate_refi_breakevenCalculation, not advice. Verify with a professional before acting. Deterministic mortgage refinance break-even analysis. Given your current loan (balance, rate, remaining term) and a refinance offer (new rate, new term, closing costs, optional points), computes:
monthly P&I savings;
the cash-flow break-even month (Senaro's formula: total refinance cost divided by monthly savings, rounded up to a whole month, built on the payback test the CFPB toolkit describes);
the interest delta over your remaining-term horizon, and each loan's interest over its whole schedule (the current loan's remaining term, the new loan's full term);
a term-matched scenario that isolates the rate cut from a term reset;
a term-reset-trap flag (a longer term and a lower payment, but more interest over the new loan's full term than over the current loan's remaining term); and
the economic break-even (net-worth crossover) month under an equal-outflow model: both sides spend the same each month; the side that keeps the current loan starts with the upfront refinance cost invested at month 0 (nothing when costs are rolled in); money not spent on a payment is invested at investment_return_pct. The search runs to the end of the longer loan term, and stops earlier where a loan's term ends with money still owed.
Rate-and-term refis only (cash-out and tax effects are out of scope).
Pick this when refinancing your existing mortgage into a new rate and term is the question; pick compare_mortgage_terms when comparing two mortgage structures on a purchase you have not yet taken out.
All defaults cite primary sources (LodeStar/ALTA closing-cost data, the CFPB toolkit's payback test). Scalar output, no chart series. payoff_months and payoff_month_shift use {status, value, explanation}; the two break-evens use {code, month, explanation}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| points | No | Discount points paid at closing, where 1.0 means 1% of the loan amount: the current balance when costs are paid upfront, or, when roll_costs_into_loan is true, the new loan amount, which includes the financed closing costs and points. Decimal from 0 to 4. Optional; defaults to 0 when omitted. | |
| chart_title | No | Reserved for the chart pipeline; validated but not yet used. Must not contain em-dashes or en-dashes. Max 120 characters. Optional. | |
| closing_costs | No | Explicit closing costs in dollars, excluding points; total upfront cost is closing_costs plus the points cost. Decimal from 0 to 1,000,000,000. Optional; omitting it uses the cited default of 0.67% of the current balance (LodeStar 2026). An IMMEDIATE break-even requires total upfront cost to be zero AND monthly_savings to be non-negative AND roll_costs_into_loan false, i.e. closing_costs AND points both 0, not closing_costs alone; a zero-total-cost refi into a worse deal (negative monthly_savings) reports NEAR_ZERO_OR_NEGATIVE_SAVINGS instead. | |
| current_balance | Yes | Outstanding principal you would refinance. Decimal, greater than 0 and at most 1,000,000,000. REQUIRED, no default. | |
| new_term_months | Yes | The new loan term in months. Integer from 1 to 480. REQUIRED, no default. | |
| new_annual_rate_pct | Yes | The offered refinance rate as a percentage. Decimal from 0 to 20. REQUIRED, no default. | |
| roll_costs_into_loan | No | Whether closing costs and points are added to the new principal instead of paid upfront. When true, points are a percentage of the new loan amount; cash-flow break-even reports COSTS_ROLLED_INTO_LOAN; and the economic break-even, when requested, compares the two loans with the financed costs in the new principal and no upfront cash. Optional; defaults to false when omitted. | |
| investment_return_pct | No | Annual return used for the economic (net-worth crossover) break-even, an EFFECTIVE ANNUAL rate: it compounds money not spent on a payment and, when costs are paid upfront, the upfront refinance cost that keeping the current loan leaves invested. The monthly compounding step is (1+pct/100)^(1/12)-1. Decimal from 0 to 30. Optional; omitting it uses the cited long-run S&P 500 nominal total-return default, about 10%; call list_defaults for the exact current value. | |
| remaining_term_months | Yes | Months left on the current loan. Integer from 1 to 480. REQUIRED, no default. | |
| current_annual_rate_pct | Yes | Current loan's annual rate as a percentage, e.g. 6.5 not 0.065. Decimal from 0 to 20. REQUIRED, no default. | |
| current_monthly_payment | No | Your actual statement P&I payment. Decimal, greater than 0 and at most 1,000,000,000. Optional; when supplied it overrides the formula-derived payment, so match your statement. Rounded to the cent, it must be greater than the first month's interest: current_balance rounded to the cent, times current_annual_rate_pct / 100 / 12, rounded to the cent. | |
| compute_economic_break_even | No | Whether to compute the economic (net-worth crossover) break-even. When false, economic_break_even reports NOT_REQUESTED; every other field is still returned. Optional; defaults to true when omitted. |