# Chart types and order flow (/vela-pro/api/chart-types)



This page documents the Footprint and TPO chart types and order-flow indicators, including their data models, data engines, and bar aggregation helpers.

Import symbols on this page from `@luxalgo/vela-pro`. Related guides: [Chart types](/vela-pro/charts/chart-types/overview), [Footprint](/vela-pro/charts/chart-types/footprint), [TPO](/vela-pro/charts/chart-types/tpo).

Feature enablers for this area ([`enableFootprint`](/vela-pro/api/enablers#enablefootprint), [`enableOrderflowIndicators`](/vela-pro/api/enablers#enableorderflowindicators), [`enableTpo`](/vela-pro/api/enablers#enabletpo)) are documented on [Enablers and options](/vela-pro/api/enablers).

## Functions [#functions]

### `aggregateFootprints` [#aggregatefootprints]

Aggregate neutral [`Trade`](/vela-pro/api/chart-types#trade)s into per-bar [`BarFootprint`](/vela-pro/api/chart-types#barfootprint)s: bucketing by time into bars and, within each bar, by price into aggressor-split levels. Pure and order-independent. Bars and levels come back ascending (by `time`, then `price`).

```typescript
function aggregateFootprints(trades: readonly Trade[], opts: FootprintBucketOptions): BarFootprint[]

// Unexported supporting type referenced above
interface FootprintBucketOptions {
    bucketMs: number;
    priceTick: number;
    originMs?: number;
}
```

See also: [`BarFootprint`](/vela-pro/api/chart-types#barfootprint), [`Trade`](/vela-pro/api/chart-types#trade).

### `aggregateSlices` [#aggregateslices]

Aggregate pre-aggregated [`FootprintSlice`](/vela-pro/api/chart-types#footprintslice)s into per-bar [`BarFootprint`](/vela-pro/api/chart-types#barfootprint)s. A slice belongs to the bar containing its open time; its levels re-bucket onto the display `priceTick` grid (slices carry a much finer grid, so this only ever merges). Exact: summing slice levels across a bar equals aggregating the underlying trades.

```typescript
function aggregateSlices(
    slices: readonly FootprintSlice[],
    opts: FootprintBucketOptions,
): BarFootprint[]

// Unexported supporting type referenced above
interface FootprintBucketOptions {
    bucketMs: number;
    priceTick: number;
    originMs?: number;
}
```

See also: [`BarFootprint`](/vela-pro/api/chart-types#barfootprint), [`FootprintSlice`](/vela-pro/api/chart-types#footprintslice).

### `alignToChart` [#aligntochart]

Align per-bar aggregates onto the CHART's bar times: `cells[i]` is the aggregate of `chartTimes[i]`, or `undefined` where coverage is missing. This is the model pipeline's alignment contract: series payloads are INDEX-aligned to the chart's bars, so an indicator must emit exactly one entry per chart bar and never a value for a time the chart has no bar (extra leading entries render the whole series shifted). Aggregates outside the chart's bar set are dropped here.

```typescript
function alignToChart(
    bars: readonly OrderflowBar[],
    chartTimes: readonly number[],
): Array<OrderflowBar | undefined>
```

See also: [`OrderflowBar`](/vela-pro/api/chart-types#orderflowbar).

### `buildCumulativeBars` [#buildcumulativebars]

Build the cumulative-delta CANDLES, one slot per chart bar (chart-aligned `cells` from [`alignToChart`](/vela-pro/api/chart-types#aligntochart)): each candle opens at the running total, closes at `open + delta`, and wicks to the intra-bar path extremes (the `'average'` metric has no sub-bar path: its candles are honestly wickless). The running total resets to 0 on every anchor-period boundary (`'all'` never resets: the sum runs from the first covered chart bar). Uncovered bars (and, for the count-fed metrics, bars without counts) leave a HOLE in the array while the total carries through: an honest gap, never a fake flat candle, and never a compacted array (compaction is exactly the index shift this module exists to prevent).

```typescript
function buildCumulativeBars(
    cells: readonly (OrderflowBar | undefined)[],
    times: readonly number[],
    metric: DeltaMetric,
    anchor: CumulativeAnchor,
): OHLCV[]
```

See also: [`CumulativeAnchor`](/vela-pro/api/chart-types#cumulativeanchor), [`DeltaMetric`](/vela-pro/api/chart-types#deltametric), [`OrderflowBar`](/vela-pro/api/chart-types#orderflowbar). From `@luxalgo/vela/plugin`: `OHLCV`.

### `buildRangeTails` [#buildrangetails]

Build the range's volume-tails read: bin every in-range footprint level onto a `resolution`-bin price grid (side volumes kept separate, overlap-distributed so volume is conserved exactly), then scan the SELL bins from the top and the BUY bins from the bottom until each side's accumulated volume reaches `thresholdFrac` of the range's total volume.

Returns null when the range holds no volume (not fetched yet, or nothing traded).

```typescript
function buildRangeTails(
    slices: readonly FootprintSlice[],
    range: { start: number; end: number },
    resolution: number,
    thresholdFrac: number,
    nowMs: number,
): RangeTailsProfile | null
```

See also: [`FootprintSlice`](/vela-pro/api/chart-types#footprintslice), [`RangeTailsProfile`](/vela-pro/api/chart-types#rangetailsprofile).

### `buildSessionVpDeveloping` [#buildsessionvpdeveloping]

The DEVELOPING structure: walk the session's slices in time order on the SAME final row grid the profile uses (stable rows: the developing lines never re-bin as later data widens the range) and emit one step per slice time with the POC and value area of everything traded so far. Steps come back ascending; empty when the session holds no volume.

```typescript
function buildSessionVpDeveloping(
    slices: readonly FootprintSlice[],
    session: TpoSessionSpan,
    rowCount: number,
    valueAreaFrac: number,
): SessionVpDevelopingStep[]
```

See also: [`FootprintSlice`](/vela-pro/api/chart-types#footprintslice), [`SessionVpDevelopingStep`](/vela-pro/api/chart-types#sessionvpdevelopingstep), [`TpoSessionSpan`](/vela-pro/api/chart-types#tposessionspan).

### `buildSessionVpProfile` [#buildsessionvpprofile]

Bucket one session's footprint levels by price. Only slices whose time falls in `[session.start, session.end)` count; each level's `[price, price + tick)` span distributes over the rows it overlaps, proportional to the overlap: total volume is conserved exactly, whatever grid the source served. The value area grows from the POC by repeatedly absorbing the larger adjacent row until it covers `valueAreaFrac` of the session's volume.

Returns null when the session holds no volume (not fetched yet, or nothing traded).

```typescript
function buildSessionVpProfile(
    slices: readonly FootprintSlice[],
    session: TpoSessionSpan,
    rowCount: number,
    valueAreaFrac: number,
    nowMs: number,
): SessionVpProfile | null
```

See also: [`FootprintSlice`](/vela-pro/api/chart-types#footprintslice), [`SessionVpProfile`](/vela-pro/api/chart-types#sessionvpprofile), [`TpoSessionSpan`](/vela-pro/api/chart-types#tposessionspan).

### `buildTpoVolumeProfile` [#buildtpovolumeprofile]

Bucket one session's volume by price from the chart's bars. Only bars whose time falls in `[sessionStart, sessionEnd)` count; each bar's volume is distributed over the rows its high–low range overlaps, proportionally to the overlap, and split up/down by the bar's close direction: total volume is conserved exactly. The value area grows from the POC by repeatedly absorbing the larger adjacent row until it covers `valueAreaFrac` of the session's volume. Pure; the layer memoizes calls per profile against the bar array identity.

Returns null when the session holds no volume (or no bars).

```typescript
function buildTpoVolumeProfile(
    bars: readonly OHLCV[],
    sessionStart: number,
    sessionEnd: number,
    rowCount: number,
    valueAreaFrac: number,
): TpoVolumeProfile | null
```

See also: [`TpoVolumeProfile`](/vela-pro/api/chart-types#tpovolumeprofile). From `@luxalgo/vela/plugin`: `OHLCV`.

### `deriveTpoStructure` [#derivetpostructure]

Derive the auction structure of one profile:

* POC: the row with the most TPOs (tie → closest to the profile's price midpoint);
* VA: classic two-row expansion around the POC until `vaPercent` of TPOs is covered;
* IB: the price extent of blocks covering the first `ibMinutes` of the session;
* singles: mid-profile rows with exactly one TPO whose run touches no extreme (extreme runs are tails/excess, not singles);
* poor high/low: ≥2 TPOs printed at the very extreme row.

```typescript
function deriveTpoStructure(profile: TpoProfile, vaPercent: number, ibMinutes: number): TpoStructure
```

See also: [`TpoProfile`](/vela-pro/api/chart-types#tpoprofile), [`TpoStructure`](/vela-pro/api/chart-types#tpostructure).

### `footprintContextMenuAttachment` [#footprintcontextmenuattachment]

```typescript
function footprintContextMenuAttachment(settingsSection: string): WidgetAttachment
```

| Parameter         | Type     | Description                                                                                                                                |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `settingsSection` | `string` | The footprint tab's title in the chart settings dialog (the registered `ChartTypeSettingsSection.title`: what "Footprint Settings" opens). |

From `@luxalgo/vela/plugin`: `WidgetAttachment`.

### `orderflowBarsFromSlices` [#orderflowbarsfromslices]

Collapse footprint slices into per-bar [`OrderflowBar`](/vela-pro/api/chart-types#orderflowbar)s. Bars bucket on the `[k·bucketMs + origin, …)` grid (pass a chart bar's `time % bucketMs` as `originMs` so the aggregates land exactly on the chart's bars); the intra-bar delta paths walk the bar's slices in time order. Bars come back ascending.

```typescript
function orderflowBarsFromSlices(
    slices: readonly FootprintSlice[],
    bucketMs: number,
    originMs?: number,
): OrderflowBar[]
```

Default: `originMs = 0`.

See also: [`FootprintSlice`](/vela-pro/api/chart-types#footprintslice), [`OrderflowBar`](/vela-pro/api/chart-types#orderflowbar).

### `sessionAt` [#sessionat]

The session containing `ms`, or null when `ms` falls in a custom window's daily gap. Sessions are UTC-anchored: days at midnight, weeks on Monday, months on the 1st.

```typescript
function sessionAt(kind: TpoSessionKind, ms: number, win?: TpoCustomWindow): TpoSessionSpan | null
```

See also: [`TpoCustomWindow`](/vela-pro/api/chart-types#tpocustomwindow), [`TpoSessionKind`](/vela-pro/api/chart-types#tposessionkind), [`TpoSessionSpan`](/vela-pro/api/chart-types#tposessionspan).

### `sessionsInRange` [#sessionsinrange]

Every session INTERSECTING `[from, to)`, ascending (bounded by `cap`, right-anchored).

```typescript
function sessionsInRange(
    kind: TpoSessionKind,
    from: number,
    to: number,
    win?: TpoCustomWindow,
    cap?: number,
): TpoSessionSpan[]
```

Default: `cap = Infinity`.

See also: [`TpoCustomWindow`](/vela-pro/api/chart-types#tpocustomwindow), [`TpoSessionKind`](/vela-pro/api/chart-types#tposessionkind), [`TpoSessionSpan`](/vela-pro/api/chart-types#tposessionspan).

### `tpoContextMenuAttachment` [#tpocontextmenuattachment]

```typescript
function tpoContextMenuAttachment(settingsSection: string): WidgetAttachment
```

| Parameter         | Type     | Description                                                                                                                    |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `settingsSection` | `string` | The TPO tab's title in the chart settings dialog (the registered `ChartTypeSettingsSection.title`: what "TPO Settings" opens). |

From `@luxalgo/vela/plugin`: `WidgetAttachment`.

## Classes [#classes]

### `FootprintCache` [#footprintcache]

A single-series cache of AGGREGATED order-flow footprints (never raw trades), keyed by bar open-time, plus the time ranges that have been fetched. Two write paths:

* `replace`: authoritative aggregation for a fetched window (REPLACE the bars).
* `add`: incremental accumulation (ADD into the forming bars).

The data engine owns one per chart: it fetches missing ranges as the user scrolls (REPLACE + `markCovered`) and folds in live slices, then hands `materialize` to the renderer. Coverage is tracked so a window fetches once.

```typescript
class FootprintCache {
    readonly size: number;
    replace(fps: readonly BarFootprint[]): void;
    add(fps: readonly BarFootprint[]): void;
    markCovered(from: number, to: number): void;
    missingRanges(from: number, to: number): Interval[];
    materialize(): BarFootprint[];
    clear(): void;
}

// Unexported supporting type referenced above
type Interval = [number, number];
```

| Member            | Type                                       | Description                                                                       |
| ----------------- | ------------------------------------------ | --------------------------------------------------------------------------------- |
| `size`            | `number`                                   | Number of cached bars.                                                            |
| `replace()`       | `(fps: readonly BarFootprint[]) => void`   | Authoritatively set the given bars (a complete aggregation for a fetched window). |
| `add()`           | `(fps: readonly BarFootprint[]) => void`   | Accumulate the given (already-aggregated) bars into existing ones.                |
| `markCovered()`   | `(from: number, to: number) => void`       | Record that `[from, to)` has been fetched (so `missingRanges` skips it).          |
| `missingRanges()` | `(from: number, to: number) => Interval[]` | The sub-ranges of `[from, to)` not yet covered by a fetch (left → right).         |
| `materialize()`   | `() => BarFootprint[]`                     | All cached bars as sorted, materialized footprints (for the renderer).            |
| `clear()`         | `() => void`                               |                                                                                   |

See also: [`BarFootprint`](/vela-pro/api/chart-types#barfootprint).

### `FootprintDataEngine` [#footprintdataengine]

```typescript
class FootprintDataEngine implements SeriesDataEngine {
    start(host: SeriesDataEngineHost): void;
    onViewport(range: VisibleRange): void;
    onBars(): void;
    onSettings(values: Record<string, unknown>): void;
    suspend(): void;
    resume(): void;
    stop(): void;
}

// Unexported supporting type referenced above
interface VisibleRange {
    from: number;
    to: number;
}
```

| Member         | Type                                        | Description                                                                                                                                                                                                             |
| -------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `start()`      | `(host: SeriesDataEngineHost) => void`      |                                                                                                                                                                                                                         |
| `onViewport()` | `(range: VisibleRange) => void`             | The visible range changed (pan/zoom) while the style is active.                                                                                                                                                         |
| `onBars()`     | `() => void`                                | A static chart's bars grew (a replay revealed its next bar): fetch it, keeping the planned range, and re-push. A live chart's new bars ride the slice subscription.                                                     |
| `onSettings()` | `(values: Record<string, unknown>) => void` | The footprint bag changed (dialog tab, context menu, a restored document). The engine has no use for the values itself (the layer reads the bag every frame); it is the per-chart observer of the `hideCandles` switch. |
| `suspend()`    | `() => void`                                | The style left `'footprint'`: stop streaming; cache + coverage stay for an instant return.                                                                                                                              |
| `resume()`     | `() => void`                                | The style returned: re-push the cache, resubscribe (catch-up heals the gap).                                                                                                                                            |
| `stop()`       | `() => void`                                | The chart is going away, or the engine is being replaced: release everything. Its host drops every push from here on.                                                                                                   |

From `@luxalgo/vela/plugin`: `SeriesDataEngine`, `SeriesDataEngineHost`.

### `TpoDataEngine` [#tpodataengine]

```typescript
class TpoDataEngine implements SeriesDataEngine {
    constructor(opts?: { chrome?: boolean });
    start(host: SeriesDataEngineHost): void;
    onViewport(range: { from: number; to: number }): void;
    onBars(): void;
    onSettings(values: Record<string, unknown>): void;
    suspend(): void;
    resume(): void;
    stop(): void;
    hitProfile(time: number, price: number): TpoProfile | null;
    sessionGrid(): SessionGrid;
}

// Unexported supporting type referenced above
interface SessionGrid {
    at(ms: number): TpoSessionSpan | null;
    next(ms: number): TpoSessionSpan | null;
    prev(ms: number): TpoSessionSpan | null;
}
```

| Member          | Type                                                  | Description                                                                                                                                                                                                                                                                                                                                      |
| --------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `constructor`   | `(opts?: { chrome?: boolean })`                       | `chrome: false` for the overlay indicator: must not steal the chart-type engine's WeakMap slot (the merge context menu keys off it).                                                                                                                                                                                                             |
| `start()`       | `(host: SeriesDataEngineHost) => void`                |                                                                                                                                                                                                                                                                                                                                                  |
| `onViewport()`  | `(range: { from: number; to: number }) => void`       | The visible range changed (pan/zoom) while the style is active.                                                                                                                                                                                                                                                                                  |
| `onBars()`      | `() => void`                                          | A static chart's bars grew (a replay revealing its next bar): the profiles regrow up to the new data edge, and a bar opening a new session plans it. A live chart refreshes on its own timer instead.                                                                                                                                            |
| `onSettings()`  | `(values: Record<string, unknown>) => void`           | New settings values from the chart-settings dialog (the type's SDK section). Also delivered once right BEFORE `start()` whenever stored values exist (a persisted config, a market switch recreating the engine): an engine must accept a pre-start call as pure configuration, so it never fetches on schema defaults the user has edited away. |
| `suspend()`     | `() => void`                                          | The style was left: pause fetching; the cache stays for a cheap resume.                                                                                                                                                                                                                                                                          |
| `resume()`      | `() => void`                                          | The style was re-entered: re-push what the layer shows (nothing pushed while suspended reached it).                                                                                                                                                                                                                                              |
| `stop()`        | `() => void`                                          | The chart is going away, or the engine is being replaced: release everything. Its host drops every push from here on.                                                                                                                                                                                                                            |
| `hitProfile()`  | `(time: number, price: number) => TpoProfile \| null` | The pushed profile under a chart point: the click must land inside the profile's session span AND its painted price extent, so empty chart areas keep the host's own context menu.                                                                                                                                                               |
| `sessionGrid()` | `() => SessionGrid`                                   | The sync session-lookup surface for the current kind/window (merge math, the context menu's neighbor questions): calendar-driven when the market is.                                                                                                                                                                                             |

See also: [`TpoProfile`](/vela-pro/api/chart-types#tpoprofile), [`TpoSessionSpan`](/vela-pro/api/chart-types#tposessionspan). From `@luxalgo/vela/plugin`: `SeriesDataEngine`, `SeriesDataEngineHost`.

## Interfaces and types [#interfaces-and-types]

### `AggressorSide` [#aggressorside]

The taker (aggressor) side of an executed trade:

* `'buy'`: the taker lifted the ask (bought into resting sell liquidity).
* `'sell'`: the taker hit the bid (sold into resting buy liquidity).

This split is what separates a true *footprint* (bid/ask volume per price) from a plain volume profile. Each venue exposes it differently; sources normalize to this neutral value at their boundary.

```typescript
type AggressorSide = 'buy' | 'sell';
```

### `BarFootprint` [#barfootprint]

Order-flow detail for ONE bar, keyed to the bar's open time. A sidecar to the canonical OHLCV bar, never embedded in it: footprints are expensive to build, lazily fetched, and not available for every symbol, whereas OHLCV always is.

```typescript
interface BarFootprint {
    time: number;
    levels: FootprintLevel[];
    buyVolume: number;
    sellVolume: number;
    delta: number;
    buyCount?: number;
    sellCount?: number;
}
```

| Member       | Type               | Description                                                                         |
| ------------ | ------------------ | ----------------------------------------------------------------------------------- |
| `time`       | `number`           | Bar open time, epoch ms: matches the corresponding `OHLCV.time`.                    |
| `levels`     | `FootprintLevel[]` | Price levels, ascending by price (low → high).                                      |
| `buyVolume`  | `number`           | Total buy-aggressor volume across all levels.                                       |
| `sellVolume` | `number`           | Total sell-aggressor volume across all levels.                                      |
| `delta`      | `number`           | `buyVolume - sellVolume` for the bar.                                               |
| `buyCount?`  | `number`           | Total per-side TRADE COUNTS across all levels: present iff the levels carry counts. |
| `sellCount?` | `number`           |                                                                                     |

See also: [`FootprintLevel`](/vela-pro/api/chart-types#footprintlevel).

### `CumulativeAnchor` [#cumulativeanchor]

Where a cumulative sum resets: a calendar period (UTC-anchored) or never.

```typescript
type CumulativeAnchor = 'day' | 'week' | 'month' | 'all';
```

### `DeltaMetric` [#deltametric]

Which per-bar delta a cumulative series accumulates: raw volume delta, trade-count delta, or the delta of AVERAGE trade sizes (volume ÷ count per side: who trades bigger, not more; needs counts, like `'count'`).

```typescript
type DeltaMetric = 'volume' | 'count' | 'average';
```

### `FootprintBatch` [#footprintbatch]

A footprint range response WITH a completeness signal: `slices` is everything the source can serve right now, and `uncovered` lists the sub-ranges of the REQUEST it could not (typically because a server is still back-filling them). Consumers that record coverage must mark it AROUND the uncovered ranges (never over them) and re-ask for those later; absent/empty `uncovered` means the response is complete.

```typescript
interface FootprintBatch {
    slices: FootprintSlice[];
    uncovered?: ReadonlyArray<readonly [number, number]>;
    sliceMs?: number;
    servedFrom?: number;
}
```

| Member        | Type                                       | Description                                                                                                                                                                                                                                                                                              |
| ------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slices`      | `FootprintSlice[]`                         |                                                                                                                                                                                                                                                                                                          |
| `uncovered?`  | `ReadonlyArray<readonly [number, number]>` | Half-open `[from, to)` ms ranges of the request that are not served yet.                                                                                                                                                                                                                                 |
| `sliceMs?`    | `number`                                   | Width (ms) of the WIDEST slice in the batch: the source's serving granularity for this request (a plan may floor it above the granularity asked for). A consumer bucketing slices into bars must refuse a batch coarser than its bar. Absent = unknown (an older source): callers assume the slices fit. |
| `servedFrom?` | `number`                                   | Where the source actually began serving (epoch ms). Past the request's `from` when the source clamped the window (a span guard, a plan's lookback horizon): the part before it was never looked at, which is not the same as empty. Absent = served from `from`.                                         |

See also: [`FootprintSlice`](/vela-pro/api/chart-types#footprintslice).

### `FootprintLevel` [#footprintlevel]

Executed volume at one price bucket within a bar, split by aggressor side.

```typescript
interface FootprintLevel {
    price: number;
    buyVolume: number;
    sellVolume: number;
    buyCount?: number;
    sellCount?: number;
}
```

| Member       | Type     | Description                                                                                                                                                                                      |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `price`      | `number` | Bucket price: the low edge of the row (`floor(price / priceTick) * priceTick`).                                                                                                                  |
| `buyVolume`  | `number` | Volume executed by buy-aggressors (ask lifts) at this level.                                                                                                                                     |
| `sellVolume` | `number` | Volume executed by sell-aggressors (bid hits) at this level.                                                                                                                                     |
| `buyCount?`  | `number` | TRADE COUNTS per side: in the venue's pinned trade unit. `undefined` = the source did not provide counts: distinct from a real 0. Counts aggregate exactly like volumes: re-bucketing sums them. |
| `sellCount?` | `number` |                                                                                                                                                                                                  |

### `FootprintSlice` [#footprintslice]

One PRE-AGGREGATED footprint slice: buy/sell volume-at-price over a fixed one-minute window, timeframe-agnostic. The chart re-buckets slices into any bar duration, so a source never needs to know the chart's timeframe. This is the neutral order-flow unit a feed serves when it can't expose individual trades.

```typescript
interface FootprintSlice {
    time: number;
    tick: number;
    levels: FootprintLevel[];
}
```

| Member   | Type               | Description                                                               |
| -------- | ------------------ | ------------------------------------------------------------------------- |
| `time`   | `number`           | Slice open time, epoch ms (minute-aligned).                               |
| `tick`   | `number`           | The price grid its levels sit on (display re-bucketing only ever merges). |
| `levels` | `FootprintLevel[]` | Price levels, ascending by price.                                         |

See also: [`FootprintLevel`](/vela-pro/api/chart-types#footprintlevel).

### `OrderflowBar` [#orderflowbar]

One bar's order-flow aggregate: the per-bar unit every pane indicator reads. Counts follow the footprint contract: `undefined` means the source did not provide them, never a real zero, and one count-less contributing level poisons the whole bar's counts, so real and fake zeros never mix.

```typescript
interface OrderflowBar {
    time: number;
    buyVolume: number;
    sellVolume: number;
    delta: number;
    buyCount?: number;
    sellCount?: number;
    deltaHigh: number;
    deltaLow: number;
    countDeltaHigh?: number;
    countDeltaLow?: number;
}
```

| Member            | Type     | Description                                                                                                                                                                                                                                                                               |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `time`            | `number` | Bar open time, epoch ms: matches the corresponding chart bar's `time`.                                                                                                                                                                                                                    |
| `buyVolume`       | `number` |                                                                                                                                                                                                                                                                                           |
| `sellVolume`      | `number` |                                                                                                                                                                                                                                                                                           |
| `delta`           | `number` | `buyVolume - sellVolume`.                                                                                                                                                                                                                                                                 |
| `buyCount?`       | `number` |                                                                                                                                                                                                                                                                                           |
| `sellCount?`      | `number` |                                                                                                                                                                                                                                                                                           |
| `deltaHigh`       | `number` | Extremes of the RUNNING volume delta inside the bar (relative to the bar's open, which is 0), walked slice by slice in time order: the cumulative candle's wick material. A bar built from one slice degenerates to `high = max(0, delta)`, `low = min(0, delta)`: honest, without wicks. |
| `deltaLow`        | `number` |                                                                                                                                                                                                                                                                                           |
| `countDeltaHigh?` | `number` | Count-delta path extremes: present iff the bar's counts are.                                                                                                                                                                                                                              |
| `countDeltaLow?`  | `number` |                                                                                                                                                                                                                                                                                           |

### `RangeTailsProfile` [#rangetailsprofile]

The full range read: both tails plus the range extent and equilibrium levels.

```typescript
interface RangeTailsProfile {
    start: number;
    end: number;
    min: number;
    max: number;
    totalVolume: number;
    supply: TailsZone;
    demand: TailsZone;
    equilibrium: number;
    wEquilibrium: number | null;
    complete: boolean;
}
```

| Member         | Type             | Description                                                               |
| -------------- | ---------------- | ------------------------------------------------------------------------- |
| `start`        | `number`         |                                                                           |
| `end`          | `number`         | Exclusive range end.                                                      |
| `min`          | `number`         | Price extent over every in-range level with volume.                       |
| `max`          | `number`         |                                                                           |
| `totalVolume`  | `number`         | Total (buy + sell) volume in the range: the threshold's denominator.      |
| `supply`       | `TailsZone`      |                                                                           |
| `demand`       | `TailsZone`      |                                                                           |
| `equilibrium`  | `number`         | Plain range midpoint.                                                     |
| `wEquilibrium` | `number \| null` | Midpoint of the two weighted averages: null until BOTH tails reached.     |
| `complete`     | `boolean`        | Whether the range lies fully in the past (a forming range keeps growing). |

See also: [`TailsZone`](/vela-pro/api/chart-types#tailszone).

### `SessionVpDevelopingStep` [#sessionvpdevelopingstep]

One step of the DEVELOPING structure: the session's POC and value area as they stood once every slice up to `time` (inclusive) had traded. Prices, not rows: `poc` at its row's middle, `vaLow`/`vaHigh` at the value area's outer bounds.

```typescript
interface SessionVpDevelopingStep {
    time: number;
    poc: number;
    vaLow: number;
    vaHigh: number;
}
```

### `SessionVpProfile` [#sessionvpprofile]

One session's volume-by-price profile, built from real footprint levels.

```typescript
interface SessionVpProfile {
    sessionStart: number;
    sessionEnd: number;
    rowH: number;
    rows: SessionVpRow[];
    maxTotal: number;
    poc: number;
    vaFrom: number;
    vaTo: number;
    complete: boolean;
    developing?: SessionVpDevelopingStep[];
}
```

| Member         | Type                        | Description                                                                                                                                                                                   |
| -------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sessionStart` | `number`                    |                                                                                                                                                                                               |
| `sessionEnd`   | `number`                    | Exclusive session end.                                                                                                                                                                        |
| `rowH`         | `number`                    | Price height of one row.                                                                                                                                                                      |
| `rows`         | `SessionVpRow[]`            | Ascending by price; length = requested row count (a flat session yields 1).                                                                                                                   |
| `maxTotal`     | `number`                    | Largest single-row total volume (normalization; > 0).                                                                                                                                         |
| `poc`          | `number`                    | Index of the point-of-control (highest total-volume) row.                                                                                                                                     |
| `vaFrom`       | `number`                    | Value-area row span, inclusive `[vaFrom, vaTo]`.                                                                                                                                              |
| `vaTo`         | `number`                    |                                                                                                                                                                                               |
| `complete`     | `boolean`                   | Whether the session lies fully in the past (a forming profile keeps growing).                                                                                                                 |
| `developing?`  | `SessionVpDevelopingStep[]` | The intra-session POC/VA evolution (see [`buildSessionVpDeveloping`](/vela-pro/api/chart-types#buildsessionvpdeveloping)): attached by the indicator only while the developing display is on. |

See also: [`SessionVpDevelopingStep`](/vela-pro/api/chart-types#sessionvpdevelopingstep), [`SessionVpRow`](/vela-pro/api/chart-types#sessionvprow).

### `SessionVpRow` [#sessionvprow]

One profile row: `[price, price + rowH)` with the aggressor-split volume in it.

```typescript
interface SessionVpRow {
    price: number;
    buy: number;
    sell: number;
}
```

| Member  | Type     | Description                  |
| ------- | -------- | ---------------------------- |
| `price` | `number` | The row's LOWER price bound. |
| `buy`   | `number` |                              |
| `sell`  | `number` |                              |

### `TailsStep` [#tailsstep]

One rung of a tail's accumulation ladder: the bin `[lo, hi)` and the cumulative side volume AFTER consuming it, as a fraction of the range's total volume.

```typescript
interface TailsStep {
    lo: number;
    hi: number;
    frac: number;
}
```

### `TailsZone` [#tailszone]

One accumulated tail (supply from the top, demand from the bottom).

```typescript
interface TailsZone {
    lo: number;
    hi: number;
    avg: number;
    wavg: number;
    steps: TailsStep[];
    reached: boolean;
}
```

| Member    | Type          | Description                                                                                                                                            |
| --------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `lo`      | `number`      | Zone price bounds: supply = `[boundary, max]`, demand = `[min, boundary]`. Meaningful only when `reached`: an unreached tail consumed the whole range. |
| `hi`      | `number`      |                                                                                                                                                        |
| `avg`     | `number`      | Plain midpoint of the zone.                                                                                                                            |
| `wavg`    | `number`      | Volume-weighted price of the consumed side volume (the zone's real center of mass). Falls back to the zone midpoint when nothing was consumed.         |
| `steps`   | `TailsStep[]` | The accumulation ladder, outermost bin first, ending at the bin where the threshold was crossed (every scanned bin when it never was).                 |
| `reached` | `boolean`     | Whether the accumulated side volume reached the threshold inside the range.                                                                            |

See also: [`TailsStep`](/vela-pro/api/chart-types#tailsstep).

### `TpoCustomWindow` [#tpocustomwindow]

A custom DAILY session window, minutes from UTC midnight. `end <= start` wraps past midnight (an overnight session); `start === end` means the full 24h day.

```typescript
interface TpoCustomWindow {
    startMin: number;
    endMin: number;
}
```

### `TpoProfile` [#tpoprofile]

One profile: the letter matrix plus its span anchors. Usually one session; a user-merged group of consecutive sessions folds into ONE profile spanning them all (the layer needs no merge awareness). Pushed by the data engine as `TpoProfile[]` (ascending by `sessionStart`) on the `'tpo'` native-data channel. Structure (POC/VA/IB/singles/poor) is DERIVED from the matrix at paint time so structural settings never round-trip through the engine.

```typescript
interface TpoProfile {
    sessionStart: number;
    sessionEnd: number;
    blockMs: number;
    blockCount: number;
    tick: number;
    rows: TpoRow[];
    open: number | null;
    close: number | null;
    complete: boolean;
    cellCounts?: boolean;
}
```

| Member         | Type             | Description                                                                                                                                                                                                        |
| -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sessionStart` | `number`         |                                                                                                                                                                                                                    |
| `sessionEnd`   | `number`         | Exclusive session end (the next session's start for calendar sessions).                                                                                                                                            |
| `blockMs`      | `number`         | One block's duration (ms): the letter period.                                                                                                                                                                      |
| `blockCount`   | `number`         | Blocks the session holds (fixed by span/blockMs, not by data coverage).                                                                                                                                            |
| `tick`         | `number`         | Row height (price units).                                                                                                                                                                                          |
| `rows`         | `TpoRow[]`       | Ascending by `price`.                                                                                                                                                                                              |
| `open`         | `number \| null` | First traded price of the session (null while no data landed).                                                                                                                                                     |
| `close`        | `number \| null` | Last traded price so far.                                                                                                                                                                                          |
| `complete`     | `boolean`        | Whether the session lies fully in the past (a forming profile keeps growing).                                                                                                                                      |
| `cellCounts?`  | `boolean`        | Whether the rows' cell metrics carry meaningful TRADE COUNTS (`buyN`/`sellN`): false when any contributing footprint level lacked them, so a trades-count display can fall back honestly instead of showing zeros. |

See also: [`TpoRow`](/vela-pro/api/chart-types#tporow).

### `TpoRow` [#tporow]

One price row of a profile. `blocks` holds the ASCENDING indices of the time blocks whose range touched this row: its length is the row's TPO count, and each index is the block's letter for the lettered display.

```typescript
interface TpoRow {
    price: number;
    blocks: number[];
    cells?: TpoCellMetrics[];
}

// Unexported supporting type referenced above
interface TpoCellMetrics {
    buy: number;
    sell: number;
    buyN?: number;
    sellN?: number;
}
```

| Member   | Type               | Description                                                                                                                                                                                                                                                             |
| -------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `price`  | `number`           | Row bottom price (the row spans `[price, price + tick)`).                                                                                                                                                                                                               |
| `blocks` | `number[]`         |                                                                                                                                                                                                                                                                         |
| `cells?` | `TpoCellMetrics[]` | Per-cell order-flow metrics aligned index-for-index with `blocks`: present only when the engine fetched the session's footprints (metric block coloring on, a footprint-capable provider). A cell the block's range touched but nothing traded in carries honest zeros. |

### `TpoSessionKind` [#tposessionkind]

How bars group into one TPO profile.

```typescript
type TpoSessionKind = 'day' | 'week' | 'month' | 'custom';
```

### `TpoSessionSpan` [#tposessionspan]

One session's time span, `[start, end)`.

```typescript
interface TpoSessionSpan {
    start: number;
    end: number;
}
```

### `TpoStructure` [#tpostructure]

The derived auction structure of one profile (see [`deriveTpoStructure`](/vela-pro/api/chart-types#derivetpostructure)).

```typescript
interface TpoStructure {
    poc: number | null;
    vah: number | null;
    val: number | null;
    ibHigh: number | null;
    ibLow: number | null;
    singles: number[];
    poorHigh: boolean;
    poorLow: boolean;
    total: number;
}
```

| Member     | Type             | Description                                                                                |
| ---------- | ---------------- | ------------------------------------------------------------------------------------------ |
| `poc`      | `number \| null` | Row price of the Point of Control (highest TPO count), or null on an empty profile.        |
| `vah`      | `number \| null` | Value-area high: the TOP edge price of the highest VA row (row price + tick).              |
| `val`      | `number \| null` | Value-area low: the bottom edge price of the lowest VA row.                                |
| `ibHigh`   | `number \| null` | Initial-balance top edge (max touched price of the IB window + tick).                      |
| `ibLow`    | `number \| null` | Initial-balance bottom edge.                                                               |
| `singles`  | `number[]`       | Row prices of MID-PROFILE single prints (runs touching an extreme are tails, not singles). |
| `poorHigh` | `boolean`        | ≥2 TPOs at the profile's top row: an unfinished (poor) high.                               |
| `poorLow`  | `boolean`        | ≥2 TPOs at the profile's bottom row: an unfinished (poor) low.                             |
| `total`    | `number`         | Total TPO count across the profile.                                                        |

### `TpoVolumeProfile` [#tpovolumeprofile]

One session's bucketed volume-by-price profile.

```typescript
interface TpoVolumeProfile {
    rows: TpoVolumeRow[];
    rowH: number;
    maxTotal: number;
    poc: number;
    vaFrom: number;
    vaTo: number;
}
```

| Member     | Type             | Description                                                                 |
| ---------- | ---------------- | --------------------------------------------------------------------------- |
| `rows`     | `TpoVolumeRow[]` | Ascending by price; length = requested row count (a flat session yields 1). |
| `rowH`     | `number`         | Price height of one row.                                                    |
| `maxTotal` | `number`         | Largest single-row total volume (normalization; > 0).                       |
| `poc`      | `number`         | Index of the point-of-control (highest total-volume) row.                   |
| `vaFrom`   | `number`         | Value-area row span, inclusive `[vaFrom, vaTo]`.                            |
| `vaTo`     | `number`         |                                                                             |

See also: [`TpoVolumeRow`](/vela-pro/api/chart-types#tpovolumerow).

### `TpoVolumeRow` [#tpovolumerow]

One profile row: `[price, price + rowH)` with the up/down volume that landed in it.

```typescript
interface TpoVolumeRow {
    price: number;
    up: number;
    down: number;
}
```

| Member  | Type     | Description                  |
| ------- | -------- | ---------------------------- |
| `price` | `number` | The row's LOWER price bound. |
| `up`    | `number` |                              |
| `down`  | `number` |                              |

### `Trade` [#trade]

One executed trade, neutral to any venue. The fundamental order-flow primitive: footprints, cumulative delta, and a time-&-sales tape are all aggregations of these.

```typescript
interface Trade {
    time: number;
    price: number;
    size: number;
    side: AggressorSide;
}
```

| Member  | Type            | Description                                               |
| ------- | --------------- | --------------------------------------------------------- |
| `time`  | `number`        | Execution time, epoch ms.                                 |
| `price` | `number`        | Execution price.                                          |
| `size`  | `number`        | Trade size in the base asset.                             |
| `side`  | `AggressorSide` | Taker side: `'buy'` lifted the ask, `'sell'` hit the bid. |

See also: [`AggressorSide`](/vela-pro/api/chart-types#aggressorside).
