Datasets · Derivatives

Basis

Perpetual futures mark price premium over index price (basis) and last trade price, in absolute and basis-point terms. The same rows over both transports, under the same names.

Exchanges: binance-futures, okx-perps, hyperliquid-perps · Intervals: 1m 5m 15m 30m 1h 4h 1d · Chart, sample rows and coverage in the catalog

Fields

8 fields, plus time

Every row carries time, the interval's start in milliseconds since the Unix epoch (UTC), and these fields. They are the Parquet columns over REST and the keys of data in a live frame.

Field	Name	Description
`basis`	Basis	Last mark price minus index price in the interval
`basis_bps`	Basis (bps)	Last mark-versus-index spread in basis points of the index price
`mark_price_spread`	Mark-Price Spread	Last mark price minus last traded price in the interval
`mark_price_spread_bps`	Mark-Price Spread (bps)	Last mark-versus-last-price spread in basis points of the last price
`basis_mean`	Mean Basis	Average mark price minus index price in the interval
`basis_bps_std`	Basis Std Dev (bps)	Standard deviation of the mark-versus-index spread in basis points
`mark_price_spread_mean`	Mean Mark-Price Spread	Average mark price minus last traded price in the interval
`mark_price_spread_bps_std`	Mark-Price Spread Std Dev (bps)	Standard deviation of the mark-versus-last-price spread in basis points

History over REST

Parameters, files and errors for every dataset

One request returns download URLs for the Parquet files that cover your date range: a file per month for older history, a file per day from 2026-08-01. Request them again when they expire.

# Install the Aperiodic CLI into ~/.local/bin
mkdir -p "$HOME/.local/bin"
curl -fsSL https://raw.githubusercontent.com/aperiodic-io/cli/main/install.sh | INSTALL_DIR="$HOME/.local/bin" bash
export PATH="$HOME/.local/bin:$PATH"

# Free preview — no API key required
aperiodic basis --preview \
  --exchange binance-futures \
  --symbol perpetual-BTC-USDT:USDT \
  --interval 5m \
  --timestamp exchange \
  --start-date 2025-05-01 \
  --end-date 2025-05-31 \
  --output-dir ./data && echo "Saved to $PWD/data"

GET/api/v1/data/basis

Parameters

Parameter	Values	Meaning
`timestamp`query · required	`exchangetrue`	Timestamp source. 'exchange' uses the exchange-reported timestamp, 'true' uses actual arrival time at our servers.
`interval`query · required	`1m5m15m30m1h4h1d`	Aggregation time interval for the data.
`exchange`query · required	`binance-futuresokx-perpshyperliquid-perps`	Source exchange for the data.
`symbol`query · required	string	Trading pair symbol in the format of Atlas' universal symbology: https://github.com/aperiodic-io/atlas
`start_date`query · required	date	Start date for the data range (YYYY-MM-DD format). A metric series starts on the first day of the raw series it is computed from (see /metadata/raw); raw trades and quotes start binance-futures from 2020-01-01, okx-perps from 2019-09-01, hyperliquid-perps from 2025-01-01. Earlier days return no files. How far back you can go depends on the plan: 5 years on Pro, full history on Prime, Prime + Raw and Institutional. An earlier start_date than the plan reaches returns 403.
`end_date`query · required	date	End date for the data range (YYYY-MM-DD format). Must be greater than or equal to start_date.

Responses

200 response

{
  "files": [
    {
      "year": 2026,
      "month": 6,
      "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-06.parquet?X-Amz-Expires=300&..."
    },
    {
      "year": 2026,
      "month": 7,
      "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-07.parquet?X-Amz-Expires=300&..."
    },
    {
      "year": 2026,
      "month": 8,
      "day": 1,
      "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-08-01.parquet?X-Amz-Expires=300&..."
    },
    {
      "year": 2026,
      "month": 8,
      "day": 2,
      "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-08-02.parquet?X-Amz-Expires=300&..."
    }
  ]
}

Status	Meaning
`200`	Successful response with download URLs for every existing file covering the range from the series' published start — one per month before 2026-08-01, one per day from 2026-08-01 onwards
`400`	Bad request - missing or invalid parameters
`401`	Unauthorized - missing or invalid API key
`403`	Forbidden - the subscription does not cover this request
`404`	Unknown dataset
`500`	Server error - failed to resolve the series start or generate download URLs

Try it

Prefilled with the shared DEMO-KEY and a free preview slice — send the request to see live data, no account required.

timestamp*

interval*

exchange*

symbol*

Suggestions shown — any valid value accepted

start_date*

Suggestions shown — any valid value accepted

end_date*

Suggestions shown — any valid value accepted

Authentication

X-API-KEY*

GET

/api/v1/data/preview/basis?timestamp=exchange&interval=5m&exchange=binance-futures&symbol=perpetual-BTC-USDT%3AUSDT&start_date=2025-05-01&end_date=2025-05-31

Response will appear here

