Futures

The futures endpoints provide granular derivatives data across 19 chart types and 10 exchanges (Binance, Bybit, OKX, Deribit, Hyperliquid by default; Bitget, Gate.io, KuCoin, MEXC, HTX available via the exchanges filter). Query open interest, liquidations, volume profiles, funding rates, long/short ratios, 3-month basis, and term structure with configurable timeframes and exchange filters.

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: 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.
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.

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 examples below.
Name
coverage
Type
object
Description
Contains availableSince (ISO timestamp or null) and availableTimeframes (array of valid timeframe strings).
Name
source
Type
string
Description
Always "supabase".

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

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

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
Asset ticker.
Name
open_interest_value
Type
number
Description
Open interest in USD.
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.

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
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
Description
Hours between settlements.
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 the latest snapshot across expiries.

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
Description
Open interest in USD.
Name
snapshot_at
Type
string
Description
ISO 8601 snapshot timestamp.

Liquidations

Chart: liquidations.

Name
exchange
Type
string
Description
Exchange name.
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 quantity in base currency.
Name
price
Type
number
Description
Liquidation price.
Name
timestamp
Type
string
Description
ISO 8601 timestamp.

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

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

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.

Request

GET

/v1/futures/coins

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

{
  "data": {
    "coins": [
      {
        "baseCoin": "BTC",
        "displayName": "BTC",
        "hasOI": true,
        "hasLiquidations": true,
        "hasLongShort": true
      },
      {
        "baseCoin": "ETH",
        "displayName": "ETH",
        "hasOI": true,
        "hasLiquidations": true,
        "hasLongShort": true
      },
      {
        "baseCoin": "SOL",
        "displayName": "SOL",
        "hasOI": true,
        "hasLiquidations": false,
        "hasLongShort": false
      }
    ]
  },
  "meta": {
    "request_id": "req_jkl012mno345pqrs",
    "timestamp": "2026-03-28T12:00:00Z"
  }
}

Read the error reference