Rust SDK - Polaris

The Polaris Rust SDK is available on crates.io as polaris-data.

Install

cargo add polaris-data

If your project does not already use Tokio, add it as well:

cargo add tokio --features macros,rt-multi-thread

The package name is polaris-data and the crate name is polaris_data. Or add it manually to Cargo.toml:

[dependencies]
polaris-data = "0.11"

The SDK is async-first and is designed for Tokio-based services, backfills, and trading infrastructure.

Quickstart

Use events(...) when you want standardized historical rows in an async service or backfill job.

use futures_util::StreamExt;
use polaris_data::{HistoricalQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let mut rows = client
        .events(HistoricalQuery {
            source: "hyperliquid".into(),
            market: "BTC".into(),
            from: Some("2024-01-01T00:00:00Z".into()),
            to: Some("2024-01-01T01:00:00Z".into()),
            allow_gaps: false,
            materialize_orderbooks: true,
        })
        .await?;

    let mut count = 0;
    while let Some(row) = rows.next().await {
        println!("{:?}", row?);
        count += 1;
    }
    println!("Fetched {count} events");
    Ok(())
}

Create a client

If you omit api_key, the client reads POLARIS_API_KEY from the environment.

use polaris_data::PolarisClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;
    println!("{}", client.health().await?);
    Ok(())
}

The main builder is:

use std::time::Duration;

use polaris_data::PolarisClient;

let client = PolarisClient::builder()
    .api_key("polaris_key_your_key")
    .base_url("https://api.polaris.supply")
    .timeout(Duration::from_secs(30))
    .dataset_root("/tmp/polaris-cache")
    .build()?;

Core methods

Use PolarisClient for discovery and snapshot-backed historical queries.

Method	Returns	Use it for
`health()`	JSON object	Confirm API availability
`catalog(CatalogQuery)`	`CatalogResponse`	Discover sources and exact market IDs
`list_snapshots(ListSnapshotsQuery)`	`Vec<SnapshotEntry>`	Find snapshot files for a range
`replay(ReplayQuery)`	`ReplayStream`	Stream standardized historical rows
`events(HistoricalQuery)`	`HistoricalStream<StandardEvent>`	Process mixed event types with bounded memory
`trades(HistoricalQuery)`	`HistoricalStream<TradeEvent>`	Analyze executions
`intents(HistoricalQuery)`	`HistoricalStream<IntentEvent>`	Analyze RFQs, quotes, executable intents, and settlements
`option_tickers(OptionTickerQuery)`	`HistoricalStream<OptionTickerEvent>`	Read a whole option chain or one exact contract
`perpetual_tickers(HistoricalQuery)`	`HistoricalStream<PerpetualTickerEvent>`	Read partial venue-published prices, open interest, premium, and funding state
`ohlcv(OhlcvQuery)`	`OhlcvOutput`	Build bars or TradingView-style output
`l2_snapshots(HistoricalQuery)`	`HistoricalStream<OrderbookEvent>`	Order book reconstruction and microstructure analysis
`l2_updates(HistoricalQuery)`	`HistoricalStream<StandardEvent>`	High-throughput application-managed books
`funding_rates(HistoricalQuery)`	`HistoricalStream<PointSeriesEvent>`	Perpetual funding studies and carry modeling
`mark_prices(HistoricalQuery)`	`HistoricalStream<PointSeriesEvent>`	Basis analysis, mark tracking, and liquidation-related research
`volume(OhlcvQuery)`	`Vec<VolumeBar>`	Bucketed trade volume series for volume profiling and participation analysis
`vwap(OhlcvQuery)`	`Vec<VwapBar>`	Bucketed VWAP series for execution benchmarking and price smoothing
`volatility(OhlcvQuery)`	`Vec<VolatilityBar>`	Bucketed realized volatility series for risk modeling and intraperiod volatility analysis
`bbo(BboQuery)`	`HistoricalStream<BboQuote>`	Best bid/offer quotes with optional native interval coalescing
`bbo_changes(BboQuery)`	`HistoricalStream<BboQuote>`	Best bid/offer changes with deep and no-op updates suppressed
`depth_metrics(HistoricalQuery, depth_pct, slippage_notional)`	`HistoricalStream<DepthMetricsRow>`	Derived depth, spread, imbalance, and slippage metrics for liquidity analysis and market impact estimation

