fintech-algorithms

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

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