Datasets · Trades
Flow Metrics
Directional order flow split by taker buy vs. sell, broken into small/medium/large notional segments, with a flow toxicity score. The same rows over both transports, under the same names.
History over RESTREST
- Endpoint
GET /api/v1/data/flow- Returns
- Parquet files for a date range
- Plan
- Pro and above
Live over WebSocketWebSocket
- Channel
flow.<exchange>.<interval>- Sends
- Each row as its bar closes
- Plan
- Pro and above; 15s and 30s on Institutional
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
36 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 |
|---|---|---|
taker_buy_volume | Taker Buy Volume | Total buy-side traded notional in the interval |
taker_sell_volume | Taker Sell Volume | Total sell-side traded notional in the interval |
taker_buy_count | Taker Buy Count | Number of buy-side trades in the interval |
taker_sell_count | Taker Sell Count | Number of sell-side trades in the interval |
volume_delta | Volume Delta | Buy-side traded quantity minus sell-side traded quantity |
volume_delta_notional | Volume Delta Notional | Buy-side traded notional minus sell-side traded notional |
flow_entropy | Flow Entropy | Entropy of the buy-versus-sell notional split in the interval |
flow_toxicity_score | Flow Toxicity Score | Past-normalized signed notional flow multiplied by past-normalized short-horizon realized volatility |
taker_buy_sell_ratio | Buy/Sell Ratio | Buy-side traded notional divided by sell-side traded notional |
taker_buy_sell_count_ratio | Buy/Sell Count Ratio | Buy-side trade count divided by sell-side trade count |
taker_buy_sell_percentage | Taker Buy % | Share of traded notional that came from buy-side trades |
taker_buy_sell_count_percentage | Taker Buy Count % | Share of trades that were buy-side trades |
taker_buy_small_order_volume | Buy Small Order Volume | Total buy-side notional from small trades under $100 |
taker_buy_small_order_count | Buy Small Order Count | Number of buy-side trades under $100 |
taker_buy_medium_order_volume | Buy Medium Order Volume | Total buy-side notional from medium trades from $100 to under $1,000 |
taker_buy_medium_order_count | Buy Medium Order Count | Number of buy-side trades from $100 to under $1,000 |
taker_buy_large_order_volume | Buy Large Order Volume | Total buy-side notional from large trades of at least $1,000 |
taker_buy_large_order_count | Buy Large Order Count | Number of buy-side trades of at least $1,000 |
taker_sell_small_order_volume | Sell Small Order Volume | Total sell-side notional from small trades under $100 |
taker_sell_small_order_count | Sell Small Order Count | Number of sell-side trades under $100 |
taker_sell_medium_order_volume | Sell Medium Order Volume | Total sell-side notional from medium trades from $100 to under $1,000 |
taker_sell_medium_order_count | Sell Medium Order Count | Number of sell-side trades from $100 to under $1,000 |
taker_sell_large_order_volume | Sell Large Order Volume | Total sell-side notional from large trades of at least $1,000 |
taker_sell_large_order_count | Sell Large Order Count | Number of sell-side trades of at least $1,000 |
taker_buy_small_order_percentage | Buy Small Order % | Ratio of small buy-side trade notional to total buy-side traded notional |
taker_buy_medium_order_percentage | Buy Medium Order % | Ratio of medium buy-side trade notional to total buy-side traded notional |
taker_buy_large_order_percentage | Buy Large Order % | Ratio of large buy-side trade notional to total buy-side traded notional |
taker_buy_small_order_count_percentage | Buy Small Count % | Share of buy-side trades that were small trades |
taker_buy_medium_order_count_percentage | Buy Medium Count % | Share of buy-side trades that were medium trades |
taker_buy_large_order_count_percentage | Buy Large Count % | Share of buy-side trades that were large trades |
taker_sell_small_order_percentage | Sell Small Order % | Ratio of small sell-side trade notional to total sell-side traded notional |
taker_sell_medium_order_percentage | Sell Medium Order % | Ratio of medium sell-side trade notional to total sell-side traded notional |
taker_sell_large_order_percentage | Sell Large Order % | Ratio of large sell-side trade notional to total sell-side traded notional |
taker_sell_small_order_count_percentage | Sell Small Count % | Share of sell-side trades that were small trades |
taker_sell_medium_order_count_percentage | Sell Medium Count % | Share of sell-side trades that were medium trades |
taker_sell_large_order_count_percentage | Sell Large Count % | Share of sell-side trades that were large trades |
History over REST
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 flow --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/flow
Parameters
| 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. |
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.
Suggestions shown — any valid value accepted
Suggestions shown — any valid value accepted
Suggestions shown — any valid value accepted
Authentication
GET
/api/v1/data/preview/flow?timestamp=exchange&interval=5m&exchange=binance-futures&symbol=perpetual-BTC-USDT%3AUSDT&start_date=2025-05-01&end_date=2025-05-31Response will appear here
Live over WebSocket
Subscribe to flow.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]"import os
from aperiodic import stream
for message in stream(
api_key=os.environ["APERIODIC_API_KEY"],
dataset="flow",
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":"flow.binance-futures.1m","data":{"time":…,"taker_buy_volume":…,"taker_sell_volume":…,…}}Your key is on Live Streams once you are on a plan that streams.