# Hybrid Pro-Rata/Time Matching

`D12-F01-A04` · Matching Engines and Venue Logic → Continuous Matching · archetype `record-transform` · difficulty 5/5 · verification **verified**

Full page: https://docs.thefintechbuilder.com/matching-engines-and-venue-logic/continuous-matching/hybrid-pro-rata-time-matching/
Agent skill: `npx skills add IslamBaraka90/Fintech-Algorithms-Library` — https://docs.thefintechbuilder.com/guides/agent-skill/

## Install and import

```bash
npm install fintech-algorithms
```

```ts
import { hybridProRataTime } from "fintech-algorithms/matching-engines-and-venue-logic/continuous-matching/hybrid-pro-rata-time-matching";
```

## Signature

```ts
hybridProRataTime(incomingRaw, priceRaw, lotRaw, fractionRaw, restingRaw)
```

Splits an incoming order between a time-priority portion and a pro-rata portion — the compromise most futures venues actually run, because pure pro-rata invites size inflation and pure price-time invites a latency race.

## Parameters

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `incomingRaw` | `number` | yes | Quantity of the aggressing order. Only the part the resting book can fill is allocated; the rest comes back as `unfilled_quantity`. |
| `priceRaw` | `number` | yes | The single price this match happens at. Echoed back as `price`. |
| `lotRaw` | `number` | yes | Lot size. Allocation is computed in whole lots, so both portions are shared out in units of this rather than in raw quantity. |
| `fractionRaw` | `number` | yes | Share of the executable quantity allocated by arrival order before the remainder goes pro rata. Zero is pure pro-rata; one is pure time priority. · min: 0, max: 1 |
| `restingRaw` | `RestingOrder[]` | yes | The resting book at this price, each order carrying `order_id`, `remaining_quantity` and `arrival_sequence`. |

## Returns

`{ model, price, lot_size, fifo_fraction, incoming_quantity, executable_quantity, fifo_target_quantity, pro_rata_target_quantity, allocated_quantity, unfilled_quantity, allocations, state }`

Both target quantities, and `allocations` ordered by arrival with each order's fill split into `fifo_quantity` and `pro_rata_quantity`. `state` is `fully-allocated` or `partially-allocated`.

## Errors

- When `fractionRaw` is below zero or above one — throws RangeError

## Complexity

Time `O(resting log resting)`, space `O(resting)`.

## Worked example

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`:

```json
600
```

`priceRaw`:

```json
100
```

`lotRaw`:

```json
1
```

`fractionRaw`:

```json
0.4
```

`restingRaw`:

```json
[
  {
    "order_id": "H-1",
    "side": "sell",
    "price": 100,
    "remaining_quantity": 500,
    "arrival_sequence": 10
  },
  {
    "order_id": "H-2",
    "side": "sell",
    "price": 100,
    "remaining_quantity": 300,
    "arrival_sequence": 20
  },
  {
    "order_id": "H-3",
    "side": "sell",
    "price": 100,
    "remaining_quantity": 200,
    "arrival_sequence": 30
  }
]
```

### Call

```ts
hybridProRataTime(incomingRaw, priceRaw, lotRaw, fractionRaw, restingRaw)
```

### Returns

object with 12 fields: model, price, lot_size, fifo_fraction, incoming_quantity, executable_quantity, fifo_target_quantity, pro_rata_target_quantity, …

```json
{
  "model": "single-price-fifo-pro-rata-split",
  "price": 100,
  "lot_size": 1,
  "fifo_fraction": 0.4,
  "incoming_quantity": 600,
  "executable_quantity": 600,
  "fifo_target_quantity": 240,
  "pro_rata_target_quantity": 360,
  "allocated_quantity": 600,
  "unfilled_quantity": 0,
  "allocations": [
    {
      "order_id": "H-1",
      "resting_quantity": 500,
      "fifo_quantity": 240,
      "pro_rata_quantity": 123,
      "allocated_quantity": 363,
      "remaining_quantity": 137,
      "arrival_sequence": 10
    },
    {
      "order_id": "H-2",
      "resting_quantity": 300,
      "fifo_quantity": 0,
      "pro_rata_quantity": 142,
      "allocated_quantity": 142,
      "remaining_quantity": 158,
      "arrival_sequence": 20
    },
    {
      "order_id": "H-3",
      "resting_quantity": 200,
      "fifo_quantity": 0,
      "pro_rata_quantity": 95,
      "allocated_quantity": 95,
      "remaining_quantity": 105,
      "arrival_sequence": 30
    }
  ],
  "state": "fully-allocated"
}
```

## Other exports

`priceTimePriority`, `proRataMatching`, `sizeTimePriority`, `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.

## Verification and provenance

Tier: **verified** (via D).

The worked example below is the figure published in this algorithm's article, replayed and asserted by the test suite on every build. The arithmetic cannot drift without the build failing.

Both tiers guarantee the signature. Full explanation: https://docs.thefintechbuilder.com/guides/verification/

Generated from the docs.json payload shipped inside fintech-algorithms@0.13.1.
The signature and parameter list are checked against the compiled implementation at build time,
so a description that contradicts the code fails the build rather than reaching this file.

## Links

- Article (how it works, step by step): https://thefintechbuilder.com/matching-engines-and-venue-logic/continuous-matching/hybrid-pro-rata-time-matching/
- Implementation source: https://github.com/IslamBaraka90/Fintech-Algorithms-Library/blob/main/src/matching-engines-and-venue-logic/continuous-matching/hybrid-pro-rata-time-matching/impl.ts
- Package on npm: https://www.npmjs.com/package/fintech-algorithms
- Domain index for agents: https://docs.thefintechbuilder.com/matching-engines-and-venue-logic/llms.txt