# Crypto Futures Term Structure & Basis Curve API
> The shape of the crypto dated-futures curve and the annualised basis at every expiry, read live from Deribit's public futures book — no key, nothing stored. A single spot price tells you nothing about what the market pays to hold a position over time: dated futures trade at a premium (contango) or a discount (backwardation) to spot, and that premium, annualised, is the cash-and-carry yield basis traders harvest. The curve endpoint returns, for a currency (BTC or ETH), the spot index, the perpetual and every listed dated future — each with its days to expiry, mark price, the absolute and percent basis to spot and the annualised basis — plus the overall curve shape (contango or backwardation) and the front- and back-month annualised basis. The basis endpoint returns the annualised basis (cash-and-carry yield) for a chosen expiry, or the front future. This is the futures-curve / term-structure cut for crypto — distinct from the spot-versus-perpetual basis API (a single point on the curve), and from the funding-rate, options, max-pain, gamma and price APIs in the catalogue. Currency is BTC or ETH; expiry is a Deribit code like 26JUN26.

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

## Pricing
- **Free** (Free) — 400 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 10,800 calls/Mo, 6 req/s
- **Pro** ($37/Mo) — 64,000 calls/Mo, 16 req/s
- **Business** ($85/Mo) — 340,000 calls/Mo, 40 req/s

## Endpoints

### Futures Curve

#### `GET /v1/basis` — Annualised basis for an expiry

**Parameters:**
- `currency` (query, required, string) — BTC or ETH Example: `BTC`
- `expiry` (query, optional, string) — Deribit expiry code (default front future) Example: `26JUN26`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/futurescurve-api/v1/basis?currency=BTC&expiry=26JUN26"
```

**Response:**
```json
{
    "data": {
        "mark": 63334.61,
        "expiry": "26JUN26",
        "source": "Deribit",
        "currency": "BTC",
        "basis_abs": 48.18,
        "basis_pct": 0.0761,
        "spot_index": 63286.43,
        "days_to_expiry": 14.26,
        "annualized_basis_pct": 1.95
    },
    "meta": {
        "timestamp": "2026-06-12T01:41:10.552Z",
        "request_id": "77fea771-ddc2-424f-be17-9d24ee36534c"
    },
    "status": "ok",
    "message": "Basis retrieved successfully",
    "success": true
}
```

#### `GET /v1/curve` — Full futures curve with annualised basis

**Parameters:**
- `currency` (query, required, string) — BTC or ETH Example: `BTC`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/futurescurve-api/v1/curve?currency=BTC"
```

**Response:**
```json
{
    "data": {
        "note": "annualized_basis_pct = (future/spot − 1) × 365/days — the cash-and-carry yield. Contango (positive) is the calm default; backwardation (negative) signals spot-demand stress. The perpetual basis is not annualised (it is continuously funded).",
        "count": 12,
        "curve": [
            {
                "mark": 63302.12,
                "expiry": "12JUN26",
                "basis_abs": 15.69,
                "basis_pct": 0.0248,
                "days_to_expiry": 0.26,
                "annualized_basis_pct": 34.4
            },
            {
                "mark": 63299.62,
                "expiry": "13JUN26",
                "basis_abs": 13.19,
                "basis_pct": 0.0208,
                "days_to_expiry": 1.26,
                "annualized_basis_pct": 6.02
            },
            {
                "mark": 63295.39,
                "expiry": "14JUN26",
                "basis_abs": 8.96,
                "basis_pct": 0.0142,
                "days_to_expiry": 2.26,
                "annualized_basis_pct": 2.28
            },
            {
                "mark": 63303.31,
                "expiry": "15JUN26",
                "basis_abs": 16.88,
                "basis_pct": 0.0267,
                "days_to_expiry": 3.26,
                "annualized_basis_pct": 2.98
            },
            {
                "mark": 63312.7,
                "expiry": "19JUN26",
                "basis_abs": 26.27,
                "basis_pct":
…(truncated, see openapi.json for full schema)
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "currency is BTC or ETH. annualized_basis_pct = (future/spot − 1) × 365/days. expiry is a Deribit code (e.g. 26JUN26) from /v1/curve. Read fresh per call, nothing cached.",
        "source": "Deribit public API (deribit.com/api/v2/public, live)",
        "service": "futurescurve-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/basis": "Annualised basis (cash-and-carry yield) for one expiry or the front future (currency=BTC, expiry optional).",
            "GET /v1/curve": "Full futures curve: perp + every dated future with annualised basis, and the contango/backwardation shape (currency=BTC)."
        },
        "currencies": [
            "BTC",
            "ETH"
        ],
        "description": "Crypto futures term structure and basis curve, read live from Deribit's public futures book (no key, nothing stored). curve returns the spot index, the perpetual and every dated future for a currency — each with days to expiry, mark, basis to spot and annualised basis — plus the contango/backwardation shape and the front/back annualised basis. basis returns the annualised basis (cash-and-carry yield) for a chosen expiry or the front future. The futures-curve / term-structure cut — distinct from the spot-versus-perpetual basis API (a single point), the funding-rate, options and price APIs.",
        "upstream_status": "ok",
        "btc_dated_futures": 12
    },
    "meta": {
        "timestamp":
…(truncated, see openapi.json for full schema)
```


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