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

Partial-Fill and Residual-Quantity Processing

Install and import#

bash
npm install fintech-algorithms
ts
import { partialFillResidual } from "fintech-algorithms/matching-engines-and-venue-logic/order-lifecycle-and-queue-state/partial-fill-and-residual-quantity-processing";

Signature#

partialFillResidual(orderQuantityRaw, fillsRaw)

Tracks cumulative fills against an order and computes the residual. Over-fill is impossible on a correct venue, so detecting it is detecting a defect rather than handling a case.

Parameters#

NameTypeNotes
orderQuantityRawnumberOriginal order quantity.
min: 1 · integer: true
fillsRawFill[]Fills in sequence, each with a quantity.

Returns#

{ filled, residual, over_filled, fills, … }

Cumulative filled and residual quantity, with an explicit over-fill flag.

Errors#

  • When a fill quantity is not positive — throws

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

orderQuantityRaw
1200
fillsRaw
[
  {
    "execution_id": "E-1",
    "quantity": 300,
    "price": 100
  },
  {
    "execution_id": "E-2",
    "quantity": 450,
    "price": 100.01
  },
  {
    "execution_id": "E-3",
    "quantity": 250,
    "price": 100.02
  }
]

Call#

partialFillResidual(orderQuantityRaw, fillsRaw)

Returns#

object with 10 fields: model, order_quantity, cumulative_quantity, leaves_quantity, fill_notional, average_fill_price, execution_count, fill_states, …

{
  "model": "partial-fill-residual-accounting",
  "order_quantity": 1200,
  "cumulative_quantity": 1000,
  "leaves_quantity": 200,
  "fill_notional": 100009.5,
  "average_fill_price": 100.0095,
  "execution_count": 3,
  "fill_states": [
    {
      "execution_id": "E-1",
      "last_quantity": 300,
      "last_price": 100,
      "cumulative_quantity": 300,
      "leaves_quantity": 900,
      "status": "partially-filled"
    },
    {
      "execution_id": "E-2",
      "last_quantity": 450,
      "last_price": 100.01,
      "cumulative_quantity": 750,
      "leaves_quantity": 450,
      "status": "partially-filled"
    },
    {
      "execution_id": "E-3",
      "last_quantity": 250,
      "last_price": 100.02,
      "cumulative_quantity": 1000,
      "leaves_quantity": 200,
      "status": "partially-filled"
    }
  ],
  "status": "partially-filled",
  "state": "partially-filled"
}

Other exports#

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

Partial-Fill and Residual-Quantity Processing — system map

Calculation flow#

Partial-Fill and Residual-Quantity Processing calculation flow 
flowchart LR
    S1["Freeze original quantity"]
    S2["Reject duplicate execution IDs"]
    S3["Validate the next fill against current leaves"]
    S4["Update cumulative notional and quantity"]
    S5["Emit residual state after every fill"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"duplicate executions and the overfill equality boundary"}
    D --> O["leaves_quantity + diagnostics"]
    O --> A["Audit: Cumulative plus leaves equals original quantity"]

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#