How-to: Place and manage orders

Match exposes three order endpoints: one to submit an order, one to list orders with filters, and one to fetch a single order with full detail. This guide covers all three, including BURN-specific and MINT-specific required fields, market versus limit orders, filter options for listing, and how to read lineage and fill data on individual orders. If you’re new to Match, start with the quickstart before continuing here.

Prerequisites

Before you begin, ensure that you’ve:

Obtained a Circle API key with Match access
Created a Circle Mint wallet with sufficient USDC balance and linked a fiat account to receive settlement proceeds (BURN orders only)
Reviewed the funding model and auction mechanics

Steps

Step 1. Place a `BURN` order

A BURN order converts USDC to fiat. It requires two fields that MINT orders omit: sourceWalletId (the wallet that funds the burn) and fiatAccountId (the bank account that receives the settlement proceeds). The idempotencyKey you supply in the request body becomes the orderId for all subsequent lookups. Use a unique UUID v4 for each new order. Reusing an idempotency key with different parameters returns a 409 with error code 137004.

curl -X POST https://api-sandbox.circle.com/v1/match/orders \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "orderType": "BURN",
    "amount": {
      "amount": "500.00",
      "currency": "USD"
    },
    "feeBps": "5",
    "postFillAction": "roll",
    "sourceWalletId": "$WALLET_ID",
    "fiatAccountId": "$FIAT_ACCOUNT_ID"
  }'

A successful request returns 202 Accepted:

{
  "data": {
    "auctionId": 42,
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending"
  }
}

Required fields for BURN orders:

Field	Required	Type	Notes
`idempotencyKey`	Yes	UUID string	Becomes the `orderId`. Must be unique per order.
`orderType`	Yes	string	`"BURN"`
`amount`	Yes	Money object	`{"amount": "500.00", "currency": "USD"}`. Minimum $100, must be a multiple of$ 100.
`postFillAction`	Yes	string	`"roll"`, `"fallback"`, or `"cancel"`.
`sourceWalletId`	Yes	string	Circle Mint wallet ID that funds the burn.
`fiatAccountId`	Yes	UUID string	Fiat account that receives settlement proceeds.
`feeBps`	No	string or null	Fee ceiling in basis points. Omit or set to `null` for a market order. See Step 3.

Step 2. Place a MINT order

A MINT order converts fiat to USDC. It uses the same endpoint and most of the same fields, but you must omit sourceWalletId and fiatAccountId. Including either field in a MINT order returns a validation error.

curl -X POST https://api-sandbox.circle.com/v1/match/orders \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "661f9511-f30c-52e5-b827-557766551111",
    "orderType": "MINT",
    "amount": {
      "amount": "1000.00",
      "currency": "USD"
    },
    "feeBps": "5",
    "postFillAction": "roll"
  }'

Required fields for MINT orders:

Field	Required	Type	Notes
`idempotencyKey`	Yes	UUID string	Becomes the `orderId`. Must be unique per order.
`orderType`	Yes	string	`"MINT"`
`amount`	Yes	Money object	`{"amount": "1000.00", "currency": "USD"}`. Minimum $100, must be a multiple of$ 100.
`postFillAction`	Yes	string	`"roll"`, `"fallback"`, or `"cancel"`.
`feeBps`	No	string or null	Minimum rebate in basis points. Omit or set to `null` for a market order. See Step 3.

Step 3. Place a market order

A market order matches at whatever clearing fee the auction produces, with no fee ceiling. To place a market order, omit feeBps entirely, or explicitly set it to null.

curl -X POST https://api-sandbox.circle.com/v1/match/orders \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "772g0622-g41d-63f6-c938-668877662222",
    "orderType": "BURN",
    "amount": {
      "amount": "500.00",
      "currency": "USD"
    },
    "postFillAction": "cancel",
    "sourceWalletId": "$WALLET_ID",
    "fiatAccountId": "$FIAT_ACCOUNT_ID"
  }'

A limit order (with feeBps set) only matches when the clearing fee does not exceed your limit. If the clearing fee is higher, the order ends the auction cycle unfilled and follows your postFillAction election.

Step 4. List orders with filters

