Circle USYC 백서 전문

ember 2025; see the StableFX documentation for current mainnet availability. | For onchain FX on Arc, see the [StableFX documentation](/stablefx). The remainder of this page concerns only the Mint Exchange API. ## Quote types Every Mint Exchange trade starts from a quote. Quotes come in two types, set through the `type` field on a quote request. * `reference`: An indicative rate-only quote. Reference quotes do not lock a rate and cannot be accepted to create a trade. They exist to give an application a current view of pricing without committing to a transaction. * `tradable`: A quote with a locked rate. Tradable quotes are valid for **3 seconds** from issuance and are the only quote type that `POST /v1/exchange/trades` will accept. A tradable quote that is not used in its validity window must be replaced by a fresh quote before a trade can be created. ## Quote, trade, and settle The Mint Exchange flow is a three-phase model: a customer first obtains a quote, then creates a trade against that quote, and then settles the trade by either sending fiat to a Circle beneficiary account or letting Circle debit the Mint balance. The following diagram shows the two settlement paths against the same quote-then-trade backbone. ```mermaid theme={null} sequenceDiagram participant C as Mint customer participant M as Mint Exchange API Note over C,M: Quote C->>M: Requests a tradable quote M-->>C: Returns quote with locked rate (valid 3s) Note over C,M: Trade C->>M: Creates a trade against the quote M-->>C: Returns trade in pending state Note over C,M: Settlement (fiat to USDC) C->>M: Sends fiat to Circle beneficiary account with tracking reference M-->>C: Confirms receipt; trade settles into USDC Note over C,M: Settlement (USDC to EURC) M->>M: Debits and credits Mint balance per settlement schedule M-->>C: Settlement batch reflects the completed legs ``` Procedural details, including the API requests for each phase, live in the [Exchange Currencies how-to](/circle-mint/howtos/exchange-currencies). ## Delivery-versus-payment settlement Cross-currency trades settle on a delivery-versus-payment (DvP) basis: Circle receives the inbound leg first and only then delivers the outbound leg. The specific mechanics depend on which currencies are exchanged. **Fiat to or from USDC.** For BRL and MXN pairs, the customer transfers fiat from a registered bank account into Circle's beneficiary account using a Circle-issued tracking reference (an identifier that ties the inbound transfer to the open trade). Once Circle's banking partner confirms receipt, the trade settles and the resulting USDC is credited to the customer's Mint balance. The reverse direction follows the same pattern with the legs reversed. HKD / USDC follows a similar wire-based pattern; consult Circle for current HKD operational details. **USDC to or from EURC.** Both legs are stablecoins held on the Mint balance, so no external fiat transfer is involved. The trade is debited and credited directly against the customer's Mint balance according to a settlement schedule configured offline with Circle. The schedule controls when batches are eligible for settlement and is not exposed as a runtime configuration on the API. ## Settlement batches and settlement instructions A settled trade is grouped into a settlement batch that records the inbound and outbound legs as `payable` and `receivable` details. The batch is the unit of reconciliation: each detail carries its own amount, currency, status, and, for fiat legs, the tracking reference that must accompany the inbound wire or PIX transfer. Settlement instructions are issued per currency and are static, so they can be cached and reused across trades. The shape of the instructions differs by rail. * MXN instructions are returned as wire-style details including an 11-character SWIFT/BIC code, a routing number, and an account number. The inbound transfer must be sent on the SPEI rail. * BRL instructions are returned as PIX details, including ISPB, branch code, account type, and the beneficiary tax ID; the inbound transfer must be sent on PIX. * HKD trades are planned to follow the wire pattern using the CHATS rail; confirm operational specifics with Circle. * SGD instructions are returned as wire-style details for Circle SG accounts that have the SGD corridor enabled. Confirm production funding details with Circle before you send SGD. * USDC and EURC settlement requires no external instructions because the legs settle directly against the Mint balance. ## Trade and settlement lifecycle A trade transitions through a small set of states tracked by the `status` field on the trade record, and the settlement batch it belongs to carries its own status. The following diagram shows the trade lifecycle. ```mermaid theme={null} stateDiagram-v2 [*] --> pending pending --> confirmed pending --> failed confirmed --> pending_settlement confirmed --> failed pending_settlement --> complete pending_settlement --> failed complete --> [*] failed --> [*] ``` The trade states have the following meanings: * `pending`: The trade has been created against an accepted quote but is not yet executed. Funds should not be sent in this state. * `confirmed`: The trade is fully executed and ready for the customer to send the inbound leg, when one is required. * `pending_settlement`: The trade is grouped into a settlement batch and is waiting for the batch to settle. * `complete`: The trade has settled and the outbound leg has been delivered. * `failed`: The trade did not complete and no settlement occurs. A settlement batch reports its own progress through the `pending` and `settled` values of `SettlementStatus`, and each detail in a batch reports a `pending` or `completed` value of its own. ## Daily limits Circle enforces per-currency daily limits on Mint Exchange activity as an operational guard rail. The current limit, the used amount, and the remaining amount for each supported currency are exposed through `GET /v1/exchange/fxConfigs/dailyLimits`. Production planning should account for these caps, especially for high-throughput corridors, because trades that would exceed the daily available amount are rejected. ## Supported currency pairs The Mint Exchange API covers a defined scope of currency pairs, each tied to a contracting entity and, for local fiat corridors, a local KYC review. The following table summarizes the pairs supported end-to-end today. | Currency pair | Entity required | Additional eligibility | | - | - | - | | BRL / USDC | Circle LLC | KYC with Circle's banking partner in Brazil; PIX settlement rail. | | MXN / USDC | Circle LLC | KYC with Circle's banking partner in Mexico; SPEI settlement rail. | | EURC / USDC | Circle LLC or Circle SAS | Settles against the Mint balance per the configured schedule. | | HKD / USDC | Circle LLC | CHATS settlement rail. | | SGD / USDC | Circle SG only | SGD bank account registered as a wire account and linked for SGD. | The SGD / USDC corridor is available in production and in the sandbox only to Circle SG customers whose accounts have Cross-Currency enabled. To link the trading account, register the SGD bank account as a wire account, then call [`PUT /v1/exchange/fxConfigs/accounts`](/api-reference/circle-mint/cross-currency/create-fx-account) with `currency` set to `SGD`. Entitled accounts can retrieve SGD wire settlement instructions from [`GET /v1/exchange/trades/settlements/instructions/SGD`](/api-reference/circle-mint/cross-currency/get-settlement-instructions). Confirm SGD daily limits and production funding details with Circle before you trade. The `ExchangeRateOptionalAmountMoney` enum in the OpenAPI specification lists additional currency codes (AED, GBP, CNH) that aren't supported. The documented daily limits response covers only BRL, MXN, EURC, and USDC, and HKD settlement instructions are exchanged with Circle directly. Availability for each pair depends on how Circle configures your account. For the procedural walkthrough of obtaining a quote, creating a trade, and sending funds, see the [Exchange Currencies how-to](/circle-mint/howtos/exchange-currencies). For the broader Mint product, see the [Circle Mint overview](/circle-mint). # How Digital Asset-Backed Borrowing works Source: https://developers.circle.com/circle-mint/concepts/digital-asset-backed-borrowing The concepts behind borrowing USDC against cirBTC: the MSCA wallet, the lending market, and how loans move through their lifecycle. Digital Asset-Backed Borrowing is a Circle Mint offering that lets you post cirBTC as collateral to a pre-approved lending market on Arc or Ethereum and borrow USDC against it. Circle handles all onchain operations for you. You never sign a transaction, and gas is sponsored. For a walkthrough, see [Borrow USDC against cirBTC collateral](/circle-mint/quickstarts/borrow-with-cirbtc). <Note>Digital Asset-Backed Borrowing is not available in New York.</Note> ## The wallet As a Mint customer entity, you get one [modular smart contract account (MSCA)](/wallets/account-types#smart-contract-accounts-sca-and-msca) per supported blockchain: Arc and Ethereum, powered by [Circle Wallets](/wallets). Each MSCA holds your cirBTC collateral for the duration of loans on that blockchain. The MSCA has two owners with a signature threshold of one: * **Circle-managed ECDSA co-signer**: an ECDSA key that Circle holds through its multiparty computation (MPC) custody. This is the active signer for every UserOperation your wallet executes. Circle uses this key to build, sign, and submit onchain transactions on your behalf. * **Your passkey**: a WebAuthn P-256 credential you register during wallet creation. This owner is dormant. Circle never uses it to sign routine operations. It exists as an independent recovery owner that Circle cannot exercise on your behalf. You never sign a blockchain transaction. All routine signing is performed server-side by the Circle co-signer. Gas is sponsored by [Circle's paymaster](/paymaster), so there is no native-token balance for you to fund or monitor. You can add additional passkey owners to the MSCA after wallet creation by calling [`POST /v1/borrow/wallets/owners`](/api-reference/circle-mint/digital-asset-backed-borrowing/add-borrow-wallet-owner). See [How-to: Add another wallet owner](/circle-mint/howtos/add-wallet-owner). ## The lending market Borrows are executed onchain in pre-approved lending markets curated by Circle: * [Morpho](https://morpho.org/) on Arc and Ethereum These markets don't underwrite borrowers or set limits per customer. The amount you can borrow is capped by the value of the cirBTC collateral you post, not by a pre-approved credit line. Circle is not the lender. The USDC you borrow comes from other lenders who have supplied liquidity to the market. Interest accrues at the market's variable borrow rate. Call [`GET /v1/borrow/markets`](/api-reference/circle-mint/digital-asset-backed-borrowing/list-borrow-markets) for live rates and [LTV parameters](#ltv-health-factor-and-liquidation). ## The asynchronous job model Every write endpoint is asynchronous. When you call [`POST /v1/borrow/loans`](/api-reference/circle-mint/digital-asset-backed-borrowing/create-borrow-loan) to borrow, [`POST /v1/borrow/loans/{id}/repayments`](/api-reference/circle-mint/digital-asset-backed-borrowing/create-borrow-repayment) to repay, or any other write, Circle responds with a job rather than the loan or repayment directly. The job tracks the asynchronous operation Circle executes on your behalf. Your integration code polls the job to observe progress. The job progresses through a series of states until it reaches a terminal state that tells you whether the operation succeeded or failed. All asynchronous writes share the same state machine, so once you understand the job lifecycle for one operation, you understand it for all of them. ### Job types The `jobType` field on a job tells you which operation the job represents. | Job type | What it does | | - | - | | `wallet_setup` | Provisions the MSCA on the blockchain. | | `borrow` | Originates a loan. | | `repay` | Repays part or all of a loan's debt. | | `add_collateral` | Adds cirBTC collateral to an existing loan. | | `withdraw_residual` | Sweeps residual collateral back to your Mint balance after a full liquidation. Circle creates these jobs automatically. | | `add_owner` | Adds a new authorized owner to your wallet. | | `remove_owner` | Removes an authorized owner from your wallet. | ### Job states The `status` field on a job progresses through the states below. | State | Terminal | What it means | | - | - | - | | `received` | No | Circle received your request and is preparing the onchain operation. | | `awaiting_approval` | No | The underlying fund transfer is waiting for your account administrator to approve it in the Mint Console. Only applies to `borrow`, `repay`, and `add_collateral` jobs when your account has an approval workflow configured. | | `submitted` | No | The signed onchain transaction has been submitted to the blockchain and is waiting for confirmation. | | `confirmed` | No | The transaction has been confirmed onchain. | | `completed` | Yes | Success. The operation finished and its effect is reflected in your Mint balance and loan record. | | `failed` | Yes | The underlying onchain operation did not succeed. Check the `error` field on the job for the human-readable reason. | | `approval_rejected` | Yes | Your account administrator rejected the underlying fund transfer in the Mint Console. The operation never reached the blockchain. Only applies to accounts with an approval workflow configured. | ### Job workflow This diagram shows how a job can move between states. ```mermaid theme={null} stateDiagram-v2 received --> awaiting_approval received --> submitted received --> failed awaiting_approval --> submitted awaiting_approval --> approval_rejected submitted --> confirmed submitted --> failed confirmed --> completed confirmed --> failed ``` ### Polling a job Call [`GET /v1/borrow/jobs/{id}`](/api-reference/circle-mint/digital-asset-backed-borrowing/get-borrow-job) to fetch the current state of a job. Poll until `status` reaches a terminal state (`completed`, `failed`, or `approval_rejected`). To list all jobs for your entity, call [`GET /v1/borrow/jobs`](/api-reference/circle-mint/digital-asset-backed-borrowing/list-borrow-jobs). Filter by `status` or `jobType` to narrow the results. ## Loan states A loan represents one borrow position against one lending market. The `status` field on a loan reflects its current state. | State | What it means | | - | - | | `active` | The loan is open and accruing interest. You can add collateral, repay part or all of the debt, or monitor the position's health. | | `closed` | The loan is fully repaid. The cirBTC collateral has been released back to your Mint balance. | | `liquidated` | A third-party liquidator repaid your debt onchain and seized collateral because your position's health factor fell below the protocol's liquidation threshold. Circle detects the liquidation and updates the loan. | | `failed` | The borrow operation never completed successfully, so no debt was ever created. | ## LTV, health factor, and liquidation A borrow position's safety is measured by two ratios that Circle monitors continuously against onchain state. Loan-to-value ratio (LTV) is the ratio of your outstanding debt to the current value of your collateral, denominated in the borrowed asset. If you borrow 3,000 USDC against cirBTC worth 10,000 USDC (per the market oracle), your LTV is `0.30`. LTV rises as your debt accrues interest, as the oracle price of cirBTC falls, or both. Health factor is the inverse safety measure. It equals `LLTV / LTV`, where `LLTV` is the lending market's liquidation threshold. A health factor of `1.0` means the position is at the liquidation boundary. Above `1.0`, the position is safe. Below `1.0`, a third-party liquidator can repay part of the debt and seize collateral to bring the position back in line. The Morpho market's `LLTV` is the protocol's liquidation threshold. Circle enforces a stricter `maxOriginationLtv` at borrow creation. This is the highest LTV Circle allows for new borrows, set below `LLTV` to leave a safety buffer against short-term oracle price movement. Both values are returned on each market in [`GET /v1/borrow/markets`](/api-reference/circle-mint/digital-asset-backed-borrowing/list-borrow-markets). ### Margin call notifications Circle monitors your position's health factor and sends the account administrator an email when your LTV reaches 90% of the market's `LLTV`. Respond by: * [Adding collateral to the loan](/circle-mint/howtos/add-collateral) to lower your LTV * [Repaying part of the debt](/circle-mint/howtos/repay-loan) to reduce the outstanding balance ### Liquidations and residual sweeps Liquidations happen onchain and are executed by third-party liquidators (usually MEV bots watching the market). Circle detects the liquidation by polling the onchain position and updates the loan's status to `liquidated`. A full liquidation may leave residual cirBTC in the MSCA if the liquidator only needed part of the collateral to cover the debt. Circle detects the residual and automatically creates a `withdraw_residual` job to sweep it back to your Mint balance. You do not need to trigger the sweep yourself in the normal flow. The [`POST /v1/borrow/loans/{id}/residual-sweep`](/api-reference/circle-mint/digital-asset-backed-borrowing/create-borrow-loan-residual-sweep) endpoint exists as a manual retry for the rare case where the automatic sweep job fails. The `OnchainLoan` schema exposes liquidation-related fields for reference: * `liquidationDetectedAt`: when Circle first detected the liquidation onchain. * `liquidatedDebtAmount`: amount of debt the liquidator repaid. * `liquidatedCollateralSeized`: amount of cirBTC the liquidator seized. * `liquidationOraclePrice`: oracle price of cirBTC at liquidation. ### Oracle drift Circle uses the same onchain oracle the lending market uses to price collateral. Oracle prices move continuously, so a position that is safe at one moment can move closer to (or past) the liquidation boundary as the oracle updates. This is why `maxOriginationLtv` is stricter than `LLTV`, and why the margin call fires well before `1.00`. ## Currency codes and token symbols Responses use two different string representations for the same asset across different fields, and it's easy to confuse them. * Circle currency code: uppercase codes like `USD` or `CIRBTC`. Used in the `asset`, `borrowAsset`, and `collateralAsset` fields to identify an amount's underlying currency. The currency code is Mint's canonical identifier for the asset. * Token symbol: mixed-case symbols like `USDC` or `cirBTC`. Used as keys in the `depositAddresses` map on your wallet to identify which token an onchain address expects. For example, `borrowAsset: "USD"` on a loan means you borrowed USDC. The corresponding token symbol `USDC` appears as a key under `wallet.depositAddresses` if you need the onchain address that receives your borrowed USDC. # How minting and redemption works Source: https://developers.circle.com/circle-mint/concepts/how-minting-works Understand how Circle Mint converts fiat to USDC (minting) and USDC back to fiat (redemption), including settlement timing, account structure, and compliance requirements. Circle Mint's core operations are minting and redemption. Minting converts fiat currency into stablecoins (USDC or EURC), and redemption converts stablecoins back to fiat. Every token mints and redeems at a 1:1 ratio with the underlying fiat currency. This page explains the mental model behind these operations, including settlement timing, account structure, onchain transfers, fees, and compliance. ## Minting Minting (also known