bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 74쪽
b6c7d8e9f00112233445566778899aabbccddeeff",
"credentialId": "a1b2c3d4e5f60718",
"status": "active",
"addedDate": "2026-06-20T14:10:00.000Z"
},
{
"id": "2e3d4c5b-6a79-8012-3456-789abcdef012",
"ownerType": "passkey",
"publicKey": "0x04c1d2e3f4051627384950a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6",
"credentialId": "b2c3d4e5f6071829",
"status": "active",
"addedDate": "2026-06-25T11:01:30.000Z"
}
]
}
]
}
```
The wallet now has two passkey recovery owners. Circle's ECDSA co-signer
continues to sign every UserOperation for the wallet. The additional passkey
does not change routine signing behavior.
</Step>
</Steps>
# How-to: Deposit fiat
Source: https://developers.circle.com/circle-mint/howtos/deposit-fiat
Link a bank account and deposit fiat to mint USDC or EURC in your Circle Mint account.
Deposit fiat (onramp) from an external bank account to mint USDC or EURC in your
Circle Mint balance. The `/wires` endpoint supports multiple payment rails,
including standard wires (FedWire and SWIFT), real-time interbank rails (RTP,
SPEI, SEPA, and CHATS) where available, and book transfers when you bank with
one of Circle's settlement partners.
<Note>
This guide focuses on standard wire deposits. The same endpoint handles other
rails -- Circle routes the deposit based on your linked bank and region.
Rail-specific parameters and additional endpoints (such as CUBIX and PIX for
local currencies) are out of scope here.
</Note>
## Prerequisites
Before you begin:
* Complete the
[account and API key setup](/circle-mint/quickstarts/getting-started).
* Have access to a bank account that can send wire transfers.
## Step 1. Link a bank account
Use the
[create a wire bank account](/api-reference/circle-mint/account/create-business-wire-account)
endpoint to register your external bank account with Circle Mint.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/businessAccount/banks/wires \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"idempotencyKey":"ba943ff1-ca16-49b2-ba55-1057e70ca5c7","accountNumber":"12340010","routingNumber":"121000248","billingDetails":{"name":"Satoshi Nakamoto","city":"Boston","country":"US","line1":"100 Money Street","district":"MA","postalCode":"01234"},"bankAddress":{"bankName":"SAN FRANCISCO","city":"SAN FRANCISCO","country":"US","line1":"100 Money Street","district":"CA"}}'
```
Expected response:
```json theme={null}
{
"data": {
"id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
"status": "pending",
"description": "WELLS FARGO BANK, NA ****0010",
"trackingRef": "CIR2GKYL4B",
"virtualAccountEnabled": true,
"billingDetails": {
"name": "Satoshi Nakamoto",
"line1": "100 Money Street",
"city": "Boston",
"postalCode": "01234",
"district": "MA",
"country": "US"
},
"bankAddress": {
"bankName": "WELLS FARGO BANK, NA",
"line1": "100 Money Street",
"city": "SAN FRANCISCO",
"district": "CA",
"country": "US"
},
"createDate": "2023-11-04T20:02:21.062Z",
"updateDate": "2023-11-04T20:02:21.062Z"
}
}
```
Record the `id` and `trackingRef` values from the response. You use both in the
following steps.
## Step 2. Retrieve wire instructions
Use the
[get wire instructions](/api-reference/circle-mint/account/get-business-wire-account-instructions)
endpoint to fetch the beneficiary details your bank needs to send the wire.
```bash theme={null}
curl https://api-sandbox.circle.com/v1/businessAccount/banks/wires/${BANK_ACCOUNT_ID}/instructions \
-H "Authorization: Bearer ${YOUR_API_KEY}"
```
Expected response:
```json theme={null}
{
"data": {
"trackingRef": "CIR22FEP33",
"beneficiary": {
"name": "CIRCLE INTERNET FINANCIAL INC",
"address1": "1 MAIN STREET",
"address2": "SUITE 1"
},
"virtualAccountEnabled": true,
"beneficiaryBank": {
"name": "CRYPTO BANK",
"address": "1 MONEY STREET",
"city": "NEW YORK",
"postalCode": "1001",
"country": "US",
"swiftCode": "CRYPTO99",
"routingNumber": "999999999",
"accountNumber": "123815146304",
"currency": "USD"
}
}
}
```
The response includes:
* **Beneficiary details** -- the name and address of the recipient (Circle).
* **Routing information** -- the bank name, SWIFT code, and routing number for
the beneficiary bank.
* **Virtual Account Number** -- the `beneficiaryBank.accountNumber` field,
unique to your linked bank account.
* **Tracking reference** -- the `trackingRef` value to include in the wire memo.
### Virtual account numbers
Not all Circle settlement banks support Virtual Account Numbers. When
`virtualAccountEnabled` is `true` in the wire instructions response, the linked
bank account has a unique VAN in the `beneficiaryBank.accountNumber` field. When
the sender includes the VAN as the account number on their wire, the tracking
reference in the wire memo becomes optional.
When `virtualAccountEnabled` is `false`, the sender must include the
`trackingRef` in the wire memo so Circle can match the deposit to your account.
Benefits of using a VAN (where supported):
* Eliminates the need for senders to include tracking references in payment
instructions.
* Reduces wire returns caused by missing or incorrect tracking references.
* Supports all wire types: domestic, international, and SWIFT.
## Step 3. Send the wire deposit
In production, initiate the wire transfer from your bank using the instructions
returned in Step 2. Confirm that the wire details -- beneficiary name, account
number, and routing number -- match exactly. Mismatched details can result in
wire returns or processing delays of several business days.
Domestic wire deposits received before the daily cutoff typically settle on the
same business day. International wires may take longer depending on intermediary
banks.
### Simulate a deposit in sandbox
In the sandbox environment, use the
[mock wire payment](/api-reference/circle-mint/account/create-mock-wire-payment)
endpoint to simulate a wire deposit without sending real funds. Provide the
`trackingRef` from Step 2 and the `beneficiaryBank.accountNumber` (the VAN) from
the wire instructions response.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/mocks/payments/wire \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"amount":{"amount":"50.00","currency":"USD"},"trackingRef":"CIR22FEP33","beneficiaryBank":{"accountNumber":"123815146304"}}'
```
Expected response:
```json theme={null}
{
"data": {
"trackingRef": "CIR22FEP33",
"amount": {
"amount": "50.00",
"currency": "USD"
},
"beneficiaryBank": {
"accountNumber": "123815146304"
},
"status": "pending"
}
}
```
<Note>
The mock wire endpoint is available in sandbox only. Mock wire deposits
process in batches and may take up to 15 minutes to complete.
</Note>
## Step 4. Verify the deposit
Use the
[list deposits](/api-reference/circle-mint/account/list-business-deposits)
endpoint to confirm the incoming fiat deposit has settled.
```bash theme={null}
curl https://api-sandbox.circle.com/v1/businessAccount/deposits \
-H "Authorization: Bearer ${YOUR_API_KEY}"
```
Expected response:
```json theme={null}
{
"data": [
{
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
"sourceWalletId": "1000066041",
"destination": {
"type": "wallet",
"id": "1000066041"
},
"amount": {
"amount": "50.00",
"currency": "USD"
},
"status": "complete",
"createDate": "2024-01-01T12:00:00.000Z"
}
]
}
```
## See also
* [How minting and redemption works](/circle-mint/concepts/how-minting-works) --
understand the minting process
* [Sandbox to Production](/circle-mint/references/sandbox-and-testing) --
transition to production
* [Create a wire bank account](/api-reference/circle-mint/account/create-business-wire-account)
\-- API reference
# How-to: Exchange currencies
Source: https://developers.circle.com/circle-mint/howtos/exchange-currencies
Use the Mint Exchange API to exchange local fiat for USDC or swap between USDC and EURC through a quote, trade, and settlement flow.
Use the Mint Exchange API to exchange a supported local fiat currency for USDC
or to swap between USDC and EURC. The following steps use an MXN to USDC trade
as the worked example. Every supported pair follows the same quote, trade, and
settle flow, so you can adapt the requests by changing the currency codes and
the fiat account type. For the conceptual model and the current list of
supported pairs, see
[Cross-currency exchange](/circle-mint/concepts/cross-currency-exchange).
## Prerequisites
Before you begin, ensure that you've:
* Confirmed with Circle that Cross-Currency Exchange is enabled on your Circle
Mint account. Activation requires a signed Cross-Currency MSA and a
contracting entity that supports your pair, as listed in the
[supported currency pairs](/circle-mint/concepts/cross-currency-exchange#supported-currency-pairs)
table. For example, SGD to USDC is available only to accounts contracted with
Circle SG. To request activation, contact your Circle representative.
* Linked a bank account to Circle Mint for the local fiat side of the trade (not
required for USDC and EURC swaps).
* Configured API authentication per the
[Getting Started quickstart](/circle-mint/quickstarts/getting-started). The
examples use a `$API_KEY` environment variable for the bearer token and the
sandbox base URL, `https://api-sandbox.circle.com`.
## Step 1. Register a fiat trading account
For a fiat pair, register the linked bank account as the trading account for the
fiat currency by sending a `PUT` request to
[`/v1/exchange/fxConfigs/accounts`](/api-reference/circle-mint/cross-currency/create-fx-account).
This is a one-time setup per currency. Skip this step for USDC and EURC swaps
and for HKD trades, whose fiat account is configured offline.
The `fiatAccountId` is the `id` of the fiat bank account you link to Circle
Mint. For MXN, link a wire account with
[`POST /v1/businessAccount/banks/wires`](/api-reference/circle-mint/account/create-business-wire-account)
if you haven't already, and use the `id` from the response. Other currencies may
need a different account type; see
[supported currency pairs](/circle-mint/concepts/cross-currency-exchange#supported-currency-pairs).
Register the account, setting `currency` to the fiat leg of the pair:
```bash theme={null}
curl -X PUT https://api-sandbox.circle.com/v1/exchange/fxConfigs/accounts \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fiatAccountId": "763a80d8-9bbb-4876-a67d-e8089389b016",
"currency": "MXN"
}'
```
Expected response:
```json theme={null}
{
"data": {
"currency": "MXN",
"fiatAccountId": "763a80d8-9bbb-4876-a67d-e8089389b016",
"createDate": "2026-04-10T17:50:09.452Z",
"updateDate": "2026-04-10T17:50:09.452Z"
}
}
```
## Step 2. Check the daily limit
Verify that the trade you plan to create has enough daily headroom by calling
[`GET /v1/exchange/fxConfigs/dailyLimits`](/api-reference/circle-mint/cross-currency/get-daily-fx-limits).
The endpoint returns the per-currency limit, the amount used so far in the
current day, and the amount still available. Trades that would exceed the
available amount are rejected at submission.
```bash theme={null}
curl https://api-sandbox.circle.com/v1/exchange/fxConfigs/dailyLimits \
-H "Authorization: Bearer $API_KEY"
```
Expected response:
```json theme={null}
{
"data": {
"dailyLimits": {
"EURC": {
"limit": "1000000.00",
"usage": "0.00",
"available": "1000000.00"
},
"MXN": {
"limit": "1000000.00",
"usage": "0.00",
"available": "1000000.00"
},
"USDC": {
"limit": "1000000.00",
"usage": "0.00",
"available": "1000000.00"
},
"BRL": {
"limit": "1000000.00",
"usage": "0.00",
"available": "1000000.00"
}
}
}
}
```
## Step 3. Request a tradable quote
Send a `POST` request to
[`/v1/exchange/quotes`](/api-reference/circle-mint/cross-currency/get-quote)
with `type` set to `tradable` to lock a rate for 3 seconds. Reference quotes are
indicative only and cannot be accepted in Step 4; see the
[quote types section](/circle-mint/concepts/cross-currency-exchange#quote-types)
for the distinction.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/exchange/quotes \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "tradable",
"from": {
"currency": "MXN",
"amount": "100.00"
},
"to": {
"currency": "USDC"
}
}'
```
Expected response:
```json theme={null}
{
"data": {
"id": "17e1ad29-a223-4ba0-bfb1-cebe861bfed1",
"rate": 0.0597,
"from": {
"currency": "MXN",
"amount": "100.00"
},
"to": {
"currency": "USDC",
"amount": "5.97"
},
"expiry": "2026-04-10T14:37:23.804Z",
"type": "tradable",
"estimatedSettlementTime": "2026-04-10T17:37:23.804Z"
}
}
```
For another pair, replace `MXN` with the currency you're exchanging. Exactly one
of `from` and `to` must be USDC. For a USDC and EURC swap, set `from` and `to`
to `USDC` and `EURC` in either direction.
## Step 4. Accept the quote by creating a trade
Lock the quoted rate by sending a `POST` request to
[`/v1/exchange/trades`](/api-reference/circle-mint/cross-currency/create-fx-trade)
with the `quoteId` from Step 3 and a new `idempotencyKey`. Only `tradable`
quotes are accepted; submitting a `reference` quote returns an error.
```bash theme={null}
curl -X POST https://api-sandbox.circle.com/v1/exchange/trades \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "7a6cba1e-6b8d-4bb8-b236-5c20a12e88f6",
"quoteId": "17e1ad29-a223-4ba0-bfb1-cebe861bfed1"
}'
```
Expected response:
```json theme={null}
{
"data": {
"id": "7a6cba1e-6b8d-4bb8-b236-5c20a12e88f6",
"from": {
"currency": "MXN",
"amount": "100.00"
},
"to": {
"currency": "USDC",
"amount": "5.97"
},
"status": "pending",
"createDate": "2026-04-10T14:37:20.804Z",
"updateDate": "2026-04-10T14:37:20.804Z",
"quoteId": "17e1ad29-a223-4ba0-bfb1-cebe861bfed1"
}
}
```
Record the trade `id`. You use it in Step 6 to poll the trade status.
## Step 5. Retrieve settlement instructions and send funds
This step applies to fiat pairs. For USDC and EURC swaps, no inbound transfer is
required; see the note at the end of this step.
Fetch the beneficiary details for the fiat leg by sending a `GET` request to
[`/v1/exchange/trades/settlements/instructions/{currency}`](/api-reference/circle-mint/cross-currency/get-settlement-instructions),
with the currency code of the fiat you're sending as the path parameter. The
shape of the instructions depends on the payment rail. Settlement instructions
are static for a given currency and can be cached and reused across trades.
```bash theme={null}
curl https://api-sandbox.circle.com/v1/exchange/trades/settlements/instructions/MXN \
-H "Authorization: Bearer $API_KEY"
```
For MXN, the response returns wire-style instructions. Send the inbound peso
transfer on the SPEI rail using these details and include the `trackingRef` in
the wire reference field so Circle can match the inbound transfer to the trade.
```json theme={null}
{
"data": {
"currency": "MXN",
"fiatAccountType": "wire",
"instruction": {
"beneficiary": {
"name": "CIRCLE INTERNET FINANCIAL INC",
"address1": "99 HIGH STREET",
"address2": "BOSTON MA 02110"
},
"beneficiaryBank": {
"name": "CIRCLE BANKING PARTNER",
"swiftCode": "BANKMXMMXXX",
"routingNumber": "322286803",
"accountNumber": "127180987654321012",
"currency": "MXN",
"address": "AVENIDA INSURGENTES SUR 3579",
"postalCode": "14020",
"country": "MX"
},
"trackingRef": "ezBrwN2nP5Bz18Lu"
}
}
}
```
<Note>
USDC and EURC swaps do not require an inbound transfer. Both legs are debited
and credited against the Mint balance per the settlement schedule configured
offline with Circle. See
[delivery-versus-payment settlement](/circle-mint/concepts/cross-currency-exchange#delivery-versus-payment-settlement)
for details.
</Note>
## Step 6. Poll the trade status
Send a `GET` request to
[`/v1/exchange/trades/{id}`](/api-reference/circle-mint/cross-currency/get-fx-trade-id)
to track the trade as it moves toward settlement. The trade transitions through
`pending`, `confirmed`, `pending_settlement`, and `complete` (or `failed`) as it
progresses. See the
[trade and settlement lifecycle](/circle-mint/concepts/cross-currency-exchange#trade-and-settlement-lifecycle)
for the full state machine.
```bash theme={null}
curl https://api-sandbox.circle.com/v1/exchange/trades/7a6cba1e-6b8d-4bb8-b236-5c20a12e88f6 \
-H "Authorization: Bearer $API_KEY"
```
Expected response:
```json theme={null}
{
"data": {
"id": "7a6cba1e-6b8d-4bb8-b236-5c20a12e88f6",
"from": {
"currency": "MXN",
"amount": "100.00"
},
"to": {
"currency": "USDC",
"amount": "5.97"
},
"status": "complete",
"createDate": "2026-04-10T14:37:20.804Z",
"updateDate": "2026-04-10T14:55:00.000Z",
"quoteId": "17e1ad29-a223-4ba0-bfb1-cebe861bfed1",
"settlementId": "67276b7d-7ea5-4f22-a231-09e2d2891c36",
"rate": "0.0597",
"expectedBatchTime": "2026-04-10T15:00:00.000Z",
"estimatedSettlementTime": "2026-04-10T17:00:00.000Z"
}
}
```
## Step 7. Retrieve the settlement batch
Once the trade reaches `complete`, retrieve the settlement batch that holds the
trade's legs by sending a `GET` request to
[`/v1/exchange/trades/settlements`](/api-reference/circle-mint/cross-currency/get-settlements).
Use the `type` query parameter to filter for the inbound (`account_receivable`)
or outbound (`account_payable`) side. Each batch lists its legs in the `details`
array, marked as `payable` and `receivable`.
```bash theme={null}
curl "https://api-sandbox.circle.com/v1/exchange/trades/settlements?type=account_receivable" \
-H "Authorization: Bearer $API_KEY"
```
Expected response:
```json theme={null}
{
"data": [
{
"id": "67276b7d-7ea5-4f22-a231-09e2d2891c36",
"entityId": "c5692eb6-33f9-431d-9481-2eee38f02081",
"status": "settled",
"createDate": "2026-04-10T14:45:04.729Z",
"updateDate": "2026-04-10T14:55:00.000Z",
"details": [
{
"id": "02bd22dc-b40f-49b8-b2d8-6e69f82cfca0",
"type": "payable",
"status": "completed",
"reference": "ezBrwN2nP5Bz18Lu",
"amount": {
"currency": "MXN",
"amount": "100.00"
},
"createDate": "2026-04-10T14:45:04.728Z",
"updateDate": "2026-04-10T14:55:00.000Z"
},
{
"id": "afbd8d53-34ea-42fa-9691-4a5c0dd96c53",
"type": "receivable",
"status": "completed",
"amount": {
"currency": "USDC",
"amount": "5.97"
},
"createDate": "2026-04-10T14:45:04.728Z",
"updateDate": "2026-04-10T14:55:00.000Z"
}
]
}
]
}
```
Repeat the request with `type=account_payable` to retrieve the outbound leg.
# How-to: Repay a loan
Source: https://developers.circle.com/circle-mint/howtos/repay-loan
Repay part or all of an open loan's outstanding USDC debt and release your cirBTC collateral back to your Circle Mint balance.
You can repay a loan in full or in part. Full repayment closes the loan and
releases the cirBTC collateral back to your Circle Mint balance. Partial
repayment reduces the outstanding debt without closing the loan or releasing
collateral. See
[How Digital Asset-Backed Borrowing works](/circle-mint/concepts/digital-asset-backed-borrowing)
for the underlying concepts.
## Prerequisites
Before you begin, ensure that you've:
* Completed the
[Borrow USDC against cirBTC collateral](/circle-mint/quickstarts/borrow-with-cirbtc)
quickstart and hold at least one loan in `active` status.
* Held sufficient USDC in your Mint balance to cover the repayment amount you
plan to submit.
## Steps
<Steps>
<Step title="Choose a repayment mode">
Decide whether you want to repay in full or partially, then call
[`POST /v1/borrow/loans/{id}/repayments`](/api-reference/circle-mint/digital-asset-backed-borrowing/create-borrow-repayment)
with the corresponding `mode`.
* **Full repay**: set `mode: FULL`. Circle measures the outstanding debt at the
moment it builds the UserOperation and repays that exact amount. On success,
Circle rele프로젝트로 돌아가기
