Depth Metrics

Use client.depth_metrics() when you need derived liquidity metrics for market impact estimation and liquidity analysis. This method calculates depth, spread, imbalance, and slippage metrics from order book data.

Method signature

depth_metrics(source, market, from_=None, to=None, depth_pct=0.01, slippage_notional=10000.0, allow_gaps=False, output="iterator", batch_size=65536)

Parameters

Parameter	Type	Required	Notes
source	str	Yes	Source ID
market	str	Yes	Normalized market or instrument ID
from_	str/datetime/date/int	No	Inclusive start time (ISO 8601, datetime, date, or epoch milliseconds)
to	str/datetime/date/int	No	Exclusive end time (same formats as from_)
depth_pct	float	No	Depth percentage for bid/ask imbalance (default: 0.01 = 1%)
slippage_notional	float	No	Notional amount for slippage calculation (default: 10000.0)
allow_gaps	bool	No	Return covered rows and warn instead of failing on coverage gaps
output	str	No	`iterator`, `batches`, or `dataframe`
batch_size	int	No	Maximum rows per Arrow batch; must be positive

Return value

A single-pass iterator of metric dictionaries by default, flat PyArrow batches with output="batches", or a Pandas DataFrame with output="dataframe".

Example response

[
    {
        'timestamp': 1704067200000,
        'source': 'hyperliquid',
        'market': 'BTC',
        'symbol': 'BTCUSD',
        'spread': 0.50,
        'spread_bps': 1.16,
        'bid_depth': 150.5,
        'ask_depth': 145.2,
        'bid_ask_imbalance': 0.0176,
        'slippage_bps': 2.5
    }
]

Fields

Depth metrics records include:

timestamp: observation time in UTC milliseconds; columnar output is timezone-aware UTC
source: source identifier
market: normalized market ID
symbol: venue-native, human-friendly symbol
spread: absolute bid-ask spread
spread_bps: spread in basis points
bid_depth: total bid volume within depth_pct of mid
ask_depth: total ask volume within depth_pct of mid
bid_ask_imbalance: (bid_depth - ask_depth) / (bid_depth + ask_depth)
slippage_bps: estimated slippage in basis points for slippage_notional size

Positive bid_ask_imbalance indicates more depth on bids (buy pressure), negative indicates more depth on asks (sell pressure).

Example

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

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

with PolarisClient() as client:
    metrics = client.depth_metrics(
        source="hyperliquid",
        market="BTC",
        from_=start,
        to=end,
        depth_pct=0.01,      # 1% depth
        slippage_notional=10000.0,  # $10k notional
    )
    print(list(islice(metrics, 2)))

How it works

client.depth_metrics() derives liquidity metrics from order book snapshots using snapshot-first replay. See Snapshots for the full flow.

L2 snapshots for raw order book data
BBO if you only need top-of-book quotes
Events if you need order book updates mixed with other event types
Quickstart

Foundation

Trade & Price Data

Orderbook & Liquidity

Derivatives Data

Method signature

Parameters

Return value

Example response

Fields

Example

How it works

​Method signature

​Parameters

​Return value

​Example response

​Fields

​Example

​How it works

​Related documentation

Method signature

Parameters

Return value

Example response

Fields

Example

How it works

Related documentation