Data & Analytics

Buy/refi-now vs wait rate-timing decision

Frames a forward 'lock now' vs 'wait for rates to drop' recommendation by combining recent rate movement (direction + magnitude over a 1w/2w/4w window) with break-even sensitivity on the borrower's loan. Returns the best current offer, a wait-scenario projection (a sensitivity, NOT a forecast), the payment swing per 25bps, the cost of waiting, and a buy_now / consider_waiting / neutral / insufficient_data lean. Distinct from /v1/rate-delta (raw historical deltas only). This route is the single source of truth; the MCP assess_buy_timing tool and the consumer app call it.

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

post/v1/buy-timing

Request

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

Request body

product_type'mortgage' | 'mortgage_arm' | 'auto_loan' | 'heloc' | 'personal_loan' | 'student_loan' | 'credit_card' required

Use mortgage_arm for an adjustable-rate mortgage (5/1, 5/5, 7/1, 10/1, ...). ARMs are a separate market from fixed-rate mortgages: an ARM's introductory rate sits structurally below a comparable fixed rate, so a blended list would rank every ARM on top and present it as cheaper — true only until it resets. All initial fixed periods share one mortgage_arm bucket. Within mortgage, term_months selects 15- vs 30-year; it has no meaning for mortgage_arm.

statestring required

2-letter US state code

loan_amountnumber required

Loan amount in dollars — drives break-even sensitivity

term_monthsinteger

Loan term in months. Defaults to 360.

current_ratenumber

Optional borrower locked/quoted rate (percent) — enables refi-now-vs-wait framing.

closing_costsnumber

Optional closing/refi costs in dollars. Defaults to 0.

rate_shift_bpsnumber

Optional hypothetical bps move if waiting. Defaults to observed movement (or 25bps).

since'1w' | '2w' | '4w'

Movement window. Defaults to 4w.

Example request

{
  "product_type": "mortgage",
  "state": "CA",
  "loan_amount": 400000,
  "term_months": 360,
  "current_rate": 7.25,
  "closing_costs": 4000,
  "rate_shift_bps": -25,
  "since": "4w"
}

Response

Buy-vs-wait assessment. Degrades gracefully: when rate history is thin, movement fields are null, recommendation is insufficient_data, confidence is low, and a note is included.

product_typestring

Loan or deposit product this applies to.

statestring

Two-letter US state code.

windowstring

How far back the rate movement was measured, as the since value used.

recommendation'buy_now' | 'consider_waiting' | 'neutral' | 'insufficient_data'

Whether to buy now or wait.

confidence'high' | 'medium' | 'low'

How much rate history backed the recommendation.

rationalestring

The reasoning behind the recommendation, in plain language.

assumed_defaultsobject

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

next_actionsobject[]

Other endpoints or tools that are the natural next step from this result.

disclosuresstring[]

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

notestring

Plain-language explanation of what this result means.

Changes

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