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

Marketable-Order Multi-Level Sweep

Install and import#

bash
npm install fintech-algorithms
ts
import { marketableOrderSweep } from "fintech-algorithms/matching-engines-and-venue-logic/order-lifecycle-and-queue-state/marketable-order-multi-level-sweep";

Signature#

marketableOrderSweep(incomingRaw, restingRaw)

Walks a marketable order across price levels until filled or exhausted — the matching-engine counterpart of the expected-fill-price calculation, producing actual fills rather than an estimate.

Parameters#

NameTypeNotes
incomingRawOrderThe marketable order.
restingRawOrder[]Resting orders across levels, in priority order.

Returns#

{ fills, levels_swept, average_price, residual, … }

Fills level by level with the residual left unfilled.

Errors#

  • When the incoming order has a non-positive quantity — throws

Complexity: time O(resting), space O(fills).

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#

incomingRaw
{
  "order_id": "IN-1",
  "side": "buy",
  "order_type": "limit",
  "quantity": 900,
  "limit_price": 100.02,
  "time_in_force": "GTC",
  "arrival_sequence": 100
}
restingRaw
[
  {
    "order_id": "B-1",
    "side": "buy",
    "price": 99.99,
    "remaining_quantity": 500,
    "priority_sequence": 1
  },
  {
    "order_id": "S-1",
    "side": "sell",
    "price": 100.01,
    "remaining_quantity": 300,
    "priority_sequence": 2
  },
  {
    "order_id": "S-2",
    "side": "sell",
    "price": 100.01,
    "remaining_quantity": 400,
    "priority_sequence": 3
  }
]

Showing 3 of 5 elements.

Call#

marketableOrderSweep(incomingRaw, restingRaw)

Returns#

object with 13 fields: model, incoming_order_id, incoming_side, requested_quantity, filled_quantity, residual_quantity, fill_notional, average_fill_price, …

{
  "model": "single-venue-price-time-marketable-sweep",
  "incoming_order_id": "IN-1",
  "incoming_side": "buy",
  "requested_quantity": 900,
  "filled_quantity": 900,
  "residual_quantity": 0,
  "fill_notional": 90011,
  "average_fill_price": 100.01222222222222,
  "fills": [
    {
      "resting_order_id": "S-1",
      "price": 100.01,
      "quantity": 300,
      "resting_remaining_quantity": 0
    },
    {
      "resting_order_id": "S-2",
      "price": 100.01,
      "quantity": 400,
      "resting_remaining_quantity": 0
    },
    {
      "resting_order_id": "S-3",
      "price": 100.02,
      "quantity": 200,
      "resting_remaining_quantity": 300
    }
  ],
  "residual_action": "none",
  "final_book": [
    {
      "order_id": "B-1",
      "side": "buy",
      "price": 99.99,
      "remaining_quantity": 500,
      "priority_sequence": 1
    },
    {
      "order_id": "S-3",
      "side": "sell",
      "price": 100.02,
      "remaining_quantity": 300,
      "priority_sequence": 4
    },
    {
      "order_id": "S-4",
      "side": "sell",
      "price": 100.03,
      "remaining_quantity": 600,
      "priority_sequence": 5
    }
  ],
  "status": "filled",
  "state": "filled"
}

Other exports#

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

Marketable-Order Multi-Level Sweep — system map

Calculation flow#

Marketable-Order Multi-Level Sweep calculation flow 
flowchart LR
    S1["Validate incoming and resting IDs quantities and seque"]
    S2["Select oppositeside candidates"]
    S3["Sort by best price then FIFO sequence"]
    S4["Fill and decrement each marketable resting order"]
    S5["Post or cancel residual and return the mutated book"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"marketability FIFO sequence and residual postversuscancel "}
    D --> O["filled_quantity + diagnostics"]
    O --> A["Audit: Incoming filled plus residual equals requested 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#