Polaris SDKs

The official Rust, Python, and TypeScript SDKs for the Polaris API. Rust and Python share one Rust engine; TypeScript is an independent Node.js and browser package. All three distributions are named polaris-data, with Python importing as polaris_data.

Documentation can be found at https://polaris.supply/docs

Install

Install the Python SDK from PyPI:

pip install polaris-data

If you use uv, install it into a project with:

uv add polaris-data

Or install it into the active environment with:

uv pip install polaris-data

Install the Rust SDK from crates.io:

cargo add polaris-data

Install the TypeScript SDK from npm:

npm install polaris-data

Python wheels always include the Rust core. CPython 3.9+ is supported through PyO3's stable ABI; there is no pure-Python runtime fallback.

Quickstart

from polaris_data import PolarisClient

with PolarisClient(api_key="polaris_key_your_key") as client:
    row_count = sum(
        1
        for _ in client.replay(
            source="binance",
            market="BTC-USDT",
            from_="2024-01-01T00:00:00Z",
            to="2024-01-01T01:00:00Z",
        )
    )
    print(f"Replayed {row_count} rows")

If api_key is omitted, the client reads POLARIS_API_KEY from the environment.

The equivalent async Rust workflow is:

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

#[tokio::main]
async fn main() -> Result<(), polaris_data::PolarisError> {
    let client = PolarisClient::builder().build()?;
    let mut rows = client
        .replay(ReplayQuery {
            source: "binance".into(),
            market: "BTC-USDT".into(),
            from: Some("2024-01-01T00:00:00Z".into()),
            to: Some("2024-01-01T01:00:00Z".into()),
            allow_gaps: false,
            materialize_orderbooks: true,
        })
        .await?;

    while let Some(row) = rows.next().await {
        println!("{:?}", row?);
    }
    Ok(())
}

For synchronous Rust applications use polaris_data::blocking::PolarisClient. It owns a Tokio runtime and returns PolarisError::BlockingInAsyncRuntime when called from an active Tokio runtime, instead of panicking.

Realtime streams

stream(...) opens an unbounded WebSocket feed of the same standardized event shape returned by replay(...). A stream covers one source and up to 1,000 markets, reconnects automatically after transport failures, and closes when its iterator is dropped or explicitly closed.

from polaris_data import PolarisClient

with PolarisClient(api_key="polaris_key_your_key") as client:
    with client.stream(source="binance", markets=["BTC-USDT", "ETH-USDT"]) as events:
        for event in events:
            print(event)

The equivalent async Rust workflow is:

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

#[tokio::main]
async fn main() -> Result<(), polaris_data::PolarisError> {
    let client = PolarisClient::builder().build()?;
    let mut events = client.stream(StreamQuery {
        source: "binance".into(),
        markets: vec!["BTC-USDT".into(), "ETH-USDT".into()],
        include_buffer: false,
        materialize_orderbooks: true,
    }).await?;

    while let Some(event) = events.next().await {
        println!("{:?}", event?);
    }
    Ok(())
}

Orderbooks are materialized by default. A standardized orderbook event replaces the complete book; each orderbook_delta updates only its listed prices, and a zero quantity deletes that price. Materialized output is relabeled orderbook and uses sorted {price, quantity} levels. Set materialize_orderbooks=False (Python), materialize_orderbooks: false (Rust), or materializeOrderbooks: false (TypeScript) to receive raw deltas.

Reconnection is best-effort: the current live protocol has no resume cursor, so a reconnect can introduce a gap or duplicate event. The SDK clears reconstructed books on reconnect and suppresses later deltas until a new snapshot arrives. Protocol and authentication errors are terminal and are not retried.

Reusable OrderbookBuilder exports in all three SDKs provide the same behavior:

from polaris_data import OrderbookBuilder

books = OrderbookBuilder()
complete = books.apply(snapshot)
complete = books.apply(delta)  # None until a snapshot; otherwise a full book
books.clear_book("lighter", "BTC-USD")

PolarisClient API

PolarisClient is the main sync client for the SDK:

PolarisClient(
    api_key=None,
    base_url="https://api.polaris.supply",
    timeout=30.0,
    dataset_root=None,
    stream_url=None,
)

Use it to inspect available data, query historical market data, and open realtime streams.

Discovery

Method Returns Use case
health() API health/status payload Connectivity checks and startup validation
catalog(source=None, market=None, q=None) Source/market metadata, including normalized instrument fields Discover supported datasets, markets, instrument metadata, and time coverage