from and to accept ISO 8601 strings, chrono::DateTime<Utc>, or Unix epoch milliseconds as i64 or u64. If you omit one or both bounds, the SDK infers a bounded historical range from catalog metadata, using the latest 7 days by default and applying public cutoff rules for preview datasets when no API key is present. Set materialize_orderbooks: true on HistoricalQuery, ReplayQuery, and StreamQuery for the default reconstruction behavior. Snapshots replace the complete state, deltas update listed prices, and zero quantity deletes a price. Books clear across gaps and reconnects, with deltas skipped until a new snapshot. Use l2_updates(...) for raw snapshots and deltas, then feed selected updates into the exported OrderbookBuilder for application-managed books.

Match event schema versions

StandardEvent is an untagged wire-compatible enum. Match StandardEvent::Legacy or StandardEvent::V2 when you need the stored envelope. The shared event.timestamp() accessor returns legacy timestamp or v2 collector_timestamp; it does not add a timestamp field to v2 rows.

use polaris_data::StandardEvent;

match &event {
    StandardEvent::Legacy(row) => println!("{}", row.timestamp),
    StandardEvent::V2(row) => println!("{:?}", row.exchange_timestamp),
}
println!("SDK time: {}", event.timestamp());

See Event envelope, Trades, and L2 snapshots and updates for v2 field and ordering changes.

Discover a market before you query it

Use catalog(...) to find the exact Polaris market ID for a venue.

use polaris_data::{CatalogQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let catalog = client
        .catalog(CatalogQuery {
            source: Some("hyperliquid".into()),
            market: None,
        })
        .await?;

    let markets: Vec<_> = catalog.markets.iter().map(|row| row.market.as_str()).collect();
    println!("{:?}", &markets[..markets.len().min(10)]);
    Ok(())
}

If you want a high-level view of supported venues and example market IDs before you query the exact pair, start with Market Coverage.

Query events

Use events(...) when you want standardized historical event rows beyond trades alone.

use futures_util::StreamExt;
use polaris_data::{HistoricalQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let mut rows = client
        .events(HistoricalQuery {
            source: "hyperliquid".into(),
            market: "BTC".into(),
            from: Some("2024-01-01T00:00:00Z".into()),
            to: Some("2024-01-01T01:00:00Z".into()),
            allow_gaps: false,
            materialize_orderbooks: true,
        })
        .await?;

    println!("{:?}", rows.next().await.transpose()?);
    Ok(())
}

Query trades

trades(...) returns normalized trade events. The SDK loads standardized snapshot data locally and filters trade rows for you.

use futures_util::StreamExt;
use polaris_data::{HistoricalQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let mut trades = client
        .trades(HistoricalQuery {
            source: "hyperliquid".into(),
            market: "SPX".into(),
            from: Some("2024-01-01T00:00:00Z".into()),
            to: Some("2024-01-01T01:00:00Z".into()),
            allow_gaps: false,
            materialize_orderbooks: true,
        })
        .await?;

    println!("{:?}", trades.next().await.transpose()?);
    Ok(())
}

Query intents and RFQs

intents(...) returns typed RFQ, quote, executable-intent, and settlement observations in stored order. Use market: "intents" and correlate rows by their captured rfq_id or intent_id.

use futures_util::StreamExt;
use polaris_data::{HistoricalQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;
    let mut observations = client
        .intents(HistoricalQuery {
            source: "uniswapx".into(),
            market: "intents".into(),
            from: None,
            to: None,
            allow_gaps: false,
            materialize_orderbooks: false,
        })
        .await?;

    println!("{:?}", observations.next().await.transpose()?);
    Ok(())
}

See the Intents and RFQs guide for lifecycle reconstruction and the schema reference for fields.

Query option tickers

Use option_tickers(...) with an underlying market such as BTC. Set instrument: None for the whole option chain, or provide one exact venue-native contract.

use futures_util::StreamExt;
use polaris_data::{OptionTickerQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;
    let mut tickers = client
        .option_tickers(OptionTickerQuery {
            source: "aevo".into(),
            market: "BTC".into(),
            instrument: None,
            from: None,
            to: None,
            allow_gaps: false,
        })
        .await?;

    println!("{:?}", tickers.next().await.transpose()?);
    Ok(())
}

Every option ticker event keeps source, the normalized underlying market, and the non-empty exact instrument separate. See Option tickers for the payload fields and realtime filtering behavior.

Query perpetual tickers

Use perpetual_tickers(...) to stream partial venue-published market state for a perpetual market.

