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

Expected Market-Order Fill Price

Install and import#

bash
npm install fintech-algorithms
ts
import { expectedFillPrice } from "fintech-algorithms/market-microstructure/market-depth-analytics/expected-market-order-fill-price";

Signature#

expectedFillPrice(bids, asks, side, quantity, limitPrice)

Walks a market order through the book and returns the volume-weighted price it would pay. The honest answer to 'what will this cost' — and it can be a partial fill, which a naive estimate silently ignores.

Parameters#

NameTypeNotes
bidsLevel[]Bid levels, best first.
asksLevel[]Ask levels, best first.
side"buy" | "sell"Order direction, which selects the side consumed.
quantitynumberOrder quantity.
min: 0
limitPricenumberOptional limit beyond which the order stops consuming levels.
optional

Returns#

{ average_price, filled_quantity, unfilled_quantity, levels_consumed, … }

The average price with the filled and **unfilled** quantities stated separately — a book too thin to fill the order is the case that matters.

Errors#

  • When quantity is not positive, or side is unrecognised — throws

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

bids
[
  {
    "price": 99.99,
    "quantity": 500
  },
  {
    "price": 99.98,
    "quantity": 800
  },
  {
    "price": 99.97,
    "quantity": 1200
  }
]

Showing 3 of 5 elements.

asks
[
  {
    "price": 100.01,
    "quantity": 300
  },
  {
    "price": 100.02,
    "quantity": 600
  },
  {
    "price": 100.03,
    "quantity": 1000
  }
]

Showing 3 of 5 elements.

side
"buy"
quantity
1500
limitPrice
null

Call#

expectedFillPrice(bids, asks, side, quantity, limitPrice)

Returns#

object with 15 fields: model, side, requested_quantity, filled_quantity, unfilled_quantity, full_fill, fills, fill_notional, …

{
  "model": "deterministic-visible-book-fill-estimate",
  "side": "buy",
  "requested_quantity": 1500,
  "filled_quantity": 1500,
  "unfilled_quantity": 0,
  "full_fill": true,
  "fills": [
    {
      "level_index": 0,
      "price": 100.01,
      "quantity": 300,
      "notional": 30003
    },
    {
      "level_index": 1,
      "price": 100.02,
      "quantity": 600,
      "notional": 60012
    },
    {
      "level_index": 2,
      "price": 100.03,
      "quantity": 600,
      "notional": 60018
    }
  ],
  "fill_notional": 150033,
  "partial_vwap": 100.022,
  "worst_fill_price": 100.03,
  "best_bid": 99.99,
  "best_ask": 100.01,
  "midpoint": 100,
  "expected_fill_price": 100.022
}

Showing 14 of 15 fields.

Other exports#

This module also exports cumulativeDepth, topNDepthImbalance, depthAtDistanceProfile, sweepCostAndSlippage, liquidityWallConcentration, depthDepletionReplenishment, marketDepthHeatmap, 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#

Expected Market-Order Fill Price — system map

Calculation flow#

Expected Market-Order Fill Price calculation flow 
flowchart LR
    S1["Select asks for a buy or bids for a sell"]
    S2["Apply the optional limitprice eligibility boundary"]
    S3["Fill from best price outward"]
    S4["Accumulate quantity and notional"]
    S5["Return fullfill price only if residual quantity is zer"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"eligible visible depth versus requested quantity"}
    D --> O["expected_fill_price + diagnostics"]
    O --> A["Audit: Filled plus unfilled quantity 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 Market-Depth Analytics family#