Access patterns

Method Returns Use case
replay(source=..., market=..., from_=None, to=None, standard=True, allow_gaps=False, parallel=False, materialize_orderbooks=True) Iterator of historical events Backfills, notebooks, and replay-style processing without materializing everything up front
stream(source=..., markets=[...], include_buffer=False, materialize_orderbooks=True) Closeable iterator of realtime events Open-ended normalized market data with automatic reconnection
raw(source=..., market=..., from_=None, to=None, limit=1000) List of raw source payloads Inspect exchange-native payloads and compare raw vs standardized schemas

Standardized Data Schemas

Method Returns Use case
events(source=..., market=..., from_=None, to=None, allow_gaps=False, materialize_orderbooks=True) Iterator of standardized historical events General-purpose historical analysis without retaining every row
trades(source=..., market=..., from_=None, to=None, allow_gaps=False) Iterator of standardized trade events Trade-level analytics, execution studies, and derived bar calculations
l2_snapshots(source=..., market=..., from_=None, to=None, allow_gaps=False, materialize_orderbooks=True) Iterator of complete orderbook rows Order book reconstruction and microstructure analysis
funding_rates(source=..., market=..., from_=None, to=None, allow_gaps=False) Iterator of funding-rate point series rows Perpetual funding studies and carry modeling
mark_prices(source=..., market=..., from_=None, to=None, allow_gaps=False) Iterator of mark-price point series rows Basis analysis, mark tracking, and liquidation-related research
ohlcv(source=..., market=..., from_=None, to=None, interval=..., format=None, allow_gaps=False) Aggregated OHLCV bars Charting, bar-based strategies, and downstream TA workflows
volume(source=..., market=..., from_=None, to=None, interval=..., allow_gaps=False) Bucketed trade volume series Volume profiling and participation analysis
vwap(source=..., market=..., from_=None, to=None, interval=..., allow_gaps=False) Bucketed VWAP series Execution benchmarking and price smoothing
volatility(source=..., market=..., from_=None, to=None, interval=..., method="log_returns", allow_gaps=False) Bucketed realized volatility series Risk modeling and intraperiod volatility analysis
bbo(source=..., market=..., from_=None, to=None, interval=None, allow_gaps=False) Iterator of best bid/offer quotes Spread tracking, quote analytics, and top-of-book monitoring
depth_metrics(source=..., market=..., from_=None, to=None, depth_pct=0.01, slippage_notional=10000.0, allow_gaps=False) Iterator of derived liquidity metrics Liquidity analysis and market impact estimation

Historical row methods are single-pass iterators. Iterate them directly for bounded memory, or call list(...) when you intentionally want an eager result. Setup and coverage errors occur when the method is called; decode errors can occur later while iterating. If you stop early, call the generator's close() method to promptly release its native reader. bbo(interval="1s") emits the last quote from each non-empty, UTC-aligned interval.

For parameter details, response shapes, and end-to-end examples, see the Python SDK docs.

Streaming benchmark

Run the opt-in end-to-end benchmark after building the Python extension:

uv run python benchmarks/streaming_memory.py

It generates a 3,000-level local book with one million deltas, consumes raw standardized events, direct BBO, and materialized L2 streams in isolated processes, and reports end-to-end wall time, rows per second, and peak RSS. The command fails when peak RSS from 100,000 to one million deltas grows by more than the larger of 20% or 64 MiB, or when long-run throughput falls below 75% of short-run throughput.

Reference results from a local development build:

Mode Scale Throughput Peak RSS
Raw events 1,000,001 rows ~83k rows/s ~36 MiB
Direct BBO 1,000,001 quotes ~173k rows/s ~35 MiB
Materialized 3,000-level L2 1,001 books ~73 books/s ~65 MiB

Use three isolated runs to compare median speed reliably, and optionally set machine-specific throughput floors:

uv run python benchmarks/streaming_memory.py --runs 3 \
  --min-rps events=50000 --min-rps bbo=100000 --min-rps l2=50

Use --modes events bbo for a faster run that skips full-book materialization. Absolute throughput floors are intentionally opt-in because results vary by hardware and build profile.

Local dataset storage

Standardized snapshots are stored under the shared Polaris app-data root so the Python SDK and CLI can reuse the same files. Legacy materialized day files are also recognized when present.

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 the same layout as the CLI:

<root>/
  data/
  daily/
  tmp/
  cache/
  locks/