use futures_util::StreamExt;
use polaris_data::{HistoricalQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;
    let mut tickers = client
        .perpetual_tickers(HistoricalQuery {
            source: "hyperliquid".into(),
            market: "BTC".into(),
            from: None,
            to: None,
            allow_gaps: false,
            materialize_orderbooks: false,
        })
        .await?;

    if let Some(ticker) = tickers.next().await {
        let ticker = ticker?;
        println!(
            "{} {:?}",
            ticker.timestamp(),
            ticker.data().mark_price.as_deref()
        );
    }
    Ok(())
}

The crate exports PerpetualTickerData, LegacyPerpetualTickerEvent, PerpetualTickerEventV2, and their PerpetualTickerEvent enum. Its timestamp(), source(), market(), and data() accessors work across both event versions. The blocking client exposes the equivalent method, and PreparedHistoricalReplay::perpetual_tickers() can filter already resolved local files without another coverage or download request. Generic events, replay, and realtime stream methods include these events automatically. See Perpetual tickers for all payload fields and validation rules.

Query OHLCV bars

Use ohlcv(...) when you want interval bars instead of individual trades.

use polaris_data::{OhlcvFormat, OhlcvInterval, OhlcvOutput, OhlcvQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let output = client
        .ohlcv(OhlcvQuery {
            source: "hyperliquid".into(),
            market: "BTC".into(),
            from: Some("2024-01-01T00:00:00Z".into()),
            to: Some("2024-01-02T00:00:00Z".into()),
            interval: OhlcvInterval::M1,
            format: OhlcvFormat::TradingView,
            allow_gaps: false,
        })
        .await?;

    match output {
        OhlcvOutput::Bars(bars) => println!("{} bars", bars.len()),
        OhlcvOutput::TradingView(tv) => println!("{} candles", tv.candles.len()),
    }

    Ok(())
}

Supported intervals are 100ms, 1s, 10s, 1m, 5m, 15m, and 1h.

Query order book snapshots

Use l2_snapshots(...) when you need order book depth data for microstructure analysis.

use futures_util::StreamExt;
use polaris_data::{HistoricalQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let mut snapshots = client
        .l2_snapshots(HistoricalQuery {
            source: "hyperliquid".into(),
            market: "BTC".into(),
            from: Some("2024-01-01T00:00:00Z".into()),
            to: Some("2024-01-01T00:05:00Z".into()),
            allow_gaps: false,
            materialize_orderbooks: true,
        })
        .await?;

    println!("{:?}", snapshots.next().await.transpose()?);
    Ok(())
}

Use l2_updates(...) when you want to manage reconstruction in your application. It returns raw StandardEvent snapshots and deltas that can be passed directly to OrderbookBuilder::update, regardless of the query’s materialize_orderbooks field. Call OrderbookBuilder::snapshot only when you need a complete sorted book; apply retains the previous combined behavior.

Query funding rates

Use funding_rates(...) to analyze perpetual funding rates and carry modeling.

use futures_util::StreamExt;
use polaris_data::{HistoricalQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let mut funding_rates = client
        .funding_rates(HistoricalQuery {
            source: "hyperliquid".into(),
            market: "BTC".into(),
            from: Some("2024-01-01T00:00:00Z".into()),
            to: Some("2024-01-02T00:00:00Z".into()),
            allow_gaps: false,
            materialize_orderbooks: true,
        })
        .await?;

    println!("{:?}", funding_rates.next().await.transpose()?);
    Ok(())
}

Query mark prices

Use mark_prices(...) for basis analysis, mark tracking, and liquidation-related research.

use futures_util::StreamExt;
use polaris_data::{HistoricalQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let mut mark_prices = client
        .mark_prices(HistoricalQuery {
            source: "hyperliquid".into(),
            market: "BTC".into(),
            from: Some("2024-01-01T00:00:00Z".into()),
            to: Some("2024-01-02T00:00:00Z".into()),
            allow_gaps: false,
            materialize_orderbooks: true,
        })
        .await?;

    println!("{:?}", mark_prices.next().await.transpose()?);
    Ok(())
}

Query volume profiles

Use volume(...) for volume profiling and participation analysis.

use polaris_data::{OhlcvInterval, OhlcvQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let volume = client
        .volume(OhlcvQuery {
            source: "hyperliquid".into(),
            market: "SPX".into(),
            from: Some("2024-01-01T00:00:00Z".into()),
            to: Some("2024-01-01T06:00:00Z".into()),
            interval: OhlcvInterval::H1,
            allow_gaps: false,
        })
        .await?;

    println!("{:?}", volume.first());
    Ok(())
}

Query VWAP series

Use vwap(...) for execution benchmarking and price smoothing.

