> For the complete documentation index, see [llms.txt](https://docs-v2.fermilabs.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-v2.fermilabs.xyz/trading/matching-logic.md).

# Matching Logic

The matching engine implements a continuous limit order book with price-time priority.

#### Order Book Structure

```rust
Orderbook {
    bids: BTreeMap<OrderbookKey, Order>,  // Sorted high-to-low
    asks: BTreeMap<OrderbookKey, Order>,  // Sorted low-to-high
}

OrderbookKey {
    price: i64,      // Negated for bids
    timestamp: u64,
    order_id: OrderId,
}
```

* **Bids**: Price negated so `BTreeMap` iteration yields highest prices first
* **Asks**: Price as-is so iteration yields lowest prices first
* **Tie-breaking**: Secondary sort by `(timestamp, order_id)` for FIFO at same price level

#### Matching Algorithm

```
while best_bid.price >= best_ask.price:
    1. Prune any zero-quantity orders at top of book
    2. Check crossing conditions (price, market_id, self-trade)
    3. Determine maker (earlier timestamp wins)
    4. Execute at maker's price
    5. Update quantities; remove exhausted orders
```

#### Maker Determination

```rust
maker_is_bid = (bid.timestamp, bid.order_id) <= (ask.timestamp, ask.order_id)
price = if maker_is_bid { bid.price } else { ask.price }
```

The order that arrived first is the maker; the match executes at the maker's price. This protects passive liquidity providers.

#### Partial Fills

When order quantities differ:

```rust
fill_quantity = bid.quantity.min(ask.quantity)
```

* Smaller order is fully filled and removed
* Larger order has quantity decremented; remains in book
* Multiple trades may result from a single aggressive order

#### Trade Output

```rust
Trade {
    market_id: MarketId,
    maker_order_id: OrderId,
    taker_order_id: OrderId,
    price: i64,
    quantity: u64,
    timestamp: u64,  // max(maker.timestamp, taker.timestamp)
}
```

#### Safety Checks

* **Cross-market prevention**: Matching stops if `bid.market_id != ask.market_id`
* **Self-trade prevention**: Optional flag stops matching if `bid.account_id == ask.account_id`

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs-v2.fermilabs.xyz/trading/matching-logic.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.