Python SDK - Polaris

The Polaris Python SDK is available on PyPI as polaris-data.

Install

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

For Pandas DataFrames or PyArrow record batches, install an optional extra:

pip install "polaris-data[dataframe]"  # Pandas + PyArrow
pip install "polaris-data[arrow]"      # PyArrow only

Quickstart

Use replay(...) when you want to stream historical rows in a notebook, script, or backfill job. You can run this without an API key set, and from_ and to are optional. If you omit them, the SDK uses the most recent available window up to the last 7 days of data, or the public cutoff date for preview datasets.

from polaris_data import PolarisClient

with PolarisClient() as client:
    for row in client.replay(
        source="hyperliquid",
        market="BTC",
    ):
        print(row)

Create a client

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

from polaris_data import PolarisClient

with PolarisClient() as client:
    print(client.health())

The main constructor is:

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

Core methods

Use PolarisClient for discovery, historical replay, and direct query workflows.

Method	Returns	Use it for
`health()`	JSON object	Confirm API availability
`catalog(source=None, market=None)`	JSON object	Discover sources and exact market IDs
`list_snapshots(source, market, from_, to, limit=1000)`	List of snapshot entries	Find snapshot files for a range
`replay(source, market, from_=None, to=None, standard=True, materialize_orderbooks=True, output="iterator", batch_size=65536)`	Iterator, exact Arrow batches, or DataFrame	Stream historical data for replay or backfills
`events(source, market, from_=None, to=None, materialize_orderbooks=True, output="iterator", batch_size=65536)`	Iterator, exact Arrow batches, or DataFrame	Process mixed event types with bounded memory
`trades(source, market, from_=None, to=None, output="iterator", batch_size=65536)`	Iterator, Arrow batches, or DataFrame	Analyze executions
`intents(source, market, from_=None, to=None, allow_gaps=False)`	Iterator of typed intent events	Analyze RFQs, quotes, executable intents, and settlements
`option_tickers(source, market, instrument=None, from_=None, to=None, allow_gaps=False)`	Iterator of typed option ticker events	Read a whole option chain or one exact contract
`perpetual_tickers(source, market, from_=None, to=None, allow_gaps=False)`	Iterator of typed perpetual ticker events	Read partial venue-published prices, open interest, premium, and funding state
`raw(source, market, from_=None, to=None, limit=1000)`	List of raw payloads	Inspect venue-native messages
`ohlcv(source, market, interval, from_=None, to=None, format=None)`	List of bars or TradingView-style JSON	Plot fast market charts
`l2_snapshots(source, market, from_=None, to=None, materialize_orderbooks=True)`	Iterator of complete orderbook rows	Order book reconstruction and microstructure analysis
`l2_updates(source, market, from_=None, to=None)`	Iterator of raw orderbook snapshots and deltas	High-throughput application-managed books
`funding_rates(source, market, from_=None, to=None, output="iterator", batch_size=65536)`	Iterator, Arrow batches, or DataFrame	Perpetual funding studies and carry modeling
`mark_prices(source, market, from_=None, to=None, output="iterator", batch_size=65536)`	Iterator, Arrow batches, or DataFrame	Basis analysis, mark tracking, and liquidation-related research
`volume(source, market, interval, from_=None, to=None)`	Bucketed trade volume series	Volume profiling and participation analysis
`vwap(source, market, interval, from_=None, to=None)`	Bucketed VWAP series	Execution benchmarking and price smoothing
`volatility(source, market, interval, from_=None, to=None, method="log_returns")`	Bucketed realized volatility series	Risk modeling and intraperiod volatility analysis
`bbo(source, market, from_=None, to=None, interval=None, changes_only=False, output="iterator", batch_size=65536)`	Iterator, Arrow batches, or DataFrame	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, output="iterator", batch_size=65536)`	Iterator, Arrow batches, or DataFrame	Liquidity analysis and market impact estimation

Historical row methods return single-pass generators. Iterate directly for bounded memory, or wrap a call in list(...) when you need indexing or repeated access. Close a partially consumed generator with rows.close(). BBO also accepts interval="100ms", "1s", "10s", "1m", "5m", "15m", or "1h" to emit the last quote from each non-empty UTC-aligned bucket.

Arrow batches and DataFrames

trades, funding_rates, mark_prices, bbo, and depth_metrics accept three output modes. The default "iterator" preserves the existing row dictionaries. "batches" yields bounded pyarrow.RecordBatch objects, while "dataframe" eagerly returns one Pandas DataFrame.

with PolarisClient() as client:
    trades_df = client.trades(
        source="hyperliquid",
        market="BTC",
        from_=start,
        to=end,
        output="dataframe",
    )

    for batch in client.bbo(
        source="hyperliquid",
        market="BTC",
        from_=start,
        to=end,
        output="batches",
        batch_size=100_000,
    ):
        process(batch)

Columnar schemas are flat. Timestamps are timezone-aware UTC milliseconds; source, market, and trade side are categorical/dictionary columns. Additional venue-specific trade and point fields are sorted under extra.<name>. Because those keys are dynamic, trade and point queries scan the resolved local files once to infer a stable schema and reopen the same files for batch emission. Trade batches and DataFrames include stable nullable maker and taker string columns. BBO and depth metrics have fixed schemas and remain single-pass. from_ and to accept ISO 8601 strings, datetime, date, or Unix epoch milliseconds. They are optional on replay(...), events(...), trades(...), option_tickers(...), perpetual_tickers(...), raw(...), and ohlcv(...). If you omit either boundary, the SDK fills the request from the most recent available window up to the last 7 days of data, or the public cutoff date for preview datasets. For historical event queries, standard=True is the default on replay(...). Pass standard=False when you explicitly want raw schema payloads through replay. For exact execution replay, request output="batches" and materialize_orderbooks=False. These batches retain every standardized event in stored capture order and include stable replay, file, and row ordinals. Nullable legacy timestamp and v2 collector/exchange columns use millisecond Arrow timestamps. Typed columns include nullable order_id, side, and is_snapshot. With raw order-book updates, event_json preserves the complete source event and unknown payloads; with materialization enabled it contains the resulting complete-book event. Raw standard=False replay remains iterator-only. Iterator dictionaries preserve their stored envelope. Check "collector_timestamp" in event to identify v2; use that value for SDK time and treat exchange_timestamp as nullable venue provenance. See Event envelope. Orderbooks are reconstructed by default across stream, replay, events, and l2_snapshots. orderbook replaces the complete state, orderbook_delta updates listed prices, and quantity zero deletes a price. State is cleared after gaps and reconnects; deltas are skipped until another snapshot arrives. Use l2_updates(...) for raw snapshots and deltas, then feed selected updates into the exported OrderbookBuilder for application-managed flows.

Discover a market before you query it

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

from polaris_data import PolarisClient

with PolarisClient() as client:
    catalog = client.catalog(source="hyperliquid")
    markets = [row["market"] for row in catalog["markets"]]
    print(markets[:10])

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. Omit from_ and to to query the recent default window, or pass them explicitly when you need a fixed range.

from polaris_data import PolarisClient

with PolarisClient() as client:
    rows = list(
        client.events(
            source="hyperliquid",
            market="BTC",
        )
    )
    print(len(rows))
    print(rows[0])

Query trades

trades(...) returns an iterator of normalized trade events. The SDK handles snapshot-backed historical reads for you. from_ and to are optional, so you can start with the recent default window and only add explicit boundaries when you need a specific range.

from datetime import datetime, timedelta, timezone

from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(hours=1)

with PolarisClient() as client:
    trades = client.trades(
        source="hyperliquid",
        market="SPX",
        from_=start,
        to=end,
    )
    print(next(trades, None))

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.

from polaris_data import PolarisClient

with PolarisClient() as client:
    observations = client.intents(
        source="uniswapx",
        market="intents",
    )
    print(next(observations, None))

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. Omit instrument to iterate over the whole option chain, or provide an exact venue-native contract to filter the results.

from polaris_data import PolarisClient

with PolarisClient() as client:
    tickers = client.option_tickers(
        source="aevo",
        market="BTC",
    )
    print(next(tickers, None))

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 iterate over partial venue-published market state for a perpetual market.

from polaris_data import PolarisClient

with PolarisClient() as client:
    tickers = client.perpetual_tickers(
        source="hyperliquid",
        market="BTC",
    )
    ticker = next(tickers, None)
    if ticker is not None:
        print(ticker["data"].get("mark_price"))

The SDK exports PerpetualTickerData, LegacyPerpetualTickerEvent, PerpetualTickerEventV2, and their PerpetualTickerEvent union. Decimal values remain strings, and omitted fields are not carried forward. 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. from_ and to are optional here as well.

from datetime import datetime, timedelta, timezone

from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(hours=6)

with PolarisClient() as client:
    bars = client.ohlcv(
        source="hyperliquid",
        market="SPX",
        from_=start,
        to=end,
        interval="1m",
    )

print(bars[0])

If you pass format="tradingview", ohlcv(...) returns TradingView-style candle and volume arrays.

Query order book snapshots

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

from datetime import datetime, timedelta, timezone

from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(minutes=5)

with PolarisClient() as client:
    snapshots = client.l2_snapshots(
        source="hyperliquid",
        market="BTC",
        from_=start,
        to=end,
    )
    print(next(snapshots, None))

For a sparse update stream, use l2_updates(...) and materialize books only when your application needs them:

from polaris_data import OrderbookBuilder, PolarisClient

books = OrderbookBuilder()
with PolarisClient() as client:
    for update in client.l2_updates(source="hyperliquid", market="BTC"):
        books.update(update)

complete_book = books.snapshot("hyperliquid", "BTC")
if complete_book is not None:
    process(complete_book)

update() changes native state without constructing a complete Python dictionary. snapshot() creates sorted levels only when requested. Use apply() when you need the previous update-and-materialize behavior.

Query funding rates

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

from datetime import datetime, timedelta, timezone

from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(hours=24)

with PolarisClient() as client:
    funding_rates = client.funding_rates(
        source="hyperliquid",
        market="BTC",
        from_=start,
        to=end,
    )
    print(next(funding_rates, None))

Query mark prices

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

from datetime import datetime, timedelta, timezone

from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(hours=24)

with PolarisClient() as client:
    mark_prices = client.mark_prices(
        source="hyperliquid",
        market="BTC",
        from_=start,
        to=end,
    )
    print(next(mark_prices, None))

Query volume profiles

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

from datetime import datetime, timedelta, timezone

from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(hours=6)

with PolarisClient() as client:
    volume = client.volume(
        source="hyperliquid",
        market="SPX",
        from_=start,
        to=end,
        interval="1h",
    )

print(volume[0])

Query VWAP series

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

from datetime import datetime, timedelta, timezone

from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(hours=6)

with PolarisClient() as client:
    vwap = client.vwap(
        source="hyperliquid",
        market="SPX",
        from_=start,
        to=end,
        interval="1h",
    )

print(vwap[0])

Query volatility series

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

from datetime import datetime, timedelta, timezone

from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(hours=6)

with PolarisClient() as client:
    volatility = client.volatility(
        source="hyperliquid",
        market="SPX",
        from_=start,
        to=end,
        interval="1h",
    )

print(volatility[0])

Query best bid/offer

Use bbo(...) for spread tracking, quote analytics, and top-of-book monitoring. Set changes_only=True when the consumer only needs actual top-of-book changes; the default continues to emit after every valid two-sided book update.

from datetime import datetime, timedelta, timezone

from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(minutes=30)

with PolarisClient() as client:
    bbo_quotes = client.bbo(
        source="hyperliquid",
        market="BTC",
        from_=start,
        to=end,
        interval="1s",
    )
    print(next(bbo_quotes, None))

Query depth metrics

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

from datetime import datetime, timedelta, timezone

from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(minutes=30)

with PolarisClient() as client:
    depth_metrics = client.depth_metrics(
        source="hyperliquid",
        market="BTC",
        from_=start,
        to=end,
        depth_pct=0.01,
        slippage_notional=10000.0,
    )
    print(next(depth_metrics, None))

Local dataset storage

The SDK stores standardized snapshots and local day files under a shared Polaris app-data root so the Python SDK and CLI 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/
  daily/
  tmp/
  cache/
  locks/

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

Standardized historical methods—including replay(...), events(...), trades(...), option_tickers(...), perpetual_tickers(...), and default or TradingView ohlcv(...)—prefer /snapshots and /download, then read local day files when they already exist. See Snapshots for the full flow.

Authentication

Public sources (e.g. Hyperliquid BTC) work without an API key. For premium sources, raw snapshots, or extended history, set your key via the POLARIS_API_KEY environment variable or pass it directly:

from polaris_data import PolarisClient

with PolarisClient(api_key="pk_live_your_key") as client:
    trades = list(
        client.trades(
            source="hyperliquid",
            market="SPX",
            from_="2024-01-01T00:00:00Z",
            to="2024-01-02T00:00:00Z",
        )
    )

See Quickstart for the full auth model.

Error handling

from polaris_data import PolarisClient, RateLimitedError, UnauthorizedError

client = PolarisClient()

try:
    client.replay(
        source="hyperliquid",
        market="BTC",
        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}")

Notebook workflow

If you want a notebook that discovers a market, loads a DataFrame, and plots a chart, start with Jupyter Notebook.

Next steps

Read Jupyter Notebook if you want notebook-ready workflows with pandas and matplotlib.
Read Catalog before you hardcode source and market IDs.
Read Quickstart if you want the shared auth model behind the SDK.
Read Snapshots if your Python workflow starts from historical files.
Read Trades, Perpetual tickers, Events, or OHLCV for detailed method documentation.

​Install

​Quickstart

​Create a client

​Core methods

​Arrow batches and DataFrames

​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

​Authentication

​Error handling

​Notebook workflow

​Next steps