> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sharpe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Futures API

> Retrieve perpetual futures chart data including open interest, liquidations, volume, funding rates, and basis across major exchanges.

The futures endpoints provide granular derivatives data across 24 chart types and 10 exchanges (Binance, Bybit, OKX, Deribit, Hyperliquid by default; Bitget, Gate.io, KuCoin, MEXC, HTX accepted by the `exchanges` filter on funding-rate, funding-cost, crowding-risk, perpetual-price, volume-snapshot, volume-history and the returns charts only). Query open interest, liquidations, volume profiles, funding rates, long/short ratios, 3-month basis, term structure, and signal views with configurable timeframes and exchange filters.

***

## Derivatives overview

`GET /v1/market/derivatives-overview`

Returns market-wide derivatives aggregates including total open interest, simple and OI-weighted funding rates, top coins by open interest, exchange count, coin count, and update timestamp. Open interest is one-sided USD notional per venue (each contract counted once); a venue listed in `oi_excluded_venues` (MEXC today, whose open interest moves 7.00x the position change of its own trade feed) is left out of every open-interest total and weight, with the reason. `total_oi_usd` is the market-wide total `/v1/global/overview` publishes (`metrics.openInterestUsd`): every crypto asset holding at least \$100K plus the RWA perps. Funding is normalized to an 8-hour equivalent before aggregation, and OI weighting weights each venue's primary rate by that contract's own open interest. The endpoint fails closed when either source dataset is unavailable instead of returning a fresh-looking zero snapshot.

No query parameters.

```bash cURL theme={null}
curl https://www.sharpe.ai/api/v1/market/derivatives-overview \
  -H "Authorization: Bearer sk_live_your_key_here"
```

```ts TypeScript theme={null}
const res = await fetch(
  'https://www.sharpe.ai/api/v1/market/derivatives-overview',
  {
    headers: {
      Authorization: 'Bearer sk_live_your_key_here',
    },
  },
)
const { data } = await res.json()
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://www.sharpe.ai/api/v1/market/derivatives-overview",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
)
data = resp.json()["data"]
```

***

## Get futures data

`GET /v1/futures/data`

Returns time-series or snapshot data for a specific futures chart. The response shape varies by chart type but always includes `chart`, `coin`, `timeframe`, and a `data` array. A `coverage` object indicates the earliest available data point and which timeframes have sufficient history.

### Query parameters

**chart** `string` *required*

The chart to fetch. One of: `perp-dislocation`, `funding-cost`, `crowding-risk`, `flow-confirmation`, `carry-curve`, `perpetual-price`, `liquidations`, `oi-stacked`, `oi-change`, `oi-daily-change`, `oi-snapshot`, `oi-volume`, `volume-snapshot`, `volume-history`, `cvd`, `long-short-ratio`, `funding-rate`, `top-trader-ls`, `returns-session`, `returns-heatmap`, `returns-hour`, `returns-day`, `annualized-basis`, `term-structure`.

**coin** `string`

Asset ticker (e.g., `BTC`, `ETH`, `SOL`). Defaults to `BTC`. Open-interest charts and overlays read every contract of the asset the ticker names, lot spellings included (`PEPE` covers `1000PEPE` and `kPEPE` contracts).

**timeframe** `string`

Lookback window. One of `1W`, `2W`, `1M`, `3M`, `6M`, `1Y`, `3Y`. Defaults to `3M`.

**exchanges** `string`

Comma-separated exchange filter (e.g., `Binance,Bybit`). When omitted, all exchanges with data for the selected chart are included. A venue the chart does not carry is rejected with `400 invalid_parameter`, and the message names the venue and lists the exchanges the chart supports: the filter accepts only venues that publish the chart's metric. Bitget, Gate.io, KuCoin, MEXC and HTX are accepted on `funding-rate`, `funding-cost`, `crowding-risk`, `perpetual-price`, `volume-snapshot`, `volume-history` and the four `returns-*` charts, and refused everywhere else (checked against the live API on 2026-10-12). Supported venues by chart: `oi-stacked`, `oi-change`, `oi-daily-change`, `oi-snapshot` and `oi-volume` take Binance, Bybit, OKX, Deribit and Hyperliquid; `carry-curve`, `perp-dislocation`, `annualized-basis` and `term-structure` take Binance, Bybit, OKX and Deribit; `liquidations` takes Binance, Bybit and Deribit (OKX is refused); `long-short-ratio` takes Binance, Bybit and OKX; `top-trader-ls` takes Binance and OKX; `cvd` and `flow-confirmation` take Binance only. `oi-stacked` serves many more venues than the ten listed above when no filter is given.

