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) 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, materialize_orderbooks=True) List of complete orderbook 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 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.10.2.tar.gz (69.2 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.2-cp39-abi3-win_arm64.whl (3.3 MB view details)

Uploaded CPython 3.9+Windows ARM64

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

Uploaded CPython 3.9+Windows x86-64

polaris_data-0.10.2-cp39-abi3-musllinux_1_2_x86_64.whl (4.4 MB view details)

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

polaris_data-0.10.2-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.2-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.2-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.2-cp39-abi3-macosx_11_0_arm64.whl (3.6 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

polaris_data-0.10.2-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.2.tar.gz.

File metadata

  • Download URL: polaris_data-0.10.2.tar.gz
  • Upload date:
  • Size: 69.2 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.2.tar.gz
Algorithm Hash digest
SHA256 dd5617195787c08d446756be9c0b29dbad7e4799b93f15f967be975443ef2cdc
MD5 55b0df51f382b1c973575409d0ec5647
BLAKE2b-256 aae5497d34de61f8935613dab5d58ed066ae91fc249e57b4570cd8cc9217d5d8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for polaris_data-0.10.2-cp39-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 e10f394debf8d4581326afaada9381e1d0b18b1134f6ef4ad229d8ab9147d957
MD5 4e34e2205ff08992562b5eab7e1d963b
BLAKE2b-256 9b203f91e4e723e795fc67f4c2d87f2539548fb060e7d2045f94654d9e7fd144

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for polaris_data-0.10.2-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 1d9c18ca1d9081affcbe2f8237b7d74707cd32c874358e0edbf04a71190876a0
MD5 2242d366410ed8dee62f84293b60d886
BLAKE2b-256 f46b5f527643fb602d80aeb438d6ad623707e4466e7b1d206da8d84bce846970

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for polaris_data-0.10.2-cp39-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 ba5b6f8b2dbbebd57a26591bf3605f0d0ec42311bbac65a94d0486f8ff3f2a96
MD5 412b81687ce35b896077dd36d25e109c
BLAKE2b-256 263b215427778c37dfa65dab23bc017f979ff96d0dda798ed28375339e90323b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for polaris_data-0.10.2-cp39-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 1ca4414edceddec6ee7f4d7893d2666f73e0f4e06b05362205bdab47b4490851
MD5 15b457382d5b44c83f4a8a6c2d0748b2
BLAKE2b-256 e0d88dbc9f566733d3b04baea9a6ae8841667955bc9900a471883917df58887a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for polaris_data-0.10.2-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 fdedaa42b692b114e6773868e21cab9579fae9fb0ba943ed71e0baa6d55ce138
MD5 6315acf64a699f133cd0e86fb0d649da
BLAKE2b-256 9491471d683980c6004da48ba3200ebb7b0d1a8df58b171ba25230d4c21bcada

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for polaris_data-0.10.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 016fc4f67bb21e5da9ec3d90156d972cf08bab18cf9ee525bfebc074808095f8
MD5 5becf47d607139ebe32baa79246d5b7c
BLAKE2b-256 95a74c1e7525e04a2b78d0de966fb420858667005d63195f00dcbdf52e35043f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for polaris_data-0.10.2-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5769a83c66395fd6a89cf42a0b44369f44bca7a186ebf8473e64c3012fb9af1d
MD5 cdbb2468cb73643eb5c33df986bcc56d
BLAKE2b-256 0b5853ca0745d2e96470dcdba7d071fbe63c47863841ee6eb7cb1fa85e7ccba3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for polaris_data-0.10.2-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 9087403f75c213cd0cfaa2ae59a0e284be97ea229d2be6e5ad89c7cee41465e4
MD5 7ae311f71a8314dc974af0246db185dd
BLAKE2b-256 948a77d87eb89ba225721ce8e3ae72e2f5b4cc033f7146939695649a4d8f405c

See more details on using hashes here.

Provenance

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

This release

0.10.2 This release

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