# Aperiodic

> Aperiodic sells point-in-time crypto market microstructure, liquidity and order-flow metrics: 220 metrics in 19 datasets on binance-futures, okx-perps, hyperliquid-perps, delivered as parquet through a CLI, a REST API and a Python SDK, plus the raw trades, quotes and derivatives data behind them in the Prime + Raw plan. A preview slice of every dataset downloads with no API key, and self-serve plans cost $79 to $1249 a month billed yearly.

Built by Aperiodic. Exchanges: `binance-futures`, `okx-perps`, `hyperliquid-perps`. Self-serve intervals: `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`; `15s`, `30s` on Institutional.

## Agent quickstart

1. **Fetch the preview slice, no API key.** Install the CLI and pull one month of 5m flow data for perpetual-BTC-USDT:USDT on binance-futures as parquet. The preview accepts only this window (2025-05-01 to 2025-05-31, 5m), for every dataset: swap flow for any dataset id.

```bash
# 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"

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
```

2. **Install the Python SDK.** The SDK returns DataFrames. The same preview slice works from Python with preview=True, still without a key.

```bash
pip install "aperiodic[polars]"
```

3. **Make a keyed call.** Your user creates a key at https://aperiodic.io/home/api. Any other symbol, interval or date range needs a key and a plan that includes the dataset's tier (flow is Tier 1; see https://aperiodic.io/pricing).

```python
from datetime import date
from aperiodic import get_metrics

df = get_metrics(
    api_key="YOUR_API_KEY",
    metric="flow",
    exchange="binance-futures",
    symbol="perpetual-BTC-USDT:USDT",
    interval="1h",
    timestamp="exchange",
    start_date=date(2025, 1, 1),
    end_date=date(2025, 3, 1),
)
```

## Preview access (no account)

- CLI: `aperiodic <dataset_id> --preview` with the flags above
- Python: `preview=True` on any SDK call
- REST: `GET https://aperiodic.io/api/v1/data/preview/{dataset_id}?timestamp=exchange&interval=5m&exchange=binance-futures&symbol=perpetual-BTC-USDT:USDT&start_date=2025-05-01&end_date=2025-05-31` with header `X-API-KEY: DEMO-KEY`
- Window: binance-futures, perpetual-BTC-USDT:USDT, 5m, 2025-05-01 to 2025-05-31, every dataset. Other parameters are refused.

## Datasets

