> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polaris.supply/llms.txt
> Use this file to discover all available pages before exploring further.

# Example Notebooks

> Start a Polaris notebook quickly, then explore a curated example notebook for single-market trade analysis with polaris_data.

Use this page when you want a fast notebook setup and then a curated runnable `polaris-data` example.

The full notebook sources live in the [`polaris-data/notebooks`](https://github.com/polaris-data/notebooks) repository. Keep this docs page as the map, and use the repository when you want the full runnable analysis.

## Start a notebook quickly

If you do not already have Jupyter running, start in a terminal:

```bash theme={null}
python3 -m pip install --upgrade jupyterlab ipykernel polaris-data pandas matplotlib
jupyter lab
```

If you already have a notebook open, install the basics in a cell:

```python theme={null}
%pip install polaris-data pandas matplotlib
```

Most Polaris notebooks follow the same first pattern:

1. Confirm the exact `source` and `market` with `catalog(...)`.
2. Fetch `ohlcv(...)` or `trades(...)`.
3. Load the response into pandas.
4. Plot or summarize the result.

```python theme={null}
import pandas as pd
from polaris_data import PolarisClient

source = "hyperliquid"
market = "BTC"

with PolarisClient() as client:
    catalog_result = client.catalog(source=source, market=market)
    bars = client.ohlcv(source=source, market=market, interval="1m")

markets_df = pd.DataFrame(catalog_result["markets"])
bars_df = pd.DataFrame(bars)
bars_df["time"] = pd.to_datetime(bars_df["timestamp"], unit="us", utc=True)

display(markets_df[["market", "start", "end"]])
display(bars_df.head())
```

Use [Market Coverage](/markets/market-coverage) first when you need a high-level view of supported venues, then confirm the exact identifier in [Catalog](/reference/catalog) before you fetch data.

## Repository overview

The current example repo is intentionally small and curated:

* [`hyperliquid_btc_trade_analysis.ipynb`](https://github.com/polaris-data/notebooks/blob/main/notebooks/hyperliquid_btc_trade_analysis.ipynb): single-market walkthrough for bars, trades, and trade-flow visualization

## Hyperliquid BTC trade analysis

Open [`hyperliquid_btc_trade_analysis.ipynb`](https://github.com/polaris-data/notebooks/blob/main/notebooks/hyperliquid_btc_trade_analysis.ipynb) when you want the most direct end-to-end SDK example.

This notebook shows how to:

* confirm the exact market with `catalog(...)`
* fetch a bounded OHLCV window and the matching raw trades
* normalize both responses into pandas DataFrames
* summarize buy and sell flow
* overlay trade points on the close series and chart signed flow per minute

Short excerpt:

```python theme={null}
from polaris_data import PolarisClient
import pandas as pd

source = "hyperliquid"
market = "BTC"

with PolarisClient() as client:
    bars = client.ohlcv(
        source=source,
        market=market,
        interval="1m",
    )
    trades = client.trades(
        source=source,
        market=market,
    )

bars_df = pd.DataFrame(bars)
trades_df = pd.json_normalize(trades)
```

Use this notebook when you want to understand the core `polaris-data` workflow quickly without adding multi-market logic.

## Choosing the right notebook

* Start with the Hyperliquid example if you want the fastest path to understanding `catalog(...)`, `ohlcv(...)`, and `trades(...)`.
* Stay in the docs and read [Python SDK](/sdks/python) if you want method signatures and usage patterns before opening a notebook.

## Next steps

* Browse the full notebook repo at [`polaris-data/notebooks`](https://github.com/polaris-data/notebooks).
* Read [Python SDK](/sdks/python) for the core client methods.
* Read [Catalog](/reference/catalog) before hardcoding source and market IDs.
* Read [OHLCV](/sdks/ohlcv) and [Trades](/sdks/trades) for the normalized response shapes behind the notebook examples.