Endpoint
GET https://requiems.xyz/v1/finance/mortgage
Calculate Mortgage
Returns the monthly payment, total cost, and full amortization schedule for a fixed-rate mortgage.
Parameters
| Name |
Type |
Required |
Location |
Description |
principal |
number |
yes |
query |
Loan amount in your chosen currency (e.g. 300000 for $300,000) |
rate |
number |
yes |
query |
Annual interest rate as a percentage (e.g. 6.5 for 6.5%). Must be greater than 0. |
years |
integer |
yes |
query |
Loan term in years (1–50) |
Response Example
{
"data": {
"principal": 300000,
"rate": 6.5,
"years": 30,
"monthly_payment": 1896.2,
"total_payment": 682632.0,
"total_interest": 382632.0,
"schedule": [
{
"month": 1,
"payment": 1896.2,
"principal": 271.2,
"interest": 1625.0,
"balance": 299728.8
},
{
"month": 2,
"payment": 1896.2,
"principal": 272.67,
"interest": 1623.53,
"balance": 299456.13
}
]
},
"metadata": {
"timestamp": "2026-01-01T00:00:00Z"
}
}
Response Fields
| Field |
Type |
Description |
principal |
number |
The original loan amount passed in the request |
rate |
number |
The annual interest rate passed in the request |
years |
integer |
The loan term in years passed in the request |
monthly_payment |
number |
Fixed monthly payment amount (rounded to 2 decimal places) |
total_payment |
number |
Total amount paid over the life of the loan |
total_interest |
number |
Total interest paid (total_payment minus principal) |
schedule |
array |
Full amortization schedule — one entry per month (years × 12 entries) |
schedule[].month |
integer |
Month number (1 to years × 12) |
schedule[].payment |
number |
Total payment for this month |
schedule[].principal |
number |
Portion of this month's payment applied to principal |
schedule[].interest |
number |
Portion of this month's payment applied to interest |
schedule[].balance |
number |
Remaining loan balance after this payment |
Errors
400 bad_request — A required parameter is missing, not a valid number, or out of range (e.g. years > 50 or rate <= 0).500 internal_error — Unexpected server error.
1---2name: mortgage-get-mortgage3description: Returns the monthly payment, total cost, and full amortization schedule for a fixed-rate mortgage.4---5
6## Endpoint
7
8**GET https://requiems.xyz/v1/finance/mortgage**
9
10## Calculate Mortgage
11
12Returns the monthly payment, total cost, and full amortization schedule for a fixed-rate mortgage.
13
14## Parameters
15
16| Name | Type | Required | Location | Description |
17| ---- | ---- | -------- | -------- | ----------- |
18| `principal` | number | yes | query | Loan amount in your chosen currency (e.g. 300000 for $300,000) |
19| `rate` | number | yes | query | Annual interest rate as a percentage (e.g. 6.5 for 6.5%). Must be greater than 0. |
20| `years` | integer | yes | query | Loan term in years (1–50) |
21
22## Response Example
23
24```json
25{
26 "data": {
27 "principal": 300000,
28 "rate": 6.5,
29 "years": 30,
30 "monthly_payment": 1896.2,
31 "total_payment": 682632.0,
32 "total_interest": 382632.0,
33 "schedule": [
34 {
35 "month": 1,
36 "payment": 1896.2,
37 "principal": 271.2,
38 "interest": 1625.0,
39 "balance": 299728.8
40 },
41 {
42 "month": 2,
43 "payment": 1896.2,
44 "principal": 272.67,
45 "interest": 1623.53,
46 "balance": 299456.13
47 }
48 ]
49 },
50 "metadata": {
51 "timestamp": "2026-01-01T00:00:00Z"
52 }
53}
54```
55
56## Response Fields
57
58| Field | Type | Description |
59| ----- | ---- | ----------- |
60| `principal` | number | The original loan amount passed in the request |
61| `rate` | number | The annual interest rate passed in the request |
62| `years` | integer | The loan term in years passed in the request |
63| `monthly_payment` | number | Fixed monthly payment amount (rounded to 2 decimal places) |
64| `total_payment` | number | Total amount paid over the life of the loan |
65| `total_interest` | number | Total interest paid (total_payment minus principal) |
66| `schedule` | array<object> | Full amortization schedule — one entry per month (years × 12 entries) |
67| `schedule[].month` | integer | Month number (1 to years × 12) |
68| `schedule[].payment` | number | Total payment for this month |
69| `schedule[].principal` | number | Portion of this month's payment applied to principal |
70| `schedule[].interest` | number | Portion of this month's payment applied to interest |
71| `schedule[].balance` | number | Remaining loan balance after this payment |
72
73## Errors
74
75- `400` **bad_request** — A required parameter is missing, not a valid number, or out of range (e.g. years > 50 or rate <= 0).
76- `500` **internal_error** — Unexpected server error.
gabrielmoreira