Aperiodic Notebooks

Interactive Python notebooks for exploring Aperiodic market data APIs.

Notebooks are authored as percent-format .py files and auto-synced to .ipynb via Jupytext. These notebooks power the Aperiodic Playground and can also be run standalone.

Installation

pip install -e ".[notebook]"

Or install from this repo (includes dev tooling):

git clone https://github.com/aperiodic-io/notebooks.git
cd notebooks
pip install -e ".[notebook,quality]"

Usage

Run the new introductory notebooks

Create and populate the UV environment:

uv venv .venv
UV_CACHE_DIR=/tmp/uv-cache uv pip install -p .venv/bin/python -e ".[notebook]"

Make sure .env contains:

APERIODIC_API_KEY=your_key_here

Then open any of the new notebooks:

.venv/bin/jupyter notebook notebooks/intro-flow.ipynb

The new notebooks analyze Binance BTC perpetuals at 5-minute resolution and read the API key from the environment when executed via uv.

Jupyter / VS Code

Open any .ipynb file in Jupyter:

jupyter notebook notebooks/getting-started.ipynb

Or open notebooks/getting-started.py directly in VS Code — the Jupyter extension recognizes # %% cells automatically.

Run as a script

python notebooks/getting-started.py

Available Notebooks

Notebook	Description
getting-started	OHLCV data fetching, charting, and basic flow metrics
derivatives	Funding rates, open interest, and basis analysis
order-flow	Taker flow, buy/sell imbalances, and cumulative delta
intro-flow	Polished 5-minute BTC perpetual flow notebook using .env API key loading
intro-derivatives	Polished 5-minute BTC perpetual derivatives regime notebook (funding, OI, basis)
intro-l1-price	Polished 5-minute BTC perpetual top-of-book microstructure notebook

Development

Notebooks are authored as .py (percent format). The .ipynb files are auto-generated by CI — do not edit them directly.

To regenerate .ipynb locally:

pip install -e ".[notebook]"
jupytext --to ipynb notebooks/*.py

Requirements

• Python 3.11+
• An Aperiodic API key

License

MIT