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

Price-Level Quantity Aggregation

Install and import#

bash
npm install fintech-algorithms
ts
import { aggregatePriceLevels } from "fintech-algorithms/market-data-engineering/order-book-feed-engineering/price-level-quantity-aggregation";

Signature#

aggregatePriceLevels(orders)

Collapses individual orders into quantity per price level — the Level 3 to Level 2 projection, and the form most analytics actually consume.

Parameters#

NameTypeNotes
ordersOrder[]Individual resting orders with price, quantity and side.

Returns#

{ bids, asks, level_count, … }

Aggregated levels per side, sorted outward from the touch.

Errors#

  • When an order has a non-positive quantity — excluded and reported

Complexity: time O(orders log levels), space O(levels).

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#

orders
[
  {
    "order_id": "B00",
    "side": "bid",
    "price_ticks": 10000,
    "quantity": 4
  },
  {
    "order_id": "A01",
    "side": "ask",
    "price_ticks": 10002,
    "quantity": 9
  },
  {
    "order_id": "B02",
    "side": "bid",
    "price_ticks": 9999,
    "quantity": 14
  }
]

Showing 3 of 32 elements.

argument 2
{
  "depth_limit": 5
}

Call#

aggregatePriceLevels(orders)

Returns#

object with 13 fields: order_count, full_bid_level_count, full_ask_level_count, depth_limit, bids, asks, visible_bid_quantity, visible_ask_quantity, …

{
  "order_count": 32,
  "full_bid_level_count": 8,
  "full_ask_level_count": 8,
  "depth_limit": 5,
  "bids": [
    {
      "price_ticks": 10000,
      "quantity": 12,
      "order_count": 2
    },
    {
      "price_ticks": 9999,
      "quantity": 32,
      "order_count": 2
    },
    {
      "price_ticks": 9998,
      "quantity": 14,
      "order_count": 2
    }
  ],
  "asks": [
    {
      "price_ticks": 10002,
      "quantity": 22,
      "order_count": 2
    },
    {
      "price_ticks": 10003,
      "quantity": 23,
      "order_count": 2
    },
    {
      "price_ticks": 10004,
      "quantity": 24,
      "order_count": 2
    }
  ],
  "visible_bid_quantity": 108,
  "visible_ask_quantity": 120,
  "full_bid_quantity": 200,
  "full_ask_quantity": 204,
  "hidden_by_depth_limit_bid_quantity": 92,
  "hidden_by_depth_limit_ask_quantity": 84,
  "state": "aggregated"
}

Other exports#

This module also exports normalizeEvents, reconstructL2, reconstructL3, recoverSequenceStream, reconcileSnapshotIncrementals, consolidateVenues, calculate. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams#

Price-Level Quantity Aggregation — d11 handoff
Price-Level Quantity Aggregation — failure map
Price-Level Quantity Aggregation — sequence boundary
Price-Level Quantity Aggregation — state transition
Price-Level Quantity Aggregation — system map

Calculation flow#

Price-Level Quantity Aggregation system flow 
flowchart LR
    A["Group exact side/price keys."] --> B["Sum quantity and count orders."]
    B --> C{"Safe to publish?"}
    C -->|"yes"| D["Calculate full totals before depth truncation."]
    C -->|"no"| E["Depth truncation must not be reported as total visible liquidity."]
    D --> F["Publish sorted L2 quantities and order counts"]
    F --> G["Route to the named D11 measurement"]

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 Order-Book Feed Engineering family#