**limit** `integer`

Maximum rows returned for paginated chart payloads. Range 1-10000.

**cursor** `string`

Opaque pagination cursor returned by a previous response.

### Response fields

**chart** `string`

The chart ID that was requested.

**coin** `string`

The asset ticker.

**timeframe** `string`

The timeframe that was applied.

**data** `array`

Array of data points. Shape varies by chart; see the examples below.

**openInterestExcludedVenues** `array`

Open-interest charts only (`oi-stacked`, `oi-change`, `oi-daily-change`, `oi-snapshot`): `{ exchange, reason }` for each venue whose rows are shown per venue but must not be summed into a total (MEXC today).

**coverage** `object`

Contains `availableSince` (ISO timestamp or null) and `availableTimeframes` (array of valid timeframe strings). When the data is incomplete it also carries `status: "partial"` and `warnings`: a database read failed or timed out after some rows arrived, or stopped at its row cap, so the oldest rows in the window can be missing. Open-interest histories (`oi-stacked`, `oi-change`, `oi-daily-change`) above 30,000 rows are resampled per venue to 2-, 4-, 6-, 12- or 24-hour buckets (last value per venue), with a warning naming the bucket.

**source** `string`

`"supabase"`, or `"live"` when nothing is stored for the coin and chart and the rows were fetched from the venues (registered coins, windows up to 90 days). A stored series is never patched with live data: a requested venue the store lacks is named in `coverage.missingExchanges` (free route) and in the envelope's `meta.coverage.missing`.

**summary** `object`

`chart=oi-snapshot` only. The coin's open interest across venues, summed by the server from the rows it returns: `oi_total_usd` (each venue's latest reading within 6 hours, one-sided USD, whole dollars; `null` with `oi_null_reason` when no venue has one), `oi_venue_count`, `oi_as_of` (the oldest reading inside the total) and `oi_excluded_venues` (`{ exchange, reason }` for venues with a reading that are left out, MEXC today).

A database read that fails before returning any row answers `503` with `Retry-After` rather than an empty dataset, so an empty `data` array means the window genuinely has no rows. A read that fails part-way returns the rows it has, with `coverage.status: "partial"` and an `X-Data-Partial` response header naming the affected tables; the free route also stops edge caching for that response.

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/futures/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d chart=oi-stacked \
  -d coin=BTC \
  -d timeframe=1M
```

```ts TypeScript theme={null}
const params = new URLSearchParams({
  chart: 'oi-stacked',
  coin: 'BTC',
  timeframe: '1M',
})
const res = await fetch(
  `https://www.sharpe.ai/api/v1/futures/data?${params}`,
  {
    headers: {
      Authorization: 'Bearer sk_live_your_key_here',
    },
  },
)
const { data } = await res.json()
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://www.sharpe.ai/api/v1/futures/data",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    params={
        "chart": "oi-stacked",
        "coin": "BTC",
        "timeframe": "1M",
    },
)
data = resp.json()["data"]
```

```json title="Response (oi-stacked)" theme={null}
{
  "data": {
    "chart": "oi-stacked",
    "coin": "BTC",
    "timeframe": "1M",
    "data": [
      {
        "exchange": "Binance",
        "base_coin": "BTC",
        "open_interest_value": 8234567890,
        "timestamp": "2026-03-01T00:00:00Z"
      },
      {
        "exchange": "Bybit",
        "base_coin": "BTC",
        "open_interest_value": 3456789012,
        "timestamp": "2026-03-01T00:00:00Z"
      }
    ],
    "coverage": {
      "availableSince": "2024-06-15T00:00:00Z",
      "availableTimeframes": ["1W", "2W", "1M", "3M", "6M", "1Y"]
    },
    "source": "supabase"
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-03-28T12:00:00Z",
    "elapsed_ms": 12
  }
}
```

```bash title="cURL (exchange the chart does not carry)" theme={null}
curl -G https://www.sharpe.ai/api/v1/futures/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d chart=oi-stacked \
  -d coin=BTC \
  -d exchanges=Bitget
