tessera-api 0.3.1

High-performance Rust client for the Tessera API — Hyperliquid datasets straight into Polars & DuckDB.
Documentation

tessera-api

Clean Hyperliquid market data — straight into Polars & DuckDB.

Crates.io docs.rs CI License: GPL v3

The official Rust client for Tessera — order-flow-enriched OHLCV, funding-rate, and positioning datasets built from raw Hyperliquid trade data, delivered as Parquet over a REST API.


Why tessera-api

  • Read where the data lives. Partitioned Parquet is read directly from object storage over HTTPS range requests. Predicate and projection pushdown mean only the row groups and columns your query touches cross the wire — no temp files, no glue code.
  • Two engines, one API. Lazily into Polars LazyFrames (default feature), or into an in-memory DuckDB database you query with plain SQL (duckdb feature).
  • Sync and async. TesseraClient for scripts and batch jobs; AsyncTesseraClient for tokio services.
  • Typed end to end. Response models are generated from the OpenAPI spec at build time, every failure is a TesseraError variant, and transient failures (429/5xx) are retried with exponential backoff and Retry-After handling.

Installation

cargo add tessera-api

Requires Rust 1.85+. Grab a free API key (no card required) at tesseralytics.dev:

export TESSERA_API_KEY="ts_..."

The free tier covers every coin and all three datasets over the trailing 30 days; full history is available as one-off download bundles (see Free tier and history bundles).

Free tier and history bundles

The free tier needs no card. It covers every coin and all three datasets — gold_ohlcv_1m, gold_funding_1h and gold_positioning_1h — over the trailing 30 days. The API serves that window at month granularity, so a free key sees the current and previous calendar month; the window is the only restriction.

History beyond the window is sold as one-off download bundles of the closed months. Each bundle carries all three datasets, is frozen at purchase, and is perpetual on the account — every API key you hold inherits it:

Bundle Markets Price
Tessera Majors BTC, ETH, SOL, HYPE $19 once
Tessera HIP-3 (xyz) Every xyz: HIP-3 market $24 once
Tessera All Markets Every coin Tessera publishes $29 once

The open month is never included. datasets() and partitions() already reflect your entitlement, so the client needs no plan logic of its own. See pricing for the full comparison.

Quickstart

use tessera::TesseraClient;

fn main() -> Result<(), tessera::TesseraError> {
    let client = TesseraClient::new(None)?; // reads $TESSERA_API_KEY

    // Partitions roll on a trailing 30-day window, so discover the newest
    // available month instead of hardcoding a date:
    let latest = client
        .partitions("gold_ohlcv_1m", Some("BTC"), None)?
        .partitions
        .pop()
        .expect("at least one partition");

    let df = client.read("gold_ohlcv_1m", "BTC", &latest.month, None)?;
    println!("{} rows for {}", df.height(), latest.month);
    println!("{}", df.head(Some(5)));
    Ok(())
}

Lazy scans

scan mints presigned URLs and returns a LazyFrame; the Parquet bytes are only read when you .collect(). Filters and column selections push down to object storage:

use polars::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = tessera::TesseraClient::new(None)?;

    let lf = client.scan(
        "gold_ohlcv_1m",
        "BTC",
        "2026-10",
        Some(&["time", "close", "volume", "buy_vol", "sell_vol"]),
    )?;

    // Daily bars from 1-minute data — filters and projections are pushed down
    // to object storage; only the columns touched cross the wire.
    let daily = lf
        .filter(col("close").gt(lit(50_000.0)))
        .group_by([col("time").dt().date().alias("day")])
        .agg([
            col("close").last().alias("close"),
            col("volume").sum().alias("volume"),
            (col("buy_vol").sum() / col("volume").sum()).alias("buy_share"),
        ])
        .sort(["day"], SortMultipleOptions::default())
        .collect()?;
    println!("{daily}");
    Ok(())
}

Presigned URLs are short-lived (~15 minutes). Collect promptly; for long-lived graphs, re-run scan to mint fresh URLs.

Multiple coins and months

coin and month arguments accept a single value or any collection; months also accept an inclusive MonthSpan. Multi-partition reads append coin/month columns so rows stay attributable to their source partition:

use tessera::{MonthSpan, TesseraClient};

fn main() -> Result<(), tessera::TesseraError> {
    let client = TesseraClient::new(None)?;

    let df = client.read(
        "gold_ohlcv_1m",
        &["BTC", "ETH", "SOL"],                 // any IntoCoins: one symbol, a slice, a Vec, …
        MonthSpan::new("2026-10", "2026-11")?,  // any IntoMonths: one month, a span, a list, …
        Some(&["time", "open", "high", "low", "close", "volume"]),
    )?;
    println!("{}", df.head(Some(5)));
    Ok(())
}

