---
name: aperiodic
description: Point-in-time market data (order flow, liquidity, funding, basis, open interest) for RWA perps (stocks, gold, oil, FX) and crypto perps on Binance, OKX and Hyperliquid, as DataFrames. Use for market research, backtests and execution costs on these perps.
---

# Aperiodic

220 point-in-time metrics in 19 datasets for every perpetual on `binance-futures`, `okx-perps`, `hyperliquid-perps`: crypto, and 500+ RWA perps on stocks, ETFs, commodities and FX. Intervals 1m to 1d.

## First run

The user pasted "Read https://aperiodic.io/start.md and follow it.", perhaps with a question or a task after it (a "Start in Claude" link on https://aperiodic.io adds one).

1. `pip install "aperiodic[polars]"` (in a virtualenv if the project has none).
2. Fetch the free preview, which needs no key, and pick what to show from it: the 5m bars with the biggest net flow, in $m.

```python
from datetime import date
import aperiodic as ap
import polars as pl

df = ap.get_metrics(
    metric="flow",
    exchange="binance-futures",
    symbol="perpetual-BTC-USDT:USDT",
    interval="5m",
    timestamp="exchange",
    start_date=date(2025, 5, 1),
    end_date=date(2025, 5, 31),
    preview=True,
)

top = (
    df.sort(pl.col("volume_delta_notional").abs(), descending=True)
    .head(5)
    .sort("time")
    .select(
        pl.col("time").dt.strftime("%Y-%m-%d %H:%M"),
        (pl.col("taker_buy_volume", "taker_sell_volume", "volume_delta_notional").cast(pl.Float64) / 1e6).round(1),
        pl.col("taker_buy_sell_ratio").cast(pl.Float64).round(2),
    )
)
buyers_led = (df["taker_buy_sell_ratio"] > 1).mean()
print(df.shape, top, f"{buyers_led:.0%}", sep="\n")
```

   The preview is only this slice (BTC on Binance, 2025-05-01 to 2025-05-31, 5m), for any dataset.

3. If they asked a question or gave a task, do it as under "Later requests". The preview only covers the slice above, so for anything else ask for a key once, in one line. Otherwise reply with exactly this, filled in from what the code printed, and nothing else. Show the table as a Markdown table, one row per row of `top`:

```
Aperiodic works: here is the free preview, taker order flow for BTC on Binance in 5m bars, 2025-05-01 to 2025-05-31 ({rows} rows × {columns} columns). The five bars with the biggest net flow:

| time (UTC) | taker buys ($m) | taker sells ($m) | net ($m) | buy/sell |
|---|---:|---:|---:|---:|
| {time} | {taker_buy_volume} | {taker_sell_volume} | {volume_delta_notional} | {taker_buy_sell_ratio} |

Buyers led in {buyers_led} of the bars. Each bar also has trade counts, a flow toxicity score, and buys and sells by order size.

With an API key I can:
- {an RWA question, e.g. how TSLA's premium behaves at weekends}
- {a crypto question}
- {a trading-cost question}

Next: create a key at https://aperiodic.io/home/api and set APERIODIC_API_KEY (or paste it here), then tell me what to look at. Want me to save Aperiodic as a skill for next time?
```

If something failed, say what in one line instead.

## Later requests

- Read the key from `APERIODIC_API_KEY`; if it is not set, ask for it once.
- Lead with the answer. Then show the data behind it, as a small Markdown table of the rows that matter (at most 10) or at most five bullets, and the code you ran. No tour of the product.
- If a dataset needs a bigger plan, the API says so: pass that on in one line.

## Essentials

- Symbols are Atlas IDs: `perpetual-TSLA-USDT:USDT` on `binance-futures` and `okx-perps`. A Hyperliquid builder market keeps its dex: `perpetual-XYZ:TSLA-USDC:USDC` on `hyperliquid-perps`. List a venue's symbols at `https://aperiodic.io/api/v1/metadata/symbols?exchange=binance-futures`.
- RWA history starts at each contract's listing, mostly in 2026.
- Datasets, by question:
  - Premium over the underlying, carry: `basis`, `funding`
  - Trading costs, liquidity: `l1_liquidity`, `slippage`, `impact`
  - Positioning: `open_interest`
  - Order flow: `flow`, `trade_size`
  - Volatility: `returns`, `range`
  - Prices: `ohlcv`, `vtwap`, `derivative_price`
- Raw trades, quotes, mark and index price and funding rates come as Parquet files on the Prime + Raw plan: see "Raw data" in https://aperiodic.io/llms.txt.
- Live data streams over a WebSocket on the same key, on plans that stream: channels, messages and limits at https://aperiodic.io/api-docs/live.
- Full reference: https://aperiodic.io/llms.txt

## Keep this as a skill

Save this file as `SKILL.md` in a folder named `aperiodic` in your skills directory (for Claude Code, `~/.claude/skills/aperiodic/SKILL.md`). Source: https://aperiodic.io/start.md