Skip to main content
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_, to, depth_pct=0.01, slippage_notional=10000.0, limit=1000)

​
Parameters

ParameterTypeRequiredNotes
sourcestrYesSource ID
marketstrYesNormalized market or instrument ID
from_str/datetime/date/intYesInclusive start time (ISO 8601, datetime, date, or epoch microseconds)
tostr/datetime/date/intYesExclusive end time (same formats as from_)
depth_pctfloatNoDepth percentage for bid/ask imbalance (default: 0.01 = 1%)
slippage_notionalfloatNoNotional amount for slippage calculation (default: 10000.0)
limitintNoPage size (default: 1000)
Note: API key required for historical ranges. Set POLARIS_API_KEY environment variable or pass api_key to PolarisClient().

​
Return value

List of derived depth and liquidity metric rows.

​
Example response

[
    {
        'timestamp': 1704067200000000,
        'venue': 'binance',
        'symbol': 'BTC-USDT',
        '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 microseconds since the Unix epoch
  • venue: exchange identifier
  • symbol: normalized instrument 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 polaris_data import PolarisClient

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

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

print(metrics[:2])

​
How it works

client.depth_metrics() derives liquidity metrics from order book snapshots using snapshot-first replay. The SDK queries the /snapshots endpoint for historical data, reads from local cached files when available, and calculates depth, spread, imbalance, and slippage metrics from the order book data. For more details on snapshot-based queries, see Snapshots.