Standardized snapshot downloads are stored under:

<root>/data/<tier>/<source>/<market>/<YYYY-MM-DD>/<opaque-key>.jsonl.zst

The opaque key is the flat upstream snapshot identifier, for example:

standard-aster-ASTERUSDT-2026-06-01-00

which is stored on disk as:

<root>/data/standard/aster/ASTERUSDT/2026-06-01/standard-aster-ASTERUSDT-2026-06-01-00.jsonl.zst

Compatible materialized day files, when present, are stored under:

<root>/daily/<source>/<market>/<YYYY-MM-DD>.jsonl.zst

Pass dataset_root=... to PolarisClient(...) 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

For standardized historical data, replay(...), events(...), trades(...), vwap(...), volatility(...), bbo(...), depth_metrics(...), l2_snapshots(...), volume(...), and default/tradingview ohlcv(...) now prefer /snapshots plus daily bulk /download?source=...&market=...&date=...&mode=json manifests, and reuse local snapshot files when they already exist:

from polaris_data import PolarisClient

with PolarisClient(api_key="polaris_key_your_key") as client:
    for row in client.replay(
        source="binance",
        market="BTC-USDT",
        from_="2024-01-01T00:00:00Z",
        to="2024-01-01T01:00:00Z",
    ):
        print(row)

If the requested standardized range cannot be satisfied from available standardized snapshots, replay(...), events(...), trades(...), vwap(...), volatility(...), bbo(...), depth_metrics(...), l2_snapshots(...), volume(...), and ohlcv(...) raise by default instead of falling back. Pass allow_gaps=True on standardized methods to return only covered data and receive a warning with the missing intervals.

Error handling

from polaris_data import PolarisClient, RateLimitedError, UnauthorizedError

client = PolarisClient()

try:
    client.replay(
        source="binance",
        market="BTC-USDT",
        from_="2024-01-01T00:00:00Z",
        to="2024-01-01T01:00:00Z",
    )
except UnauthorizedError:
    print("API key is required")
except RateLimitedError as err:
    print(f"Rate limited. Reset at: {err.reset_at}")

Tests

uv run pytest
cargo test --workspace
cd typescript && npm ci && npm run typecheck && npm test

Build and inspect the native Python wheel with:

uv run --with maturin maturin build --release

Python, Rust, and TypeScript are versioned independently. Python releases use python-vX.Y.Z tags and publish polaris-data to PyPI; Rust releases use rust-vX.Y.Z tags and publish polaris-data to crates.io; TypeScript releases use typescript-vX.Y.Z tags and publish polaris-data to npm.

Project links

Data verified by PyPI on Aug 10, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.16.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for hilliamt from gravatar.com hilliamt

Credits

Author: Polaris

GitHub Statistics

Data verified by PyPI on Aug 10, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.9

Tags

polaris market-data trading sdk

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

