Live microstructure (bars.*)
On this page
Availability by instrument
The four microstructure accessors (bars.orderBook, bars.trades, bars.cvd, bars.footprint) are real-time, not backtest-capable. Availability depends on the instrument class. Check the table before writing an indicator that depends on a channel.
| Instrument class | orderBook | trades | cvd | footprint | Notes |
|---|---|---|---|---|---|
| Crypto (BTC, ETH, alts) | live | live | derived | derived | Binance spot via SSE. No broker required. |
| US equities | broker | broker | broker | broker | Needs a connected stock broker (Alpaca or Tradier). AllTick L1 covers price but not aggressor side. |
| Forex | broker | broker | broker | broker | Needs a connected forex broker (OANDA). |
ChannelStatus values
Every microstructure accessor exposes a status field. Always check it before dereferencing: the accessor can legally return a starting/stale/broker-required snapshot rather than null.
liveFresh data flowing. Safe to read.
startingSubscription opened but no frames yet. Expect live within a second or two.
staleUpstream stream paused or reconnecting. The last snapshot is still readable, just older than 5s.
closedMarket is closed for this instrument.
broker-requiredThis instrument needs an authenticated broker with the right capability. Connect one from Trade on the left rail.
unsupportedNo provider offers this channel for this instrument today.
errorSubscription errored. Read `.error` for the upstream message.
bars.orderBook
Top-of-book L2 snapshot. bids sorted DESC by price, asks ASC by price, plus convenience bestBid, bestAsk, spread, mid. Returns null when no L2 feed is subscribed for the current instrument (crypto uses Binance; stocks/forex need a broker).
import { Lab, bars, draw } from '@chartlabs/script-sdk';
export default class Imbalance extends Lab {
static readonly meta = {
name: 'Book Imbalance',
slug: 'book-imbalance',
version: '1.0.0',
placement: 'subpane' as const,
};
private imb = draw.line({ name: 'Imbalance', color: '#60a5fa' });
onBar() {
const book = bars.orderBook;
if (!book || book.status !== 'live' || !book.bestBid || !book.bestAsk) {
this.imb.push(0);
return;
}
const bidVol = book.bids.slice(0, 5).reduce((s, l) => s + l.size, 0);
const askVol = book.asks.slice(0, 5).reduce((s, l) => s + l.size, 0);
const total = bidVol + askVol;
this.imb.push(total > 0 ? (bidVol - askVol) / total : 0);
}
}bars.trades
Rolling window of recent tick prints (oldest first). Up to 5000 trades per symbol. Each Trade carries timestamp, price, size, side ('buy' | 'sell' | 'unknown'), id. 'unknown' means the upstream feed didn’t publish an aggressor flag: the CVD / Footprint channels apply the tick rule to infer it.
import { Lab, bars, draw } from '@chartlabs/script-sdk';
export default class TradeFlow extends Lab {
static readonly meta = {
name: 'Trade Flow',
slug: 'trade-flow',
version: '1.0.0',
placement: 'subpane' as const,
};
private delta = draw.line({ name: 'Delta', color: '#a78bfa' });
onBar() {
const tape = bars.trades;
if (!tape || tape.status !== 'live' || tape.trades.length === 0) return;
let d = 0;
for (const t of tape.trades) {
if (t.side === 'buy') d += t.size;
if (t.side === 'sell') d -= t.size;
}
this.delta.push(d);
}
}bars.cvd
Derived from the trade tape. points is chronologically ascending with per-print signed deltas and a running cumulative. The convenience .cumulative on the series itself is the most recent point’s value. Available whenever bars.trades is live.
import { Lab, bars, draw } from '@chartlabs/script-sdk';
export default class CvdLine extends Lab {
static readonly meta = {
name: 'CVD',
slug: 'cvd-line',
version: '1.0.0',
placement: 'subpane' as const,
};
private line = draw.line({ name: 'CVD', color: '#22d3ee' });
onBar() {
const cvd = bars.cvd;
if (!cvd || cvd.status !== 'live' || cvd.points.length === 0) return;
// .cumulative is the running total since the tape started streaming
this.line.push(cvd.cumulative);
}
}bars.footprint
Derived per-bar buy/sell volume split by price level, with imbalance flags (default 3:1). .bars is completed bars oldest-first; .activeBar is the still-forming bar. Each FootprintLevel carries price, buyVolume, sellVolume, imbalance. Available whenever bars.trades is live.
import { Lab, bars, draw } from '@chartlabs/script-sdk';
export default class FootprintDelta extends Lab {
static readonly meta = {
name: 'Footprint Delta',
slug: 'footprint-delta',
version: '1.0.0',
placement: 'subpane' as const,
};
private d = draw.line({ name: 'Delta', color: '#60a5fa' });
onBar() {
const fp = bars.footprint;
if (!fp || fp.status !== 'live' || fp.bars.length === 0) {
this.d.push(0);
return;
}
// Each bar also has .levels (per-price buy/sell volume with an imbalance
// flag). This example rolls the newest completed bar up to one delta.
this.d.push(fp.bars[fp.bars.length - 1].delta);
}
}