19 datasets, 220 metrics. Machine-readable catalog: [catalog.json](https://aperiodic.io/catalog.json)

### Market Data

- [Candlesticks](https://aperiodic.io/catalog/ohlcv): `ohlcv`, 6 metrics, Tier 0. Open, High, Low, Close, Volume candlestick data with notional volume. Markdown: `/catalog/ohlcv.agent`
- [VWAP / TWAP](https://aperiodic.io/catalog/vtwap): `vtwap`, 2 metrics, Tier 0. Volume-weighted and time-weighted average prices for precise execution benchmarks. Markdown: `/catalog/vtwap.agent`

### Derivatives

- [Basis](https://aperiodic.io/catalog/basis): `basis`, 8 metrics, Tier 1. Perpetual futures mark price premium over index price (basis) and last trade price, in absolute and basis-point terms. Markdown: `/catalog/basis.agent`
- [Funding](https://aperiodic.io/catalog/funding): `funding`, 3 metrics, Tier 1. Funding rate and update frequencies for perpetual futures contracts. Markdown: `/catalog/funding.agent`
- [Open Interest](https://aperiodic.io/catalog/open_interest): `open_interest`, 4 metrics, Tier 1. Open interest values with percentage change, volatility, and OI/price change ratio. Markdown: `/catalog/open_interest.agent`
- [Derivative Price](https://aperiodic.io/catalog/derivative_price): `derivative_price`, 9 metrics, Tier 1. Snapshot of mark, index, and last trade prices with interval percentage changes and pairwise divergence ratios. Markdown: `/catalog/derivative_price.agent`

### Trades

- [Flow Metrics](https://aperiodic.io/catalog/flow): `flow`, 36 metrics, Tier 1. Directional order flow split by taker buy vs. sell, broken into small/medium/large notional segments, with a flow toxicity score. Markdown: `/catalog/flow.agent`
- [Trade Size](https://aperiodic.io/catalog/trade_size): `trade_size`, 24 metrics, Tier 1. Trade notional split into small (< $100), medium ($100–$1,000), and large (≥ $1,000) segments, with summary statistics for individual trade sizes. Markdown: `/catalog/trade_size.agent`
- [Price Range & Distribution](https://aperiodic.io/catalog/range): `range`, 10 metrics, Tier 1. Intrabar high-low price range and full distribution statistics (mean, median, std, skewness, kurtosis) for trade prices within each interval. Markdown: `/catalog/range.agent`
- [Impact Metrics](https://aperiodic.io/catalog/impact): `impact`, 5 metrics, Tier 2. How much each unit of trading volume moves the price, measured via Amihud illiquidity, Kyle lambda, impact per notional, and large-trade reversal. Markdown: `/catalog/impact.agent`
- [Up / Down Tick Metrics](https://aperiodic.io/catalog/updownticks): `updownticks`, 14 metrics, Tier 2. Uptick and downtick count, volume, ratios and percentages based on price movement direction. Markdown: `/catalog/updownticks.agent`
- [Trade Run Structure](https://aperiodic.io/catalog/run_structure): `run_structure`, 7 metrics, Tier 2. Consecutive same-direction trade run lengths, imbalance, flip rate, and price change on direction flip. Markdown: `/catalog/run_structure.agent`
- [Returns & Volatility](https://aperiodic.io/catalog/returns): `returns`, 6 metrics, Tier 2. Log-return based metrics: variance, realized volatility, bipower variation, jump ratio, autocorrelation, and trendiness. Markdown: `/catalog/returns.agent`
- [Slippage](https://aperiodic.io/catalog/slippage): `slippage`, 10 metrics, Tier 2. How much each trade pays above the best ask (buys) or receives below the best bid (sells) relative to the prevailing quote, aggregated per interval. Markdown: `/catalog/slippage.agent`

### L1 — Top of Book

- [L1 Price](https://aperiodic.io/catalog/l1_price): `l1_price`, 12 metrics, Tier 2. Best bid and ask prices with quantities, midprice, quantity-weighted midprice, time/volume-weighted averages, and quote update frequency. Markdown: `/catalog/l1_price.agent`
- [L1 Imbalance](https://aperiodic.io/catalog/l1_imbalance): `l1_imbalance`, 10 metrics, Tier 3. Bid/ask imbalance, ratio, percentages — both instantaneous (last) and averaged over the interval. Markdown: `/catalog/l1_imbalance.agent`
- [L1 Liquidity](https://aperiodic.io/catalog/l1_liquidity): `l1_liquidity`, 14 metrics, Tier 3. Spread (absolute and bps), depth, dollar depth — instantaneous and interval-averaged. Markdown: `/catalog/l1_liquidity.agent`

### L2 — Order Book

- [L2 Order Book Imbalance](https://aperiodic.io/catalog/l2_imbalance): `l2_imbalance`, 24 metrics, Tier 3. Multi-depth (5, 10, 20, 25 levels) order book imbalance, ratio, and averages. Markdown: `/catalog/l2_imbalance.agent`
- [L2 Order Book Liquidity](https://aperiodic.io/catalog/l2_liquidity): `l2_liquidity`, 16 metrics, Tier 3. Total bid/ask depth aggregated over 5, 10, 20, 25 order book levels — instantaneous and interval-averaged. Markdown: `/catalog/l2_liquidity.agent`

## Raw data

6 raw datasets, counted separately from the 19 metric datasets, for the Prime + Raw and Institutional plans: https://aperiodic.io/raw-data (markdown: `/raw-data.agent`).

- [Trades](https://aperiodic.io/catalog/raw/trades): `trades`. Every trade printed on the venue, with its trade id, taker side, price and size. Venues: binance-futures, okx-perps, hyperliquid-perps. Columns: `exchange_timestamp`, `local_timestamp`, `local_timestamp_kind`, `id`, `side`, `price`, `amount`. Markdown: `/catalog/raw/trades.agent`
- [Quotes](https://aperiodic.io/catalog/raw/quotes): `quotes`. Top-of-book updates: best bid and best ask with their sizes, one row per change. Venues: binance-futures, okx-perps, hyperliquid-perps. Columns: `exchange_timestamp`, `local_timestamp`, `local_timestamp_kind`, `bid_price`, `bid_amount`, `ask_price`, `ask_amount`. Markdown: `/catalog/raw/quotes.agent`
- [Mark price](https://aperiodic.io/catalog/raw/mark_price): `mark_price`. The venue’s mark price, one row each time it changes. Venues: binance-futures, okx-perps, hyperliquid-perps. Columns: `exchange_timestamp`, `local_timestamp`, `local_timestamp_kind`, `mark_price`. Markdown: `/catalog/raw/mark_price.agent`
- [Index price](https://aperiodic.io/catalog/raw/index_price): `index_price`. The venue’s index price for the contract’s underlying, one row each time it changes. Venues: binance-futures, okx-perps, hyperliquid-perps. Columns: `exchange_timestamp`, `local_timestamp`, `local_timestamp_kind`, `index_price`. Markdown: `/catalog/raw/index_price.agent`
- [Funding rate](https://aperiodic.io/catalog/raw/funding_rate): `funding_rate`. The current funding rate and the next funding time, one row each time either changes. Venues: binance-futures, okx-perps, hyperliquid-perps. Columns: `exchange_timestamp`, `local_timestamp`, `local_timestamp_kind`, `funding_rate`, `next_funding_timestamp`. Markdown: `/catalog/raw/funding_rate.agent`
- [Open interest](https://aperiodic.io/catalog/raw/open_interest): `open_interest`. Open interest as the venue reports it, one row each time it changes. Venues: binance-futures, okx-perps, hyperliquid-perps. Columns: `exchange_timestamp`, `local_timestamp`, `local_timestamp_kind`, `open_interest`. Markdown: `/catalog/raw/open_interest.agent`

- REST: `GET https://aperiodic.io/api/v1/data/raw/{dataset}?exchange=&symbol=&start_date=&end_date=` (at most 366 days) returns presigned Parquet URLs valid for one hour: one file per month before 2026-08-01, one per day after. Other plans get HTTP 403 `raw_not_in_plan`.
- Preview with `X-API-KEY: DEMO-KEY`: `GET https://aperiodic.io/api/v1/data/raw/preview/{dataset}?exchange=&symbol=`, the 2025-06 file of each venue's BTC perpetual; add `download=true` for a redirect to the file itself, so `curl -fL -o NAME` saves it in one request. Coverage: `GET https://aperiodic.io/api/v1/metadata/raw` (no key).
- Python: `aperiodic.get_raw(...)`, `aperiodic.download_raw(..., output_dir=...)`.
- `exchange_timestamp` is the venue's time. `local_timestamp` is measured on days we captured ourselves and modelled from our measured latency before that; `local_timestamp_kind` says which. Not for latency research on modelled days.
- Not offered: raw L2 order book, liquidations, spot, dated futures, other venues.

## Pricing and licence

Self-serve: $79 to $1249 a month billed yearly, $95 to $1579 month to month.

- **Core Historical**: $79/month billed yearly, $95 month to month. Tiers: tier0, tier1; 4 years of history; Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d; API (Elevated Rate Limits); Licence: Personal use
- **Pro Historical**: $299/month billed yearly, $379 month to month. Tiers: tier0, tier1, tier2; 4 years of history; Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d; API (High Rate Limits); Licence: Personal use
- **Prime Historical**: $699/month billed yearly, $879 month to month. Tiers: tier0, tier1, tier2, tier3; Full history; Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d; API (No Rate Limits); Licence: Personal use
- **Prime + Raw**: $1249/month billed yearly, $1579 month to month. Everything in Prime; Raw data: trades, quotes, mark, index, funding, OI; Binance, OKX & Hyperliquid perpetuals; Full history, updated daily; Licence: Personal use
- **Institutional**: quoted. Negotiated SLA; AUM-based pricing; Real-time data stream; Sub-minute intervals: 15s, 30s, 1m, 5m, 15m, 30m, 1h, 4h, 1d; REST API, S3, and custom delivery channels; Deployment in your cloud or on-prem; Commercial licence & dedicated support; Proof of Concept: historical time slice

- Self-serve plans (Core Historical, Pro Historical, Prime Historical, Prime + Raw) carry a personal-use licence.
- Commercial use needs the Institutional plan, which adds a commercial licence, a negotiated SLA and 15s/30s intervals. It is quoted, not self-serve: https://aperiodic.io/booking.
- Raw data (Prime + Raw) is licensed for internal research and trading only and may not be redistributed.
- Terms: https://aperiodic.io/terms-of-service.

## Documentation

- [Agent guide](https://aperiodic.io/agents): quickstart and FAQ for agents. Markdown: `/agents.agent`
- [Full LLM reference](https://aperiodic.io/llms-full.txt): API reference, fields, error codes
- [OpenAPI 3.0 specification](https://aperiodic.io/api.data.specification.json)
- [API documentation](https://aperiodic.io/api-docs)
- [Python SDK on PyPI](https://pypi.org/project/aperiodic/)
- [CLI on GitHub](https://github.com/aperiodic-io/cli)
- [Atlas security master](https://aperiodic.io/atlas): the free, open-source symbology behind every Aperiodic symbol ([GitHub](https://github.com/aperiodic-io/atlas))
- [A2A agent card](https://aperiodic.io/.well-known/agent.json)
- [AI plugin manifest](https://aperiodic.io/.well-known/ai-plugin.json)
- Append `.agent` to catalog, metrics, compare, pricing and raw-data URLs for markdown, e.g. `/pricing.agent`

## Comparisons

- [Crypto market data vendors compared](https://aperiodic.io/compare): 16 vendors and the exchanges' own archives next to Aperiodic on 40 criteria, every fact linked to the vendor's own page and dated. Built by Aperiodic, which is one of the columns; nobody is ranked. Markdown: `/compare.agent`, one vendor: `/compare/vendors/{vendor}.agent`. Data: [CSV](https://aperiodic.io/compare/crypto-data-vendors.csv), [JSON](https://aperiodic.io/compare/crypto-data-vendors.json); quoting with a link is fine, republishing needs permission ([terms](https://aperiodic.io/compare/methodology#terms))
- [Aperiodic vs Tardis.dev](https://aperiodic.io/compare/aperiodic-vs-tardis): Looking for a Tardis.dev alternative? Aperiodic is the better pick for signal research on perps, and the wrong one for tick replay. Try it with no API key. Markdown: `/compare/aperiodic-vs-tardis.agent`
- [Aperiodic vs CoinGlass](https://aperiodic.io/compare/aperiodic-vs-coinglass): Looking for a CoinGlass alternative? Keep CoinGlass for watching liquidations. Use Aperiodic when code is the consumer: per-venue parquet, no API key to try. Markdown: `/compare/aperiodic-vs-coinglass.agent`
- [Aperiodic vs Kaiko](https://aperiodic.io/compare/aperiodic-vs-kaiko): Looking for a Kaiko alternative? Kaiko wins on history, venues and regulated benchmarks. Aperiodic is self-serve from $79 with a no-key preview. Markdown: `/compare/aperiodic-vs-kaiko.agent`
- [Aperiodic vs Amberdata](https://aperiodic.io/compare/aperiodic-vs-amberdata): Looking for an Amberdata alternative? Amberdata wins on venues, history and options analytics. Aperiodic lists its price and has a no-key preview. Markdown: `/compare/aperiodic-vs-amberdata.agent`

## Optional

- [Catalog](https://aperiodic.io/catalog)
- [Pricing](https://aperiodic.io/pricing)
- [FAQ](https://aperiodic.io/faq)
- [Sign up](https://aperiodic.io/auth/sign-up)
- Contact: info@aperiodic.io