fintech-algorithms

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

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