Vela, our next-generation charting platform, is live at vela.luxalgo.com.
LuxAlgo
Quotes, depth, and footprints

Footprint data

Implement the FootprintFeed interface on your data provider to power Footprint charts, order-flow indicators, and Pine Script® footprint requests.

View as Markdown

The Footprint chart type and Vela Pro's order-flow indicators render traded volume at each price level split by taker side. Standard OHLCV candles from Vela's open-source core DataProvider interface do not carry price-level volume, so your provider supplies it by implementing the three-method FootprintFeed interface alongside getBars.

Data model

The transport unit is a slice, representing one minute of trades for a single market aggregated into price levels:

interface FootprintSlice {
    time: number; // minute open timestamp in epoch milliseconds, minute-aligned
    tick: number; // price grid increment for the levels
    levels: FootprintLevel[]; // sorted ascending by price
}

interface FootprintLevel {
    price: number; // lower edge of the price bucket: floor(tradePrice / tick) * tick
    buyVolume: number; // volume traded where the taker bought
    sellVolume: number; // volume traded where the taker sold
    buyCount?: number; // trade count for taker buys, when available
    sellCount?: number;
}

Slices are independent of the chart's active timeframe. Vela Pro aggregates 1-minute slices into the chart's bars at any timeframe and merges price levels into display rows according to zoom and row-step settings. Because volume aggregation is exact, a 5-minute footprint bar summed from five 1-minute slices matches one built directly from raw trades.

Choose tick carefully for each market. Vela Pro only merges levels into coarser buckets and never subdivides them, so tick determines the finest price rows available when zoomed in. Use the instrument's minimum tick (or a fixed small multiple on wide-range markets) and keep tick uniform across all slices for that market.

buyCount and sellCount are optional, and omitting them is distinct from 0. Omit both fields when your upstream data source does not report trade counts so that Trade Count indicators, Average footprint modes, and count rows in Bar Stats display gaps rather than synthetic zeros. If any single level within a bar lacks counts, the entire bar is treated as count-less, so populate counts on every level or omit them everywhere.

The FootprintFeed interface

interface FootprintFeed {
    getFootprints(ticker: string, range: FootprintRange, sliceMs?: number): Promise<FootprintBatch>;
    subscribeFootprints(ticker: string, since: number, onSlices: (slices: FootprintSlice[]) => void): () => void;
    footprintCaps(ticker: string): FootprintCaps;
}

Vela Pro checks providers with hasFootprints(provider), which returns true only when all three methods are implemented.

Historical slices

getFootprints(ticker, range, sliceMs?) returns slices across the inclusive [range.from, range.to] interval in epoch milliseconds. range.session specifies 'regular' or 'extended' hours (typically matching the chart's session) and can be ignored on continuous 24/7 markets. sliceMs is an optional hint indicating the bar duration in milliseconds into which the caller will sum slices; feeds storing 1-minute slices can ignore it.

getFootprints resolves to a FootprintBatch:

FieldDescription
slicesAll slices currently available in the range. Omit minutes during which no trades occurred.
uncoveredPending [from, to) sub-ranges still being built on demand by your server. Vela Pro renders loading placeholders over uncovered bars and re-queries after a few seconds.
sliceMsWidth of the widest slice returned in milliseconds (60_000 for 1-minute slices). Servers storing pre-aggregated coarser buckets may return slices whose width evenly divides the requested sliceMs.
servedFromEarliest timestamp served when your backend truncates the request at a historical lookback limit.

Returning empty slices with an empty uncovered array indicates that no trades occurred in that window; Vela Pro retries historical empty ranges a few times before treating them as final. Rejected promises are retried after 20 seconds.

Live slice streaming

subscribeFootprints(ticker, since, onSlices) first replays all slices from the minute containing since up to the current time, and then pushes updates as live trades arrive. This initial catch-up replay is required because historical getFootprints calls stop before the chart's forming bar and rely on the live subscription for everything from since onward.

Every onSlices call must deliver complete FootprintSlice snapshots rather than incremental deltas. Re-send the active minute's full accumulated slice whenever new trades print; Vela Pro replaces existing slices matched by time.

Emit slices for all trading sessions on the live stream. When a chart displays 'regular' hours, Vela Pro filters out slices outside the regular windows returned by your market calendar.

Fetch planning capabilities

footprintCaps(ticker) configures how the Footprint chart type schedules viewport requests:

FieldBehavior
bulkFetchSet true when your server stores pre-aggregated slices and can serve wide ranges cheaply; the chart fetches the visible range at any zoom level (plus one screen of margin on each side) in batches of up to 700 bars. Set false when slices are built on demand from raw ticks; the chart starts with the newest 12 bars in chunks of 1 to 4 bars and fetches the full visible viewport only when zoomed to 90 bars or fewer.
maxFetchSpanSecWhen bulkFetch is true, caps the maximum lookback span requested for a single viewport (measured backward from its right edge, in seconds). Defaults to 12 hours (43_200 seconds, or 12 bars on a 1-hour chart) when omitted. Pass Infinity to bound requests solely by the visible range.

Order-flow indicators schedule fetches independently. Volume Delta, CVD, and the trade count indicators cover up to 3,000 loaded chart bars in batches of 250 bars (two requests in flight at a time), while profile and range indicators request the specific sessions or bar intervals they display.

Provider implementation example

import type { BarRange, DataProvider, OHLCV } from '@luxalgo/vela';
import type { FootprintBatch, FootprintCaps, FootprintFeed, FootprintRange, FootprintSlice } from '@luxalgo/vela-pro';

const API = 'https://api.example.com';
type WireLevel = [price: number, buy: number, sell: number, buyCount?: number, sellCount?: number];
interface WireFootprints {
    tick: number;
    slices: Array<{ t: number; levels: WireLevel[] }>;
    pending?: Array<[from: number, to: number]>;
}

const toSlices = (data: WireFootprints): FootprintSlice[] =>
    data.slices.map((slice) => ({
        time: slice.t,
        tick: data.tick,
        levels: slice.levels.map(([price, buyVolume, sellVolume, buyCount, sellCount]) => ({ price, buyVolume, sellVolume, buyCount, sellCount })),
    }));

export class AcmeProvider implements DataProvider, FootprintFeed {
    async getBars(ticker: string, timeframe: string, range: BarRange): Promise<OHLCV[]> {
        const query = new URLSearchParams({ symbol: ticker, timeframe, limit: String(range.limit ?? 500) });
        return (await (await fetch(`${API}/candles?${query}`)).json()) as OHLCV[];
    }

    async getFootprints(ticker: string, range: FootprintRange): Promise<FootprintBatch> {
        const query = new URLSearchParams({ symbol: ticker, session: range.session ?? 'regular' });
        if (range.from !== undefined) query.set('from', String(range.from));
        if (range.to !== undefined) query.set('to', String(range.to));
        const data = (await (await fetch(`${API}/footprints?${query}`)).json()) as WireFootprints;
        return { slices: toSlices(data), uncovered: data.pending ?? [], sliceMs: 60_000 };
    }

    subscribeFootprints(ticker: string, since: number, onSlices: (slices: FootprintSlice[]) => void): () => void {
        // Server replays from `since` on connect, then pushes the full forming minute as trades arrive.
        const socket = new WebSocket(`wss://stream.example.com/footprints?symbol=${encodeURIComponent(ticker)}&since=${since}`);
        socket.onmessage = (event) => onSlices(toSlices(JSON.parse(String(event.data)) as WireFootprints));
        return () => socket.close();
    }

    footprintCaps(): FootprintCaps {
        return { bulkFetch: true, maxFetchSpanSec: Infinity }; // pre-aggregated slices allow unbounded viewport spans
    }
}

getBars is abbreviated above; see Custom data providers for a production implementation. Once AcmeProvider is registered on the workspace, the Footprint chart type and order-flow indicators detect FootprintFeed automatically:

import { VelaWorkspace } from '@luxalgo/vela/workspace';
import type { DataProvider } from '@luxalgo/vela';
import { enableVelaPro, hasFootprints, type FootprintFeed } from '@luxalgo/vela-pro';

declare const AcmeProvider: new () => DataProvider & FootprintFeed; // provider class above

enableVelaPro();

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    symbol: 'acme:ESZ6',
    timeframe: '5',
    live: true,
    priceStyle: 'footprint',
    providers: { acme: () => new AcmeProvider() },
});

