dexdataSign in

Perpetuals API

One venue derivatives instrument's basis against spot over time

Futures or perpetual price minus the same venue's spot price, in the quote currency and as a percent, for one instrument on one venue, 1m to 1w per bucket, oldest first.

GET/api/external/perps/derivatives-basis-history/{symbol}
Get a free API keyTry it in the API reference

What it returns

The basis of one derivatives instrument on one venue — its price minus the same venue's spot price for the coin, at the close of each bucket — oldest first, in the quote currency and as a percentage of the instrument price. Positive means the instrument traded above spot (contango, or a premium on a perpetual); negative, below. The spot price is the venue's own spot pair for the coin, which can be quoted in a dollar stablecoin against a US-dollar instrument (e.g. XBT/USDT for PF_XBTUSD on Kraken), and the basis then also carries the stablecoin's own gap to the dollar. The newest bucket is normally the one still in progress when the figures were read (complete: false). symbol is the venue's instrument id, spelled exactly as listed (case-sensitive) — take venue and instrument from a derivatives-coin-venues row. Dated futures answer too, by the venue's own id (e.g. "BTCUSDT_261225" on Binance), though derivatives-coin-venues lists perpetuals only. Seven venues answer: Binance, OKX, Bybit, Gate, Bitget, Kraken and Crypto.com. An instrument the venue does not list in that spelling, or has no basis for, answers 404.

Chains

This endpoint is not tied to a chain: it takes no chain in its request.

Request

Send your key in the x-dex-data-key header. Replace each <placeholder> with a real value.

curl -H "x-dex-data-key: $DEXDATA_API_KEY" \
  "https://api.dexdata.io/api/external/perps/derivatives-basis-history/<symbol>?venue=Binance"
Parameters
ParameterDescription
venue

query · string · required

The trading venue, spelled exactly as listed (case-sensitive), as derivatives-coin-venues names it.BinanceOKXBybitGateBitgetKrakenCrypto.com
interval

query · string · optional

Bucket width. Defaults to one day.1m3m5m15m30m1h4h6h8h12h1d1w
limit

query · integer · optional

How many of the most recent buckets to return, 1 to 1000. Defaults to 100. Fewer come back when the instrument's or the spot pair's history is shorter, or a bucket carries no figure. limit ≤ 450 keeps the answer under 32 KB.
symbol

path · string · required

The venue's own instrument id, exactly as instrument in derivatives-coin-venues rows, case included: e.g. "BTCUSDT" (Binance, Bybit), "BTC-USDT-SWAP" (OKX), "BTC_USDT" (Gate), "PF_XBTUSD" (Kraken) — not a bare coin ticker such as "BTC", and not a token mint or contract address. Case-sensitive.

Response fields

A JSON response. Every field is always present; null means the value could not be established, never zero.

Response fields of One venue derivatives instrument's basis against spot over time
FieldTypeDescription
venuestringThe trading venue.
instrumentstringThe instrument id, exactly as asked.
intervalstringThe bucket width.
pointsobject[]Oldest first.
points[].atnumberThe bucket's open, unix seconds.
points[].basisnumber | nullInstrument price minus the venue's spot price at the bucket's close — for the bucket in progress, the latest — in the quote currency. null when not stated.
points[].basisPctnumber | nullbasis as a percentage of the instrument price (0.05 = 0.05%). null when not stated.
points[].completebooleanWhether the figures are final. false only on the newest bucket, which was still in progress when its figures were read.

Start building with DexData today

Sign in, create a key and make your first call in a minute. Free credits every month, and you only pay for calls that succeed.

Get a free API key