polaris_data-0.11.0.tar.gz (73.1 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

polaris_data-0.11.0-cp39-abi3-win_arm64.whl (3.4 MB view details)

Uploaded CPython 3.9+Windows ARM64

polaris_data-0.11.0-cp39-abi3-win_amd64.whl (3.6 MB view details)

Uploaded CPython 3.9+Windows x86-64

polaris_data-0.11.0-cp39-abi3-musllinux_1_2_x86_64.whl (4.5 MB view details)

Uploaded CPython 3.9+musllinux: musl 1.2+ x86-64

polaris_data-0.11.0-cp39-abi3-musllinux_1_2_aarch64.whl (4.3 MB view details)

Uploaded CPython 3.9+musllinux: musl 1.2+ ARM64

polaris_data-0.11.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.1 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

polaris_data-0.11.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (4.1 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

polaris_data-0.11.0-cp39-abi3-macosx_11_0_arm64.whl (3.6 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

polaris_data-0.11.0-cp39-abi3-macosx_10_12_x86_64.whl (3.8 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file polaris_data-0.11.0.tar.gz.

File metadata

  • Download URL: polaris_data-0.11.0.tar.gz
  • Upload date:
  • Size: 73.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for polaris_data-0.11.0.tar.gz
Algorithm Hash digest
SHA256 007b677f6605d2e550903e6e5bf1c0898e764847e3b03b8df3284465e9e5a602
MD5 a16e14319287c7bf61a65f5dbc0af960
BLAKE2b-256 c534375cf700d312c6244c630632360e9b703f13996067ceef140a40122f4d35

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.11.0.tar.gz:

Publisher: release-python.yml on polaris-data/sdks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polaris_data-0.11.0-cp39-abi3-win_arm64.whl.

File metadata

File hashes

Hashes for polaris_data-0.11.0-cp39-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 e46db1523b4317e01551344d347ab2ad348b2097ed6c8d7c80fdbd0f18acd41b
MD5 a4e103eb37e47b1953c0a930643de55e
BLAKE2b-256 ef37f45a63fe0c0f2bd5b70343bd7f4796e7090fd79b306af04833e5832912de

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.11.0-cp39-abi3-win_arm64.whl:

Publisher: release-python.yml on polaris-data/sdks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polaris_data-0.11.0-cp39-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for polaris_data-0.11.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 20e50cf3fc1012101b56b75613b5f6e918dc3f8950234a6f0f4910cc33dfccbd
MD5 bf306390d79efe8d63bd194ece470392
BLAKE2b-256 5b9b1dd028b2ec63ddb4115ce8bcde4b4a5547dab1b57447601b3209bc59c54c

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.11.0-cp39-abi3-win_amd64.whl:

Publisher: release-python.yml on polaris-data/sdks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polaris_data-0.11.0-cp39-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for polaris_data-0.11.0-cp39-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 02f97dd35d090a1ecac610f143a723222a03131bc7ca88c164314cceda54dd80
MD5 f1d6aa8caaabdb026733c42d90a0a532
BLAKE2b-256 6adf76c34274043e77714f33be898f2ee48d86e7e474135976dc21e247b02efe

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.11.0-cp39-abi3-musllinux_1_2_x86_64.whl:

Publisher: release-python.yml on polaris-data/sdks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polaris_data-0.11.0-cp39-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for polaris_data-0.11.0-cp39-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 03efa7e2fd8c12d3935f88573253cb17d8bd9f378113513f089174d4a4443ce6
MD5 85560d41cd95bc127ff15602c5814135
BLAKE2b-256 c35d12d096cbfe3460f7bd8319f35039515b05acbf33176528479950b7b32941

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.11.0-cp39-abi3-musllinux_1_2_aarch64.whl:

Publisher: release-python.yml on polaris-data/sdks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polaris_data-0.11.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for polaris_data-0.11.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 e499fc5453c439c40ad618419861fa8f9a0c339d8b39ec420d30d90e6c183536
MD5 75d541bb5917f355897017db28185d84
BLAKE2b-256 37acacdb4276cd51681084aafb20c69f2f5c29a008c1cb95483800f246044ffe

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.11.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release-python.yml on polaris-data/sdks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polaris_data-0.11.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for polaris_data-0.11.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 0ed873017f80619e9195706bc77febb4cde9402a7efcc916abef2ec7413ba9d4
MD5 69137e3d99a7b19f7b8e13c205e717cf
BLAKE2b-256 dae784da9abcb781894282e91410aa25608dedaabbcc5307c6bf5db47f2f3148

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.11.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release-python.yml on polaris-data/sdks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polaris_data-0.11.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for polaris_data-0.11.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 80e108604e6d86078482fface99d6b73b2328295ef1a9c0f3f451fde126de09b
MD5 c2d26c2755a5a8b4fce18130c0436ce8
BLAKE2b-256 c1881e508ac3b7cc4171d6a24ba59375ccb2809cb51a20a7eb5d5fe4d5a4f1f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.11.0-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release-python.yml on polaris-data/sdks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file polaris_data-0.11.0-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for polaris_data-0.11.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 97ee0c642703232bf036602d153a964538dc553b92d8ba8b0f69b210221cc588
MD5 a4538c640685a805d951ffe3bf6931ef
BLAKE2b-256 4233ae953a902b494148f6ecc4b94e374fd5e0e114ae61d844085393fb7c5f3b

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.11.0-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: release-python.yml on polaris-data/sdks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.16.0

9 files

0.15.0

9 files

0.14.1

9 files

0.14.0

9 files

0.13.0

9 files

0.12.0

9 files

This release

0.11.0 This release

9 files

0.10.2

9 files

0.10.1

9 files

0.10.0

9 files

0.9.0

9 files

0.8.6

2 files

0.8.5

2 files

0.8.4

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.0

2 files

0.6.0

2 files

0.5.1

2 files

0.5.0

2 files

0.4.1

2 files

0.4.0

2 files

0.3.1

2 files

0.3.0

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page