L2 Snapshots and Updates

Use the L2 methods to read complete reconstructed books or the original stored order book updates. The SDKs support legacy snapshots and deltas alongside unified v2 orderbook events.

Choose an L2 method

Method	Output	Use it for
`l2_snapshots()` / `l2Snapshots()`	Complete sorted book after every applicable update	Analysis that requires every intermediate full book
`l2_updates()` / `l2Updates()`	Original snapshots and sparse deltas	Application-managed state, custom sampling, and low-allocation processing

Method signatures

l2_snapshots(source, market, from_=None, to=None, allow_gaps=False, materialize_orderbooks=True)
l2_updates(source, market, from_=None, to=None, allow_gaps=False)

l2_snapshots(HistoricalQuery) -> HistoricalStream<OrderbookEvent>
l2_updates(HistoricalQuery) -> HistoricalStream<StandardEvent>

l2Snapshots({ source, market, from?, to?, materializeOrderbooks? }) => Promise<OrderbookEvent[]>
l2Updates({ source, market, from?, to? }) => Promise<OrderbookEvent[]>

Parameters

Parameter	Type	Required	Notes
source	string	Yes	Source ID
market	string	Yes	Normalized market or instrument ID
from / from_	string/date/datetime/number	No	Inclusive start time
to	string/date/datetime/number	No	Exclusive end time
allow_gaps	boolean	No	Python and Rust only. Return covered rows and warn instead of failing on coverage gaps
materialize_orderbooks / materializeOrderbooks	boolean	No	L2 snapshots only. Reconstruct complete books from deltas; defaults to `true`

If either time boundary is omitted, the SDK resolves a bounded range from catalog metadata. Explicitly bounded ranges can replay from complete local coverage without a network request.

Event versions and time

Legacy rows retain their original orderbook, orderbook_snapshot, l2_snapshot, or orderbook_delta type and use timestamp. V2 uses only type: "orderbook", uses data.is_snapshot to classify the update, and uses collector_timestamp as the SDK event time. Nullable exchange_timestamp remains venue-time provenance. A snapshot replaces both sides of the book. A delta replaces the quantity at each listed price, and quantity zero removes that price. A legacy delta can omit an unchanged side; v2 provides both side arrays.

Complete L2 snapshots

l2_snapshots() and l2Snapshots() reconstruct complete books by default. Python and Rust return single-pass streams; TypeScript returns an array. Materialized L2 rows use the standard event envelope with type: "orderbook" and these fields under data:

data.bids: bid levels sorted from highest to lowest price
data.asks: ask levels sorted from lowest to highest price
data.is_snapshot: v2 origin flag; true replaces the book and false applies absolute updates

Materialized v2 deltas retain data.is_snapshot: false even though their bids and asks contain the complete current book. This lets you identify the stored update that produced the materialized state.

from datetime import datetime, timedelta, timezone
from itertools import islice
from polaris_data import PolarisClient

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

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

Reconstruction lifecycle

A snapshot initializes or replaces the complete book.
A delta updates only its listed price levels.
A zero-quantity update deletes its price level.
A coverage gap or reconnect clears reconstructed state.
Following deltas are skipped until another snapshot initializes the book.

Raw L2 updates

l2_updates() and l2Updates() return the original snapshots and sparse deltas without constructing a complete book for every update. Use them for execution replay, custom sampling, or application-managed order book state. A v2 snapshot has data.is_snapshot: true; a v2 delta has data.is_snapshot: false:

[
  {
    "collector_timestamp": 1704067200000,
    "collector_sequence": 100,
    "exchange_timestamp": 1704067199990,
    "exchange_sequence": null,
    "source": "hyperliquid",
    "market": "BTC",
    "symbol": "BTCUSD",
    "type": "orderbook",
    "data": {
      "is_snapshot": true,
      "bids": [[43250.0, 1.5], [43249.5, 2.0]],
      "asks": [[43250.5, 1.2], [43251.0, 3.5]]
    }
  },
  {
    "collector_timestamp": 1704067200001,
    "collector_sequence": 101,
    "exchange_timestamp": 1704067199991,
    "exchange_sequence": null,
    "source": "hyperliquid",
    "market": "BTC",
    "symbol": "BTCUSD",
    "type": "orderbook",
    "data": {
      "is_snapshot": false,
      "bids": [[43250.0, 2.25]],
      "asks": [[43251.0, 0.0]]
    }
  }
]

Build complete books on demand

Use OrderbookBuilder.update() to maintain native book state without allocating a complete result after every update. Call snapshot() only when you need sorted bid and ask levels. Builder state is isolated by (source, market).

from polaris_data import OrderbookBuilder, PolarisClient

books = OrderbookBuilder()

with PolarisClient() as client:
    for update in client.l2_updates(
        source="hyperliquid",
        market="BTC",
        from_="2024-01-01T00:00:00Z",
        to="2024-01-01T01:00:00Z",
    ):
        books.update(update)

book = books.snapshot("hyperliquid", "BTC")
if book is not None:
    print(book["bids"][:5], book["asks"][:5])

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

let client = PolarisClient::builder().build()?;
let mut updates = client
    .l2_updates(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: false,
    })
    .await?;
let mut books = OrderbookBuilder::new();

while let Some(update) = updates.next().await.transpose()? {
    books.update(&update)?;
}

if let Some(book) = books.snapshot("hyperliquid", "BTC") {
    println!("{} bids, {} asks", book.bids.len(), book.asks.len());
}

import { OrderbookBuilder, PolarisClient } from "polaris-data";

await using client = new PolarisClient();
const books = new OrderbookBuilder();
const updates = await client.l2Updates({
  source: "hyperliquid",
  market: "BTC",
  from: "2024-01-01T00:00:00Z",
  to: "2024-01-01T01:00:00Z",
});

for (const update of updates) {
  books.update(update);
}

const book = books.snapshot("hyperliquid", "BTC");
if (book) console.log(book.bids.slice(0, 5), book.asks.slice(0, 5));

update() returns false for a delta received before its first snapshot. snapshot(source, market) returns None or undefined until that book has been initialized.

Builder methods

Method	Behavior
`update(event)`	Mutates book state without constructing a complete book
`snapshot(source, market)`	Materializes the current sorted bids and asks
`apply(event)`	Updates state and returns a complete book event
`clear_book(source, market)` / `clearBook(source, market)`	Removes one book
`clear()`	Removes all managed books

Use update() in high-frequency loops. Use apply() only when every update must immediately produce a complete book. When apply() materializes a v2 delta, the output deliberately retains data.is_snapshot: false.

Do not carry reconstructed state across a known coverage gap. Keep allow_gaps=False for continuous books, or process each covered interval separately and clear the builder before the next interval.

How it works

Both L2 methods use snapshot-first historical replay. See Snapshots for the full flow. Raw update iteration stays bounded in memory.

BBO if you only need top-of-book quotes
Depth metrics for derived liquidity metrics
Events for order book updates mixed with other event types
Snapshots for historical coverage and storage
Quickstart

Foundation

Trade & Price Data

Orderbook & Liquidity

Derivatives Data

L2 Snapshots and Updates

Choose an L2 method

Method signatures

Parameters

Event versions and time

Complete L2 snapshots

Reconstruction lifecycle

Raw L2 updates

Build complete books on demand

Builder methods

How it works

​Choose an L2 method

​Method signatures

​Parameters

​Event versions and time

​Complete L2 snapshots

​Reconstruction lifecycle

​Raw L2 updates

​Build complete books on demand

​Builder methods

​How it works

​Related documentation

Choose an L2 method

Method signatures

Parameters

Event versions and time

Complete L2 snapshots

Reconstruction lifecycle

Raw L2 updates

Build complete books on demand

Builder methods

How it works

Related documentation