# Crypto Basis API
> Live crypto spot-versus-perpetual basis and premium as an API, served from the Bybit v5 feed. The basis is the gap between a coin's perpetual-futures price and its spot price: when the perp trades above spot the market is in contango (leveraged longs are paying up), when below it is in backwardation. For any coin this returns the spot price, the perp last, mark and index price, the basis in absolute and percentage terms, the mark-to-index premium, the market structure, and the funding rate — per-8-hour and annualised — that arbitrages the basis away. Get a coin's basis, or scan the majors ranked by basis. The cash-and-carry and funding-arbitrage signal layer for trading and dashboard apps. Live, no key, no cache. Distinct from funding-rate, open-interest and price APIs — this is the spot-perp basis.

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

## Pricing
- **Free** (Free) — 8,000 calls/Mo, 5 req/s
- **Starter** ($14/Mo) — 105,000 calls/Mo, 15 req/s
- **Pro** ($35/Mo) — 520,000 calls/Mo, 40 req/s
- **Desk** ($83/Mo) — 2,700,000 calls/Mo, 100 req/s

## Endpoints

### Basis

#### `GET /v1/basis` — A coin spot-perp basis, premium and funding

**Parameters:**
- `symbol` (query, required, string) — Coin ticker Example: `BTC`

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

**Response:**
```json
{
    "data": {
        "base": "BTC",
        "symbol": "BTCUSDT",
        "basis_abs": -35.5,
        "basis_pct": -0.0565,
        "structure": "backwardation",
        "mark_price": 62827.44,
        "perp_price": 62821.2,
        "spot_price": 62856.7,
        "index_price": 62860.31,
        "funding_rate": -5.56e-6,
        "funding_8h_pct": -0.0006,
        "funding_annualized_pct": -0.61,
        "mark_index_premium_pct": -0.0523
    },
    "meta": {
        "timestamp": "2026-06-09T03:02:06.835Z",
        "request_id": "c6fe828e-4139-4bc7-88aa-b709251855ac"
    },
    "status": "ok",
    "message": "Basis retrieved successfully",
    "success": true
}
```

### Scan

#### `GET /v1/scan` — Majors ranked by basis

**Parameters:**
- `add` (query, optional, string) — Extra tickers, comma-separated Example: `PEPE,WIF`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cryptobasis-api/v1/scan?add=PEPE%2CWIF"
```

**Response:**
```json
{
    "data": {
        "coins": [
            {
                "base": "BTC",
                "symbol": "BTCUSDT",
                "basis_abs": -35.5,
                "basis_pct": -0.0565,
                "structure": "backwardation",
                "mark_price": 62827.44,
                "perp_price": 62821.2,
                "spot_price": 62856.7,
                "index_price": 62859.33,
                "funding_rate": -5.56e-6,
                "funding_8h_pct": -0.0006,
                "funding_annualized_pct": -0.61,
                "mark_index_premium_pct": -0.0507
            },
            {
                "base": "XRP",
                "symbol": "XRPUSDT",
                "basis_abs": 0,
                "basis_pct": -0.0607,
                "structure": "backwardation",
                "mark_price": 1.1529,
                "perp_price": 1.1529,
                "spot_price": 1.1536,
                "index_price": 1.1538,
                "funding_rate": -0.00021722,
                "funding_8h_pct": -0.0217,
                "funding_annualized_pct": -23.79,
                "mark_index_premium_pct": -0.078
            },
            {
                "base": "ETH",
                "symbol": "ETHUSDT",
                "basis_abs": -1.15,
                "basis_pct": -0.069,
                "structure": "backwardation",
                "mark_price": 1665.76,
                "perp_price": 1665.75,
                "spot_price": 1666.9,
                "index_price": 1666
…(truncated, see openapi.json for full schema)
```

### Symbols

#### `GET /v1/symbols` — Major coins covered by scan

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

**Response:**
```json
{
    "data": {
        "note": "Any Bybit coin with both a USDT spot and a USDT linear perp works via symbol=<BASE>. The scan board covers these majors:",
        "count": 10,
        "majors": [
            "BTC",
            "ETH",
            "SOL",
            "BNB",
            "XRP",
            "DOGE",
            "ADA",
            "AVAX",
            "LINK",
            "LTC"
        ]
    },
    "meta": {
        "timestamp": "2026-06-09T03:02:07.529Z",
        "request_id": "ff94a4bb-0d53-44f7-a911-39cbf5a0ca85"
    },
    "status": "ok",
    "message": "Symbols retrieved successfully",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Service metadata

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

**Response:**
```json
{
    "data": {
        "source": "Bybit v5 spot + linear tickers (live)",
        "service": "cryptobasis-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/scan": "Majors ranked by basis (add=PEPE,WIF to extend).",
            "GET /v1/basis": "A coin's spot-perp basis, premium and funding (symbol=BTC).",
            "GET /v1/symbols": "The majors covered by scan (any Bybit USDT spot+perp works)."
        },
        "description": "Live crypto spot-vs-perpetual basis and premium from Bybit v5: for any coin, the spot price, the perp last/mark/index price, the basis (absolute and percent), the mark-to-index premium, the market structure (contango/backwardation/flat) and the funding rate (per-8h and annualised). Get a coin's basis or scan the majors ranked by basis. Live, no key. Distinct from funding-rate, open-interest and price APIs — this is the spot-perp basis / cash-and-carry signal.",
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-09T03:02:07.782Z",
        "request_id": "ccf97bf3-8bdc-43e8-8275-510879a57f68"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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