Futures API

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.

GET/v1/market/derivatives-overview

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.

Request

GET

/v1/market/derivatives-overview

curl https://www.sharpe.ai/api/v1/market/derivatives-overview \
  -H "Authorization: Bearer sk_live_your_key_here"

GET/v1/futures/data

Get 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

Name
chart
Type
string
Description
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.
Name
coin
Type
string
Description
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).
Name
timeframe
Type
string
Description
Lookback window. One of 1W, 2W, 1M, 3M, 6M, 1Y, 3Y. Defaults to 3M.
Name
exchanges
Type
string
Description
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.
Name
limit
Type
integer
Description
Maximum rows returned for paginated chart payloads. Range 1-10000.
Name
cursor
Type
string
Description
Opaque pagination cursor returned by a previous response.

Response fields

Name
chart
Type
string
Description
The chart ID that was requested.
Name
coin
Type
string
Description
The asset ticker.
Name
timeframe
Type
string
Description
The timeframe that was applied.
Name
data
Type
array
Description
Array of data points. Shape varies by chart; see the examples below.
Name
openInterestExcludedVenues
Type
array
Description
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).
Name
coverage
Type
object
Description
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.
Name
source
Type
string
Description
"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.
Name
summary
Type
object
Description
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.

Request

GET

/v1/futures/data

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

Response (oi-stacked)

{
  "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
  }
}

cURL (exchange the chart does not carry)

curl -G https://www.sharpe.ai/api/futures/data \
  -d chart=oi-stacked \
  -d coin=BTC \
  -d exchanges=Bitget

Error body (400)

{
  "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.",
  "error": "Invalid ?exchanges= parameter: Bitget is not available for chart oi-stacked (supported for chart oi-stacked: Binance, Bybit, OKX, Deribit, Hyperliquid)"
}

cURL (funding-rate accepts Bitget)

curl -G https://www.sharpe.ai/api/futures/data \
  -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.

Name
exchange
Type
string
Description
Exchange name (e.g., Binance, Bybit).
Name
base_coin
Type
string
Description
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.
Name
open_interest_value
Type
number
Description
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.
Name
timestamp
Type
string
Description
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. /api/futures/data?chart=cvd also includes open-interest overlay rows (open_interest_value, no close) used to normalise CVD by open interest; tell them apart by close. They are not CVD values.

Name
exchange
Type
string
Description
Exchange name.
Name
base_coin
Type
string
Description
Asset ticker (e.g., BTC, ETH).
Name
timeframe
Type
string
Description
Candle interval used for this row (e.g., 1h, 4h, 1d).
Name
open
Type
number
Description
Open price.
Name
high
Type
number
Description
High price.
Name
low
Type
number
Description
Low price.
Name
close
Type
number
Description
Close price.
Name
volume
Type
number
Description
Volume in base currency.
Name
volume_usd
Type
number
Description
Free route /api/futures/data only, optional. When a payload above 1,500 rows is aggregated into time buckets per venue (1 hour when the rows span under 7 days, 4 hours under 30 days, else 1 day), the USD volume of each aggregated candle: every source candle's volume × close, summed. Use it instead of volume × close, which prices the whole bucket at its last close. null when no candle in the bucket had a positive volume and close; absent on unaggregated rows.
Name
timestamp
Type
string
Description
ISO 8601 timestamp.

Funding rate

Chart: funding-rate.

Name
exchange
Type
string
Description
Exchange name.
Name
base_coin
Type
string
Description
The base asset ticker (e.g., BTC, ETH).
Name
rate
Type
number
Description
Funding rate as a decimal.
Name
interval_hours
Type
number | null
Description
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.
Name
settled_at
Type
string
Description
ISO 8601 settlement timestamp.

Long/short ratio

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

Name
exchange
Type
string
Description
Exchange name. For top-trader-ls, suffixed with _top_trader.
Name
base_coin
Type
string
Description
The base asset ticker (e.g., BTC, ETH).
Name
long_ratio
Type
number
Description
Fraction of accounts long (0-1).
Name
short_ratio
Type
number
Description
Fraction of accounts short (0-1).
Name
timestamp
Type
string
Description
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.

Name
exchange
Type
string
Description
Exchange name.
Name
base_coin
Type
string
Description
The base asset ticker (e.g., BTC, ETH).
Name
contract_symbol
Type
string
Description
Dated futures contract identifier.
Name
days_to_expiry
Type
number
Description
Days from the snapshot to contract expiry.
Name
annualized_basis_pct
Type
number
Description
Annualized basis in percent.
Name
timestamp
Type
string
Description
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.

Name
exchange
Type
string
Description
Exchange name.
Name
base_coin
Type
string
Description
Asset ticker (e.g., BTC, ETH).
Name
contract_symbol
Type
string
Description
Contract identifier (e.g., BTC-260626).
Name
expiry_date
Type
string
Description
Expiry date.
Name
days_to_expiry
Type
number
Description
Days until contract expiry.
Name
futures_price
Type
number
Description
Futures contract price.
Name
spot_price
Type
number
Description
Current spot price.
Name
basis_pct
Type
number
Description
Basis as a percentage (futures price vs spot price).
Name
annualized_basis_pct
Type
number
Description
Annualized basis percentage.
Name
volume_24h_usd
Type
number
Description
24-hour volume in USD.
Name
open_interest_usd
Type
number | null
Description
One-sided open interest in USD (each contract counted once). null when the venue publishes no open interest for the contract, never 0.
Name
snapshot_at
Type
string
Description
ISO 8601 snapshot timestamp.

Liquidations

Chart: liquidations.

Name
exchange
Type
string
Description
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.
Name
base_coin
Type
string
Description
The base asset ticker (e.g., BTC, ETH).
Name
side
Type
string
Description
"long" or "short".
Name
quantity
Type
number
Description
Liquidated USD notional. The ingestion boundary converts venue-native base quantity to USD before persistence.
Name
price
Type
number
Description
Liquidation price.
Name
timestamp
Type
string
Description
ISO 8601 timestamp.

Response (funding-rate)

{
  "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
  }
}

Response (term-structure)

{
  "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_pct": 1.49,
        "annualized_basis_pct": 6.04,
        "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
  }
}

GET/v1/futures/coins

List available 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

Name
coins
Type
array
Description
Array of coin objects.
Name
coins[].baseCoin
Type
string
Description
Asset ticker (e.g., BTC, ETH).
Name
coins[].displayName
Type
string
Description
Display name for the coin.
Name
coins[].hasOI
Type
boolean
Description
Whether open interest data is available.
Name
coins[].hasLiquidations
Type
boolean
Description
Whether liquidation data is available.
Name
coins[].hasLongShort
Type
boolean
Description
Whether long/short ratio data is available.
Name
coins[].hasFunding
Type
boolean
Description
Whether funding-rate data is available.
Name
coins[].hasCVD
Type
boolean
Description
Whether taker buy/sell volume is available for cumulative volume delta.
Name
coins[].hasBasis
Type
boolean
Description
Whether dated-futures basis data is available.
Name
coins[].venueCount
Type
integer
Description
Number of venues listing the coin in the discovery table.
Name
coins[].venues
Type
array
Description
Venue names observed for the coin.
Name
coins[].marketCapRank
Type
integer | null
Description
Market-cap rank when available.

Request

GET

/v1/futures/coins

curl -G https://www.sharpe.ai/api/v1/futures/coins \
  -H "Authorization: Bearer sk_live_your_key_here"

Response

{
  "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