Price-Time Priority

Install and import#

npm install fintech-algorithms

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#

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#

{
  "order_id": "B-IN",
  "side": "buy",
  "order_type": "limit",
  "quantity": 650,
  "limit_price": 100.1
}

[
  {
    "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#

Calculation flow#

flowchart LR
    S1["Validate identity side price quantity and sequence"]
    S2["Sort opposite interest best price first"]
    S3["Break equalprice ties by ascending arrival sequence"]
    S4["Fill until the aggressor is complete or price no longe"]
    S5["Return fills residual average price and final book"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"the incoming limit and equalprice FIFO order"}
    D --> O["filled_quantity + diagnostics"]
    O --> A["Audit: Worse price never executes before a better executable pric"]

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#

• Matching principles — Eurex Frankfurt AG
• Matching Algorithm Overview — CME Group
• Evidence boundary

The rest of the Continuous Matching family#

• Pro-Rata MatchingAllocates a fill across all resting orders at a price in proportion to size, ignoring arrival time.
• Size-Time PriorityOrders by size first and arrival second — rewarding large resting orders.
• Hybrid Pro-Rata/Time MatchingSplits an incoming order between a time-priority portion and a pro-rata portion — the compromise most futures venues actually r…