Source: https://tesseralytics.dev/blog/one-off-download-tutorial

[← Blog](https://tesseralytics.dev/blog)

Tutorial 7 October 2026

# Download Hyperliquid data to your local machine: a step-by-step tutorial

Buy a one-off bundle, write a small Python tool with the SDK, run it with uvx, and persist data locally as Parquet or DuckDB. No subscription, no commitment — the data is yours.

Tessera's one-off download bundles give you a perpetual copy of Hyperliquid data — no subscription, no expiry. Three bundles are available: [Tessera Majors ($19)](https://tesseralytics.dev/pricing), [Tessera HIP-3 ($24)](https://tesseralytics.dev/pricing), and [Tessera All Markets ($29)](https://tesseralytics.dev/pricing). Each includes all three datasets — `gold_ohlcv_1m`, `gold_funding_1h`, and `gold_positioning_1h` — over all closed months.

You can follow this tutorial without buying anything. A free account gives you `gold_ohlcv_1m` (minute candles) for BTC, ETH, SOL and HYPE over the trailing month — enough to run every example below. Buying a bundle unlocks all three datasets, every coin, and the full closed history back to October 2025.

## Get an API key

Sign up at [tesseralytics.dev/account](https://tesseralytics.dev/account), create an API key, and copy it. The key is shown once — store it somewhere safe. Export it as an environment variable:

```
export TESSERA_API_KEY="sk_..."   # from https://tesseralytics.dev
```

## Buy a bundle

Head to [/pricing](https://tesseralytics.dev/pricing), pick a bundle, and check out via Stripe. The purchase is a one-time payment — the data is yours forever. The open month is excluded; subscribe to Pro if you want freshness.

## Write the download tool

The approach is a small Python script that uses the SDK to pull data and save it locally. The script uses inline dependencies (PEP 723) so it runs with `uvx` — no `pip install`, no venv:

```
# /// script
# dependencies = ["tessera-api"]
# ///
import tessera

client = tessera.TesseraClient()  # reads $TESSERA_API_KEY

# List what you can see
datasets = client.datasets()
for d in datasets.datasets:
    print(f"{d.name}: {d.description}")

# Pull BTC minute candles for a specific month
df = client.read("gold_ohlcv_1m", "BTC", "2026-09")
print(f"Pulled {len(df)} rows")

# Save as a single flat Parquet file
df.write_parquet("btc_ohlcv_2026-09.parquet")
print("Saved to btc_ohlcv_2026-09.parquet")
```

`datasets()` returns every dataset your plan can reach. `read()` pulls a partition as a Polars DataFrame. `write_parquet()` saves it as a single flat Parquet file — a columnar format that is faster and smaller than CSV, and readable by pandas, polars, DuckDB, and most modern tools.

That pulled one partition. To download multiple coins or months at once, use `scan()` with a `MonthSpan`:

```
import tessera

client = tessera.TesseraClient()

# Pull BTC and ETH minute candles for three months
lf = client.scan(
    "gold_ohlcv_1m",
    coin=["BTC", "ETH"],
    month=tessera.MonthSpan("2026-07", "2026-09"),
    columns=["time", "coin", "close", "volume"],
)

# Collect and save as a single Parquet file
df = lf.collect()
df.write_parquet("btc_eth_ohlcv_2026-07_to_2026-09.parquet")
print(f"Saved {len(df)} rows")
```

## Install uv

`uvx` is part of `uv`, a fast Python package manager. If you don't have it yet, install it:

```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Verify it works:

```
uv --version
```

## Run it with uvx

`uvx` runs the script in an isolated environment. First run takes a few seconds (it downloads the SDK); subsequent runs are instant:

```
uvx download_data.py
```

Prefer a permanent install? `pip install tessera-api` works too.

## Persist as DuckDB instead

DuckDB is a local SQL database — like sqlite but with powerful analytics capabilities. You can query it with SQL, open it in tools, or connect from Python or R. DuckDB queries Polars DataFrames directly, so you can pull data with the SDK and insert it into a DuckDB file in a few lines:

```
# /// script
# dependencies = ["tessera-api", "duckdb"]
# ///
import tessera
import duckdb

client = tessera.TesseraClient()

# Create a local DuckDB file
con = duckdb.connect("ohlcv.duckdb")

# Pull data and insert it — DuckDB queries Polars DataFrames directly
df = client.read("gold_ohlcv_1m", "BTC", "2026-09")
con.execute("CREATE TABLE ohlcv AS SELECT * FROM df")
con.close()
print("Saved to ohlcv.duckdb")
```

## Query your local data

Read the Parquet file back with polars:

```
import polars as pl

df = pl.read_parquet("btc_ohlcv_2026-09.parquet")
print(df.head())
```

Or query the DuckDB file with SQL:

```
import duckdb

con = duckdb.connect("ohlcv.duckdb")
result = con.execute(
    "SELECT close FROM ohlcv WHERE time > '2026-09-15' LIMIT 5"
).fetchall()
print(result)
con.close()
```

Or open it in the DuckDB CLI for interactive SQL:

```
duckdb ohlcv.duckdb
```

## Where to go from here

The [SDK reference](https://tesseralytics.dev/sdks) has the full API. The [data dictionary](https://tesseralytics.dev/datasets) explains every column. And if you haven't already, [buy a bundle](https://tesseralytics.dev/pricing) to unlock the full history. The data is yours — no subscription, no expiry.

[← Back to blog](https://tesseralytics.dev/blog)