Positioning
History over RESTREST
- Endpoint
GET /api/v1/data/positioning- Returns
- Parquet files for a date range
- Plan
- Prime and above
Live over WebSocketWebSocket
- Channel
positioning.<exchange>.<interval>- Sends
- Each row as its bar closes
- Plan
- Prime and above
Exchanges: binance-futures, okx-perps, hyperliquid-perps · Intervals: 15m 30m 1h 4h 1d · Chart, sample rows and coverage in the catalog
Fields
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 |
|---|---|---|
open_interest_divergence | Open Interest Divergence | The open interest build (log open interest in contracts minus its 12-hour time-decayed mean, in units of that gap's 7-day root mean square, both over the bars before) left after removing what the same build on mark price explains (a 7-day time-decayed beta, both clipped at ±3), in units of its own 7-day root mean square. Positions building (above 0) or unwinding (below 0) beyond what price explains; uncorrelated with price |
leverage_index | Leverage Index | Open interest notional divided by the 7-day time-decayed mean of daily taker notional, over the days before the bar's day. Open interest per dollar a day trades |
crowding | Crowding | 1e4 × 1-day time-decayed funding rate × max(0, 100 × (log open interest − its 3.5-day time-decayed mean)). Funding, in bps per venue funding period, paid on positions being added; 0 while positions shrink |
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 positioning --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/positioning
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 | 15m30m1h4h1d | 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. Crypto and real-world asset (RWA) perpetuals share it: `perpetual-BTC-USDT:USDT`, `perpetual-TSLA-USDT:USDT` for a tokenized stock on Binance or OKX, and `perpetual-XYZ:TSLA-USDC:USDC` for a Hyperliquid HIP-3 market, its dex before the colon. /metadata/symbols lists a venue's symbols with their asset classes. |
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
{
"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.
/api/v1/data/preview/positioning?timestamp=exchange&interval=5m&exchange=binance-futures&symbol=perpetual-BTC-USDT%3AUSDT&start_date=2025-05-01&end_date=2025-05-31Live over WebSocket
Subscribe to positioning.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
- 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="positioning",
exchange="binance-futures",
interval="15m",
symbols=["perpetual-BTC-USDT:USDT"], # omit for every symbol on your plan
):
print(message.channel, message.snapshot, message.data){"channel":"positioning.binance-futures.1m","data":{"time":…,"open_interest_divergence":…,"leverage_index":…,…}}Your key is on Live Streams once you are on a plan that streams.