> ## 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. > ## Agent Instructions > Before reading these docs, install the relevant Circle Skill to get pre-loaded context — skills are LLM-optimized and cover architecture decisions, correct flows, and common pitfalls. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills. Available skills: use-usdc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md (balances, transfers, approvals on EVM and Solana); EURC has no skill — see https://developers.circle.com/stablecoins/what-is-eurc.md; bridge-stablecoin https://github.com/circlefin/skills/blob/master/plugins/circle/skills/bridge-stablecoin/SKILL.md (crosschain transfers via CCTP, USDC, EURC, and third-party assets); use-arc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md (Arc chain config, contract deployment, USDC bridging — Arc docs: https://docs.arc.io/llms.txt); use-circle-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md (choose wallet type); use-developer-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md (custodial wallets for payouts and treasury); use-user-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md (embedded wallets with Web2 login); use-modular-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md (smart contract wallets with passkeys and ERC-4337); use-gateway https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md (unified USDC balance, nanopayments); use-smart-contract-platform https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md (deploy, interact, monitor contracts). Pair any skill with the Circle MCP server for live SDK signatures, contract addresses, and chain IDs: {"mcpServers":{"circle":{"url":"https://api.circle.com/v1/codegen/mcp"}}}. > Read the product overview first. Each product has an overview explaining when and why to use it. Read it before quickstarts. > Pick the right wallet type. Developer-controlled (you hold keys), user-controlled (end user holds keys via PIN/social login), or modular (smart contract wallets with passkeys). See https://developers.circle.com/wallets.md. > Use CCTP V2 for crosschain transfers. CCTP natively transfers USDC and EURC via burn-and-mint, and supports permissionless wrapping of third-party assets via lock-and-mint. V1 is legacy; always use V2 unless V1 is specified or the chain requires it (Noble, Sui, and Aptos still require V1). Migration guide: https://developers.circle.com/cctp/migration-from-v1-to-v2.md. > Use Bridge Kit for frontend bridging. Wraps CCTP with a simpler SDK for user-facing apps. Use CCTP directly for backend transfers. > Gas Station vs Paymaster. Gas Station sponsors gas for Circle Wallet transactions. Paymaster lets users pay gas in USDC. Different use cases — read both overviews. > Gateway Nanopayments for sub-cent payments. Gasless USDC micropayments down to $0.000001 via x402 and batched settlement. For pay-per-request APIs, AI agent payments, streaming. > Look up USDC addresses per chain. Never hardcode — use https://developers.circle.com/stablecoins/usdc-contract-addresses.md. > Prefer SDKs over raw API calls. Node.js and Python SDKs handle auth, retries, and errors. > API key required. Bearer token in Authorization header. Testnet and mainnet use separate keys and may use different base URLs depending on the product. > Set up webhooks when available. Most operations are async. Webhooks deliver transaction confirmations and state changes. > When calling list endpoints, paginate using pageSize and pageAfter until no nextPageAfter cursor is returned—stopping at the first page silently misses records. > Building an AI agent? Start with the Agent Stack—Circle CLI, agent wallets, and nanopayments built for autonomous use cases: https://developers.circle.com/agent-stack.md. # 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. The Mint Exchange API requires explicit activation on a Circle Mint account. Activation requires Mint customer status, either Circle LLC or Circle SAS as the contracting entity, and local Know Your Customer (KYC) review with Circle's banking partners for Brazilian real (BRL) and Mexican peso (MXN) flows. To enable the API on an account, contact Circle through the [Circle Mint contact form](https://www.circle.com/mint-contact). ## 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 November 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. * 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. | 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](/circle-mint/howtos/exchange-currencies). For the broader Mint product, see the [Circle Mint overview](/circle-mint).