# Data feeds (/vela-pro/api/data-feeds)



This page documents the extended feed interfaces that a `DataProvider` can implement beyond OHLCV candles, including footprint slices, Level 2 market depth, trade tape streams, quotes, and the in-memory footprint store.

Import symbols on this page from `@luxalgo/vela-pro`. Related guides: [Data connectivity overview](/vela-pro/data/overview), [Footprint data](/vela-pro/data/feeds/footprints), [Quotes and market depth](/vela-pro/data/feeds/quotes-and-depth).

## Functions [#functions]

### `blankQuote` [#blankquote]

Also exported from `@luxalgo/vela-pro-watchlist`, `@luxalgo/vela-pro/plugin`.

```typescript
function blankQuote(symbol: string): Quote
```

See also: [`Quote`](/vela-pro/api/data-feeds#quote).

### `footprintFeedFor` [#footprintfeedfor]

The shared order-flow feed behind a chart symbol, or null when its provider serves none. The entry point for any indicator that reads footprints: everything read through it is fetched once and shared with every other consumer of that provider.

```typescript
function footprintFeedFor(
    data: FootprintFeedSurface,
    symbol: string,
): { feed: FootprintStore; ticker: string; provider: string } | null
```

See also: [`FootprintFeedSurface`](/vela-pro/api/data-feeds#footprintfeedsurface), [`FootprintStore`](/vela-pro/api/data-feeds#footprintstore-class).

### `footprintStore` [#footprintstore]

The shared store of a footprint-capable provider: one per provider instance.

```typescript
function footprintStore(feed: FootprintFeed): FootprintStore
```

See also: [`FootprintFeed`](/vela-pro/api/data-feeds#footprintfeed), [`FootprintStore`](/vela-pro/api/data-feeds#footprintstore-class).

### `groupLevels` [#grouplevels]

Group book levels into `step`-wide buckets (bids floor, asks ceil), summing their sizes.

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function groupLevels(levels: readonly BookLevel[], step: number, side: 'bid' | 'ask'): BookLevel[]
```

See also: [`BookLevel`](/vela-pro/api/data-feeds#booklevel).

### `hasDepthFeed` [#hasdepthfeed]

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
function hasDepthFeed(p: unknown): p is DepthFeed
```

See also: [`DepthFeed`](/vela-pro/api/data-feeds#depthfeed).

### `hasFootprints` [#hasfootprints]

Narrow a registered provider to its order-flow surface, if it has one.

```typescript
function hasFootprints(p: DataProvider | undefined): p is DataProvider & FootprintFeed
```

See also: [`FootprintFeed`](/vela-pro/api/data-feeds#footprintfeed). From `@luxalgo/vela/plugin`: `DataProvider`.

### `withChange` [#withchange]

Chg and Chg% from the last price and the previous close.

Also exported from `@luxalgo/vela-pro-watchlist`, `@luxalgo/vela-pro/plugin`.

```typescript
function withChange(q: Quote): Quote
```

See also: [`Quote`](/vela-pro/api/data-feeds#quote).

## Classes [#classes]

### `BookState` [#bookstate]

One book kept from a snapshot and its level changes (a size of 0 removes a level): the shape most venues send.

```typescript
class BookState {
    tick: number;
    time: number;
    reset(
        bids: ReadonlyArray<readonly [number, number]>,
        asks: ReadonlyArray<readonly [number, number]>,
        tick: number,
        time?: number,
    ): void;
    update(
        bids: ReadonlyArray<readonly [number, number]>,
        asks: ReadonlyArray<readonly [number, number]>,
        time?: number,
    ): void;
    snapshot(depth?: number): BookSnapshot;
}
```

Defaults: `reset(time = Date.now())`, `update(time = Date.now())`, `snapshot(depth = 50)`.

See also: [`BookSnapshot`](/vela-pro/api/data-feeds#booksnapshot).

### `FootprintStore` class [#footprintstore-class]

```typescript
class FootprintStore implements FootprintFeed {
    constructor(source: FootprintFeed);
    footprintCaps(ticker: string): FootprintCaps;
    getFootprints(ticker: string, range: FootprintRange, sliceMs?: number): Promise<FootprintBatch>;
    subscribeFootprints(
        ticker: string,
        since: number,
        onSlices: (slices: FootprintSlice[]) => void,
    ): () => void;
    peek(
        ticker: string,
        range: { from: number; to: number; session?: string },
        sliceMs?: number,
    ): FootprintPeek;
    stats(): FootprintStoreStats;
    clear(): void;
}
```

| Member                  | Type                                                                                                         | Description                                                                                                                                                                                                                                                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `constructor`           | `(source: FootprintFeed)`                                                                                    |                                                                                                                                                                                                                                                                                                                                                |
| `footprintCaps()`       | `(ticker: string) => FootprintCaps`                                                                          | Fetch-planner capabilities for one ticker.                                                                                                                                                                                                                                                                                                     |
| `getFootprints()`       | `(ticker: string, range: FootprintRange, sliceMs?: number) => Promise<FootprintBatch>`                       | Pre-aggregated one-minute footprint slices for `[range.from, range.to]`. `sliceMs` is a granularity HINT (the chart's bar duration): a multi-timeframe source may serve bucket slices that divide it (fewer, bigger slices, same sums). Returns a completeness-aware batch (see [`FootprintBatch`](/vela-pro/api/chart-types#footprintbatch)). |
| `subscribeFootprints()` | `(ticker: string, since: number, onSlices: (slices: FootprintSlice[]) => void) => () => void`                | Live footprint slices from `since` onward. Deliveries are FULL-STATE snapshots per slice (the forming minute grows across deliveries): consumers replace by slice time, never accumulate. Returns an unsubscribe function.                                                                                                                     |
| `peek()`                | `(ticker: string, range: { from: number; to: number; session?: string }, sliceMs?: number) => FootprintPeek` | What the store holds for `(ticker, session, sliceMs)` inside `[from, to]`: no request.                                                                                                                                                                                                                                                         |
| `stats()`               | `() => FootprintStoreStats`                                                                                  |                                                                                                                                                                                                                                                                                                                                                |
| `clear()`               | `() => void`                                                                                                 | Forget every kept interval (live subscriptions are untouched).                                                                                                                                                                                                                                                                                 |

See also: [`FootprintBatch`](/vela-pro/api/chart-types#footprintbatch), [`FootprintCaps`](/vela-pro/api/data-feeds#footprintcaps), [`FootprintFeed`](/vela-pro/api/data-feeds#footprintfeed), [`FootprintPeek`](/vela-pro/api/data-feeds#footprintpeek), [`FootprintRange`](/vela-pro/api/data-feeds#footprintrange), [`FootprintSlice`](/vela-pro/api/chart-types#footprintslice), [`FootprintStoreStats`](/vela-pro/api/data-feeds#footprintstorestats).

### `ProviderQuotes` [#providerquotes]

Also exported from `@luxalgo/vela-pro-watchlist`, `@luxalgo/vela-pro/plugin`.

```typescript
class ProviderQuotes implements QuoteSource {
    constructor(data: () => DataFacade | null);
    dailyBars(symbol: string, count: number): Promise<OHLCV[]>;
    watch(symbol: string, onQuote: (q: Quote) => void): () => void;
    peek(symbol: string): Quote | null;
    dispose(): void;
}

// Unexported supporting type referenced above
type DataFacade = WidgetContext['chart']['data'];
```

| Member        | Type                                                          | Description                                                                                                                                                                                                                                     |
| ------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `constructor` | `(data: () => DataFacade \| null)`                            | `data`: the registry to resolve symbols through (the active chart's).                                                                                                                                                                           |
| `dailyBars()` | `(symbol: string, count: number) => Promise<OHLCV[]>`         | Up to `count` daily bars of `symbol`, oldest first; the last may be today's, still forming. Rejects when no history can be had. Optional: without it, the figures read from daily history (period returns, drawdowns, correlations) stay empty. |
| `watch()`     | `(symbol: string, onQuote: (q: Quote) => void) => () => void` | Follow `symbol`'s quote; `onQuote` gets every change. Returns the unsubscribe.                                                                                                                                                                  |
| `peek()`      | `(symbol: string) => Quote \| null`                           | The latest quote held for `symbol` (null when nobody watches it).                                                                                                                                                                               |
| `dispose()`   | `() => void`                                                  |                                                                                                                                                                                                                                                 |

See also: [`Quote`](/vela-pro/api/data-feeds#quote), [`QuoteSource`](/vela-pro/api/data-feeds#quotesource). From `@luxalgo/vela/plugin`: `OHLCV`, `WidgetContext`.

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

### `BookLevel` [#booklevel]

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
interface BookLevel {
    price: number;
    size: number;
}
```

### `BookSnapshot` [#booksnapshot]

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
interface BookSnapshot {
    bids: BookLevel[];
    asks: BookLevel[];
    tick: number;
    time: number;
}
```

| Member | Type          | Description                                      |
| ------ | ------------- | ------------------------------------------------ |
| `bids` | `BookLevel[]` | Best first: highest bid first, lowest ask first. |
| `asks` | `BookLevel[]` |                                                  |
| `tick` | `number`      | The price increment the book is read at.         |
| `time` | `number`      |                                                  |

See also: [`BookLevel`](/vela-pro/api/data-feeds#booklevel).

### `DepthFeed` [#depthfeed]

```typescript
interface DepthFeed {
    subscribeBook?(
        ticker: string,
        onBook: (book: BookSnapshot) => void,
        opts?: { depth?: number; onError?: (reason: string) => void },
    ): DepthSubscription;
    subscribeTrades?(
        ticker: string,
        onTrades: (trades: TapeTrade[], history?: boolean) => void,
        opts?: { onError?: (reason: string) => void },
    ): DepthSubscription;
}
```

| Member               | Type                                                                                                             | Description                                                                                           |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `subscribeBook?()`   | `(ticker: string, onBook: (book: BookSnapshot) => void, opts?: { depth?: number; …` (truncated; see declaration) | Follow `ticker`'s book; `onBook` gets the whole (top-`depth`) book after every change.                |
| `subscribeTrades?()` | `(ticker: string, onTrades: (trades: TapeTrade[], history?: boolean) => void, …` (truncated; see declaration)    | Follow `ticker`'s trades; `onTrades` gets new prints, newest last (`history` marks a first backfill). |

See also: [`BookSnapshot`](/vela-pro/api/data-feeds#booksnapshot), [`DepthSubscription`](/vela-pro/api/data-feeds#depthsubscription), [`TapeTrade`](/vela-pro/api/data-feeds#tapetrade).

### `DepthSubscription` [#depthsubscription]

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
interface DepthSubscription {
    close(): void;
}
```

### `FootprintCaps` [#footprintcaps]

How the engine's fetch planner should treat this feed for one ticker.

```typescript
interface FootprintCaps {
    bulkFetch: boolean;
    maxFetchSpanSec?: number;
}
```

| Member             | Type      | Description                                                                                                                                                                                         |
| ------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bulkFetch`        | `boolean` | One request returns complete slices for a wide range at low cost (a pre-aggregated, server-cached source). The planner then keeps the whole visible range covered instead of rationing tiny chunks. |
| `maxFetchSpanSec?` | `number`  | Cap on one viewport fetch window, in SECONDS (`Infinity` = uncapped: the visible range plus its pan buffer is the only bound).                                                                      |

### `FootprintFeed` [#footprintfeed]

The order-flow surface a footprint-capable provider exposes (beyond the core's port).

```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;
}
```

| Member                  | Type                                                                                          | Description                                                                                                                                                                                                                                                                                                                                    |
| ----------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getFootprints()`       | `(ticker: string, range: FootprintRange, sliceMs?: number) => Promise<FootprintBatch>`        | Pre-aggregated one-minute footprint slices for `[range.from, range.to]`. `sliceMs` is a granularity HINT (the chart's bar duration): a multi-timeframe source may serve bucket slices that divide it (fewer, bigger slices, same sums). Returns a completeness-aware batch (see [`FootprintBatch`](/vela-pro/api/chart-types#footprintbatch)). |
| `subscribeFootprints()` | `(ticker: string, since: number, onSlices: (slices: FootprintSlice[]) => void) => () => void` | Live footprint slices from `since` onward. Deliveries are FULL-STATE snapshots per slice (the forming minute grows across deliveries): consumers replace by slice time, never accumulate. Returns an unsubscribe function.                                                                                                                     |
| `footprintCaps()`       | `(ticker: string) => FootprintCaps`                                                           | Fetch-planner capabilities for one ticker.                                                                                                                                                                                                                                                                                                     |

See also: [`FootprintBatch`](/vela-pro/api/chart-types#footprintbatch), [`FootprintCaps`](/vela-pro/api/data-feeds#footprintcaps), [`FootprintRange`](/vela-pro/api/data-feeds#footprintrange), [`FootprintSlice`](/vela-pro/api/chart-types#footprintslice).

### `FootprintFeedSurface` [#footprintfeedsurface]

What [`footprintFeedFor`](/vela-pro/api/data-feeds#footprintfeedfor) needs of a chart's data surface: structural, so any host context fits.

```typescript
interface FootprintFeedSurface {
    resolve(symbol: string): { provider: string; ticker: string } | null;
    providerInstance(name: string): DataProvider | undefined;
}
```

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

### `FootprintPeek` [#footprintpeek]

A synchronous look at what the store holds for one series.

```typescript
interface FootprintPeek {
    slices: FootprintSlice[];
    covered: Array<[number, number]>;
}
```

| Member    | Type                      | Description                                                               |
| --------- | ------------------------- | ------------------------------------------------------------------------- |
| `slices`  | `FootprintSlice[]`        | Kept slices inside the asked range, ascending.                            |
| `covered` | `Array<[number, number]>` | The `[from, to)` stretches of the range the slices are authoritative for. |

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

### `FootprintRange` [#footprintrange]

A time range request, `[from, to]` epoch ms (either side optional).

```typescript
interface FootprintRange {
    from?: number;
    to?: number;
    session?: string;
}
```

| Member     | Type     | Description                                                                                                                                                                                                                             |
| ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `from?`    | `number` |                                                                                                                                                                                                                                         |
| `to?`      | `number` |                                                                                                                                                                                                                                         |
| `session?` | `string` | The chart's trading session (`'regular'` \| `'extended'`): session markets store the extended superset and filter at serve time, so an RTH consumer must say so or the server's regular default decides. Ignored by continuous markets. |

### `FootprintStoreStats` [#footprintstorestats]

What the store did since it was created (diagnostics and tests).

```typescript
interface FootprintStoreStats {
    upstreamRequests: number;
    memoryHits: number;
    sharedRequests: number;
    liveUpstreams: number;
    liveSubscribers: number;
    intervals: number;
    retainedLevels: number;
}
```

| Member             | Type     | Description                                              |
| ------------------ | -------- | -------------------------------------------------------- |
| `upstreamRequests` | `number` | Range requests sent to the underlying feed.              |
| `memoryHits`       | `number` | Answers served entirely from memory.                     |
| `sharedRequests`   | `number` | Requests that joined an identical one already in flight. |
| `liveUpstreams`    | `number` | Upstream live subscriptions currently open.              |
| `liveSubscribers`  | `number` | Live subscribers currently fed.                          |
| `intervals`        | `number` |                                                          |
| `retainedLevels`   | `number` |                                                          |

### `Quote` [#quote]

One symbol's quote.

Also exported from `@luxalgo/vela-pro-watchlist`, `@luxalgo/vela-pro/plugin`.

```typescript
interface Quote {
    symbol: string;
    last: number | null;
    prevClose: number | null;
    open: number | null;
    high: number | null;
    low: number | null;
    volume: number | null;
    change: number | null;
    changePercent: number | null;
    spark: number[];
    tick: number;
    updated: number;
    unresolved?: boolean;
}
```

| Member          | Type             | Description                                                        |
| --------------- | ---------------- | ------------------------------------------------------------------ |
| `symbol`        | `string`         |                                                                    |
| `last`          | `number \| null` |                                                                    |
| `prevClose`     | `number \| null` | The previous session's close: what Chg and Chg% are measured from. |
| `open`          | `number \| null` |                                                                    |
| `high`          | `number \| null` |                                                                    |
| `low`           | `number \| null` |                                                                    |
| `volume`        | `number \| null` |                                                                    |
| `change`        | `number \| null` |                                                                    |
| `changePercent` | `number \| null` |                                                                    |
| `spark`         | `number[]`       | Closes over the last day, oldest first.                            |
| `tick`          | `number`         | Price increment, for formatting.                                   |
| `updated`       | `number`         |                                                                    |
| `unresolved?`   | `boolean`        | No provider serves the symbol.                                     |

### `QuoteSource` [#quotesource]

Also exported from `@luxalgo/vela-pro-watchlist`, `@luxalgo/vela-pro/plugin`.

```typescript
interface QuoteSource {
    watch(symbol: string, onQuote: (q: Quote) => void): () => void;
    dailyBars?(symbol: string, count: number): Promise<readonly OHLCV[]>;
}
```

| Member         | Type                                                           | Description                                                                                                                                                                                                                                     |
| -------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `watch()`      | `(symbol: string, onQuote: (q: Quote) => void) => () => void`  | Follow `symbol`'s quote; `onQuote` gets every change. Returns the unsubscribe.                                                                                                                                                                  |
| `dailyBars?()` | `(symbol: string, count: number) => Promise<readonly OHLCV[]>` | Up to `count` daily bars of `symbol`, oldest first; the last may be today's, still forming. Rejects when no history can be had. Optional: without it, the figures read from daily history (period returns, drawdowns, correlations) stay empty. |

See also: [`Quote`](/vela-pro/api/data-feeds#quote). From `@luxalgo/vela/plugin`: `OHLCV`.

### `TapeTrade` [#tapetrade]

Also exported from `@luxalgo/vela-pro/plugin`.

```typescript
interface TapeTrade {
    id: string;
    time: number;
    price: number;
    size: number;
    side: 'buy' | 'sell';
}
```

| Member  | Type              | Description       |
| ------- | ----------------- | ----------------- |
| `id`    | `string`          |                   |
| `time`  | `number`          |                   |
| `price` | `number`          |                   |
| `size`  | `number`          |                   |
| `side`  | `'buy' \| 'sell'` | The taker's side. |