```

```json title="Error body (400)" theme={null}
{
  "type": "https://www.sharpe.ai/errors/invalid_parameter",
  "title": "Invalid Parameter",
  "status": 400,
  "detail": "Invalid ?exchanges= parameter: Bitget is not available for chart oi-stacked (supported for chart oi-stacked: Binance, Bybit, OKX, Deribit, Hyperliquid)",
  "request_id": "req_880d492a425f4f6bb26a",
  "doc_url": "https://www.sharpe.ai/docs/errors#error-codes",
  "suggested_action": "Check the parameter value against the endpoint documentation. Use GET /v1/futures/coins or GET /v1/meta/coverage to discover valid values."
}
```

```bash title="cURL (funding-rate accepts Bitget)" theme={null}
curl -G https://www.sharpe.ai/api/v1/futures/data \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d chart=funding-rate \
  -d coin=BTC \
  -d timeframe=1W \
  -d exchanges=Bitget
```

***

## Chart data shapes

Different `chart` values return rows with different columns. Here are the key shapes:

### Open interest charts

Charts: `oi-stacked`, `oi-change`, `oi-daily-change`, `oi-snapshot`.

**exchange** `string`

Exchange name (e.g., `Binance`, `Bybit`).

**base\_coin** `string`

The requested coin. Each row is one venue's open interest for the hour: the sum of the perpetual contracts the venue holds throughout the requested window (for example Binance BTCUSDT plus the coin-margined BTCUSD\_PERP). A contract whose stored history starts or stops inside the window is left out of the whole window, so a venue's series never steps on coverage; a 3M history can therefore sum fewer contracts than a 1M one. `oi-snapshot` reads the last 24 hours on every timeframe, so it sums the contracts the venue holds now.

**open\_interest\_value** `number`

One-sided open interest in USD: each contract counted once, however the venue publishes it (Bybit, Gate.io, Bitget, Pacifica, Backpack, ApeX and Extended publish both sides and are read through their own one-sided field or halved, so they read about half the two-sided figure some aggregators show). The terminal's `oi-stacked` chart sums the venues outside its picker into one Other band.

**timestamp** `string`

ISO 8601 timestamp.

### OHLCV charts

Charts: `perpetual-price`, `volume-snapshot`, `volume-history`, `oi-volume`, `cvd`, `returns-session`, `returns-heatmap`, `returns-hour`, `returns-day`.

`cvd` carries candle rows, not a precomputed delta. Compute CVD per exchange as the running sum of `(2 * taker_buy_volume - volume) * close` over rows that have a taker volume.

**exchange** `string`

Exchange name.

**base\_coin** `string`

Asset ticker (e.g., `BTC`, `ETH`).

**timeframe** `string`

Candle interval used for this row (e.g., `1h`, `4h`, `1d`).

**open** `number`

Open price.

**high** `number`

High price.

**low** `number`

Low price.

**close** `number`

Close price.

**volume** `number`

Volume in base currency.

**timestamp** `string`

ISO 8601 timestamp.

### Funding rate

Chart: `funding-rate`.

**exchange** `string`

Exchange name.

**base\_coin** `string`

The base asset ticker (e.g., `BTC`, `ETH`).

**rate** `number`

Funding rate as a decimal.

**interval\_hours** `number | null`

Hours this settlement covered: the gap to the venue's previous settlement when it reads as a funding cadence, else the venue's stored interval. `null` when neither is readable -- never assumed to be 8.

**settled\_at** `string`

ISO 8601 settlement timestamp.

### Long/short ratio

Charts: `long-short-ratio`, `top-trader-ls`.

**exchange** `string`

Exchange name. For `top-trader-ls`, suffixed with `_top_trader`.

**base\_coin** `string`

The base asset ticker (e.g., `BTC`, `ETH`).

**long\_ratio** `number`

Fraction of accounts long (0-1).

**short\_ratio** `number`

Fraction of accounts short (0-1).

**timestamp** `string`

ISO 8601 timestamp.

### 3-month basis

Chart: `annualized-basis`. Returns the dated futures contract closest to 90 days from expiry for each exchange and snapshot.

**exchange** `string`

Exchange name.

**base\_coin** `string`

The base asset ticker (e.g., `BTC`, `ETH`).

**contract\_symbol** `string`

Dated futures contract identifier.

**days\_to\_expiry** `number`

Days from the snapshot to contract expiry.

**basis\_apr** `number`

The contract's basis annualized over `days_to_expiry`, a fraction per year (`0.0604` is 6.04%).

**timestamp** `string`

ISO 8601 snapshot timestamp.

### Term structure

Chart: `term-structure`. Returns each venue's latest snapshot from the last 7 days, one point per venue and expiry: dated contracts only, of any cycle (monthlies as well as quarterlies), at least 14 days to expiry, with |annualized basis| no more than 100%. Where two contracts share an expiry on one venue, the one with the higher 24h volume is kept.

**exchange** `string`

Exchange name.

**base\_coin** `string`

Asset ticker (e.g., `BTC`, `ETH`).

**contract\_symbol** `string`

Contract identifier (e.g., `BTC-260626`).

**expiry\_date** `string`

Expiry date.

**days\_to\_expiry** `number`

Days until contract expiry.

**futures\_price** `number`

Futures contract price.

**spot\_price** `number`

Current spot price.

**basis\_rate** `number | null`

The contract's basis to expiry (futures over spot, minus 1), a fraction (`0.0149` is 1.49%). `null` on Velo's synthetic 3-month rows (`contract_symbol` ending in `-VELO-3M-BASIS`), which store an annualized figure in its place.

**basis\_apr** `number`

`basis_rate` × 365 / `days_to_expiry`, a fraction per year (`0.0604` is 6.04%).

**volume\_24h\_usd** `number`

24-hour volume in USD.

**open\_interest\_usd** `number | null`

One-sided open interest in USD (each contract counted once). `null`
when the venue publishes no open interest for the contract, never `0`.

**snapshot\_at** `string`

ISO 8601 snapshot timestamp.

### Liquidations

Chart: `liquidations`.

**exchange** `string`

Exchange name: Binance, Bybit or Deribit. Binance and Bybit come from our own capture of their liquidation streams, Deribit from Velo. OKX is not served: its series is a delayed, partial sample of OKX's liquidations, not their total.

**base\_coin** `string`

The base asset ticker (e.g., `BTC`, `ETH`).

**side** `string`

`"long"` or `"short"`.

**quantity** `number`

Liquidated USD notional. The ingestion boundary converts venue-native base quantity to USD before persistence.

**price** `number`

Liquidation price.

**timestamp** `string`

ISO 8601 timestamp.

```json title="Response (funding-rate)" theme={null}
{
  "data": {
    "chart": "funding-rate",
    "coin": "ETH",
    "timeframe": "1W",
    "data": [
      {
        "exchange": "Binance",
        "base_coin": "ETH",
        "rate": 0.0001,
        "interval_hours": 8,
        "settled_at": "2026-03-21T00:00:00Z"
      },
      {
        "exchange": "Bybit",
        "base_coin": "ETH",
        "rate": 0.00008,
        "interval_hours": 8,
        "settled_at": "2026-03-21T00:00:00Z"
      }
    ],
    "coverage": {
      "availableSince": "2024-01-01T00:00:00Z",
      "availableTimeframes": ["1W", "2W", "1M", "3M", "6M", "1Y", "3Y"]
    },
    "source": "supabase"
  },
  "meta": {
    "request_id": "req_def456ghi789jklm",
    "timestamp": "2026-03-28T12:00:00Z",
    "elapsed_ms": 12
  }
}
```

```json title="Response (term-structure)" theme={null}
{
  "data": {
    "chart": "term-structure",
    "coin": "BTC",
    "timeframe": "3M",
    "data": [
      {
        "exchange": "Binance",
        "base_coin": "BTC",
        "contract_symbol": "BTC-260626",
        "expiry_date": "2026-06-26",
        "days_to_expiry": 90,
        "futures_price": 88500,
        "spot_price": 87200,
        "basis_rate": 0.0149,
        "basis_apr": 0.0604,
        "volume_24h_usd": 245000000,
        "open_interest_usd": 1890000000,
        "snapshot_at": "2026-03-28T11:55:00Z"
      }
    ],
    "coverage": {
      "availableSince": "2025-09-01T00:00:00Z",
      "availableTimeframes": ["1W", "2W", "1M", "3M", "6M"]
    },
    "source": "supabase"
  },
  "meta": {
    "request_id": "req_ghi789jkl012mnop",
    "timestamp": "2026-03-28T12:00:00Z",
    "elapsed_ms": 12
  }
}
```

***

## List available coins

`GET /v1/futures/coins`

Returns the list of coins with futures data, ordered by market cap rank. Each coin indicates which chart categories have data available. Use this to populate coin selectors and conditionally enable chart types in your UI.

### Response fields

**coins** `array`

Array of coin objects.

**coins\[].baseCoin** `string`

Asset ticker (e.g., `BTC`, `ETH`).

**coins\[].displayName** `string`

Display name for the coin.

**coins\[].hasOI** `boolean`

Whether open interest data is available.

**coins\[].hasLiquidations** `boolean`

Whether liquidation data is available.

**coins\[].hasLongShort** `boolean`

Whether long/short ratio data is available.

**coins\[].hasFunding** `boolean`

Whether funding-rate data is available.

**coins\[].hasCVD** `boolean`

Whether taker buy/sell volume is available for cumulative volume delta.

**coins\[].hasBasis** `boolean`

Whether dated-futures basis data is available.

**coins\[].venueCount** `integer`

Number of venues listing the coin in the discovery table.

**coins\[].venues** `array`

Venue names observed for the coin.

**coins\[].marketCapRank** `integer | null`

Market-cap rank when available.

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/futures/coins \
  -H "Authorization: Bearer sk_live_your_key_here"
```

