Get started
API Documentation
Point-in-time market microstructure metrics over one API key: pull history as Parquet files over REST, or stream every new row over WebSocket. Every dataset has both, under the same name and with the same fields.
- History · REST
- /api/v1
- Live · WebSocket
- wss://stream.aperiodic.io/v1/stream
- Auth
- X-API-KEY header
- Version
- 1.6.1
Authentication
One key for both. Send it in the X-API-KEY header on every REST request and on the WebSocket handshake. Browsers can't set headers on a WebSocket, so stream from a server, a notebook or a script.
Sign up to get your key. Until then, the free preview answers to the shared DEMO-KEY, which the examples below use.
Quickstart
A month of candles over REST, then the same candles live as each bar closes. The history call runs as it is, on the free preview.
History over REST
# 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 ohlcv --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"Live over WebSocket
pip install "aperiodic[stream]"import os
from aperiodic import stream
for message in stream(
api_key=os.environ["APERIODIC_API_KEY"],
dataset="ohlcv",
exchange="binance-futures",
interval="1m",
symbols=["perpetual-BTC-USDT:USDT"], # omit for every symbol on your plan
):
print(message.channel, message.snapshot, message.data)Next: parameters, files and errors for history, and connecting, replay and limits for the live feed.
Datasets
Each dataset's page has its fields, its REST endpoint with a Try it panel, and its live channel.
Trades
- Flow MetricsDirectional order flow split by taker buy vs. sell, broken into small/medium/large notional segments, with a flow toxicity score.
flow - Trade SizeTrade notional split into small (< $100), medium ($100–$1,000), and large (≥ $1,000) segments, with summary statistics for individual trade sizes.
trade_size - Price Range & DistributionIntrabar high-low price range and full distribution statistics (mean, median, std, skewness, kurtosis) for trade prices within each interval.
range - Impact MetricsHow much each unit of trading volume moves the price, measured via Amihud illiquidity, Kyle lambda, impact per notional, and large-trade reversal.
impact - Up / Down Tick MetricsUptick and downtick count, volume, ratios and percentages based on price movement direction.
updownticks - Trade Run StructureConsecutive same-direction trade run lengths, imbalance, flip rate, and price change on direction flip.
run_structure - Returns & VolatilityLog-return based metrics: variance, realized volatility, bipower variation, jump ratio, autocorrelation, and trendiness.
returns - SlippageHow much each trade pays above the best ask (buys) or receives below the best bid (sells) relative to the prevailing quote, aggregated per interval.
slippage
Derivatives
- BasisPerpetual futures mark price premium over index price (basis) and last trade price, in absolute and basis-point terms.
basis - FundingFunding rate and update frequencies for perpetual futures contracts.
funding - Open InterestOpen interest values with percentage change, volatility, and OI/price change ratio.
open_interest - Derivative PriceSnapshot of mark, index, and last trade prices with interval percentage changes and pairwise divergence ratios.
derivative_price
Market Data
L1 (Top of Book)
- L1 PriceBest bid and ask prices with quantities, midprice, quantity-weighted midprice, time/volume-weighted averages, and quote update frequency.
l1_price - L1 ImbalanceBid/ask imbalance, ratio, percentages — both instantaneous (last) and averaged over the interval.
l1_imbalance - L1 LiquiditySpread (absolute and bps), depth, dollar depth — instantaneous and interval-averaged.
l1_liquidity