# Bond Pricing API
> Fixed-income bond maths as an API, computed locally and deterministically. The price endpoint computes a bond's price from its face value, coupon rate, yield to maturity, years to maturity and coupon frequency — Price = Σ coupon/(1+y)ᵗ + face/(1+y)ⁿ with y the periodic yield — and reports the clean price as a percent of par, the annual coupon, the current yield and whether the bond trades at a premium, discount or par. The yield endpoint inverts this, solving for the yield to maturity that matches a given market price by bisection, with the current yield. The duration endpoint computes the Macaulay duration (the cash-flow-weighted average time), the modified duration (which approximates the percent price change per 1 % yield move), the convexity and the DV01 (the price change per basis point). A zero-coupon bond is just coupon rate 0. Everything is computed locally and deterministically, so it is instant and private. Ideal for fintech, fixed-income, treasury and portfolio app developers, bond-analytics and risk tools, and finance education. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is bond analytics; for option pricing use an options API and for NPV and IRR an NPV 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/bond-api/..."
```

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

## Endpoints

### Bond

#### `GET /v1/duration` — Duration & convexity

**Parameters:**
- `face_value` (query, optional, string) — Face value Example: `1000`
- `coupon_rate` (query, required, string) — Annual coupon rate (%) Example: `5`
- `maturity` (query, required, string) — Years to maturity Example: `10`
- `frequency` (query, optional, string) — Coupons per year Example: `2`
- `ytm` (query, required, string) — Yield to maturity (%) Example: `6`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bond-api/v1/duration?face_value=1000&coupon_rate=5&maturity=10&frequency=2&ytm=6"
```

**Response:**
```json
{
    "data": {
        "dv01": 0.709486,
        "note": "Macaulay duration is the cash-flow-weighted average time; modified = Macaulay/(1+y) and approximates % price change per 1 % yield move. DV01 is the price change per 1 bp.",
        "price": 925.612626,
        "inputs": {
            "ytm_pct": 6,
            "frequency": 2,
            "face_value": 1000,
            "maturity_years": 10,
            "coupon_rate_pct": 5
        },
        "convexity": 71.785398,
        "macaulay_duration_years": 7.894997,
        "modified_duration_years": 7.665046
    },
    "meta": {
        "timestamp": "2026-06-05T03:09:00.249Z",
        "request_id": "1adf4cf0-cece-4671-ab22-d9149843837a"
    },
    "status": "ok",
    "message": "Duration & convexity",
    "success": true
}
```

#### `GET /v1/price` — Bond price

**Parameters:**
- `face_value` (query, optional, string) — Face value Example: `1000`
- `coupon_rate` (query, required, string) — Annual coupon rate (%) Example: `5`
- `maturity` (query, required, string) — Years to maturity Example: `10`
- `frequency` (query, optional, string) — Coupons per year Example: `2`
- `ytm` (query, required, string) — Yield to maturity (%) Example: `6`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bond-api/v1/price?face_value=1000&coupon_rate=5&maturity=10&frequency=2&ytm=6"
```

**Response:**
```json
{
    "data": {
        "note": "Price = Σ coupon/(1+y)ᵗ + face/(1+y)ⁿ with y the periodic yield. Above par = premium (coupon > YTM).",
        "price": 925.612626,
        "inputs": {
            "ytm_pct": 6,
            "frequency": 2,
            "face_value": 1000,
            "maturity_years": 10,
            "coupon_rate_pct": 5
        },
        "annual_coupon": 50,
        "current_yield_pct": 5.401828,
        "premium_or_discount": "discount",
        "clean_price_percent_of_par": 92.561263
    },
    "meta": {
        "timestamp": "2026-06-05T03:09:00.322Z",
        "request_id": "0c1269aa-6f02-4007-b0da-9713d70a605b"
    },
    "status": "ok",
    "message": "Bond price",
    "success": true
}
```

#### `GET /v1/yield` — Yield to maturity

**Parameters:**
- `face_value` (query, optional, string) — Face value Example: `1000`
- `coupon_rate` (query, required, string) — Annual coupon rate (%) Example: `5`
- `maturity` (query, required, string) — Years to maturity Example: `10`
- `frequency` (query, optional, string) — Coupons per year Example: `2`
- `price` (query, required, string) — Market price Example: `925.61`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bond-api/v1/yield?face_value=1000&coupon_rate=5&maturity=10&frequency=2&price=925.61"
```

**Response:**
```json
{
    "data": {
        "note": "YTM is the annualised discount rate that makes the present value of the cash flows equal the price (by bisection).",
        "inputs": {
            "price": 925.61,
            "frequency": 2,
            "face_value": 1000,
            "maturity_years": 10,
            "coupon_rate_pct": 5
        },
        "current_yield_pct": 5.401843,
        "yield_to_maturity_pct": 6.000037
    },
    "meta": {
        "timestamp": "2026-06-05T03:09:00.416Z",
        "request_id": "f95d1ef4-0352-4034-a78e-8ba7e3b5e7b8"
    },
    "status": "ok",
    "message": "Yield to maturity",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Face value defaults to 1000; coupon_rate and ytm are annual percents; maturity in years; frequency is coupons per year (default 2). Zero-coupon = coupon_rate 0.",
        "service": "bond-api",
        "formulae": {
            "price": "Σ c/(1+y)ᵗ + F/(1+y)ⁿ",
            "convexity": "Σ t(t+1)·CF/(1+y)^(t+2) / price",
            "modified_duration": "Macaulay / (1 + y)"
        },
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/price": "Bond price, clean price, current yield and premium/discount from the YTM.",
            "GET /v1/yield": "Yield to maturity and current yield from a market price.",
            "GET /v1/duration": "Macaulay and modified duration, convexity and DV01."
        },
        "description": "Bond analytics: price from yield, yield to maturity from price, and Macaulay/modified duration with convexity."
    },
    "meta": {
        "timestamp": "2026-06-05T03:09:00.502Z",
        "request_id": "6482e1ac-3a62-482f-8436-cc9bc8f62886"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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