fintech-algorithms

Dollar Bars

Install and import

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

Signature

constructBars(trades, config)

Closes a bar once a target traded *value* is reached. Unlike volume bars this stays comparable as the price level changes — 1,000 shares of a $10 stock and of a $500 stock are not the same event.

Parameters

NameTypeNotes
tradesTrade[]The raw tape in chronological order. Each trade carries tradeId, timestamp, session, symbol, price, volume and currency.
config{ targetDollar: number; currency: string; priceDecimals?: number; quantityDecimals?: number; closePartial?: boolean }targetDollar is the notional that closes a bar and currency the unit it is denominated in. The two decimal settings fix the rounding used when accumulating price × quantity, so the same tape gives the same bars on any machine.

Returns

Bar[] · length fewer

One bar per completed notional bucket.

Errors

  • When targetDollar is not positive — throws
  • When a trade's currency does not match the configured currency — 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,
  "targetDollar": 140000,
  "currency": "USD",
  "priceDecimals": 2,
  "quantityDecimals": 0
}

Call

constructBars(trades, config)

Returns

array of 21 objects

[
  {
    "barIndex": 0,
    "session": "2026-01-05",
    "symbol": "SYNTH",
    "currency": "USD",
    "startTime": "2026-01-05T14:30:00.000Z",
    "endTime": "2026-01-05T14:30:54.000Z",
    "lastTradeTime": "2026-01-05T14:30:54.000Z",
    "open": 99.99,
    "high": 100.06,
    "low": 99.98,
    "close": 100.05,
    "volume": 1531,
    "dollarValue": 153130.02,
    "targetDollar": 140000
  },
  {
    "barIndex": 1,
    "session": "2026-01-05",
    "symbol": "SYNTH",
    "currency": "USD",
    "startTime": "2026-01-05T14:31:01.000Z",
    "endTime": "2026-01-05T14:31:48.000Z",
    "lastTradeTime": "2026-01-05T14:31:48.000Z",
    "open": 100.06,
    "high": 100.12,
    "low": 100.04,
    "close": 100.11,
    "volume": 1469,
    "dollarValue": 147027,
    "targetDollar": 140000
  },
  {
    "barIndex": 2,
    "session": "2026-01-05",
    "symbol": "SYNTH",
    "currency": "USD",
    "startTime": "2026-01-05T14:31:52.000Z",
    "endTime": "2026-01-05T14:32:33.000Z",
    "lastTradeTime": "2026-01-05T14:32:33.000Z",
    "open": 100.11,
    "high": 100.18,
    "low": 100.1,
    "close": 100.18,
    "volume": 1436,
    "dollarValue": 143797.07,
    "targetDollar": 140000
  }
]

Showing 3 of 21 elements.

Diagrams

Dollar Bars — article hero
Dollar Bars — boundary and state
Dollar Bars — construction anatomy

Calculation flow

Causal construction flow — Dollar Bars 
flowchart TD
    A["Receive corrected, eligible trade"] --> B["Validate symbol, currency, units, time, and tie sequence"]
    B --> C{"New session?"}
    C -->|Yes| D{"Keep partial tails?"}
    D -->|Yes| E["Emit prior session partial"]
    D -->|No| F["Discard prior session partial"]
    E --> G["Reset exact cumulative state"]
    F --> G
    C -->|No| H["Keep open-bar state"]
    G --> I["Add whole trade: scaled price × scaled quantity"]
    H --> I
    I --> J{"Cumulative notional ≥ target?"}
    J -->|No| A
    J -->|Yes| K["Emit complete bar, lineage, and excess"]
    K --> L["Reset open-bar state"]
    L --> 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