# Loan & Mortgage API
> Loan and mortgage amortization maths as an API, computed locally and deterministically. The payment endpoint computes the fixed monthly payment of a fully-amortizing loan, M = P·r·(1+r)ⁿ / ((1+r)ⁿ − 1), where r is the annual rate divided by twelve and n is the number of monthly payments, and returns the total paid over the life of the loan, the total interest and the share of every dollar that goes to interest. The schedule endpoint breaks any single payment into its interest and principal parts, shows the remaining balance after it, and the cumulative interest and principal paid so far — so you can see exactly how a mortgage shifts from interest to equity over time. The affordability endpoint inverts the formula to give the largest principal a chosen monthly budget can service at a given rate and term. The term is entered as years or months, and zero-interest loans are handled. Everything is computed locally and deterministically, so it is instant and private. Ideal for fintech, real-estate, banking and personal-finance app developers, mortgage and auto-loan calculators, and finance education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is loan amortization; for break-even and CVP analysis use a break-even API and for savings-goal projections use a savings API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/loan-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($15/Mo) — 40,000 calls/Mo, 8 req/s
- **Pro** ($39/Mo) — 250,000 calls/Mo, 25 req/s
- **Mega** ($119/Mo) — 1,507,000 calls/Mo, 80 req/s

## Endpoints

### Loan

#### `GET /v1/affordability` — Max principal

**Parameters:**
- `monthly_payment` (query, required, string) — Monthly budget Example: `1199.10`
- `annual_rate` (query, required, string) — Annual interest rate (%) Example: `6`
- `years` (query, optional, string) — Term in years Example: `30`
- `months` (query, optional, string) — Or term in months

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/loan-api/v1/affordability?monthly_payment=1199.10&annual_rate=6&years=30"
```

**Response:**
```json
{
    "data": {
        "note": "Inverse amortization: P = M·((1+r)ⁿ − 1) / (r·(1+r)ⁿ). The most you can borrow for a given monthly budget.",
        "inputs": {
            "payments": 360,
            "annual_rate_pct": 6,
            "monthly_payment": 1199.1
        },
        "total_paid": 431676,
        "max_principal": 199999.82,
        "total_interest": 231676.18,
        "number_of_payments": 360
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:08.837Z",
        "request_id": "42a8428e-108d-4e17-93ab-cee434b5fd9a"
    },
    "status": "ok",
    "message": "Affordability",
    "success": true
}
```

#### `GET /v1/payment` — Monthly payment

**Parameters:**
- `principal` (query, required, string) — Loan principal Example: `200000`
- `annual_rate` (query, required, string) — Annual interest rate (%) Example: `6`
- `years` (query, optional, string) — Term in years Example: `30`
- `months` (query, optional, string) — Or term in months

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/loan-api/v1/payment?principal=200000&annual_rate=6&years=30"
```

**Response:**
```json
{
    "data": {
        "note": "Fully-amortizing fixed-rate loan: M = P·r·(1+r)ⁿ / ((1+r)ⁿ − 1), r = annual rate / 12.",
        "inputs": {
            "payments": 360,
            "principal": 200000,
            "annual_rate_pct": 6
        },
        "total_paid": 431676.38,
        "total_interest": 231676.38,
        "monthly_payment": 1199.1,
        "interest_fraction": 0.53669,
        "number_of_payments": 360
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:08.944Z",
        "request_id": "30dd0143-84aa-4cb1-b7a0-33f9a8a8699c"
    },
    "status": "ok",
    "message": "Monthly payment",
    "success": true
}
```

#### `GET /v1/schedule` — Amortization split

**Parameters:**
- `principal` (query, required, string) — Loan principal Example: `200000`
- `annual_rate` (query, required, string) — Annual interest rate (%) Example: `6`
- `years` (query, optional, string) — Term in years Example: `30`
- `months` (query, optional, string) — Or term in months
- `payment_number` (query, optional, string) — Which payment to break down Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/loan-api/v1/schedule?principal=200000&annual_rate=6&years=30&payment_number=1"
```

**Response:**
```json
{
    "data": {
        "note": "Each payment: interest = balance·r, principal = M − interest. Balance falls until it reaches zero on the final payment.",
        "inputs": {
            "payments": 360,
            "principal": 200000,
            "payment_number": 1,
            "annual_rate_pct": 6
        },
        "monthly_payment": 1199.1,
        "payment_interest": 1000,
        "payment_principal": 199.1,
        "remaining_balance": 199800.9,
        "cumulative_interest": 1000,
        "cumulative_principal": 199.1
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:09.080Z",
        "request_id": "9987732b-f887-45f5-9ef5-54f25f6d4e1f"
    },
    "status": "ok",
    "message": "Amortization split",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/loan-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Amounts in any single currency; annual_rate in percent; term as 'years' or 'months'. Fixed-rate, fully-amortizing loans (mortgages, auto and personal loans).",
        "service": "loan-api",
        "formulae": {
            "payment": "M = P·r·(1+r)ⁿ / ((1+r)ⁿ − 1)",
            "principal": "P = M·((1+r)ⁿ − 1) / (r·(1+r)ⁿ)",
            "monthly_rate": "r = annual_rate / 100 / 12",
            "zero_interest": "M = P / n"
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/payment": "Monthly payment, total paid and total interest for a fixed-rate loan.",
            "GET /v1/schedule": "Interest/principal split and remaining balance at a given payment number.",
            "GET /v1/affordability": "Largest principal a given monthly payment can service."
        },
        "description": "Loan and mortgage amortization calculator: monthly payment and total interest, per-payment interest/principal split with running balance, and the maximum principal a monthly budget can afford."
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:09.187Z",
        "request_id": "0a7e8b6b-cd6d-4724-a853-d329ea35cab3"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/loan-api
OpenAPI spec: https://www.oanor.com/api/loan-api/openapi.json