Cross-orderbook matching

An order can fill against the other outcome in the same binary market. For example, your BUY YES can match another trader's BUY NO, even though neither trader is selling existing shares. Together, the buyers fund a new YES/NO pair.

This is cross-orderbook matching. It applies where complementary matching is enabled, and only between YES and NO in the same market. Each binary market within a multi-outcome event has its own pair.

Why the prices complement each other

One collateral unit backs one YES share plus one NO share. Creating a pair requires one collateral unit; combining a pair returns one collateral unit.

That lets two buyers create a pair together, or two sellers combine their existing shares to release the collateral:

The same rules apply with YES and NO swapped. A BUY YES and a SELL NO do not match each other.

The maker is the resting order; the taker is the incoming order. For a same-outcome trade, both trade at the maker's price. For a cross-outcome trade, the maker trades at its quoted price and the taker trades at 1 minus the maker's price. A buy limit is the most you will pay, and a sell limit is the least you will receive; your actual price can be better.

Worked examples

All examples use different accounts and 100 shares per order. Prices and totals are in collateral units. Fees are excluded from the arithmetic; taker fees can apply to all three settlement modes.

Same outcome: transfer existing shares

Alice has a resting SELL YES for 100 shares at 0.60. Bob submits a BUY YES for 100 shares with a limit of 0.70.

1. Bob's limit covers Alice's price, so the orders match at 0.60.
2. Bob pays 60 collateral units and receives Alice's 100 YES shares.
3. Alice receives 60 collateral units. No new YES/NO pairs are created.

Bob's limit allowed a cost of 70, but the execution costs 60 before fees. The fill reports settlement_mode: "NORMAL".

Two buyers: create a pair

Alice has a resting BUY NO for 100 shares at 0.40. Bob submits a BUY YES for 100 shares with a limit of 0.70. Assume no eligible YES sell orders are resting.

1. The limits sum to 1.10, so they can fund a pair costing 1 per share.
2. Alice pays her quoted 0.40 per NO share: 40 collateral units in total.
3. Bob pays the complement, 1 − 0.40 = 0.60, per YES share: 60 in total.
4. The combined 100 collateral units create 100 YES shares and 100 NO shares. Bob receives the YES shares; Alice receives the NO shares.

Bob does not pay his full 0.70 limit. The pair costs 1, so his execution price is 0.60. The fill reports settlement_mode: "MINT".

If Bob's limit were 0.50 instead, 0.50 + 0.40 = 0.90 would not fund a pair. These two orders would not match. A sum of exactly 1 is sufficient.

Two sellers: combine a pair

Alice owns 100 NO shares and has a resting SELL NO at 0.60. Bob owns 100 YES shares and submits a SELL YES with a limit of 0.30. Assume no eligible YES buy orders are resting.

1. The limits sum to 0.90, so one collateral unit per pair covers both sellers.
2. Their 100 YES and 100 NO shares are combined and burned, releasing 100 collateral units.
3. Alice receives her quoted 0.60 per NO share: 60 collateral units.
4. Bob receives 1 − 0.60 = 0.40 per YES share: 40 collateral units.

Bob receives more than his 0.30 minimum. Both traders give up the shares they sold. The fill reports settlement_mode: "MERGE".

If Bob required 0.50, 0.50 + 0.60 = 1.10 would exceed the collateral released by a pair, so these orders would not match. A sum of exactly 1 is sufficient.

SELL orders require the actual outcome shares, including for cross-outcome matches. See Inventory for acquiring, splitting, and reserving shares.

Which order fills first?

Eligible orders on both outcomes compete in one price ranking:

1. Compare each resting order at its effective price for the incoming outcome. A complementary order's effective price is 1 − its quoted price.
2. Fill the best price first: lowest for a BUY, highest for a SELL.
3. At the same effective price, fill the oldest resting order first, regardless of which outcome it was placed on.

Same-outcome liquidity has no automatic priority over complementary liquidity.

For example, a BUY YES with a 0.70 limit encounters a YES ask at 0.65 and a NO bid at 0.40. It fills against the NO bid first, at an effective YES price of 0.60. Any remaining quantity can then fill the YES ask at 0.65. If the YES ask were also 0.60, whichever resting order arrived first would fill first.

The orderbook snapshot includes complementary liquidity at its effective price for the requested outcome. A NO bid at 0.40 appears as a YES ask at 0.60; a NO ask at 0.60 appears as a YES bid at 0.40. Quantities at the same effective price are added together. The YES and NO snapshots show the same liquidity from opposite perspectives, so do not add their depths together when estimating available liquidity.

Partial fills and time in force

Each match uses the smaller remaining quantity of the two orders. Suppose Alice's BUY NO at 0.40 is the only available liquidity and Bob buys 150 YES at a 0.70 limit. They can create 100 pairs: Bob receives 100 YES for 60 collateral units before fees, leaving 50 shares of his order unfilled.

• With GTC or GTD, Bob's remaining 50-share BUY rests at his original 0.70 limit, subject to its expiry.
• With FAK, the unfilled 50 shares are cancelled.
• With FOK, the complete 150 shares must be fillable against other accounts. If only Alice's 100 shares are available, the order is rejected without a fill.

An order can receive several fills, including both NORMAL and cross-outcome fills. See time in force for the order controls.

Your own orders and post-only quotes

Check your resting orders on both outcomes before placing an aggressive order. Self-trade prevention applies to all three settlement modes. If your BUY YES reaches your own eligible BUY NO, or your SELL YES reaches your own eligible SELL NO, the resting order's entire remaining quantity is cancelled. The incoming order continues looking for another account to trade with.

This produces an order_cancelled event with reason SELF_TRADE_PREVENTION, not a self-trade fill. Use split or merge to create or combine your own pairs.

A post-only order can be rejected for taking complementary liquidity even when the requested outcome has no eligible opposite-side orders. A cross against only your own order can still cancel the older order through self-trade prevention. See Self-trade prevention for examples and the FOK exception.

Reading your fills

On the account stream, use:

In a MINT fill both accounts buy, and in a MERGE fill both sell, but each trades a different outcome. Cross-outcome matches are reported as fill events; the separate tokens_minted and tokens_merged events describe explicit split and merge operations.