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,
        })
        .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,
    }).await?;

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

Reconnection is best-effort: the current live protocol has no resume cursor, so a reconnect can introduce a gap or duplicate event. Protocol and authentication errors are terminal and are not retried.

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) Iterator of historical events Backfills, notebooks, and replay-style processing without materializing everything up front
stream(source=..., markets=[...], include_buffer=False) 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) List of standardized historical events General-purpose historical analysis when you want the normalized event stream in memory
trades(source=..., market=..., from_=None, to=None, allow_gaps=False) List of standardized trade events Trade-level analytics, execution studies, and derived bar calculations
l2_snapshots(source=..., market=..., from_=None, to=None, allow_gaps=False) List of standardized orderbook snapshot rows Order book reconstruction and microstructure analysis
funding_rates(source=..., market=..., from_=None, to=None, allow_gaps=False) List of funding-rate point series rows Perpetual funding studies and carry modeling
mark_prices(source=..., market=..., from_=None, to=None, allow_gaps=False) List 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, allow_gaps=False) Best bid/offer quote series 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) Derived depth, spread, imbalance, and slippage metrics Liquidity analysis and market impact estimation

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

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 7, 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 7, 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.10.1.tar.gz (64.7 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.10.1-cp39-abi3-win_arm64.whl (3.3 MB view details)

Uploaded CPython 3.9+Windows ARM64

polaris_data-0.10.1-cp39-abi3-win_amd64.whl (3.5 MB view details)

Uploaded CPython 3.9+Windows x86-64

polaris_data-0.10.1-cp39-abi3-musllinux_1_2_x86_64.whl (4.3 MB view details)

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

polaris_data-0.10.1-cp39-abi3-musllinux_1_2_aarch64.whl (4.2 MB view details)

Uploaded CPython 3.9+musllinux: musl 1.2+ ARM64

polaris_data-0.10.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.0 MB view details)

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

polaris_data-0.10.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (4.0 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

polaris_data-0.10.1-cp39-abi3-macosx_11_0_arm64.whl (3.5 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

polaris_data-0.10.1-cp39-abi3-macosx_10_12_x86_64.whl (3.7 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: polaris_data-0.10.1.tar.gz
  • Upload date:
  • Size: 64.7 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.10.1.tar.gz
Algorithm Hash digest
SHA256 50a5bf0cc2f391eeaca747219c59582201034d6542e1e63643663e163b0812e1
MD5 6440383b45665f1d3c95f0304183a1d3
BLAKE2b-256 0a3369e6887ee32f184f7eed078a9daef4560310b05c22fbe5d833d7d0acecd5

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.10.1.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.10.1-cp39-abi3-win_arm64.whl.

File metadata

File hashes

Hashes for polaris_data-0.10.1-cp39-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 a83176e3bf251b9dd9f3d6e5014043a656b484ba0d519956ce0ab7a0763900fc
MD5 4b30ff4b0dd007dfa11483a0a873b4dc
BLAKE2b-256 08db78dffcb750532a378db5d7fcc96a906c534395cf93d2f9128b9d2fbee7ac

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.10.1-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.10.1-cp39-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for polaris_data-0.10.1-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 73afd0d832ed0a9d3cba8ad180bc8c8ffc4511d2bd7662c5a80c8c41a2cb988e
MD5 2c102fc26e5742fcc3d22bd482919ada
BLAKE2b-256 0fe396c5303667f0e5cc7ca6f4f6c8c2aae05d0c0438b266e8f9bf8dc6e74b72

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.10.1-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.10.1-cp39-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for polaris_data-0.10.1-cp39-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 65fb808685d20be52a05b3aa5e7a18bba61cda078e2ccf8064d1ea0a1f3fa907
MD5 0a12624bd50b65a3c5ad36658876d947
BLAKE2b-256 85351bed04aab1050940d1c5c1e526f0c252d5f13e308f49e1b5712cd90f1c3d

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.10.1-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.10.1-cp39-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for polaris_data-0.10.1-cp39-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 1e1ff5880ae421fcf859191d4d26ad7ae7e95017621a76fbaf009fea62062434
MD5 9e4f58477ccd18b77c9eeba50822d193
BLAKE2b-256 354ea8431dfb78160691bf2f40a4072dd3a96e42c26e96faefcce2632407c03e

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.10.1-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.10.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for polaris_data-0.10.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c1b2ce10a85c2082a33df80fb72b057f2a7fd75838fe3239011b9b651f559d99
MD5 93aa7161b79a377e03a936077692c261
BLAKE2b-256 f18502598a33e397d98cc09007258039010aea4f08edab0ee5ba1e0b25ee57b0

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.10.1-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.10.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for polaris_data-0.10.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 453cff3a6dd97c32191fd28dc329f6481927cd409de88af787f304b19038d3f3
MD5 025eca84cf0de5069b70bf19325f85eb
BLAKE2b-256 26e4e8f6f4df441a8b25e6fdf3a9aa084a7f160a59dab33be3f7acc4d54f6b62

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.10.1-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.10.1-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for polaris_data-0.10.1-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 bbd909cb762d35d7b4458932846377919e348a80200592d32468ac88861e979a
MD5 663d5ddccb321c726f17dcc396354d21
BLAKE2b-256 42ba1a8a83e1bc2785e01163fd84a593d7c54655ea2c16026b6e449cc021b4d5

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.10.1-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.10.1-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for polaris_data-0.10.1-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 1ae049c6fdc7583f653cd1470830196a88dce5163c9d911b16a803dfcc727b98
MD5 dedab256b9fbc94fa3d1cd3b656d728c
BLAKE2b-256 1baf2c2841147c3504d506c6d4ab43d629520c07f760bcbac97f2bd241e31ea3

See more details on using hashes here.

Provenance

The following attestation bundles were made for polaris_data-0.10.1-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

0.11.0

9 files

0.10.2

9 files

This release

0.10.1 This release

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