> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How Match works

> Explains the batch-auction mechanics that govern Match, including auction cadence, uniform clearing fee, clearing objective, allocation priority, and order lifecycle.

Match settles USDC burn and mint demand through a periodic batch auction that
prices a clearing fee in basis points. The auction never prices USDC itself;
USDC always remains 1:1 with USD. Understanding the auction mechanics (how the
clearing fee is set, how fills are allocated, and how unfilled remainder is
handled) is foundational to participating effectively.

## Auction cadence

Match runs on repeating cycles. Each cycle begins when the previous one closes
and ends when the auction clears. Near the end of each cycle, a lock window
opens before clearing.

### Auction lifecycle

The following diagram shows the phases of a single auction cycle.

```mermaid theme={null}
flowchart LR
    A([Open]) --> B[Orders and modifications accepted]
    B --> C([Lock window opens])
    C --> D[Price improvements only\nNo cancellations or size changes]
    D --> E([Clear])
    E --> F([Settle])
```

**Open phase:** Participants submit new orders, modify existing orders
(including cancellations and size changes), or improve their fee limits.

**Lock window:** Before clearing, the auction enters a lock window. New orders
and price improvements are still accepted, but cancellations and size changes
are blocked. Attempting to make a fee less competitive during the lock window
returns error 137005. This prevents last-second liquidity withdrawal.

**Clear:** The auction engine sets a single uniform clearing fee and allocates
fills.

**Settle:** Filled burn-side orders receive USD to their Circle Mint account.
Filled mint-side orders receive USDC. Unfilled remainder follows each
participant's post-fill election.

## Uniform clearing fee

Every matched order in a given auction cycle clears at the same fee, expressed
in basis points. There is no bespoke bilateral pricing. Burn-side participants
pay the clearing fee; mint-side participants receive the corresponding rebate.
The clearing fee never exceeds the fee cap.

## Clearing objective

The auction engine determines the clearing fee by working through three
objectives in priority order:

1. **Maximize matched volume.** The engine finds the fee level that allows the
   greatest total volume to be matched between the burn side and the mint side.
2. **Minimize absolute imbalance.** If multiple fee levels produce the same
   matched volume, the engine chooses the one with the smallest absolute
   difference between matched burn volume and matched mint volume.
3. **Prefer the higher fee on an exact tie.** If two fee levels still produce
   identical matched volume and identical imbalance, the engine picks the higher
   fee. This is the minter-bias tiebreaker: it resolves the edge case by
   favoring the fee that benefits mint-side participants. In the extreme case
   where a pure market-vs-market tie produces no imbalance at any fee level, the
   auction resolves at the fee cap.

## Allocation priority

After the engine sets the clearing fee, it assigns fills to individual orders in
two passes:

1. **Price aggressiveness.** Orders with limits more favorable than the clearing
   fee fill first. A burn-side order willing to pay 8 bps fills before one
   capped at 6 bps when the clearing fee is 6 bps.
2. **Pro-rata at the marginal price level.** Orders whose limit equals exactly
   the clearing fee share the remaining available fill proportionally to their
   order size.

## Self-match prevention

A participant cannot hold resting orders on both the burn side and the mint side
of the same auction simultaneously. Attempting to do so returns error 137006
(HTTP 409). This rule prevents a single participant from matching against
themselves.

## Post-fill elections

When an order is only partially matched, the participant's post-fill election
determines what happens to the unfilled remainder.

| Action     | Behavior                                                                                                                                                 |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roll`     | Carries the unfilled remainder into the next auction cycle as a new order. Order lineage is tracked through a parent-child relationship using `orderId`. |
| `fallback` | Routes the unfilled remainder to Circle Mint (the standard minting or burning service) rather than re-entering the auction.                              |
| `cancel`   | Drops the unfilled remainder entirely.                                                                                                                   |

## Market orders

A market order has `feeBps` omitted or set to null. It carries no fee constraint
and fills at any valid clearing fee the auction sets. Market orders are the most
price-aggressive order type and receive first priority during allocation.

## Order size constraints

All orders must be a minimum of $100 and a multiple of $100. This granularity is
required for integer-cent fee arithmetic during clearing.

## Order status lifecycle

An order moves through the following statuses as it progresses through an
auction cycle.

| Status         | Meaning                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------- |
| `pending`      | Order has been accepted and is resting in the open auction.                                 |
| `settling`     | The auction has cleared and the order is being settled.                                     |
| `filled`       | The order was fully matched and settled.                                                    |
| `partial_fill` | The order was partially matched. Unfilled remainder was handled per the post-fill election. |
| `unfilled`     | The order received no fill. Unfilled remainder was handled per the post-fill election.      |
| `cancelled`    | The order was cancelled before clearing or dropped by a `cancel` post-fill election.        |
| `failed`       | Settlement could not be completed.                                                          |