Data & Analytics

Discount-points / rate-buydown optimizer

Given a candidate loan and a menu of points / lender-credit tradeoffs (each a points spend and the resulting rate), returns per-option break-even months, lifetime interest, savings over the hold horizon, and the optimal point-spend. The points analog of refinance break-even. Pure math — the optimization logic lives here as the single source of truth; the MCP optimize_buydown tool and the consumer app call this route.

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

post/v1/buydown

Request

  • Base URL: https://api.rateapi.dev
  • URL: https://api.rateapi.dev/v1/buydown
  • Auth: API key in header X-API-Key

Request body

loan_amountnumber required

Loan principal in dollars (>0)

term_monthsinteger required

Loan term in months

base_ratenumber required

The no-points (par) interest rate, percent

hold_monthsinteger

Expected time-in-loan horizon for lifetime savings. Defaults to term_months.

statestring

Optional 2-letter US state code (validated only if supplied; not load-bearing for the math).

Example request

{
  "loan_amount": 360000,
  "term_months": 360,
  "base_rate": 6.75,
  "hold_months": 360
}

Response

Buydown analysis with per-option break-even and the optimal point-spend. When no option produces positive net savings over the hold horizon, optimal is null, recommendation is no_points, and reason is set.

base_ratestring

The rate before any points are bought, formatted as a percentage string.

base_monthly_paymentstring

Monthly payment at the base rate, formatted as a US dollar string.

loan_amountstring

Loan amount in US dollars.

term_monthsinteger

Loan term in months.

hold_monthsinteger

How long the borrower is assumed to hold the loan. Defaults to the full term.

statestring

Two-letter US state code.

recommendation'buy_points' | 'take_credit' | 'no_points'

What to do: buy points, take a lender credit, or pay par.

reasonstring

Why no option beat paying par. Present only when optimal is null.

assumed_defaultsobject

Values filled in where the caller supplied none, so the result is reproducible.

disclosuresstring[]

Statements that must be shown to a consumer alongside this result.

Changes

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