fintech-algorithms

Volume-Imbalance Bars

Install and import

bash
npm install fintech-algorithms
ts
import { constructBars } from "fintech-algorithms/market-data-engineering/bar-construction/volume-imbalance-bars";

Signature

constructBars(trades, config)

The imbalance rule applied to signed *volume* rather than signed tick count, so one large order weighs more than many small ones pointing the same way.

Parameters

NameTypeNotes
tradesTrade[]The raw tape in chronological order. Each trade carries tradeId, timestamp, session, symbol, price, volume and currency.
config{ initialTickSign: number; initialExpectedTicks: number; initialExpectedSignedVolume: number; alphaTicks: number; alphaSignedVolume: number; thresholdFloorShares: number; thresholdScale: number; closePartial?: boolean }As for tick-imbalance bars, but the tracked quantity is signed volume. thresholdFloorShares is the floor in shares, and thresholdScale multiplies the expectation to form the trigger.

Returns

Bar[] · length fewer

One bar per signed-volume imbalance event.

Errors

  • When any alpha falls outside 0…1, or a seed expectation is not positive — throws

Complexity: time O(n), space O(bars).

Worked example

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input

trades
[
  {
    "tradeId": "T0001",
    "timestamp": "2026-01-05T14:30:00.000Z",
    "session": "2026-01-05",
    "symbol": "SYNTH",
    "price": 99.99,
    "volume": 36,
    "currency": "USD"
  },
  {
    "tradeId": "T0002",
    "timestamp": "2026-01-05T14:30:04.000Z",
    "session": "2026-01-05",
    "symbol": "SYNTH",
    "price": 99.99,
    "volume": 73,
    "currency": "USD"
  },
  {
    "tradeId": "T0003",
    "timestamp": "2026-01-05T14:30:07.000Z",
    "session": "2026-01-05",
    "symbol": "SYNTH",
    "price": 100,
    "volume": 110,
    "currency": "USD"
  }
]

Showing 3 of 240 elements.

config
{
  "closePartial": true,
  "initialTickSign": 1,
  "initialExpectedTicks": 16,
  "initialExpectedSignedVolume": 35,
  "alphaTicks": 0.2,
  "alphaSignedVolume": 0.2,
  "thresholdFloorShares": 300,
  "thresholdScale": 1
}

Call

constructBars(trades, config)

Returns

array of 18 objects

[
  {
    "barIndex": 0,
    "session": "2026-01-05",
    "startTime": "2026-01-05T14:30:00.000Z",
    "endTime": "2026-01-05T14:33:09.000Z",
    "open": 99.99,
    "high": 100.21,
    "low": 99.98,
    "close": 100.21,
    "volume": 5436,
    "dollarValue": 544137.11,
    "tickCount": 44,
    "firstTradeId": "T0001",
    "lastTradeId": "T0044",
    "closeReason": "threshold"
  },
  {
    "barIndex": 1,
    "session": "2026-01-05",
    "startTime": "2026-01-05T14:33:10.000Z",
    "endTime": "2026-01-05T14:34:01.000Z",
    "open": 100.21,
    "high": 100.34,
    "low": 100.21,
    "close": 100.34,
    "volume": 1259,
    "dollarValue": 126246.92,
    "tickCount": 11,
    "firstTradeId": "T0045",
    "lastTradeId": "T0055",
    "closeReason": "threshold"
  },
  {
    "barIndex": 2,
    "session": "2026-01-05",
    "startTime": "2026-01-05T14:34:07.000Z",
    "endTime": "2026-01-05T14:35:06.000Z",
    "open": 100.35,
    "high": 100.51,
    "low": 100.35,
    "close": 100.51,
    "volume": 2000,
    "dollarValue": 200814.77,
    "tickCount": 15,
    "firstTradeId": "T0056",
    "lastTradeId": "T0070",
    "closeReason": "threshold"
  }
]

Showing 3 of 18 elements.

Diagrams

Volume-Imbalance Bars — article hero
Volume-Imbalance Bars — boundary and state
Volume-Imbalance Bars — construction anatomy

Calculation flow

Causal volume-imbalance construction flow 
flowchart TD
    A["Receive corrected, eligible, ordered trade"] --> B{"New session?"}
    B -->|Yes| C["Apply partial-tail policy"]
    C --> D["Reset sign and expectation seeds"]
    B -->|No| E["Keep frozen threshold"]
    D --> F["Infer tick sign and add signed shares"]
    E --> F
    F --> G{"Absolute signed shares >= frozen threshold?"}
    G -->|No| A
    G -->|Yes| H["Emit complete bar, lineage, and overshoot"]
    H --> I["Update expected ticks and signed shares per trade"]
    I --> J["Reset accumulation and freeze next threshold"]
    J --> A

How it works

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References