# CAGR & Returns API
> Investment growth and return maths as an API, computed locally and deterministically. The cagr endpoint computes the compound annual growth rate, CAGR = (end/begin)^(1/years) − 1 — the single smoothed annual rate that compounds a starting value into an ending value — together with the total return and the growth multiple, so €1,000 growing to €2,000 over five years works out to about 14.87 %/yr. The future-value endpoint compounds a single lump sum, FV = PV·(1+r)^n, and the present-value endpoint discounts a future lump sum back to today, PV = FV/(1+r)^n. The annualize endpoint converts a total holding-period return over a span of years into an equivalent annual rate, and back the other way. The doubling-time endpoint gives the exact time for money to double, ln2/ln(1+r), alongside the Rule-of-72, Rule-of-70 and Rule-of-69.3 quick estimates — at 8 % money doubles in about nine years. Rates are decimals (0.07 = 7 %) except the doubling endpoint which takes a percentage. Everything is computed locally and deterministically, so it is instant and private. Ideal for fintech, investing, portfolio, robo-advisor, personal-finance and finance-education app developers, return-and-growth calculators, and dashboards. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 5 endpoints. These are single-sum growth and return metrics; for level-payment loans use a loan API and for regular-deposit savings 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/cagr-api/..."
```

## Pricing
- **Free** (Free) — 6,000 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 60,000 calls/Mo, 6 req/s
- **Pro** ($17/Mo) — 270,000 calls/Mo, 15 req/s
- **Mega** ($49/Mo) — 1,500,000 calls/Mo, 40 req/s

## Endpoints

### Returns

#### `GET /v1/annualize` — Annualize a total return

**Parameters:**
- `total_return` (query, optional, string) — Total return (e.g. 0.5 = +50%) Example: `0.5`
- `annual_return` (query, optional, string) — Or annual return to compound
- `years` (query, required, string) — Number of years Example: `3`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cagr-api/v1/annualize?total_return=0.5&years=3"
```

**Response:**
```json
{
    "data": {
        "note": "Annualized = (1 + total_return)^(1/years) − 1.",
        "inputs": {
            "years": 3,
            "total_return": 0.5
        },
        "annualized_return": 0.14471424,
        "annualized_percent": 14.471424
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:25.411Z",
        "request_id": "f5bf8db5-674d-4565-9f1a-26f4344616ba"
    },
    "status": "ok",
    "message": "Annualize a return",
    "success": true
}
```

#### `GET /v1/cagr` — Compound annual growth rate

**Parameters:**
- `begin_value` (query, required, string) — Beginning value Example: `1000`
- `end_value` (query, required, string) — Ending value Example: `2000`
- `years` (query, required, string) — Number of years Example: `5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cagr-api/v1/cagr?begin_value=1000&end_value=2000&years=5"
```

**Response:**
```json
{
    "data": {
        "cagr": 0.14869835,
        "note": "CAGR = (end/begin)^(1/years) − 1 — the smooth annual rate that compounds the start value to the end value. €1,000 → €2,000 over 5 years is ≈14.87 %/yr.",
        "inputs": {
            "years": 5,
            "end_value": 2000,
            "begin_value": 1000
        },
        "multiple": 2,
        "cagr_percent": 14.869835,
        "total_return": 1,
        "total_return_percent": 100
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:25.539Z",
        "request_id": "e095da69-bd5b-4a80-9d82-0b607afe2900"
    },
    "status": "ok",
    "message": "Compound annual growth rate",
    "success": true
}
```

#### `GET /v1/doubling-time` — Doubling time / Rule of 72

**Parameters:**
- `rate_percent` (query, required, string) — Rate in percent (e.g. 8) Example: `8`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cagr-api/v1/doubling-time?rate_percent=8"
```

**Response:**
```json
{
    "data": {
        "note": "Doubling time: exact = ln2/ln(1+r). The Rule of 72 (72/rate%) is a handy estimate — at 8 % money doubles in about 9 years.",
        "inputs": {
            "rate_percent": 8
        },
        "rule_of_70": 8.75,
        "rule_of_72": 9,
        "exact_years": 9.006468,
        "rule_of_69_3": 8.6625
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:25.654Z",
        "request_id": "937563f2-9d53-465e-bb80-c78ec00d3ab5"
    },
    "status": "ok",
    "message": "Doubling time",
    "success": true
}
```

#### `GET /v1/future-value` — Lump-sum future value

**Parameters:**
- `present_value` (query, required, string) — Present value Example: `1000`
- `rate` (query, required, string) — Rate per period (e.g. 0.07) Example: `0.07`
- `periods` (query, required, string) — Number of periods Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cagr-api/v1/future-value?present_value=1000&rate=0.07&periods=10"
```

**Response:**
```json
{
    "data": {
        "note": "Lump-sum compound growth FV = PV·(1+r)^n. €1,000 at 7 % for 10 periods grows to ≈€1,967.15.",
        "growth": 967.151357,
        "inputs": {
            "rate": 0.07,
            "periods": 10,
            "present_value": 1000
        },
        "future_value": 1967.151357
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:25.757Z",
        "request_id": "26cac6c9-1405-41b1-946d-d8ed2609af16"
    },
    "status": "ok",
    "message": "Future value",
    "success": true
}
```

#### `GET /v1/present-value` — Lump-sum present value

**Parameters:**
- `future_value` (query, required, string) — Future value Example: `1967.15`
- `rate` (query, required, string) — Rate per period Example: `0.07`
- `periods` (query, required, string) — Number of periods Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cagr-api/v1/present-value?future_value=1967.15&rate=0.07&periods=10"
```

**Response:**
```json
{
    "data": {
        "note": "Lump-sum discounting PV = FV/(1+r)^n — what a future amount is worth today.",
        "inputs": {
            "rate": 0.07,
            "periods": 10,
            "future_value": 1967.15
        },
        "discount": 967.15069,
        "present_value": 999.99931
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:25.841Z",
        "request_id": "5239d4f8-846d-4dc4-8609-8a00e6c482b6"
    },
    "status": "ok",
    "message": "Present value",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Rates as decimals (0.07 = 7 %) except doubling-time which takes rate_percent. Single-sum growth and return metrics; for level-payment loans use a loan API and for regular-deposit savings a savings API.",
        "service": "cagr-api",
        "endpoints": {
            "GET /v1/cagr": "Compound annual growth rate from begin/end value and years.",
            "GET /v1/meta": "This document.",
            "GET /v1/annualize": "Convert a total return over a span into an annual rate (or back).",
            "GET /v1/future-value": "Lump-sum compound growth FV = PV·(1+r)^n.",
            "GET /v1/doubling-time": "Exact doubling time and Rule-of-72/70/69.3 estimates.",
            "GET /v1/present-value": "Discount a future lump sum PV = FV/(1+r)^n."
        },
        "description": "Investment growth and return: CAGR, lump-sum future/present value, annualizing a total return, and doubling time (Rule of 72)."
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:25.902Z",
        "request_id": "9d854386-f02f-4c5d-ab21-784bc0032ef8"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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