console.info(hasFootprints(workspace.chart.data.providerInstance('acme'))); // true

Backend requirements

  • Aggregate trade prints per market, 1-minute open timestamp, and price level into taker buy volume, taker sell volume, and optional trade counts.
  • Serve range queries returning minute slices with levels sorted ascending by price on a single consistent tick grid per market.
  • Provide a live stream that replays slices from since upon connection and sends full snapshots of the forming minute as trades arrive.
  • When historical slices are built asynchronously on demand, return in-progress [from, to) intervals in uncovered.

Aggregation and caching

All footprint consumers on a provider instance (the Footprint chart type, order-flow indicators, and TPO order-flow coloring) read through one shared footprint store per provider. The store deduplicates identical in-flight requests, opens at most one live subscribeFootprints stream per ticker, and caches complete historical segments older than 15 minutes in memory for 10 minutes.

The Footprint chart type sums slices onto the chart's bar timestamps (loading newest bars first), draws loading skeletons across uncovered or in-flight ranges, fetches only missing segments when panning, and updates forming bars from the live subscription.

Custom native indicators can read from the same store via footprintFeedFor(chart.data, symbol), which returns the shared store and resolved ticker, or null when the symbol's provider does not implement FootprintFeed.

Footprints in Pine Script®

Pine Script® scripts request footprint bars with request.footprint(). The scripting engine reads them from a FootprintSource callback backed by your feed and passed to enableVelaPro. Without a configured FootprintSource, request.footprint() evaluates to na on custom providers.

import { timeframeToMs, type DataProvider } from '@luxalgo/vela';
import type { FootprintSource } from '@luxalgo/vela-pinets';
import { aggregateSlices, enableVelaPro, footprintStore, type FootprintFeed } from '@luxalgo/vela-pro';

declare const acme: DataProvider & FootprintFeed; // provider instance registered on the workspace

const footprints: FootprintSource = async (symbol, timeframe, range) => {
    const ticker = symbol.slice(symbol.indexOf(':') + 1); // handles both 'acme:ESZ6' and 'ESZ6'
    const bucketMs = timeframeToMs(timeframe);
    const { slices } = await footprintStore(acme).getFootprints(ticker, { from: range.from, to: range.to, session: 'extended' }, bucketMs);
    if (slices.length === 0) return [];
    const tick = slices.reduce((finest, slice) => Math.min(finest, slice.tick), Infinity);
    const bars = aggregateSlices(slices, { bucketMs, priceTick: tick, originMs: range.from ?? 0 });
    return bars.map((bar) => ({ openTime: bar.time, tick, levels: bar.levels }));
};

enableVelaPro({ pineEngine: { footprints } });

FootprintSource returns one entry per chart bar keyed by openTime. Any bar omitted from the returned array reads as na in Pine Script®. See Pine Script® with PineTS for additional engine configuration options.

On this page