Circle USYC 백서 전문

ields) table | | `auction_opened` | A new auction cycle starts | `auctionId`, `lockAt` (ISO 8601), `clearAt` (ISO 8601), `auctionIntervalNs` (integer, nanoseconds) | | `auction_locked` | Lock window opens | `auctionId`, `phase: "locked"` | | `auction_cleared` | Auction clears | `auctionId`, `clearingFeeBps` (string or null if no match), `matchedSizeCents` (integer cents) | | `indicative_updated` | Periodically during the open phase | `indicativeFeeBps` (string or null), `matchableSizeCents` (integer cents), `netImbalanceCents` (integer cents) | ### Market channel fields The following fields are present on the `snapshot` event and on most market events. For background on auction phases and clearing, see [How Match works](/circle-match/concepts/how-it-works). | Field | Type | Description | | - | - | - | | `phase` | string | Current auction phase: `"open"`, `"locked"`, or `"settling"` | | `indicativeFeeBps` | string or null | Indicative clearing fee in basis points; null if no indicative match exists | | `matchableSizeCents` | integer | Volume (in cents) that would match at the indicative fee | | `netImbalanceCents` | integer | Net imbalance in cents; negative values indicate burn side exceeds mint side | | `mintTotalCents` | integer | Total mint-side volume in cents | | `burnTotalCents` | integer | Total burn-side volume in cents | | `lockAt` | string | ISO 8601 timestamp when the lock window opens | | `clearAt` | string | ISO 8601 timestamp when the auction clears | | `lastClearResult` | object or null | Result from the last cleared auction; null if no prior auction has cleared | #### `lastClearResult` fields | Field | Type | Description | | - | - | - | | `auctionId` | integer | Identifier for the last cleared auction | | `clearingFeeBps` | string or null | Clearing fee in basis points; null if no orders matched | | `matchedSizeCents` | integer | Total matched volume in cents | ## Account channel The account channel is private and scoped to the authenticated entity. It requires a valid ticket. **Subscribe:** ```json theme={null} { "type": "subscribe", "channel": "account" } ``` ### Account channel events | Event type | When sent | Key fields | | - | - | - | | `account_snapshot` | On subscribe | Current open orders, available balance, reserved balance, total balance | | `order_received` | A new order is accepted | `orderId` (UUID), `status: "pending"`, `orderType`, `amount` (integer cents), `feeBps` (string or null), `postFillAction` | | `order_modified` | An order's fee is modified | `orderId`, `feeBps` (string or null) | | `order_canceled` | A single order is cancelled | `orderId`, `status: "cancelled"` | | `order_canceled_all` | A cancel-all request completes | `orderIds` (array of UUIDs), `auctionId` | | `account_cleared` | An auction clears with activity for this account | `fills` (array), `forwardOrders` (array), `feesRebatedCents` (signed integer) | ### `account_cleared` fields | Field | Type | Description | | - | - | - | | `fills` | array | One fill object per matched order. Each fill contains: `orderId`, `filledAmountCents`, `unfilledAmountCents`, `clearingFeeBps`, `matchedAt` | | `forwardOrders` | array | Orders rolled into the next auction, resulting from a `roll` post-fill action | | `feesRebatedCents` | signed integer | Net rebate or fee for the auction. Positive: net rebate received (mint side). Negative: net fee paid (burn side). Zero: no fills. | ## Reconnection Tickets are single-use and cannot be reused after the connection opens. When a connection drops: 1. Obtain a new ticket using `POST /v1/match/ws/ticket`. 2. Open a new WebSocket connection with the new ticket. 3. Re-send your `subscribe` messages. The server delivers a fresh snapshot on re-subscribe. Events that occurred during the disconnection are not replayed. If the auction cleared while you were disconnected, the `account_cleared` event for that auction is not delivered. Use `GET /v1/match/orders` to reconcile any fills you may have missed. # Circle Mint Source: https://developers.circle.com/circle-mint Mint and redeem USDC, EURC, and cirBTC directly from Circle. <Note> Circle Mint is for institutional customers minting USDC, EURC, or cirBTC. It is typically used by exchanges, institutional traders, wallet providers, banks, and consumer-app companies. [Contact Circle](https://www.circle.com/mint-contact) to learn more. </Note> Circle Mint lets you mint and redeem [USDC](/stablecoins/what-is-usdc), EURC, and [cirBTC](/assets/what-is-cirbtc) directly from Circle. USDC and EURC redeem 1:1 for their backing fiat currency: U.S. dollars for USDC, euros for EURC. cirBTC redeems 1:1 for native BTC held at a regulated entity in the Circle group. Manage your account through the [Mint Console](https://app.circle.com/) or the Circle Mint API. Deposit fiat from a linked bank account, convert it to USDC or EURC, and send stablecoins to blockchain wallets globally. To start integrating, [set up your account and API key](/circle-mint/quickstarts/getting-started). ## What you can do <CardGroup> <Card title="Mint and redeem stablecoins" icon="coins" href="/circle-mint/quickstarts/mint-and-redeem"> Convert fiat to USDC or EURC and redeem stablecoins back to fiat through your Circle Mint account. </Card> <Card title="Mint and redeem cirBTC" icon="bitcoin" href="/circle-mint/quickstarts/mint-and-redeem-cirbtc"> Deposit BTC to mint cirBTC, transfer it onchain, and redeem it back to BTC through your Circle Mint account. </Card> <Card title="Transfer onchain" icon="arrow-right-arrow-left" href="/circle-mint/howtos/transfer-on-chain"> Send and receive USDC and EURC on supported blockchains. </Card> <Card title="Accept stablecoin payments" icon="money-bill-wave" href="/cpn/stablecoin-payments/howtos/receive-stablecoin-payin"> Use Circle's Payment APIs to accept USDC deposits from your customers. </Card> <Card title="Exchange currencies" icon="rotate" href="/circle-mint/howtos/exchange-currencies"> Convert between local currencies and USDC using cross-currency APIs. </Card> </CardGroup> # Credit API Source: https://developers.circle.com/circle-mint/concepts/credit-api Understand how the Credit API exposes Circle Mint's Settlement Advance and Line of Credit products, the credit-line model, and the lifecycle of credit transfers and repayments. The Credit API is the borrower-facing programmatic interface to Circle Mint's two credit facilities: Settlement Advance and Line of Credit. It exposes endpoints under `/v1/credit/` that you use to inspect your credit line, initiate draws, follow disbursement, and process repayments in fiat or crypto. For step-by-step procedural walkthroughs, see the [Settlement Advance quickstart](/circle-mint/quickstarts/settlement-advance) and the [Line of Credit quickstart](/circle-mint/quickstarts/line-of-credit). <Note> The Credit API requires three things before activation: an executed Core API Agreement, a separate offline credit contract with Circle, and the Credit API entitlement enabled on your account. To start the process, [contact Circle](https://www.circle.com/mint-contact) to discuss credit products and request that the Credit API entitlement be enabled. </Note> ## Two products: Settlement Advance and Line of Credit The Credit API surfaces two distinct products. A given customer holds one credit line for one product; the product determines how draws are requested, how fees accrue, and which repayment paths are available. | | Settlement Advance | Line of Credit | | - | - | - | | Target use case | Covers settlement-timing gaps for customers on slow fiat rails, such as OTC desks, capital markets firms, and payment companies. You prefund a settlement and request the advance against it. | Provides fast, automated drawdowns for ongoing liquidity needs. Suited to customers who want programmatic access to working capital without per-draw manual review. | | Draw mechanics | Reserve-then-request flow: you reserve funds, wire USD to Circle, upload the wire proof, and Circle's Treasury team approves the disbursement. | Auto-approved single request: a `POST /v1/credit/transfers` call moves the transfer through `requested` and into `disbursed` without manual review. | | Repayment paths | Fiat only. You wire USD to a Circle-issued repayment account. | Fiat (wire) or crypto. Crypto repayments deduct USDC from your Circle Mint wallet. | | `feeCadence` options | `daily` only. Recurring fees accrue every 24 hours and repayment is due 7 days after disbursement. | `daily` or `hourly`. Hourly cadence accrues fees every hour with a 24-hour repayment window, sized for capital-markets workflows that need same-day repayment turns. | ## The credit-line model Your credit line is the facility object the Credit API revolves around. Every draw, fee, and repayment is recorded against it. `GET /v1/credit` returns the current state of the line. The subsections below explain the parts of that model you should be most familiar with. ### One credit line per customer, scoped to a product A Circle Mint customer has at most one credit line, and the line is scoped to a single `product`: either `settlementAdvance` or `lineOfCredit`. The settlement currency is USD. If your business needs both products, that requires a separate contractual conversation with Circle, not a second credit line on the same account. ### Fee rates The credit line's `feeRates` object captures the two rates that can apply to a draw: * `drawFee`: A one-time fee assessed at disbursement. Only Settlement Advance uses `drawFee`; Line of Credit does not charge a per-draw fee. * `recurringFee`: A fee that accrues against the outstanding balance at the cadence defined by `feeCadence`. Both products use `recurringFee`. Both rates are decimal multipliers applied to the transfer amount. For example, a `recurringFee` of `0.001` represents a 0.1% rate. Fees accrue automatically and are deducted from your Circle Mint wallet balance. ### Fee cadence and repayment timing `feeCadence` controls how often `recurringFee` accrues and how soon a disbursed transfer must be repaid: * `daily`: Fees accrue every 24 hours. Each disbursed transfer is due 7 days after disbursement. * `hourly`: Fees accrue every hour. Each disbursed transfer is due 24 hours after disbursement. Hourly cadence is available on Line of Credit only and is designed for trading and capital-markets workflows that recycle capital intraday. ### Minimum balance The credit line carries a `minBalance` requirement: the USDC balance you must keep in your Circle Mint wallet while the credit line is active. The minimum balance is an operating constraint that supports fee deduction and crypto repayment for Line of Credit customers; falling below it surfaces as a validation error that blocks new draws. ### Validation errors `validationErrors` is a list of blocking conditions on new transfer creation. When it is non-empty, the credit line cannot originate new transfers and the relevant create-transfer endpoints return HTTP 400 until the conditions clear. Three codes can appear: * `INSUFFICIENT_BALANCE`: The Circle Mint wallet's USDC balance is below `minBalance`. * `PENDING_FEES`: Accrued fees are still pending settlement against the wallet. * `OVERDUE_TRANSFERS`: At least one disbursed transfer has passed its due date without being fully repaid. Treat `validationErrors` as constraints to check before initiating a draw. The quickstarts cover how to resolve each condition operationally. ## Credit transfer lifecycle A credit transfer is one draw against your credit line. The two products follow different lifecycles because Settlement Advance involves a reserve-then-request handshake with manual Treasury approval, while Line of Credit auto-approves on request. ### Settlement Advance lifecycle A Settlement Advance transfer starts when you reserve funds and ends when the disbursed amount is fully repaid. The reservation step exists so you can lock in capacity against your line while you initiate the supporting wire. ```mermaid theme={null} stateDiagram-v2 [*] --> funds_reserved funds_reserved --> requested funds_reserved --> expired funds_reserved --> canceled requested --> disbursed requested --> rejected disbursed --> paid disbursed --> past_due ``` * `funds_reserved`: Capacity is reserved against your credit line. The reservation expires after 30 minutes if it is not progressed to `requested`, and only one transfer at a time may be in this state per credit line. * `requested`: You have submitted wire proof for the reserved transfer and Circle's Treasury team is reviewing the request. * `disbursed`: Treasury has approved the advance and the funds have landed in your Mint wallet (or, with Credit Express, at the verified blockchain destination). * `paid`: The disbursed amount has been fully repaid. * `expired`: The reservation timed out before it was progressed to `requested`. * `canceled`: You canceled the reservation before submitting wire proof. * `rejected`: Treasury declined the request. * `past_due`: The disbursed amount has not been fully repaid by its due date. ### Line of Credit lifecycle A Line of Credit transfer skips the reservation step. A single create request moves the transfer to `requested` and Circle auto-disburses it. ```mermaid theme={null} stateDiagram-v2 [*] --> requested requested --> disbursed requested --> rejected disbursed --> paid disbursed --> past_due ``` * `requested`: The draw has been created and is being processed for disbursement. * `disbursed`: Funds have landed in your Mint wallet (or at the verified blockchain destination when Credit Express is configured). * `paid`: The disbursed amount has been fully repaid. * `rejected`: Circle declined the request. * `past_due`: The disbursed amount has not been fully repaid by its due date. ## Credit Express Credit Express is an optional destination configuration for a credit transfer. Instead of disbursing into your Circle Mint wallet, Circle sends the USDC directly onchain to a verified address from your Circle Mint recipient address book. Credit Express is available on both Settlement Advance and Line of Credit. The feature requires that the destination address is already registered and verified through the recipient address book; you cannot register a new address as part of a draw. When a transfer is configured with a Credit Express destination, the disbursement carries an additional onchain delivery status that progresses through `pending`, `initiated`, `complete`, and `failed`. That status is separate from the credit transfer's own status—the transfer reflects the credit relationship between you and Circle, while the destination status reflects the onchain leg of the disbursement. ## Repayment Repayments retire outstanding balances on disbursed transfers. The Credit API supports two repayment paths; product choice determines which paths are available. ### Fiat repayment Fiat repayment is available for both Settlement Advance and Line of Credit. You wire USD to a Circle-issued repayment account; Circle matches the incoming wire to your credit line and applies it against outstanding transfers. The repayment account is initially `unverified` and stays in that state until the first incoming wire is matched to it, at which point it transitions to `active`. The account's wire instructions remain stable across that transition. Each fiat repayment record exposes `repaymentAccountId`, the identifier of the fiat account the repayment was applied to. Pass it to `GET /v1/credit/repaymentAccounts/{fiatAccountId}` to retrieve the account's bank details and wire instructions. The field is present for fiat repayments with a linked account and omitted for crypto repayments. ### Crypto repayment Crypto repayment is available for Line of Credit only. Circle deducts USDC from your Circle Mint wallet and applies it to outstanding transfers. The repayment amount is capped at the current outstanding balance—you cannot prepay beyond what is owed. Settlement Advance does not support crypto repayment; calls to the crypto repayment endpoint against a Settlement Advance credit line return HTTP 400. ## Account attribution Credit transfer, fee, and crypto repayment records each expose `accountId`, the identifier of the Circle account the funds moved through. This is distinct from `repaymentAccountId`, which identifies the fiat bank account used for a fiat repayment. ## Webhook topics The Credit API publishes three webhook topics so your server can follow credit activity asynchronously rather than polling. Subscribe to whichever topics match the events you need to react to. Payloads mirror the corresponding `GET` endpoints, so a notification carries the same shape your code already handles when fetching a single resource. * `creditTransfers`: Fires when a credit transfer changes status—for example, when a Settlement Advance request is approved and moves to `disbursed`, or when a transfer becomes `past_due`. * `creditFees`: Fires when a fee accrues against the credit line. Cadence matches `feeCadence`, so daily lines emit fee notifications every 24 hours while hourly Line of Credit lines emit them every hour. * `creditRepayments`: Fires when Circle matches an incoming wire repayment or records a completed crypto repayment. The payload includes `repaymentAccountId` for fiat repayments, so you can reconcile the repayment to its bank account without an extra lookup. # Cross-currency exchange Source: https://developers.circle.com/circle-mint/concepts/cross-currency-exchange Understand how the Mint Exchange API exchanges local fiat for USDC and swaps between USDC and EURC through banking partners, the quote-trade-settle model, and delivery-versus-payment settlement. Cross-Currency Exchange is Circle Mint's offchain facility for exchanging local fiat currency into USDC and for swapping between USDC and EURC. The product, exposed through the Mint Exchange API at `/v1/exchange/*`, has been live since 2024 and runs against Circle's regulated banking partners in each supported market. A trade moves through a quote, then a trade record, then a settlement, with funds delivered on a delivery-versus-payment (DvP) basis. This page covers the conceptual model behind the Mint Exchange API, including how it differs from Circle's onchain StableFX product, the lifecycle of a trade, and the scope of supported currency pairs. <Note> The Mint Exchange API requires explicit activation on a Circle Mint account. Activation requires Mint customer status, a signed Cross-Currency MSA with Circle, and a supported contracting entity: Circle LLC, Circle SAS, or Circle SG. Circle SG accounts are eligible only for the Singapore dollar (SGD) corridor. Brazilian real (BRL) and Mexican peso (MXN) flows also require local Know Your Customer (KYC) review with Circle's banking partners. To enable the API on an account, contact Circle through the [Circle Mint contact form](https://www.circle.com/mint-contact). </Note> ## How this product compares to StableFX Two Circle products share the `/v1/exchange/` URL prefix and the "FX" tag, but they are different services with different settlement layers, counterparties, and audiences. The Mint Exchange API is the subject of this page. StableFX is a newer onchain request-for-quote (RFQ) network on Arc. The following table contrasts them. | | Mint Exchange (Cross-Currency) | StableFX | | - | - | - | | Settlement layer | Offchain delivery-versus-payment through Circle's banking partners and Mint balance. | Onchain payment-versus-payment through a smart-contract escrow on Arc. | | Counterparties | Circle and the Mint customer, with a regulated banking partner per local market. | A network of makers and takers on an institutional RFQ venue. | | URL prefix | `/v1/exchange/*` | `/v1/exchange/stablefx/*` | | Launch status | Live since 2024. | Live on testnet since Nov