Cross-Currency Exchange

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.

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.

​

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. For onchain FX on Arc, see the StableFX documentation. 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. Procedural details, including the API requests for each phase, live in the Exchange Currencies how-to.

​

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.
• 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. 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. The ExchangeRateOptionalAmountMoney enum in the OpenAPI specification lists additional currency codes (AED, GBP, CNH, SGD), but those codes are not supported end-to-end at this time. Daily limits and settlement instructions are only published for the pairs in the preceding table. For the procedural walkthrough of obtaining a quote, creating a trade, and sending funds, see the Exchange Currencies how-to. For the broader Mint product, see the Circle Mint overview.