fintech-algorithms

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

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