Datasets · L1 (Top of Book)

L1 Liquidity

Spread (absolute and bps), depth, dollar depth — instantaneous and interval-averaged. The same rows over both transports, under the same names.

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

Fields

14 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
`spread`	Spread	Last best ask price minus best bid price in the interval
`spread_bps`	Spread (bps)	Last bid-ask spread in basis points of the midprice
`spread_depth_ratio`	Spread/Depth Ratio	Last bid-ask spread divided by total top-of-book quantity
`total_depth`	Total Depth	Last total top-of-book quantity across bid and ask
`dollar_depth_bid`	Bid Dollar Depth	Last bid-side top-of-book notional
`dollar_depth_ask`	Ask Dollar Depth	Last ask-side top-of-book notional
`total_dollar_depth`	Total Dollar Depth	Last total top-of-book notional across bid and ask
`spread_avg`	Avg Spread	Average bid-ask spread in the interval
`spread_bps_avg`	Avg Spread (bps)	Average bid-ask spread in basis points over the interval
`spread_depth_ratio_avg`	Avg Spread/Depth Ratio	Average spread-to-depth ratio over the interval
`total_depth_avg`	Avg Total Depth	Average total top-of-book quantity across bid and ask in the interval
`dollar_depth_bid_avg`	Avg Bid Dollar Depth	Average bid-side top-of-book notional in the interval
`dollar_depth_ask_avg`	Avg Ask Dollar Depth	Average ask-side top-of-book notional in the interval
`total_dollar_depth_avg`	Avg Total Dollar Depth	Average total top-of-book notional across bid and ask in the interval

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 l1_liquidity --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/l1_liquidity

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	`15s30s1m5m15m30m1h4h1d`	Aggregation time interval for the data. Sub-minute intervals (15s, 30s) require an Institutional plan.
`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/l1_liquidity?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 l1_liquidity.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: 15s 30s 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="l1_liquidity",
    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":"l1_liquidity.binance-futures.1m","data":{"time":…,"spread":…,"spread_bps":…,…}}

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

Field

Name

Description

spread

Spread

Last best ask price minus best bid price in the interval

spread_bps

Spread (bps)

Last bid-ask spread in basis points of the midprice

spread_depth_ratio

Spread/Depth Ratio

Last bid-ask spread divided by total top-of-book quantity

total_depth

Total Depth

Last total top-of-book quantity across bid and ask

dollar_depth_bid

Bid Dollar Depth

Last bid-side top-of-book notional

dollar_depth_ask

Ask Dollar Depth

Last ask-side top-of-book notional

total_dollar_depth

Total Dollar Depth

Last total top-of-book notional across bid and ask

spread_avg

Avg Spread

Average bid-ask spread in the interval

spread_bps_avg

Avg Spread (bps)

Average bid-ask spread in basis points over the interval

spread_depth_ratio_avg

Avg Spread/Depth Ratio

Average spread-to-depth ratio over the interval

total_depth_avg

Avg Total Depth

Average total top-of-book quantity across bid and ask in the interval

dollar_depth_bid_avg

Avg Bid Dollar Depth

Average bid-side top-of-book notional in the interval

dollar_depth_ask_avg

Avg Ask Dollar Depth

Average ask-side top-of-book notional in the interval

total_dollar_depth_avg

Avg Total Dollar Depth

Average total top-of-book notional across bid and ask in the interval

# 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 l1_liquidity --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

15s30s1m5m15m30m1h4h1d

Aggregation time interval for the data. Sub-minute intervals (15s, 30s) require an Institutional plan.

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="l1_liquidity", exchange="binance-futures", interval="1m", symbols=["perpetual-BTC-USDT:USDT"], # omit for every symbol on your plan ): print(message.channel, message.snapshot, message.data)

L1 Liquidity

History over RESTREST

Live over WebSocketWebSocket

Fields

History over REST

Parameters

Responses

Try it

Live over WebSocket

L1 Liquidity

History over RESTREST

Live over WebSocketWebSocket

Fields

History over REST

Parameters

Responses

Try it

Live over WebSocket