fintech-algorithms

Price-Time Priority

Install and import

bash
npm install fintech-algorithms
ts
import { priceTimePriority } from "fintech-algorithms/matching-engines-and-venue-logic/continuous-matching/price-time-priority";

Signature

priceTimePriority(incomingRaw, restingRaw)

Matches an incoming order against resting orders by best price, then earliest arrival. The default rule on most equity venues, and the one that makes queue position valuable. Prices and quantities are integer **atoms** — the venue's minimum increment — not floating-point currency. Matching arithmetic that rounds is matching arithmetic that disagrees with the exchange.

Parameters

NameTypeNotes
incomingRawOrderThe aggressing order.
restingRawOrder[]Resting orders with prices, quantities and arrival sequence.

Returns

{ fills, residual, book_after, … }

Fills in priority order with any residual quantity and the resulting book.

Errors

  • When an order has non-integer atoms or a non-positive quantity — throws

Complexity: time O(resting log 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": "B-IN",
  "side": "buy",
  "order_type": "limit",
  "quantity": 650,
  "limit_price": 100.1
}
restingRaw
[
  {
    "order_id": "S-1",
    "side": "sell",
    "price": 100,
    "remaining_quantity": 200,
    "arrival_sequence": 10
  },
  {
    "order_id": "S-2",
    "side": "sell",
    "price": 100,
    "remaining_quantity": 300,
    "arrival_sequence": 20
  },
  {
    "order_id": "S-3",
    "side": "sell",
    "price": 100.05,
    "remaining_quantity": 400,
    "arrival_sequence": 30
  }
]

Showing 3 of 4 elements.

Call

priceTimePriority(incomingRaw, restingRaw)

Returns

object with 10 fields: model, incoming_order_id, requested_quantity, filled_quantity, residual_quantity, average_fill_price, fill_count, fills, …

{
  "model": "single-venue-price-time-priority",
  "incoming_order_id": "B-IN",
  "requested_quantity": 650,
  "filled_quantity": 650,
  "residual_quantity": 0,
  "average_fill_price": 100.01153846153846,
  "fill_count": 3,
  "fills": [
    {
      "resting_order_id": "S-1",
      "price": 100,
      "quantity": 200,
      "arrival_sequence": 10
    },
    {
      "resting_order_id": "S-2",
      "price": 100,
      "quantity": 300,
      "arrival_sequence": 20
    },
    {
      "resting_order_id": "S-3",
      "price": 100.05,
      "quantity": 150,
      "arrival_sequence": 30
    }
  ],
  "final_resting_orders": [
    {
      "order_id": "S-3",
      "side": "sell",
      "price": 100.05,
      "remaining_quantity": 250,
      "arrival_sequence": 30
    },
    {
      "order_id": "S-4",
      "side": "sell",
      "price": 100.1,
      "remaining_quantity": 500,
      "arrival_sequence": 40
    }
  ],
  "state": "filled"
}

Other exports

This module also exports proRataMatching, sizeTimePriority, hybridProRataTime, 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

Price-Time Priority — 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