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

Queue Position and Ahead-Volume Calculation

Install and import#

bash
npm install fintech-algorithms
ts
import { queuePositionAheadVolume } from "fintech-algorithms/matching-engines-and-venue-logic/order-lifecycle-and-queue-state/queue-position-and-ahead-volume-calculation";

Signature#

queuePositionAheadVolume(ordersRaw, targetIdRaw)

How much volume sits ahead of a given order at its price. This is the number that decides fill probability under price-time priority — position in the queue, not distance from the touch.

Parameters#

NameTypeNotes
ordersRawOrder[]Resting orders at the price, in priority order.
targetIdRawstringThe order whose position is wanted.

Returns#

{ position, ahead_volume, behind_volume, total, … }

Position with volume ahead and behind.

Errors#

  • When the target order is not in the queue — throws

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

ordersRaw
[
  {
    "order_id": "Q-1",
    "side": "buy",
    "price": 100,
    "remaining_quantity": 300,
    "arrival_sequence": 1,
    "displayed": true
  },
  {
    "order_id": "H-1",
    "side": "buy",
    "price": 100,
    "remaining_quantity": 1000,
    "arrival_sequence": 2,
    "displayed": false
  },
  {
    "order_id": "Q-2",
    "side": "buy",
    "price": 100,
    "remaining_quantity": 450,
    "arrival_sequence": 3,
    "displayed": true
  }
]

Showing 3 of 6 elements.

targetIdRaw
"TARGET"

Call#

queuePositionAheadVolume(ordersRaw, targetIdRaw)

Returns#

object with 12 fields: model, target_order_id, side, price, ahead_order_count, ahead_volume, displayed_queue_rank, behind_order_count, …

{
  "model": "displayed-price-time-fifo-ahead-volume",
  "target_order_id": "TARGET",
  "side": "buy",
  "price": 100,
  "ahead_order_count": 2,
  "ahead_volume": 750,
  "displayed_queue_rank": 3,
  "behind_order_count": 1,
  "behind_volume": 250,
  "hidden_same_price_quantity_excluded": 1000,
  "ahead_order_ids": ["Q-1", "Q-2"],
  "state": "queued-behind-displayed-volume"
}

Other exports#

This module also exports limitOrderLifecycle, cancelReplacePriority, partialFillResidual, icebergReplenishment, marketableOrderSweep, 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#

Queue Position and Ahead-Volume Calculation — system map

Calculation flow#

Queue Position and Ahead-Volume Calculation calculation flow 
flowchart LR
    S1["Validate unique order IDs and sequences"]
    S2["Locate a displayed target"]
    S3["Filter exact side and price"]
    S4["Sort displayed orders by arrival sequence"]
    S5["Sum earlier residuals and report hidden excluded quant"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"displayedonly FIFO and exact price equality"}
    D --> O["ahead_volume + diagnostics"]
    O --> A["Audit: Displayed rank equals ahead order count plus one"]

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 Lifecycle and Queue State family#