tessera-api
Clean Hyperliquid market data — straight into Polars & DuckDB.

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 BTC, ETH, SOL and HYPE for the trailing month.
Quickstart
use tessera::TesseraClient;
fn main() -> Result<(), tessera::TesseraError> {
let client = TesseraClient::new(None)?;
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-08",
Some(&["time", "close", "volume", "buy_vol", "sell_vol"]),
)?;
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"], MonthSpan::new("2026-07", "2026-08")?, Some(&["time", "open", "high", "low", "close", "volume"]),
)?;
println!("{}", df.head(Some(5)));
Ok(())
}
Months outside the trailing 12-month window are no longer served (TesseraError::NotFound)
— 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-08", 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-08",
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)?; 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)?;
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)?;
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());
}
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));
}
let download = client.download_url("gold_ohlcv_1m", "BTC", "2026-08")?;
println!("{} (expires at {})", download.url, download.expires_at);
Ok(())
}
Documentation
License
GPL-3.0 © Tessera. See LICENSE.