# NPV & IRR API
> Discounted-cash-flow investment-appraisal maths as an API, computed locally and deterministically. The npv endpoint computes the net present value of a project from an upfront outlay, a series of future net cash flows and a discount rate, NPV = −initial + Σ CFₜ/(1+r)ᵗ, and reports the present value of the inflows, the profitability index and a plain accept-or-reject decision. The irr endpoint solves the internal rate of return — the discount rate that makes the NPV zero — by robust bisection over the cash flows, the figure you compare against a hurdle rate. The payback endpoint computes both the simple payback period, when the cumulative cash flow first recovers the outlay, and the discounted payback period, which discounts each flow first. Cash flows are passed as a comma-separated list, one per period. Everything is computed locally and deterministically, so it is instant and private. Ideal for finance, corporate, fintech and project-management app developers, capital-budgeting and feasibility tools, and finance education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is capital budgeting; for loan amortization use a loan API and for CAGR and real returns an investment 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/npv-api/..."
```

## Pricing
- **Free** (Free) — 2,000 calls/Mo, 2 req/s
- **Starter** ($15/Mo) — 30,000 calls/Mo, 5 req/s
- **Pro** ($39/Mo) — 200,000 calls/Mo, 20 req/s
- **Mega** ($119/Mo) — 1,500,000 calls/Mo, 60 req/s

## Endpoints

### Investment

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

**Parameters:**
- `initial` (query, required, string) — Initial investment (outlay) Example: `1000`
- `cash_flows` (query, required, string) — Comma-separated cash flows Example: `300,400,500,600`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/npv-api/v1/irr?initial=1000&cash_flows=300%2C400%2C500%2C600"
```

**Response:**
```json
{
    "data": {
        "note": "IRR is the discount rate that makes NPV zero. Accept a project when its IRR exceeds your required rate of return (hurdle rate).",
        "inputs": {
            "initial": 1000,
            "periods": 4
        },
        "irr_pct": 24.888336
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:01.039Z",
        "request_id": "091c37c2-eae9-4022-be11-032cdbd38fb8"
    },
    "status": "ok",
    "message": "Internal rate of return",
    "success": true
}
```

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

**Parameters:**
- `initial` (query, required, string) — Initial investment (outlay) Example: `1000`
- `cash_flows` (query, required, string) — Comma-separated cash flows (year 1..n) Example: `300,400,500,600`
- `rate` (query, required, string) — Discount rate (%) Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/npv-api/v1/npv?initial=1000&cash_flows=300%2C400%2C500%2C600&rate=10"
```

**Response:**
```json
{
    "data": {
        "npv": 388.7713,
        "note": "NPV = −initial + Σ CFₜ/(1+r)ᵗ. A positive NPV adds value; the profitability index is PV of inflows ÷ initial.",
        "inputs": {
            "initial": 1000,
            "periods": 4,
            "rate_pct": 10
        },
        "decision": "accept (creates value)",
        "profitability_index": 1.388771,
        "present_value_inflows": 1388.7713
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:01.156Z",
        "request_id": "7f718673-5cc3-493d-b875-b8a52f9eb6f5"
    },
    "status": "ok",
    "message": "Net present value",
    "success": true
}
```

#### `GET /v1/payback` — Payback period

**Parameters:**
- `initial` (query, required, string) — Initial investment (outlay) Example: `1000`
- `cash_flows` (query, required, string) — Comma-separated cash flows Example: `300,400,500,600`
- `rate` (query, optional, string) — Discount rate (%) for discounted payback Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/npv-api/v1/payback?initial=1000&cash_flows=300%2C400%2C500%2C600&rate=10"
```

**Response:**
```json
{
    "data": {
        "note": "Payback period is when cumulative cash flow recovers the initial outlay; the discounted version first discounts each flow at the given rate.",
        "inputs": {
            "initial": 1000,
            "periods": 4,
            "rate_pct": 10
        },
        "simple_recovered": true,
        "discounted_recovered": true,
        "simple_payback_years": 2.6,
        "discounted_payback_years": 3.0513
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:01.266Z",
        "request_id": "70b0deb5-1bc6-4a34-b3e6-f5ef23a34dbf"
    },
    "status": "ok",
    "message": "Payback period",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "'initial' is the upfront outlay (positive); 'cash_flows' is a comma-separated list of net inflows for periods 1..n; 'rate' is the discount rate in percent.",
        "service": "npv-api",
        "formulae": {
            "irr": "the rate r where NPV = 0",
            "npv": "−initial + Σ CFₜ/(1+r)ᵗ",
            "profitability_index": "PV of inflows / initial"
        },
        "endpoints": {
            "GET /v1/irr": "Internal rate of return — the discount rate that makes NPV zero.",
            "GET /v1/npv": "Net present value, PV of inflows, profitability index and accept/reject decision.",
            "GET /v1/meta": "This document.",
            "GET /v1/payback": "Simple and discounted payback period from the cash flows."
        },
        "description": "Discounted-cash-flow investment appraisal: net present value and profitability index, internal rate of return, and simple and discounted payback periods."
    },
    "meta": {
        "timestamp": "2026-06-04T18:38:01.384Z",
        "request_id": "20758ae2-2fff-4e1e-b315-07441316f669"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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