Live microstructure (bars.*)

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 classorderBooktradescvdfootprintNotes
Crypto (BTC, ETH, alts)livelivederivedderivedBinance spot via SSE. No broker required.
US equitiesbrokerbrokerbrokerbrokerNeeds a connected stock broker (Alpaca or Tradier). AllTick L1 covers price but not aggressor side.
ForexbrokerbrokerbrokerbrokerNeeds 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.

live

Fresh data flowing. Safe to read.

starting

Subscription opened but no frames yet. Expect live within a second or two.

stale

Upstream stream paused or reconnecting. The last snapshot is still readable, just older than 5s.

closed

Market is closed for this instrument.

broker-required

This instrument needs an authenticated broker with the right capability. Connect one from Trade on the left rail.

unsupported

No provider offers this channel for this instrument today.

error

Subscription 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).

book-imbalance.ts
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.

trade-flow.ts
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.

cvd-line.ts
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.

footprint-delta.ts
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);
  }
}