use polaris_data::{OhlcvInterval, OhlcvQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let vwap = client
        .vwap(OhlcvQuery {
            source: "hyperliquid".into(),
            market: "SPX".into(),
            from: Some("2024-01-01T00:00:00Z".into()),
            to: Some("2024-01-01T06:00:00Z".into()),
            interval: OhlcvInterval::H1,
            allow_gaps: false,
        })
        .await?;

    println!("{:?}", vwap.first());
    Ok(())
}

Query volatility series

Use volatility(...) for risk modeling and intraperiod volatility analysis.

use polaris_data::{OhlcvInterval, OhlcvQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let volatility = client
        .volatility(OhlcvQuery {
            source: "hyperliquid".into(),
            market: "SPX".into(),
            from: Some("2024-01-01T00:00:00Z".into()),
            to: Some("2024-01-01T06:00:00Z".into()),
            interval: OhlcvInterval::H1,
            allow_gaps: false,
        })
        .await?;

    println!("{:?}", volatility.first());
    Ok(())
}

Query best bid/offer

Use bbo(...) for spread tracking, quote analytics, and top-of-book monitoring. Use bbo_changes(...) with the same query when only actual best-price or best-quantity changes should be emitted.

use futures_util::StreamExt;
use polaris_data::{BboQuery, OhlcvInterval, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let mut bbo_quotes = client
        .bbo(BboQuery {
            source: "hyperliquid".into(),
            market: "BTC".into(),
            from: Some("2024-01-01T00:00:00Z".into()),
            to: Some("2024-01-01T00:30:00Z".into()),
            allow_gaps: false,
            interval: Some(OhlcvInterval::S1),
        })
        .await?;

    println!("{:?}", bbo_quotes.next().await.transpose()?);
    Ok(())
}

Query depth metrics

Use depth_metrics(...) for liquidity analysis and market impact estimation.

use futures_util::StreamExt;
use polaris_data::{HistoricalQuery, PolarisClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = PolarisClient::builder().build()?;

    let mut depth_metrics = client
        .depth_metrics(
            HistoricalQuery {
                source: "hyperliquid".into(),
                market: "BTC".into(),
                from: Some("2024-01-01T00:00:00Z".into()),
                to: Some("2024-01-01T00:30:00Z".into()),
                allow_gaps: false,
                materialize_orderbooks: true,
            },
            Some(0.01),    // depth_pct
            Some(10000.0), // slippage_notional
        )
        .await?;

    println!("{:?}", depth_metrics.next().await.transpose()?);
    Ok(())
}

Local dataset storage

The SDK stores standardized snapshots and local cache data under the shared Polaris app-data root so the Rust SDK and other Polaris tools can reuse the same files. Default roots:

macOS: ~/Library/Application Support/polaris
Linux: $XDG_DATA_HOME/polaris or ~/.local/share/polaris
Windows: %APPDATA%\\polaris

Within that root, the SDK uses this layout:

<root>/
  data/
  tmp/
  cache/

Use dataset_root(...) on the builder to override the root explicitly.

POLARIS_ROOT overrides the shared root globally.
POLARIS_DATASET_DOWNLOAD_DIR is still accepted as a deprecated compatibility override.

Snapshot-first replay

Standardized historical methods—including replay(...), events(...), trades(...), option_tickers(...), perpetual_tickers(...), and ohlcv(...)—use snapshot-first replay. See Snapshots for the full flow.

Gap handling

By default, snapshot-backed methods fail if the requested range is not fully covered by available standardized snapshots. Set allow_gaps: true when you want the SDK to:

return only covered rows
skip missing intervals
emit a log::warn! entry describing the gaps

Authentication

Public sources work without an API key. For premium sources or extended history, set your key via POLARIS_API_KEY or configure it directly on the builder:

export POLARIS_API_KEY="polaris_key_your_key"

See Quickstart for the shared auth model.

Next steps

Read Quickstart if you want the shared auth model behind the SDK.
Read Snapshots if your Rust workflow starts from historical files.
Read Trades, Perpetual tickers, Events, or OHLCV for detailed method documentation.

​Install

​Quickstart

​Create a client

​Core methods

​Match event schema versions

​Discover a market before you query it

​Query events

​Query trades

​Query intents and RFQs

​Query option tickers

​Query perpetual tickers

​Query OHLCV bars

​Query order book snapshots

​Query funding rates

​Query mark prices

​Query volume profiles

​Query VWAP series

​Query volatility series

​Query best bid/offer

​Query depth metrics

​Local dataset storage

​Snapshot-first replay

​Gap handling

​Authentication

​Next steps