bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 69쪽
d 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. |
# How-to: Cancel and modify orders
Source: https://developers.circle.com/circle-match/howtos/cancel-and-modify-orders
Cancel a single resting order, cancel all orders in an auction, or change an order's fee limit before the auction clears.
Match provides three mutation endpoints for resting orders: cancel a single
order, cancel all of your orders in the current auction, or modify an order's
fee limit. These operations are available at any time during an auction cycle
with one exception: the lock window that opens before clearing imposes
additional constraints.
<Warning>
During the lock window, cancellations are blocked and only fee changes that
make an order more competitive are accepted. Attempting to cancel returns
error 136001. Attempting to make a fee less competitive returns error 137005.
New orders are still accepted during the lock window. For a full explanation
of the lock window and auction lifecycle, see [How Match
works](/circle-match/concepts/how-it-works).
</Warning>
## Prerequisites
Before you begin, ensure that you've:
* Obtained a Circle API key with Match access
* Placed at least one order that is in `pending` status (see
[Place and manage orders](/circle-match/howtos/place-orders))
* Retrieved the `auctionId` and `orderId` for the order you want to act on
## Steps
### Step 1. Cancel a single order
Send a `POST` request to `/v1/match/orders/cancel` with the `auctionId` and
`orderId` of the resting order.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/match/orders/cancel \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"auctionId": 42,
"orderId": "550e8400-e29b-41d4-a716-446655440000"
}'
```
A successful response returns status `cancelled`:
```json theme={null}
{
"data": {
"auctionId": 42,
"orderId": "550e8400-e29b-41d4-a716-446655440000",
"status": "cancelled"
}
}
```
If the lock window is open, the request is rejected with error 136001. Wait for
the auction to clear and retry against the next auction cycle if the order rolls
over.
### Step 2. Cancel all orders
To cancel every resting order you have in the current auction, send a `POST`
request to `/v1/match/orders/cancel-all`. No request body is required.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/match/orders/cancel-all \
-H "Authorization: Bearer $API_KEY"
```
A successful response lists all cancelled order IDs:
```json theme={null}
{
"data": {
"auctionId": 42,
"orderIds": [
"550e8400-e29b-41d4-a716-446655440000",
"661f9511-f30c-52e5-b827-557766551111"
],
"status": "cancelled"
}
}
```
If you have no resting orders in the current auction, `orderIds` is an empty
array and the call still returns 200. As with single-order cancellation, this
endpoint returns error 136001 when the lock window is open.
### Step 3. Modify an order's fee
Use `POST /v1/match/orders/modify` to change the fee limit on a resting order.
Only the fee changes; the order remains in `pending` status with its original
size and side.
The competitiveness direction differs by order type:
* **BURN orders:** a higher `feeBps` is more competitive (willing to pay a
larger fee)
* **MINT orders:** a lower `feeBps` is more competitive (requiring a smaller
rebate)
Outside the lock window, you can move the fee in either direction. During the
lock window, the new `feeBps` must be more competitive than the current value.
Submitting a less competitive fee during the lock window returns error 137005.
To convert a limit order to a market order, set `feeBps` to `null`.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/match/orders/modify \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"auctionId": 42,
"orderId": "550e8400-e29b-41d4-a716-446655440000",
"feeBps": "3"
}'
```
A successful response confirms the order is still `pending` with the updated
fee:
```json theme={null}
{
"data": {
"auctionId": 42,
"orderId": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending"
}
}
```
## Error reference
| Code | HTTP | Meaning |
| - | - | - |
| 136001 | 400 | The auction is locked. Cancellations are not accepted until the auction clears. |
| 136002 | 400 | The auction is settling the previous batch. Try again after settlement completes. |
| 137005 | 400 | During the lock window, a fee change must improve competitiveness. The submitted fee is less competitive than the current fee. |
# How-to: Fund your account
Source: https://developers.circle.com/circle-match/howtos/fund-your-account
Prepare burn-side and mint-side balances so you can place Match orders.
Funding works differently depending on which side of Match you participate on.
Burn-side participants draw from an existing Circle Mint USDC wallet; no
separate deposit is needed. Mint-side participants wire USD to a Match fiat
account. Circle then converts the received USD to a Match-only USDC balance.
This guide walks through both paths and shows you how to confirm your balance is
ready before placing orders. For background on why these two models exist, see
[Funding model](/circle-match/concepts/funding-model).
## Prerequisites
Before you begin, ensure that you've:
* Obtained a Circle API key with Match access
* Completed onboarding for the participant role you intend to use (burn side,
mint side, or both)
## Burn-side funding
Burn-side orders are funded by your existing Circle Mint USDC wallet. There is
no separate deposit step. When you place a burn order, Circle reserves the
specified amount from your Mint wallet balance for the duration of the auction
cycle.
Before placing an order, confirm that:
* Your Circle Mint wallet holds at least \$100 USDC (the minimum order size)
* The balance available in your Mint wallet covers the order amount, accounting
for any USDC already reserved by resting orders
If your available balance is too low when you submit a burn order, the API
returns error `137001` (Insufficient available balance, HTTP 400). Add USDC to
your Circle Mint wallet and retry.
## Mint-side funding
### Step 1. Wire USD to your Match fiat account
Wire USD from your bank to the Match fiat account provided during onboarding.
Circle converts the received USD to a Match-only USDC balance. This USDC is
restricted. It cannot be sent to blockchain addresses. To withdraw it, use a
no-fee withdrawal that burns the USDC and wires USD back to a linked fiat
account.
Wire timing depends on your bank and the time of day. Contact your Circle
account representative if a wire has not settled in the expected window.
### Step 2. Confirm your balance
After the wire settles, call `GET /v1/match/account` to verify that your Match
USDC balance reflects the deposited amount.
```bash theme={null}
curl -X GET https://api-sandbox.circle.com/v1/match/account \
-H "Authorization: Bearer $API_KEY"
```
The following example shows a successful response:
```json theme={null}
{
"data": {
"accountId": "550e8400-e29b-41d4-a716-446655440000",
"usdc": {
"available": { "amount": "4000.00", "currency": "USD" },
"reserved": { "amount": "1000.00", "currency": "USD" },
"total": { "amount": "5000.00", "currency": "USD" }
},
"exposure": {
"activeOrderCount": 3,
"mintOrderCount": 2,
"burnOrderCount": 1
},
"activity": {
"from": "2026-07-18T00:00:00Z",
"to": "2026-08-17T00:00:00Z",
"totalMatched": { "amount": "18000.00", "currency": "USD" },
"rebatesEarned": { "amount": "50.00", "currency": "USD" },
"feesPaid": { "amount": "0.00", "currency": "USD" }
}
}
}
```
**Balance fields:**
| Field | Description |
| - | - |
| `usdc.total` | Your full Match USDC balance, including any amount currently reserved by open orders. Applies to mint-side participants only. |
| `usdc.reserved` | The portion of `usdc.total` held by open resting orders. This amount is not available for new orders. |
| `usdc.available` | `usdc.total` minus `usdc.reserved`. This is the balance you can use when placing new mint orders. |
| `exposure` | Order count breakdown: `activeOrderCount`, `mintOrderCount`, `burnOrderCount`. |
| `activity` | Windowed totals for the reporting period: `totalMatched`, `rebatesEarned`, `feesPaid`. |
<Note>
The account summary is a best-effort, non-consistent snapshot. `activity`
figures may lead settlement and are for operational visibility only. For exact
reconciliation, use your order and settlement records instead.
</Note>
Your `usdc.available` must be at least \$100 before you can place a mint order.
If you call `GET /v1/match/account` before your account is set up, the API
returns error `138003` (HTTP 404). Contact your Circle account representative to
confirm your account is active.
## Error reference
| Code | HTTP | Meaning |
| - | - | - |
| 137001 | 400 | Insufficient available balance. Your available USDC is too low to cover the order amount. |
| 138003 | 404 | No Match wallet found. The entity does not have a Match account. |
| 139001 | 400 | The Match wallet for this account is invalid or unavailable. |
# How-to: Monitor your account
Source: https://developers.circle.com/circle-match/howtos/monitor-account
Call GET /v1/match/account to check your Match balance and activity totals, and learn when to use order records instead.
The Match account endpoint returns a snapshot of your balance and a summary of
burn, mint, and fee activity. Use this snapshot for quick checks before placing
orders. For exact figures, use your order and settlement records. This guide
shows you how to read each field and when to use each data source.
## Prerequisites
Before you begin, ensure that you've:
* Obtained a Circle API key with Match access
* Completed onboarding as a burn-side or mint-side participant (or both)
## Steps
### Step 1. Retrieve your account summary
Call `GET /v1/match/account` to fetch your current balance and activity totals.
```bash theme={null}
curl -X GET https://api-sandbox.circle.com/v1/match/account \
-H "Authorization: Bearer $API_KEY"
```
A successful response has the following structure:
```json theme={null}
{
"data": {
"accountId": "550e8400-e29b-41d4-a716-446655440000",
"usdc": {
"available": { "amount": "4000.00", "currency": "USD" },
"reserved": { "amount": "1000.00", "currency": "USD" },
"total": { "amount": "5000.00", "currency": "USD" }
},
"exposure": {
"activeOrderCount": 3,
"mintOrderCount": 2,
"burnOrderCount": 1
},
"activity": {
"from": "2026-07-18T00:00:00Z",
"to": "2026-08-17T00:00:00Z",
"totalMatched": { "amount": "18000.00", "currency": "USD" },
"rebatesEarned": { "amount": "50.00", "currency": "USD" },
"feesPaid": { "amount": "0.00", "currency": "USD" }
}
}
}
```
### Step 2. Interpret the balance fields
The `usdc` object reflects your Match USDC position at the time of the request.
For a detailed explanation of how these balances relate to the funding model,
see [Funding model](/circle-match/concepts/funding-model).
| Field | Description |
| - | - |
| `usdc.total` | Your full Match USDC balance, including any amount currently reserved by open orders. Applies to mint-side participants only. |
| `usdc.reserved` | The portion of `usdc.total` held by resting orders. Not available for new orders or withdrawals until the orders settle or are canceled. |
| `usdc.available` | `usdc.total` minus `usdc.reserved`. This is the balance you can use when placing new mint orders or initiating a withdrawal. |
| `exposure` | Order count breakdown: `activeOrderCount` (total), `mintOrderCount`, `burnOrderCount`. |
### Step 3. Interpret the `activity` window
The `activity` object shows matched volume and fee figures for a rolling
reporting window. The window boundaries are provided in the `from` and `to`
fields.
| Field | Description |
| - | - |
| `from` | Start of the reporting window (inclusive). |
| `to` | End of the reporting window (inclusive). |
| `totalMatched` | Total USD amount matched during the window. |
| `rebatesEarned` | Total rebates received. Nonzero for mint-side participants who received a rebate at clearing. |
| `feesPaid` | Total fees paid. Nonzero for burn-side participants who paid the clearing fee. |
<Warning>
The account summary is a **best-effort snapshot**. Field values may not reflect a single point in time. Different fields can be computed at slightly different moments. Activity figures (`activity.totalMatched`, `activity.rebatesEarned`, `activity.feesPaid`) may appear before settlement clears in your bank account or wallet.
**Do not use the account summary for reconciliation or audits.** For exact
figures, use your order records (`GET /v1/match/orders`) and settlement records.
</Warning>
## When to use each data source
| Use case | Data source |
| - | - |
| Check whether you have enough balance before placing an order | Account summary (`GET /v1/match/account`) |
| Display rough balance and activity stats on a dashboard | Account summary (`GET /v1/match/account`) |
| Reconcile activity against bank statements | Order records and settlement records |
| Produce an audit trail | Order records and settlement records |
| Make any decision requiring an exact, authoritative figure | Order records and settlement records |
For event-driven monitoring without polling, subscribe to real-time account and
order updates over WebSocket. See
[Subscribe to real-time updates](/circle-match/howtos/subscribe-to-real-time-updates).
# How-to: Place and manage orders
Source: https://developers.circle.com/circle-match/howtos/place-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:**
프로젝트로 돌아가기
