> ## 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-to: Place and manage orders > Place BURN and MINT orders, apply filters when listing, and trace rolled orders using lineage fields. 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](/circle-match/quickstarts/place-your-first-order) 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](/circle-match/concepts/funding-model) and [auction mechanics](/circle-match/concepts/how-it-works) ## 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. ```bash theme={null} 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`: ```json theme={null} { "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-3-place-a-market-order). | ### 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. ```bash theme={null} 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). | ### 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`. ```bash theme={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. ```bash theme={null} 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: ```json theme={null} { "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. ```bash theme={null} 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: ```json theme={null} { "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. |