Live over WebSocket

Connecting, replay and limits for every channel

Subscribe to basis.binance-futures.1m, or any exchange and interval below, and each row arrives as its bar closes. After a reconnect, add since to the subscribe to get the bars you missed first (replay).

Exchanges: binance-futures okx-perps hyperliquid-perps
Intervals: 1m 5m 15m 30m 1h 4h 1d

pip install "aperiodic[stream]"

pypi ↗

import os

from aperiodic import stream

for message in stream(
    api_key=os.environ["APERIODIC_API_KEY"],
    dataset="basis",
    exchange="binance-futures",
    interval="1m",
    symbols=["perpetual-BTC-USDT:USDT"],  # omit for every symbol on your plan
):
    print(message.channel, message.snapshot, message.data)

Each row

{"channel":"basis.binance-futures.1m","data":{"time":…,"basis":…,"basis_bps":…,…}}

Your key is on Live Streams once you are on a plan that streams.

Field

Name

Description

basis

Basis

Last mark price minus index price in the interval

basis_bps

Basis (bps)

Last mark-versus-index spread in basis points of the index price

mark_price_spread

Mark-Price Spread

Last mark price minus last traded price in the interval

mark_price_spread_bps

Mark-Price Spread (bps)

Last mark-versus-last-price spread in basis points of the last price

basis_mean

Mean Basis

Average mark price minus index price in the interval

basis_bps_std

Basis Std Dev (bps)

Standard deviation of the mark-versus-index spread in basis points

mark_price_spread_mean

Mean Mark-Price Spread

Average mark price minus last traded price in the interval

mark_price_spread_bps_std

Mark-Price Spread Std Dev (bps)

Standard deviation of the mark-versus-last-price spread in basis points

# Install the Aperiodic CLI into ~/.local/bin mkdir -p "$HOME/.local/bin" curl -fsSL https://raw.githubusercontent.com/aperiodic-io/cli/main/install.sh | INSTALL_DIR="$HOME/.local/bin" bash export PATH="$HOME/.local/bin:$PATH" # Free preview — no API key required aperiodic basis --preview \ --exchange binance-futures \ --symbol perpetual-BTC-USDT:USDT \ --interval 5m \ --timestamp exchange \ --start-date 2025-05-01 \ --end-date 2025-05-31 \ --output-dir ./data && echo "Saved to $PWD/data"

Parameter

Values

Meaning

timestampquery · required

exchangetrue

Timestamp source. 'exchange' uses the exchange-reported timestamp, 'true' uses actual arrival time at our servers.

intervalquery · required

1m5m15m30m1h4h1d

Aggregation time interval for the data.

exchangequery · required

binance-futuresokx-perpshyperliquid-perps

Source exchange for the data.

symbolquery · required

string

Trading pair symbol in the format of Atlas' universal symbology: https://github.com/aperiodic-io/atlas

start_datequery · required

date

Start date for the data range (YYYY-MM-DD format). A metric series starts on the first day of the raw series it is computed from (see /metadata/raw); raw trades and quotes start binance-futures from 2020-01-01, okx-perps from 2019-09-01, hyperliquid-perps from 2025-01-01. Earlier days return no files. How far back you can go depends on the plan: 5 years on Pro, full history on Prime, Prime + Raw and Institutional. An earlier start_date than the plan reaches returns 403.

end_datequery · required

date

End date for the data range (YYYY-MM-DD format). Must be greater than or equal to start_date.

{ "files": [ { "year": 2026, "month": 6, "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-06.parquet?X-Amz-Expires=300&..." }, { "year": 2026, "month": 7, "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-07.parquet?X-Amz-Expires=300&..." }, { "year": 2026, "month": 8, "day": 1, "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-08-01.parquet?X-Amz-Expires=300&..." }, { "year": 2026, "month": 8, "day": 2, "url": "https://ohlcv.aperiodic.io/binance-futures/1h/BTCUSDT/2026-08-02.parquet?X-Amz-Expires=300&..." } ] }

Status

Meaning

200

Successful response with download URLs for every existing file covering the range from the series' published start — one per month before 2026-08-01, one per day from 2026-08-01 onwards

400

Bad request - missing or invalid parameters

401

Unauthorized - missing or invalid API key

403

Forbidden - the subscription does not cover this request

404

Unknown dataset

500

Server error - failed to resolve the series start or generate download URLs

import os from aperiodic import stream for message in stream( api_key=os.environ["APERIODIC_API_KEY"], dataset="basis", exchange="binance-futures", interval="1m", symbols=["perpetual-BTC-USDT:USDT"], # omit for every symbol on your plan ): print(message.channel, message.snapshot, message.data)

Basis

History over RESTREST

Live over WebSocketWebSocket

Fields

History over REST

Parameters

Responses

Try it

Live over WebSocket

Basis

History over RESTREST

Live over WebSocketWebSocket

Fields

History over REST

Parameters

Responses

Try it

Live over WebSocket