```ts TypeScript theme={null}
const res = await fetch(
  'https://www.sharpe.ai/api/v1/futures/coins',
  {
    headers: {
      Authorization: 'Bearer sk_live_your_key_here',
    },
  },
)
const { data } = await res.json()
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://www.sharpe.ai/api/v1/futures/coins",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
)
data = resp.json()["data"]
```

```json Response theme={null}
{
  "data": {
    "coins": [
      {
        "baseCoin": "BTC",
        "displayName": "BTC",
        "hasOI": true,
        "hasFunding": true,
        "hasLiquidations": true,
        "hasLongShort": true,
        "hasCVD": true,
        "hasBasis": true,
        "venueCount": 5,
        "venues": ["Binance", "Bybit", "OKX", "Deribit", "Hyperliquid"],
        "marketCapRank": 1
      },
      {
        "baseCoin": "ETH",
        "displayName": "ETH",
        "hasOI": true,
        "hasFunding": true,
        "hasLiquidations": true,
        "hasLongShort": true,
        "hasCVD": true,
        "hasBasis": true,
        "venueCount": 5,
        "venues": ["Binance", "Bybit", "OKX", "Deribit", "Hyperliquid"],
        "marketCapRank": 2
      },
      {
        "baseCoin": "SOL",
        "displayName": "SOL",
        "hasOI": true,
        "hasFunding": true,
        "hasLiquidations": false,
        "hasLongShort": false,
        "hasCVD": true,
        "hasBasis": false,
        "venueCount": 4,
        "venues": ["Binance", "Bybit", "OKX", "Hyperliquid"],
        "marketCapRank": 5
      }
    ]
  },
  "meta": {
    "request_id": "req_jkl012mno345pqrs",
    "timestamp": "2026-03-28T12:00:00Z",
    "elapsed_ms": 12
  }
}
```

***

[Read the error reference](https://docs.sharpe.ai/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.