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

Top-N Depth Imbalance

Install and import#

bash
npm install fintech-algorithms
ts
import { topNDepthImbalance } from "fintech-algorithms/market-microstructure/market-depth-analytics/top-n-depth-imbalance";

Signature#

topNDepthImbalance(bidsRaw, asksRaw, nRaw, thresholdRaw)

Depth imbalance restricted to the top N levels — the same idea as queue imbalance, bounded to the part of the book that is realistically accessible.

Parameters#

NameTypeNotes
bidsRawLevel[]Bid levels, best first.
asksRawLevel[]Ask levels, best first.
nRawnumberLevels to include.
min: 1 · integer: true
thresholdRawnumberMagnitude above which the imbalance is flagged as significant.
min: 0

Returns#

{ imbalance, bid_depth, ask_depth, significant, … }

The imbalance with the depths behind it and whether it cleared the threshold.

Errors#

  • When nRaw exceeds the levels supplied — throws

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

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.

nRaw
3
thresholdRaw
0.1

Call#

topNDepthImbalance(bidsRaw, asksRaw, nRaw, thresholdRaw)

Returns#

object with 9 fields: model, n, bid_depth, ask_depth, total_depth, imbalance, threshold, state, …

{
  "model": "top-n-visible-depth-imbalance",
  "n": 3,
  "bid_depth": 2500,
  "ask_depth": 1900,
  "total_depth": 4400,
  "imbalance": 0.13636363636363635,
  "threshold": 0.1,
  "state": "bid-heavy",
  "complete_window": true
}

Other exports#

This module also exports cumulativeDepth, 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#

Top-N Depth Imbalance — system map

Calculation flow#

Top-N Depth Imbalance calculation flow 
flowchart LR
    S1["Validate at least N levels on both sides"]
    S2["Sum the first N bid quantities"]
    S3["Sum the first N ask quantities"]
    S4["Normalize the signed difference by total depth"]
    S5["Classify against the symmetric threshold"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"threshold and the completewindow requirement"}
    D --> O["imbalance + diagnostics"]
    O --> A["Audit: Imbalance is in 11"]

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#