Use GET /v1/match/orders to retrieve a paginated list of your orders. All parameters are optional.

curl -X GET "https://api-sandbox.circle.com/v1/match/orders?status=pending&orderType=BURN&pageSize=50" \
  -H "Authorization: Bearer $API_KEY"

Available query parameters:

Parameter	Type	Notes
`page`	integer	Page number, 1-based. Defaults to 1.
`pageSize`	integer	Results per page. Default 20, maximum 100.
`status`	string	Filter by order status. An unknown value returns 400.
`orderType`	string	`BURN` or `MINT`. Any other value returns 400.
`orderId`	UUID string	Returns only the order matching this UUID. A malformed value returns 400.
`from`	date-time string	Created-at lower bound (inclusive).
`to`	date-time string	Created-at upper bound (inclusive). Passing `from` after `to` returns 400.

The response includes a pagination object alongside the orders array:

{
  "data": {
    "orders": ["..."],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "total": 142
    }
  }
}

Step 5. Get a single order and read lineage and fill

Use GET /v1/match/orders/{id} to fetch full detail for one order, including its lineage and fill result.

curl -X GET "https://api-sandbox.circle.com/v1/match/orders/$ORDER_ID" \
  -H "Authorization: Bearer $API_KEY"

Reading lineage fields When an order rolls into a new auction cycle, Match creates a new order linked to the original. The lineage object lets you trace the full chain:

lineage.parentOrderId: the UUID of the order this one rolled from. null if this is the original order.
lineage.childOrderId: the UUID of the order this one rolled into. null if the order hasn’t rolled yet, or if it was cancelled.

To reconstruct the full history of a rolled order, start with any order in the chain and follow parentOrderId backward or childOrderId forward until you reach null. Reading the fill object The fill field is null until the order is matched. Once matched, it contains:

{
  "fill": {
    "filledAmount": { "amount": "500.00", "currency": "USD" },
    "unfilledAmount": { "amount": "0.00", "currency": "USD" },
    "clearingFeeBps": "3",
    "matchedAt": "2026-08-17T00:05:00Z"
  }
}

A non-zero unfilledAmount indicates a partial fill. In that case, check lineage.childOrderId to find the follow-on order that was created for the unfilled portion according to your postFillAction election.

Order status lifecycle

Status	Description
`pending`	Accepted and queued for the current auction. Not yet matched or settled.
`settling`	Matched in the auction. Funds are moving between counterparties.
`filled`	The entire order matched and settlement is complete.
`partial_fill`	Only part of the order matched. The unfilled portion followed your `postFillAction` election.
`unfilled`	The auction closed with no fill for this order. The order followed your `postFillAction` election.
`cancelled`	You canceled the order before it matched.
`failed`	The order matched but the underlying funding never settled. No trade occurred.

Error reference

Code	HTTP	Meaning
137002	400	One or more wallet IDs in the request are invalid.
137003	400	One or more wallet IDs were not found.
137004	409	Idempotency key reused with different parameters.
137006	409	Self-match violation: you already have an open order on the opposite side of this auction.
137007	400	The fiat account cannot be used for this burn order.
137008	400	Maximum orders per auction reached. Wait for the next auction cycle.
137009	400	Exceeds your transaction limit.
137010	400	This account is not eligible to place orders.

Mint

Match

StableFX

Digital Asset Accounts

End User Onboarding

How-to: Place and manage orders

Prerequisites

Steps

Step 1. Place a `BURN` order

Step 2. Place a MINT order

Step 3. Place a market order

Step 4. List orders with filters

Step 5. Get a single order and read lineage and fill

Order status lifecycle

Error reference

​Prerequisites

​Steps

​Step 1. Place a BURN order

​Step 2. Place a MINT order

​Step 3. Place a market order

​Step 4. List orders with filters

​Step 5. Get a single order and read lineage and fill

​Order status lifecycle

​Error reference

Prerequisites

Steps

Step 1. Place a `BURN` order

Step 2. Place a MINT order

Step 3. Place a market order

Step 4. List orders with filters

Step 5. Get a single order and read lineage and fill

Order status lifecycle

Error reference