---
title: "Refinance break-even analysis"
method: POST
path: "/v1/refinance-break-even"
tags: ["Data & Analytics"]
---

# Refinance break-even analysis

`POST /v1/refinance-break-even`

## Request

- Base URL: `https://api.rateapi.dev`
- URL: `https://api.rateapi.dev/v1/refinance-break-even`
- Auth: API key in header `X-API-Key`

Given a current loan (balance, term, rate), finds the best qualifying market refinance offer and computes monthly savings, lifetime savings, closing costs, break-even months, net lifetime savings, and whether refinancing is worth it. The break-even logic lives here as the single source of truth; the MCP `refinance_break_even` tool and the consumer app call this route.

**Authentication required**: Pass your API key in the `X-API-Key` header.

## Request body

- object
  - `state` string, required: 2-letter US state code
  - `product_type` 'auto_loan' | 'mortgage' | 'heloc' | 'personal_loan' | 'student_loan', required: Loan or deposit product this applies to.
  - `balance` number, required: Outstanding loan balance to refinance
  - `term_months` integer, required: Remaining (or new) term in months
  - `current_rate` number, required: Current loan interest rate (percent)
  - `closing_costs` number: Optional refinance closing costs. Defaults to 0.
  - `credit_score` integer: Optional borrower credit score used to qualify market offers.

## Response `200`

Break-even analysis. When no market offer beats the current rate, only `current_rate`, `closing_costs`, `break_even_months` (null), `refinance_worth_it` (false), and `reason` are populated.

- object
  - `state` string: Two-letter US state code.
  - `product_type` string: Loan or deposit product this applies to.
  - `current_rate` string: The rate the borrower pays today, formatted as a percentage string.
  - `best_market_rate` string: The best rate available to refinance into, formatted as a percentage string.
  - `best_lender` string: Credit union offering that rate.
  - `current_monthly_payment` string: What the borrower pays today, formatted as a US dollar string.
  - `new_monthly_payment` string: What they would pay after refinancing, formatted as a US dollar string.
  - `monthly_savings` string: Monthly payment reduction in US dollars.
  - `lifetime_savings` string: Total payment reduction over the full term, in US dollars.
  - `closing_costs` string: Cost of doing the refinance, formatted as a US dollar string.
  - `break_even_months` integer, nullable: ceil(closing_costs / monthly_savings) when savings>0 & costs>0; 0 when costs==0; null otherwise.
  - `net_lifetime_savings` string: Lifetime saving after closing costs, formatted as a US dollar string.
  - `refinance_worth_it` boolean: True when the net lifetime saving is positive and the break-even lands inside the time the borrower expects to hold the loan.
  - `reason` string: Why refinancing is not worth it. Present only when `refinance_worth_it` is false.
  - `assumed_defaults` object: Values filled in where the caller supplied none, so the result is reproducible.
  - `next_actions` object[]: Other endpoints or tools that are the natural next step from this result.
  - `disclosures` string[]: Statements that must be shown to a consumer alongside this result.

## Other responses

- `400`: The request was malformed — a missing required field, an unparseable body, or a parameter outside its allowed range. The `error` field names what was wrong; retrying the identical request will fail identically.
- `401`: No API key, or a key that is unknown or disabled. Send it in the `X-API-Key` header. Free keys are issued instantly by POST /keys with an email address. The response carries `WWW-Authenticate` pointing at this host's protected-resource metadata, and the `RateLimit-*` headers describing the Free-tier budget a key issued now would carry (scope `anonymous`) — a rejected request spends none of it, so `Remaining` equals `Limit`.
- `429`: Quota exhausted for the current window. `Retry-After` gives the seconds to wait; `upgradeInfo` explains how to lift the cap. Retrying before the reset will fail again and still counts as a request.

---

[API](https://skmtc.dev/rateapi/apis/rate-api.md) · [All operations](https://skmtc.dev/rateapi/apis/rate-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rateapi/apis/rate-api/revisions/06a6db76995f?raw)