How do I calculate a monthly payment?
GET /api/v1/mortgage-calculator/payment with loan_amount (or home_value + downpayment) and interest_rate returns the monthly payment, total interest, and total loan cost.
Mortgage Calculator API
Amortization Schedules
Refinance Analysis
Real-Time Calculation
Mortgage math. Solved instantly.
Compute monthly payments, full amortization schedules, refinance savings, and home appreciation projections — all in real time from a single GET request.
Payment · breakdownAmortization · scheduleRefinance · savingsNo key · required for math
Run the numbers, instantly.
This calls the live Mortgage Calculator API. Adjust the inputs, then run a monthly payment or refinance comparison.
Request builder
Loan terms in, full breakdown out.
GET /mortgage/payment
No dataset required
All calculations run in real time from your inputs — no snapshot dataset or live provider key needed for /payment or /refinance.
Output preview
Live response from the API, plus the exact request to reproduce it.
Click Run sample request to calculate.
Why Mortgage Calculator API
Real math, no dataset required.
Full payment breakdown
Principal and interest, escrow estimate, total interest, and total loan cost from a single request.
Full amortization schedule
Pass includeSchedule=true for a month-by-month payoff timeline with a start_date.
Refinance comparison
GET /refinance compares current vs. proposed loan terms and returns monthly savings and break-even months.
Extra payment modeling
monthly_extra_payment shows months saved and interest savings from paying down principal faster.
Home appreciation projection
Add annual_appreciation_rate and home_value for a yearly projected home value curve.
Live market rates (optional)
GET /current-rates returns live FRED weekly average rates when a FRED API key is configured.
/api/v1/mortgage-calculator
Endpoints, at a glance.
Payment calculation with optional amortization and appreciation, refinance comparison, and an optional live current-rates endpoint — all GET.
GET/api/v1/mortgage-calculator/payment
Payment calculation
Monthly payment, total interest, optional amortization schedule and appreciation projection.
GET/api/v1/mortgage-calculator/refinance
Refinance analysis
Compares current loan cost to a proposed new loan. Returns savings and break-even point.
GET/api/v1/mortgage-calculator/current-rates
Current rates
Live weekly average mortgage rates from FRED. Returns 503 when FRED_API_KEY is not configured.
| Parameter | Type | Required | Description |
|---|---|---|---|
| loan_amount | number | yes* | Total loan amount for /payment. *Or supply home_value + downpayment. |
| interest_rate | number | yes | Annual interest rate as a percentage, e.g. 6.5, for /payment. |
| duration_years | number | no | Loan term in years for /payment. Default 30. |
| includeSchedule | boolean | no | If true, includes the full amortization schedule. |
| annual_appreciation_rate | number | no | Annual home value growth rate for the appreciation projection. |
| current_loan_amount / current_interest_rate / current_remaining_years | number | yes | Current loan terms for /refinance. |
| new_interest_rate / new_duration_years | number | yes | Proposed new loan terms for /refinance. |
| refinance_cost | number | no | Closing cost for /refinance break-even calculation. |
Routes live under /api/v1/mortgage-calculator/*, matching the catalog service name.
Error reference
Failures you can plan for.
/payment and /refinance never trigger a 503 — only /current-rates without a configured FRED key does.
400Validation Error
Missing or invalid required parameter, e.g. interest_rate or refinance loan terms.
401Unauthorized
Missing or invalid gateway API key. Send x-api-key or api_key with every request.
429Rate Limited
More than 100 requests in a 15-minute window per IP.
500Internal Error
Unexpected calculation failure.
502Upstream Error
FRED API unreachable or returned invalid data for /current-rates.
503Feature Gated
/current-rates called without FRED_API_KEY configured server-side.
Example validation error (400)
{
"error": "Invalid or missing interest_rate",
"correlationId": "1784510800000-xyz123"
}FAQ
API questions developers ask first.
Can I get a full amortization schedule?
Yes. Pass includeSchedule=true (and optionally start_date) to /payment for a month-by-month payoff timeline alongside the summary numbers.
How does refinance analysis work?
GET /api/v1/mortgage-calculator/refinance compares your current loan to a proposed new loan and returns monthly savings and the break-even month where accumulated savings equal closing costs.
Is there a live market rates endpoint?
Yes. GET /current-rates returns live weekly average 30-year fixed, 15-year fixed, and 5-year ARM rates from FRED, but requires a FRED_API_KEY configured server-side — it returns 503 without one.
What is the public path for this API?
Use /api/v1/mortgage-calculator/payment (and /refinance, /current-rates). The gateway looks up the service by the first path segment, which is the catalog name mortgage-calculator.
Add mortgage math in one request.
Payment breakdowns, amortization schedules, and refinance comparisons, computed in real time with no dataset dependency.