Metrics library · L1 & L2 order book
Bid size against ask size at the best quote, at the bar's close and averaged through it.
Bid/ask imbalance, ratio, percentages — both instantaneous (last) and averaged over the interval.
The 5m bar from 14:00 to 14:05 UTC on 14 May 2025, Binance BTC-USDT perpetual, from the free preview.
Step 1
imbalance_ratio runs from −1 (nothing on the bid) to 1 (nothing on the ask). At this bar's close the two sides were nearly even.
Step 2
The last-quote value jumps from bar to bar. The average over the bar's updates moves less. Each update counts once, however long it stood.
Step 3
The average is 56.3, though the bid held 44.0% of the size on average. A few updates with a nearly empty ask make bid / ask very large, and the mean follows them. imbalance_ratio is bounded at −1 and 1, so it does not have this problem.
Step 4
BTC-USDT perpetual on Binance, 5m bars, 1 to 31 May 2025, from the free preview.
Bars by average top-of-book imbalance, ask-heavy to bid-heavy. Basis points.
Bars sorted by their average imbalance: the most ask-heavy tenth fell 6.71 bps on average, the most bid-heavy tenth rose 6.50 bps. The book leaned with the move as it happened.
For the next bar, the value at the close did better than the average (0.055 against 0.002), because it is the latest information. It is also noisier: in 12% of bars it sat beyond ±0.9, with one side nearly empty at that instant.
imbalance is bid size minus ask size at the best quote. imbalance_ratio scales it from -1 (all ask) to 1 (all bid). bid_percentage and ask_percentage are each side’s share.
The _avg fields are the mean over every quote update in the interval, each update counting once. The plain fields are the last quote. They differ most when quotes were being pulled and replaced.
bid_ask_ratio grows very large when one side is nearly empty. Use the ratio scaled to ±1 instead.
Order book imbalance is arguably the single most validated short-term predictive signal in the market microstructure literature. The intuition is immediate: if there's substantially more resting size on the bid than the ask, the next price move is more likely upward.
Cont, Kukanov & Stoikov (2014) provided the definitive empirical analysis, showing that order book imbalance — defined as:
predicts the direction of the next mid-price change with statistically and economically significant accuracy across multiple equity markets. The signal is monotonic: stronger imbalance produces larger expected price moves, and the relationship is approximately linear.
Their insight was that the imbalance captures the queue dynamics of the limit order book: when one side has substantially more depth, the probability that the opposite side is depleted first (triggering a price change toward the deeper side) increases mechanically.
A single snapshot of imbalance is noisy — market makers continuously refresh quotes, and a momentary asymmetry can be an artifact of staggered updates. Huang & Polak (2011) showed that time-averaged imbalance over longer windows provides a smoother, more predictive signal that captures the sustained directional tilt of the book rather than transient fluctuations.
We compute both:
The divergence between them — how much the closing snapshot differs from the average — itself carries information. A large divergence indicates recent quote instability, suggesting a potential regime change within the bar.
Top-of-book (L1) imbalance captures only the best bid and ask. But Cao, Chen & Griffin (2005) demonstrated that information about future price changes exists at deeper levels of the book. A thin top-of-book bid sitting in front of massive size at deeper levels is structurally different from a thin bid with nothing behind it.
We compute L2 imbalance at cumulative depth tiers: 5, 10, 20, and 25 price levels per side. This captures the full shape of supply-demand imbalance, not just the frontier.
The L1-L2 divergence is the most actionable signal. When L1 shows thin bids but L2 reveals deep bid-side support, the apparent weakness is a mirage — the top-of-book thinness is likely a market maker adjusting inventory, not a genuine absence of demand. Conversely, thick L1 bids with empty L2 behind them indicate a single concentrated quote — remove that one market maker and there's a price gap.
References:
# Install the Aperiodic CLI into ~/.local/bin
mkdir -p "$HOME/.local/bin"
curl -fsSL https://raw.githubusercontent.com/aperiodic-io/cli/main/install.sh | INSTALL_DIR="$HOME/.local/bin" bash
export PATH="$HOME/.local/bin:$PATH"
# Free preview — no API key required
aperiodic l1_imbalance --preview \
--exchange binance-futures \
--symbol perpetual-BTC-USDT:USDT \
--interval 5m \
--timestamp exchange \
--start-date 2025-05-01 \
--end-date 2025-05-31 \
--output-dir ./data && echo "Saved to $PWD/data"