# Investment Calculator API
> Investment and capital-budgeting maths as an API. The npv endpoint computes the net present value of a series of cash flows at a discount rate (the first flow is usually the negative initial investment). The irr endpoint finds the internal rate of return — the discount rate at which the net present value is zero — by a robust bracketed search. The annuity endpoint solves a level (ordinary) annuity: give the rate, the number of periods and any one of the payment, present value or future value, and it returns the other two. The depreciation endpoint builds a full year-by-year schedule by the straight-line, declining-balance (any factor, including double-declining) or sum-of-the-years'-digits method, never depreciating below the salvage value. Rates may be entered as a percentage or a fraction. Everything is computed locally and deterministically, so it is instant and private. Ideal for investment analysis and capital budgeting, accounting and corporate-finance tools, business planning, and finance education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 5 endpoints. This is investment and capital-budgeting maths; for loans, mortgages and compound interest use a financial-calculator 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/financecalc-api/..."
```

## Pricing
- **Free** (Free) — 7,535 calls/Mo, 2 req/s
- **Starter** ($9/Mo) — 17,050 calls/Mo, 8 req/s
- **Pro** ($29/Mo) — 221,500 calls/Mo, 20 req/s
- **Mega** ($67/Mo) — 1,150,000 calls/Mo, 50 req/s

## Endpoints

### Finance

#### `GET /v1/annuity` — Solve a level annuity

**Parameters:**
- `rate` (query, required, string) — Per-period rate Example: `5`
- `periods` (query, required, string) — Number of periods Example: `10`
- `payment` (query, optional, string) — Or present_value / future_value Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/financecalc-api/v1/annuity?rate=5&periods=10&payment=100"
```

**Response:**
```json
{
    "data": {
        "type": "ordinary annuity (payments at period end)",
        "payment": 100,
        "periods": 10,
        "future_value": 1257.79,
        "rate_percent": 5,
        "present_value": 772.17
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:08.118Z",
        "request_id": "37373a41-d88c-40c6-898a-7826849b78db"
    },
    "status": "ok",
    "message": "Annuity",
    "success": true
}
```

#### `GET /v1/depreciation` — Depreciation schedule

**Parameters:**
- `cost` (query, required, string) — Asset cost Example: `10000`
- `salvage` (query, optional, string) — Salvage value Example: `1000`
- `life` (query, required, string) — Years Example: `5`
- `method` (query, optional, string) — straight_line|declining_balance|sum_of_years Example: `straight_line`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/financecalc-api/v1/depreciation?cost=10000&salvage=1000&life=5&method=straight_line"
```

**Response:**
```json
{
    "data": {
        "cost": 10000,
        "life": 5,
        "method": "straight_line",
        "salvage": 1000,
        "schedule": [
            {
                "year": 1,
                "book_value": 8200,
                "accumulated": 1800,
                "depreciation": 1800
            },
            {
                "year": 2,
                "book_value": 6400,
                "accumulated": 3600,
                "depreciation": 1800
            },
            {
                "year": 3,
                "book_value": 4600,
                "accumulated": 5400,
                "depreciation": 1800
            },
            {
                "year": 4,
                "book_value": 2800,
                "accumulated": 7200,
                "depreciation": 1800
            },
            {
                "year": 5,
                "book_value": 1000,
                "accumulated": 9000,
                "depreciation": 1800
            }
        ],
        "total_depreciation": 9000
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:08.222Z",
        "request_id": "62327f2d-b582-4dc2-8603-f41f0e84360a"
    },
    "status": "ok",
    "message": "Depreciation",
    "success": true
}
```

#### `GET /v1/irr` — Internal rate of return

**Parameters:**
- `cashflows` (query, required, string) — List of cash flows Example: `[-1000,500,500,500]`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/financecalc-api/v1/irr?cashflows=%5B-1000%2C500%2C500%2C500%5D"
```

**Response:**
```json
{
    "data": {
        "irr": 0.23375193,
        "cashflows": [
            -1000,
            500,
            500,
            500
        ],
        "npv_at_irr": 0,
        "irr_percent": 23.3752
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:08.315Z",
        "request_id": "10d911fd-c18a-4d4f-bda7-9740f76bc0ac"
    },
    "status": "ok",
    "message": "IRR",
    "success": true
}
```

#### `GET /v1/npv` — Net present value

**Parameters:**
- `cashflows` (query, required, string) — List of cash flows Example: `[-1000,500,500,500]`
- `rate` (query, required, string) — Discount rate (% or fraction) Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/financecalc-api/v1/npv?cashflows=%5B-1000%2C500%2C500%2C500%5D&rate=10"
```

**Response:**
```json
{
    "data": {
        "npv": 243.43,
        "cashflows": [
            -1000,
            500,
            500,
            500
        ],
        "rate_percent": 10
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:08.414Z",
        "request_id": "c87da843-3e03-4a88-969a-c3cadc005b98"
    },
    "status": "ok",
    "message": "NPV",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "name": "Investment Calculator API",
        "notes": "Annuities are ordinary (payments at period end). Rates accept percent (10) or fraction (0.10). IRR uses a bracketed bisection; unconventional flows may have none or several. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/npv",
                "params": {
                    "rate": "discount rate (percent or fraction)",
                    "cashflows": "[-1000,500,500,500]"
                },
                "returns": "the net present value"
            },
            {
                "path": "/v1/irr",
                "params": {
                    "cashflows": "[-1000,500,500,500]"
                },
                "returns": "the internal rate of return"
            },
            {
                "path": "/v1/annuity",
                "params": {
                    "rate": "per-period rate",
                    "payment": "or present_value or future_value (give exactly one)",
                    "periods": "number of periods"
                },
                "returns": "payment, present value and future value"
            },
            {
                "path": "/v1/depreciation",
                "params": {
                    "cost": "asset cost",
                    "life": "years",
                    "factor": "for declining balance (default 2)",
                    "method": "straight_line|declining_balance|sum_of_y
…(truncated, see openapi.json for full schema)
```


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