The current month is day-backed: it has no single month object, so the API publishes one Parquet per day. read, scan and to_duckdb concatenate those day objects transparently — a partition is still one logical month, and provenance columns stay per partition.

Months outside the trailing 30-day window are not served (TesseraError::NotFound) unless your account holds a bundle covering them — call partitions() to discover what's available, as in the quickstart.

Async

Inside a tokio runtime, use AsyncTesseraClient (the sync client owns a private runtime and must not be constructed from async code):

use tessera::AsyncTesseraClient;

#[tokio::main]
async fn main() -> Result<(), tessera::TesseraError> {
    let client = AsyncTesseraClient::new(None)?;

    let df = client
        .read("gold_ohlcv_1m", &["BTC", "ETH"], "2026-10", None)
        .await?;
    println!("{} rows", df.height());
    Ok(())
}

SQL with DuckDB

Opt in to the duckdb feature (drop the default polars feature if you don't need both):

tessera-api = { version = "0.1", default-features = false, features = ["duckdb"] }

to_duckdb returns an in-memory connection exposing a tessera view over the presigned Parquet; filters and aggregations push down to object storage via httpfs:

use tessera::TesseraClient;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = TesseraClient::new(None)?;
    let conn = client.to_duckdb(
        "gold_ohlcv_1m",
        &["BTC", "ETH"],
        "2026-10",
        Some(&["time", "close", "volume"]),
    )?;

    let mut stmt =
        conn.prepare("SELECT coin, count(*), round(avg(close), 2) FROM tessera GROUP BY coin")?;
    let rows = stmt.query_map([], |row| {
        Ok((
            row.get::<_, String>(0)?,
            row.get::<_, i64>(1)?,
            row.get::<_, f64>(2)?,
        ))
    })?;
    for row in rows {
        let (coin, n, avg_close) = row?;
        println!("{coin}: {n} bars, avg close {avg_close}");
    }
    Ok(())
}

Configuration

use std::time::Duration;

use tessera::{ClientConfig, TesseraClient};

fn main() -> Result<(), tessera::TesseraError> {
    let mut config = ClientConfig::new(None)?; // API key from $TESSERA_API_KEY
    config.timeout = Duration::from_secs(60);
    config.max_retries = 5;

    let client = TesseraClient::from_config(config)?;
    let _ = client.datasets()?;
    Ok(())
}

ClientConfig also exposes base_url and user_agent.

Error handling

Every failure is a TesseraError; match on the variants you care about (or use the status_code() / code() helpers):

use tessera::{TesseraClient, TesseraError};

fn main() -> Result<(), TesseraError> {
    let client = TesseraClient::new(None)?;

    // Months outside the trailing 30-day window 404 → NotFound unless a
    // bundle covers them:
    match client.read("gold_ohlcv_1m", "BTC", "2024-01", None) {
        Ok(df) => println!("{}", df.head(Some(5))),
        Err(TesseraError::NotFound { message, .. }) => {
            eprintln!("no such partition: {message}");
        }
        Err(TesseraError::PresignExpired) => {
            eprintln!("presigned URL expired — call read()/scan() again for fresh ones");
        }
        Err(err) => return Err(err),
    }
    Ok(())
}

The raw API

The typed endpoints are also available directly — for browsing the catalog or fetching the Parquet bytes yourself:

fn main() -> Result<(), tessera::TesseraError> {
    let client = tessera::TesseraClient::new(None)?;

    // Every dataset visible to your entitlement: name, coins, month coverage, partition count.
    for ds in &client.datasets()?.datasets {
        let earliest = ds.months.earliest.as_deref().unwrap_or("?");
        let latest = ds.months.latest.as_deref().unwrap_or("?");
        println!("{} · {} coins · {earliest}…{latest}", ds.name, ds.coins.len());
    }

    // Per-partition detail for one dataset: month, row count, on-disk size, …
    for p in &client.partitions("gold_ohlcv_1m", Some("BTC"), None)?.partitions {
        let rows = p.rows.map_or_else(|| "-".to_string(), |r| r.to_string());
        println!("{} · {rows} rows · {} MiB", p.month, p.size_bytes / (1024 * 1024));
    }

    // Presigned download URLs for a single partition: one object for a
    // finalised month, one per day for the day-backed open month.
    let download = client.download_url("gold_ohlcv_1m", "BTC", "2026-10")?;
    for url in tessera::download_urls(download)? {
        println!("{url}");
    }
    Ok(())
}

Documentation

License

GPL-3.0 © Tessera. See LICENSE.