# Financial Calculator API
> Common money math as an API. Calculate a loan: its monthly payment, total interest and total cost — with an optional full amortization schedule and the effect of extra monthly payments. Break down a mortgage into PITI (principal & interest, property tax, insurance, PMI and HOA) from a purchase price and down payment. Project compound interest and savings growth with optional recurring contributions (future value, total contributions, interest earned). And compute ROI on an investment, with annualised return when you supply the holding period. Every calculation is exact, deterministic and instant — pure local math, no third-party service and nothing stored. Live. 5 endpoints. Built for loan and mortgage calculators, savings and retirement planners, fintech tools and budgeting apps. Distinct from market-data and bank-data services. No upstream key.

## 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/fincalc-api/..."
```

## Pricing
- **Free** (Free) — 1,620 calls/Mo, 2 req/s
- **Starter** ($8/Mo) — 34,000 calls/Mo, 8 req/s
- **Pro** ($28/Mo) — 195,000 calls/Mo, 20 req/s
- **Mega** ($64/Mo) — 990,000 calls/Mo, 50 req/s

## Endpoints

### Loans

#### `GET /v1/loan` — Loan amortization

**Parameters:**
- `principal` (query, required, string) — Loan amount Example: `200000`
- `rate` (query, required, string) — Annual interest rate % Example: `6`
- `years` (query, required, string) — Term in years Example: `30`
- `extra` (query, optional, string) — Extra monthly payment
- `schedule` (query, optional, string) — true → include amortization table

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

**Response:**
```json
{
    "data": {
        "principal": 200000,
        "total_paid": 431676.38,
        "annual_rate": 6,
        "term_months": 360,
        "extra_payment": 0,
        "total_interest": 231676.38,
        "monthly_payment": 1199.1,
        "number_of_payments": 360,
        "base_monthly_payment": 1199.1
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:02.733Z",
        "request_id": "4e0c4df5-979a-44be-83aa-694d315b79e3"
    },
    "status": "ok",
    "message": "Loan amortization",
    "success": true
}
```

#### `GET /v1/mortgage` — Mortgage PITI

**Parameters:**
- `price` (query, required, string) — Purchase price Example: `400000`
- `down_payment` (query, optional, string) — Down payment Example: `80000`
- `rate` (query, required, string) — Annual rate % Example: `6.5`
- `years` (query, optional, string) — Term years (default 30) Example: `30`
- `property_tax` (query, optional, string) — Annual property tax Example: `4800`
- `insurance` (query, optional, string) — Annual insurance Example: `1200`
- `pmi` (query, optional, string) — Annual PMI
- `hoa` (query, optional, string) — Monthly HOA

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fincalc-api/v1/mortgage?price=400000&down_payment=80000&rate=6.5&years=30&property_tax=4800&insurance=1200"
```

**Response:**
```json
{
    "data": {
        "monthly": {
            "hoa": 0,
            "pmi": 0,
            "total": 2522.62,
            "insurance": 100,
            "property_tax": 400,
            "principal_interest": 2022.62
        },
        "term_years": 30,
        "total_paid": 728142.36,
        "annual_rate": 6.5,
        "loan_amount": 320000,
        "total_interest": 408142.36
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:02.838Z",
        "request_id": "8b79178f-d519-4f50-bfe0-5f94643c82af"
    },
    "status": "ok",
    "message": "Mortgage PITI",
    "success": true
}
```

### Savings

#### `GET /v1/compound-interest` — Compound interest

**Parameters:**
- `principal` (query, required, string) — Starting amount Example: `10000`
- `rate` (query, required, string) — Annual rate % Example: `7`
- `years` (query, required, string) — Years Example: `20`
- `compounds_per_year` (query, optional, string) — Default 12 Example: `12`
- `contribution` (query, optional, string) — Per-period contribution Example: `500`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fincalc-api/v1/compound-interest?principal=10000&rate=7&years=20&compounds_per_year=12&contribution=500"
```

**Response:**
```json
{
    "data": {
        "years": 20,
        "principal": 10000,
        "annual_rate": 7,
        "future_value": 300850.72,
        "interest_earned": 170850.72,
        "compounds_per_year": 12,
        "total_contributions": 130000,
        "contribution_per_period": 500
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:02.926Z",
        "request_id": "989624e9-4e07-496e-8aa6-288ca0908d42"
    },
    "status": "ok",
    "message": "Compound interest",
    "success": true
}
```

### Investing

#### `GET /v1/roi` — Return on investment

**Parameters:**
- `initial` (query, required, string) — Initial value Example: `1000`
- `final` (query, required, string) — Final value Example: `2500`
- `years` (query, optional, string) — Holding period (for annualised) Example: `5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fincalc-api/v1/roi?initial=1000&final=2500&years=5"
```

**Response:**
```json
{
    "data": {
        "final": 2500,
        "initial": 1000,
        "net_gain": 1500,
        "roi_percent": 150,
        "annualized_percent": 20.11
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:03.033Z",
        "request_id": "adfae80d-297a-40ec-904d-7566891c772e"
    },
    "status": "ok",
    "message": "Return on investment",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "auth": "none upstream; this gateway requires x-api-key",
        "name": "Financial Calculator API",
        "note": "Loan amortization (/v1/loan: principal, rate, years; ?schedule=true for the table; ?extra= for extra payments), mortgage PITI (/v1/mortgage: price/down_payment or principal, rate, years, property_tax, insurance, pmi, hoa), compound interest (/v1/compound-interest: principal, rate, years, compounds_per_year, contribution), and ROI (/v1/roi: initial, final, ?years). Deterministic and instant. Distinct from finance-api (market data).",
        "source": "Local financial math — no key, no upstream",
        "endpoints": 5
    },
    "meta": {
        "timestamp": "2026-06-02T16:52:03.141Z",
        "request_id": "e88be9bc-91d1-4613-a0e8-13f820f30182"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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