# Footprint data (/vela-pro/data/feeds/footprints)



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 [#data-model]

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

```typescript
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 [#the-footprintfeed-interface]

```typescript
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 [#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`:

| Field        | Description                                                                                                                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slices`     | All slices currently available in the range. Omit minutes during which no trades occurred.                                                                                                              |
| `uncovered`  | Pending `[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.                               |
| `sliceMs`    | Width 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`. |
| `servedFrom` | Earliest 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 [#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](/vela-pro/data/symbols/sessions#market-calendar).

### Fetch planning capabilities [#fetch-planning-capabilities]

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

| Field             | Behavior                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bulkFetch`       | Set `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. |
| `maxFetchSpanSec` | When `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 [#provider-implementation-example]

```ts
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](/vela-pro/data/custom-source) for a production implementation. Once `AcmeProvider` is registered on the workspace, the Footprint chart type and order-flow indicators detect `FootprintFeed` automatically:

```ts
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 [#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 [#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® [#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.

```ts
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](/vela-pro/indicators/pine/runtime) for additional engine configuration options.

## Related [#related]

* [Footprint](/vela-pro/charts/chart-types/footprint)
* [Built-in indicators](/vela-pro/indicators/included)
* [Quotes and market depth](/vela-pro/data/feeds/quotes-and-depth)
* [Data feeds API reference](/vela-pro/api/data-feeds)
