fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

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#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

trades
[
  {
    "tradeId": "W1",
    "timestamp": "2026-01-05T14:30:00.000Z",
    "session": "2026-01-05",
    "symbol": "SYNTH",
    "price": 100,
    "volume": 40,
    "currency": "USD"
  },
  {
    "tradeId": "W2",
    "timestamp": "2026-01-05T14:30:01.000Z",
    "session": "2026-01-05",
    "symbol": "SYNTH",
    "price": 90,
    "volume": 70,
    "currency": "USD"
  }
]
config
{
  "targetDollar": 10000,
  "currency": "USD",
  "priceDecimals": 2,
  "quantityDecimals": 0,
  "closePartial": true
}

Call#

constructBars(trades, config)

Returns#

array of 1 object

[
  {
    "barIndex": 0,
    "session": "2026-01-05",
    "symbol": "SYNTH",
    "currency": "USD",
    "startTime": "2026-01-05T14:30:00.000Z",
    "endTime": "2026-01-05T14:30:01.000Z",
    "lastTradeTime": "2026-01-05T14:30:01.000Z",
    "open": 100,
    "high": 100,
    "low": 90,
    "close": 90,
    "volume": 110,
    "dollarValue": 10300,
    "targetDollar": 10000
  }
]

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#

The rest of the Bar Construction family#

  • Time BarsGroups a trade tape into fixed-duration bars.
  • Tick BarsCloses a bar every N trades rather than every N seconds.
  • Volume BarsCloses a bar once a target share volume has traded.
  • Tick-Imbalance BarsCloses a bar when signed tick flow becomes unusually one-sided relative to what recent history led you to expect.
  • Volume-Imbalance BarsThe imbalance rule applied to signed *volume* rather than signed tick count, so one large order weighs more than many small one…
  • Tick-Run BarsCloses a bar when a run of same-signed trades exceeds what the recent buy probability makes plausible.