aperiodic 4.0.0

Client library for Aperiodic aggregate market data API - OHLCV and more

Aperiodic Python Client

Python client library for Aperiodic.io — institutional-grade market microstructure, liquidity and order flow metrics with full exchange universe coverage. Turn flow dynamics into alpha in hours, not months. No tick infrastructure to build or maintain.

Access pre-computed derivative and microstructure metrics with parallel downloads for optimal performance.

Installation

pip install aperiodic

Install from source:

git clone https://github.com/aperiodic-io/aperiodic-client.git
cd aperiodic-client
pip install -e .

Authentication

All endpoints require your Aperiodic.io API key passed as api_key="...".

Symbology

Symbols are expected in Atlas unified symbology — a standardised, exchange-agnostic naming scheme.

• Atlas repo: https://github.com/aperiodic-io/atlas
• Example symbol: perpetual-BTC-USDT:USDT

Quick Start

from datetime import date
from aperiodic import get_ohlcv

df = get_ohlcv(
    api_key="your-api-key",
    timestamp="true",
    interval="1h",
    exchange="binance-futures",
    symbol="perpetual-BTC-USDT:USDT",
    start_date=date(2024, 1, 1),
    end_date=date(2024, 1, 31),
)

print(df.head())
print(df.columns)

Available Functions

Dataset	Sync	Async	metric values
Order, L1, L2 metrics	get_metrics	get_metrics_async	see below
OHLCV candles	get_ohlcv	get_ohlcv_async	—
VWAP	get_vwap	get_vwap_async	—
TWAP	get_twap	get_twap_async	—
Derivative metrics	get_derivative_metrics	get_derivative_metrics_async	see below
Exchange symbols	get_symbols	get_symbols_async	—

get_metrics — Trade & order book metrics

Trade metrics (TradeMetric): "vtwap", "flow", "trade_size", "impact", "range", "updownticks", "run_structure", "returns", "slippage"

L1 order book (L1Metric): "l1_price", "l1_imbalance", "l1_liquidity"

L2 order book (L2Metric): "l2_imbalance", "l2_liquidity"

get_derivative_metrics — Derivative metrics

"basis", "funding", "open_interest", "derivative_price"

Core Parameters

All data endpoints share this shape:

• api_key: Your Aperiodic.io API key.
• timestamp: "exchange" or "true".
• interval: "1m" | "5m" | "15m" | "30m" | "1h" | "4h" | "1d".
• exchange: "binance-futures" | "okx-perps".
• symbol: Atlas-formatted symbol string (e.g. "perpetual-BTC-USDT:USDT").
• start_date / end_date: Inclusive date boundaries.
• show_progress: show tqdm progress bar (default: True).
• max_concurrent: max parallel file downloads (default: 10).

Examples

Trade metrics

from datetime import date
from aperiodic import get_metrics

flow_df = get_metrics(
    api_key="your-api-key",
    metric="flow",
    timestamp="exchange",
    interval="5m",
    exchange="binance-futures",
    symbol="perpetual-ETH-USDT:USDT",
    start_date=date(2024, 2, 1),
    end_date=date(2024, 2, 29),
)

L1 / L2 order book metrics

from datetime import date
from aperiodic import get_metrics

l1_df = get_metrics(
    api_key="your-api-key",
    metric="l1_imbalance",
    timestamp="true",
    interval="1m",
    exchange="binance-futures",
    symbol="perpetual-BTC-USDT:USDT",
    start_date=date(2024, 3, 1),
    end_date=date(2024, 3, 7),
)

l2_df = get_metrics(
    api_key="your-api-key",
    metric="l2_liquidity",
    timestamp="true",
    interval="1m",
    exchange="binance-futures",
    symbol="perpetual-BTC-USDT:USDT",
    start_date=date(2024, 3, 1),
    end_date=date(2024, 3, 7),
)

Derivative metrics

from datetime import date
from aperiodic import get_derivative_metrics

funding_df = get_derivative_metrics(
    api_key="your-api-key",
    metric="funding",
    timestamp="exchange",
    interval="1h",
    exchange="binance-futures",
    symbol="perpetual-BTC-USDT:USDT",
    start_date=date(2024, 1, 1),
    end_date=date(2024, 3, 31),
)

Symbol discovery

from aperiodic import get_symbols

symbols = get_symbols(api_key="your-api-key", exchange="binance-futures")
perpetuals = [s for s in symbols if s.startswith("perpetual-")]
print(f"Found {len(perpetuals)} perpetual symbols")

Async usage

import asyncio
from datetime import date
from aperiodic import get_metrics_async, get_symbols_async

async def main() -> None:
    symbols = await get_symbols_async(
        api_key="your-api-key",
        exchange="binance-futures",
    )
    for symbol in symbols:
        df = await get_metrics_async(
            api_key="your-api-key",
            metric="l1_liquidity",
            timestamp="true",
            interval="1h",
            exchange="binance-futures",
            symbol=symbol,
            start_date=date(2024, 1, 1),
            end_date=date(2026, 1, 1),
        )

asyncio.run(main())

Error Handling

from datetime import date
from aperiodic import APIError, DownloadError, get_ohlcv

try:
    df = get_ohlcv(
        api_key="your-api-key",
        timestamp="true",
        interval="1d",
        exchange="binance-futures",
        symbol="perpetual-BTC-USDT:USDT",
        start_date=date(2024, 1, 1),
        end_date=date(2024, 1, 31),
    )
except APIError as exc:
    print(f"API error {exc.status_code}: {exc.message}")
    if exc.details:
        print(exc.details)
except DownloadError as exc:
    print(f"Download failed for {exc.year}-{exc.month:02d}: {exc.original_error}")

Performance Notes

• Downloads are split into monthly parquet files server-side.
• Files are fetched concurrently and concatenated locally.
• Final output is sorted and filtered to your exact requested date range.
• Tune max_concurrent based on your network and compute resources.

Requirements

• Python 3.11+
• httpx
• polars
• tqdm
• nest-asyncio

License

MIT