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

Cumulative Bid/Ask Depth

Install and import#

bash
npm install fintech-algorithms
ts
import { cumulativeDepth } from "fintech-algorithms/market-microstructure/market-depth-analytics/cumulative-bid-ask-depth";

Signature#

cumulativeDepth(bidsRaw, asksRaw, tickRaw)

Running total of quantity available as you walk out from the touch on each side — the basis of every question about how much can be traded before price moves.

Parameters#

NameTypeNotes
bidsRawLevel[]Bid levels, best first.
asksRawLevel[]Ask levels, best first.
tickRawnumberTick size, used to express distance in ticks rather than currency.
min: 0

Returns#

{ bids, asks, total_bid_depth, total_ask_depth, … }

Cumulative depth per level on each side.

Errors#

  • When tick size is not positive, or a level has negative size — throws

Complexity: time O(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#

bidsRaw
[
  {
    "price": 99.99,
    "quantity": 500
  },
  {
    "price": 99.98,
    "quantity": 800
  },
  {
    "price": 99.97,
    "quantity": 1200
  }
]

Showing 3 of 5 elements.

asksRaw
[
  {
    "price": 100.01,
    "quantity": 300
  },
  {
    "price": 100.02,
    "quantity": 600
  },
  {
    "price": 100.03,
    "quantity": 1000
  }
]

Showing 3 of 5 elements.

tickRaw
0.01

Call#

cumulativeDepth(bidsRaw, asksRaw, tickRaw)

Returns#

object with 10 fields: model, best_bid, best_ask, tick_size, spread_ticks, bid_levels, ask_levels, total_bid_depth, …

{
  "model": "visible-cumulative-depth",
  "best_bid": 99.99,
  "best_ask": 100.01,
  "tick_size": 0.01,
  "spread_ticks": 2,
  "bid_levels": [
    {
      "price": 99.99,
      "quantity": 500,
      "distance_ticks": 0,
      "cumulative_quantity": 500
    },
    {
      "price": 99.98,
      "quantity": 800,
      "distance_ticks": 1,
      "cumulative_quantity": 1300
    },
    {
      "price": 99.97,
      "quantity": 1200,
      "distance_ticks": 2,
      "cumulative_quantity": 2500
    }
  ],
  "ask_levels": [
    {
      "price": 100.01,
      "quantity": 300,
      "distance_ticks": 0,
      "cumulative_quantity": 300
    },
    {
      "price": 100.02,
      "quantity": 600,
      "distance_ticks": 1,
      "cumulative_quantity": 900
    },
    {
      "price": 100.03,
      "quantity": 1000,
      "distance_ticks": 2,
      "cumulative_quantity": 1900
    }
  ],
  "total_bid_depth": 3600,
  "total_ask_depth": 3300,
  "state": "bid-deeper"
}

Other exports#

This module also exports topNDepthImbalance, depthAtDistanceProfile, expectedFillPrice, sweepCostAndSlippage, liquidityWallConcentration, depthDepletionReplenishment, marketDepthHeatmap, 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#

Cumulative Bid/Ask Depth — system map

Calculation flow#

Cumulative Bid/Ask Depth calculation flow 
flowchart LR
    S1["Validate and preserve besttoworse price order"]
    S2["Set each sides running quantity to zero"]
    S3["Add each level and emit its cumulative quantity"]
    S4["Compare final included totals"]
    S5["Return curves totals tick distances and state"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"the included level window and visibleonly scope"}
    D --> O["total_bid_depth + diagnostics"]
    O --> A["Audit: Cumulative quantities are nondecreasing"]

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 Market-Depth Analytics family#