# Aperiodic — Complete LLM Reference

> Aperiodic (https://aperiodic.io) is a crypto market data platform providing institutional-grade microstructure datasets. This document is the comprehensive reference for AI agents and LLMs.

## Quick Start

### Authentication
All API requests require an `X-API-KEY` header.
- Sign up: https://aperiodic.io/auth/sign-up
- Get API key: https://aperiodic.io/home/api (requires a paid subscription)

### Base URL
```
https://aperiodic.io/api/v1/data/{bucket}
```

### Python SDK (recommended)
```bash
pip install aperiodic
```
```python
from aperiodic import get_ohlcv

df = get_ohlcv(
    api_key="YOUR_KEY",
    timestamp="true",
    interval="1d",
    exchange="binance-futures",
    symbol="perpetual-BTC-USDT:USDT",
    start_date="2024-01-01",
    end_date="2024-06-01",
)
```

### cURL
```bash
curl -H "X-API-KEY: YOUR_KEY" \
  "https://aperiodic.io/api/v1/data/ohlcv?timestamp=true&interval=1d&exchange=binance-futures&symbol=perpetual-BTC-USDT:USDT&start_date=2024-01-01&end_date=2024-03-01"
```

## API Parameters

| Parameter | Required | Values |
|-----------|----------|--------|
| `exchange` | Yes | `binance-futures`, `okx-perps` |
| `symbol` | Yes | e.g. `perpetual-BTC-USDT:USDT`, `perpetual-ETH-USDT:USDT` |
| `interval` | Yes | `1s`*, `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d` |
| `start_date` | Yes | ISO date, e.g. `2024-01-01` |
| `end_date` | Yes | ISO date, e.g. `2024-06-01` |
| `timestamp` | No | `true` (datetime index) or `exchange` (exchange timestamps) |

*`1s` interval requires `timestamp=true` and Tier 3 subscription.

### Symbols Endpoint
```
GET https://aperiodic.io/api/v1/metadata/symbols?exchange=binance-futures
```
Returns: `{ "symbols": ["perpetual-BTC-USDT:USDT", ...], "exchange": "binance-futures" }`

### Catalog Endpoint
```
GET https://aperiodic.io/api/v1/metadata/catalog
```
Returns all datasets with field metadata.

## Response Format

Success response returns pre-signed URLs to monthly Parquet files (5-minute expiration):
```json
{
  "files": [
    { "year": 2024, "month": 1, "url": "https://..." },
    { "year": 2024, "month": 2, "url": "https://..." }
  ]
}
```

The Python SDK automatically downloads and concatenates these into a pandas DataFrame.

## Error Codes

| Status | Error | Cause | Recovery |
|--------|-------|-------|----------|
| 400 | Invalid query parameters | Missing or malformed parameters | Check required params: exchange, symbol, interval, start_date, end_date |
| 400 | Interval not available | Requested interval not in dataset's supported list | Check dataset's `intervals` field via catalog endpoint |
| 401 | No API key | Missing `X-API-KEY` header | Add header: `X-API-KEY: YOUR_KEY` |
| 401 | Subscription does not have data API access | Free tier or no subscription | Subscribe at https://aperiodic.io/home/billing |
| 403 | Subscription does not have access to dataset | Dataset tier exceeds subscription | Upgrade subscription to required tier |
| 403 | Interval requires Tier 3 | `1s` interval needs Prime subscription | Upgrade to Prime or use `1m`+ intervals |
| 404 | Unknown dataset | Invalid bucket name | Use valid dataset ID from catalog |
| 500 | Failed to generate URLs | Server error | Retry after 5 seconds |

All error responses include CORS headers and have the shape:
```json
{ "error": "Error message", "details": ["optional", "validation", "details"] }
```

## Subscription Tiers

| Tier | Price | Datasets | Intervals | API Access |
|------|-------|----------|-----------|------------|
| Free (logged in) | $0 | View-only catalog | — | No |
| Basic | From $29/mo | Open + Tier 0 (ohlcv, vtwap) | 15m–1d | Yes |
| Core | From $79/mo | + Tier 1 (flow, trade_size, range, basis, funding, open_interest, derivative_price) | 15m–1d | Yes |
| Pro | From $149/mo | + Tier 2 (impact, updownticks, run_structure, returns, slippage, l1_price) | 15m–1d | Yes |
| Prime | From $299/mo | + Tier 3 (l1_imbalance, l1_liquidity, l2_imbalance, l2_liquidity) | 1m–1d (all) | Yes |
| Institutional | Custom | All datasets + priority support | 1m–1d (all) | Yes |

## Complete Dataset Reference

### Trades Category

#### `flow` — Flow Metrics (Tier 1)
Directional order flow split by taker buy vs. sell, broken into small/medium/large notional segments, with a flow toxicity score.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `taker_buy_volume` — Total taker buy volume
- `taker_sell_volume` — Total taker sell volume
- `volume_delta` — Buy minus sell volume
- `flow_toxicity_score` — Flow toxicity indicator (higher = more informed flow)
- `taker_buy_sell_ratio` — Buy/sell volume ratio
- Size-segmented fields: `small_buy_volume`, `medium_buy_volume`, `large_buy_volume` (and sell equivalents)

Total fields: 51

#### `trade_size` — Trade Size Distribution (Tier 1)
Trade notional split into small (< $100), medium ($100–$1,000), and large (≥ $1,000) segments, with summary statistics.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `small_order_volume`, `medium_order_volume`, `large_order_volume`
- `trade_amount_mean`, `trade_amount_std`, `trade_amount_skewness`, `trade_amount_kurtosis`

Total fields: 25

#### `range` — Price Range & Distribution (Tier 1)
Intrabar high-low price range and distribution statistics for trade prices.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `range` — High minus low
- `range_bps` — Range in basis points
- `price_mean`, `price_median`, `price_std`, `price_skewness`, `price_kurtosis`, `price_cv`

Total fields: 10

#### `impact` — Market Impact Metrics (Tier 2)
How much each unit of trading volume moves the price.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `amihud_like` — Amihud illiquidity ratio
- `kyle_like_lambda` — Kyle's lambda estimate
- `impact_per_notional` — Price impact per unit notional
- `large_trade_reversal` — Post-large-trade price reversal
- `directional_impact_asymmetry` — Buy vs sell impact asymmetry

Total fields: 5

#### `updownticks` — Up/Down Tick Metrics (Tier 2)
Uptick and downtick count, volume, ratios based on price movement direction.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `uptick_volume`, `downtick_volume`
- `uptick_downtick_volume_ratio`
- `uptick_count_percentage`, `downtick_count_percentage`

Total fields: 15

#### `run_structure` — Trade Run Structure (Tier 2)
Consecutive same-direction trade run lengths, imbalance, and flip metrics.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `buy_run_max_len`, `sell_run_max_len`
- `run_imbalance`, `flip_rate`, `price_change_on_flip`

Total fields: 7

#### `returns` — Returns & Volatility (Tier 2)
Log-return based metrics including realized volatility and jump detection.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `logret_var` — Log-return variance
- `realized_vol` — Realized volatility
- `bipower_variation` — Bipower variation (continuous component)
- `jump_ratio` — Jump-to-total variance ratio
- `ret_autocorr_lag1` — Return autocorrelation
- `trendiness` — Directional persistence

Total fields: 6

#### `slippage` — Execution Slippage (Tier 2)
How much each trade pays above best ask (buys) or receives below best bid (sells).

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `slippage_mean`, `slippage_bps_mean`, `slippage_bps_std`
- `slippage_bps_p95`, `slippage_bps_vwap`
- `slippage_bps_buy_mean`, `slippage_bps_buy_sell_ratio`

Total fields: 10

### Derivatives Category

#### `basis` — Futures-Spot Basis (Tier 1)
Perpetual futures mark price premium over index price.

Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `basis`, `basis_bps` — Absolute and bps basis
- `mark_price_spread`, `mark_price_spread_bps`
- `basis_mean`, `basis_bps_std`

Total fields: 8

#### `funding` — Perpetual Funding Rates (Tier 1)
Funding rate and update frequencies.

Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `funding_rate` — Current funding rate
- `funding_rate_update_frequency` — Updates per interval
- `funding_rate_avg_update_interval` — Average time between updates

Total fields: 3

#### `open_interest` — Open Interest (Tier 1)
Open interest values with change metrics.

Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `open_interest` — Current OI value
- `open_interest_pct_change` — Period-over-period change
- `open_interest_volatility` — OI volatility
- `oi_price_change_ratio` — OI change relative to price change

Total fields: 4

#### `derivative_price` — Derivative Prices (Tier 1)
Snapshot of mark, index, and last trade prices with divergence ratios.

Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `last_price`, `index_price`, `mark_price`
- `last_price_pct_change`, `index_price_pct_change`, `mark_price_pct_change`
- `mark_index_pct_change_ratio`

Total fields: 9

### Market Category

#### `ohlcv` — Candlesticks (Tier 0)
Standard OHLCV candles with volume breakdowns.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Fields:
- `open`, `high`, `low`, `close` — Price fields
- `volume` — Trade volume
- `volume_notional` — Notional volume (USD)

Total fields: 6

#### `vtwap` — VWAP/TWAP (Tier 0)
Volume-weighted and time-weighted average prices.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Fields:
- `vwap` — Volume-weighted average price
- `twap` — Time-weighted average price

Total fields: 2

### L1 (Top of Book) Category

#### `l1_price` — Best Bid/Ask (Tier 2)
Best bid/ask prices, quantities, midprice, and weighted averages.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `ask_price`, `bid_price`, `ask_amount`, `bid_amount`
- `midprice`, `weighted_midprice`
- `quote_update_frequency`, `avg_update_interval`
- `bid_price_twap`, `ask_price_twap`, `bid_price_vwap`, `ask_price_vwap`

Total fields: 12

#### `l1_imbalance` — Bid/Ask Imbalance (Tier 3)
Bid/ask imbalance metrics, both instantaneous and interval-averaged.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `imbalance`, `imbalance_ratio`, `bid_ask_ratio`
- `bid_percentage`, `ask_percentage`
- `imbalance_avg`, `imbalance_ratio_avg` (interval averages)

Total fields: 10

#### `l1_liquidity` — Top-of-Book Liquidity (Tier 3)
Spread, depth, and dollar depth metrics.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields:
- `spread`, `spread_bps`, `spread_depth_ratio`
- `total_depth`, `dollar_depth_bid`, `dollar_depth_ask`, `total_dollar_depth`
- `spread_avg`, `spread_bps_avg` (interval averages)

Total fields: 14

### L2 (Order Book) Category

#### `l2_imbalance` — Multi-Level Imbalance (Tier 3)
Order book imbalance at 5, 10, 20, and 25 levels deep.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields (at each depth 5/10/20/25):
- `imbalance_{depth}`, `imbalance_ratio_{depth}`, `bid_ask_ratio_{depth}`
- Plus interval-averaged versions

Total fields: 27

#### `l2_liquidity` — Multi-Level Depth (Tier 3)
Total bid/ask depth at 5, 10, 20, and 25 levels.

Intervals: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 1d
Exchanges: binance-futures, okx-perps

Key fields (at each depth 5/10/20/25):
- `ask_agg_{depth}`, `bid_agg_{depth}`
- Plus interval-averaged versions

Total fields: 16

## Agent Integration

### LLM-Readable Pages (.agent)
Append `.agent` to any supported URL path for a Markdown version:
- `https://aperiodic.io/index.agent` — Landing page summary
- `https://aperiodic.io/agents.agent` — Full agent integration docs
- `https://aperiodic.io/catalog/{dataset_id}.agent` — Dataset docs (e.g. `/catalog/flow.agent`)
- `https://aperiodic.io/metrics/{category}.agent` — Category overview (e.g. `/metrics/trades.agent`)
- `https://aperiodic.io/pricing.agent` — Pricing tiers

### Claude Skills for Quant Research
Pre-built skill files for Claude Code:
- https://aperiodic.io/skills/market-analysis.md — Market analysis (OHLCV, flow, funding, liquidity)
- https://aperiodic.io/skills/factor-research.md — Cross-sectional factor construction & evaluation
- https://aperiodic.io/skills/backtest-strategies.md — Strategy backtesting with realistic costs

### Discovery Endpoints
- LLM summary: https://aperiodic.io/llms.txt
- Full LLM reference: https://aperiodic.io/llms-full.txt (this document)
- OpenAPI 3.0 spec: https://aperiodic.io/api.data.specification.json
- AI plugin manifest: https://aperiodic.io/.well-known/ai-plugin.json
- A2A Agent Card: https://aperiodic.io/.well-known/agent.json

## Typical Research Use Cases

- Order flow alpha signals (flow toxicity, imbalance)
- Institutional accumulation and flow toxicity detection
- Transaction cost and market impact modeling
- Volatility/jump decomposition
- Execution quality and slippage benchmarking
- Short-horizon directional persistence analysis
- Funding rate regime analysis and carry strategies
- Deep liquidity analysis and order book modeling
- Cross-sectional factor construction

## Coverage

- **Exchanges**: Binance Futures, OKX Perpetuals (10+ coming soon)
- **History**: 5+ years of historical data
- **Instruments**: Full perpetual futures universe per exchange
- **Methodology**: Point-in-time, immutable, exchange-timestamped

## Contact

- Website: https://aperiodic.io
- Email: info@aperiodic.io
- Twitter: https://x.com/unravel_finance
- Telegram: https://t.me/unravel_finance

## Disclaimer

All content is for informational purposes only and does not constitute legal, tax, investment, or financial advice.

---

Last updated: March 2026