fintech-algorithms

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

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