> ## 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. # xReserve technical guide This guide provides a detailed reference for partner blockchains and developers integrating with xReserve. It defines key terms, onchain message formats, and the attestation flow used to move tokens across blockchains. ## Domains Domains are Circle-issued numeric identifiers that map to specific blockchains. They are used in xReserve messages and attestations. * **Source domains** use small, 0-indexed integers. They represent blockchains where the [USDC reserves](#usdc-reserve) are held in xReserve contracts for USDC-backed stablecoins. * **Remote domains** start at 10001 and represent blockchains where USDC-backed stablecoins are issued and circulated. ## Blockchain types ### Source chain The source chain is the blockchain where the xReserve contract exists and USDC is deposited and held in reserve. ### Remote chain The remote chain is the xReserve partner blockchain that issues and circulates USDC-backed stablecoins on their blockchain after an xReserve deposit is made. ### Destination chain After a remote chain burns USDC-backed stablecoins on its blockchain, xReserve releases the associated USDC on the source chain. The blockchain where the user ultimately withdraws these funds is the destination chain. There are three ways a user can withdraw these funds: * **Withdraw USDC on a Gateway supported blockchain**: xReserve holds funds in a [Circle Gateway](/gateway) wallet. This lets users convert USDC-backed stablecoin into USDC on any [Gateway supported blockchain](/gateway/references/supported-blockchains), including the source chain, without needing to perform an additional crosschain transfer. * **Withdraw USDC on a CCTP-supported blockchain**: If a user requests to withdraw USDC on a non-Gateway supported blockchain, xReserve uses Circle's [Cross-Chain Transfer Protocol](/cctp) to forward the funds to a [CCTP supported blockchain](/cctp/cctp-supported-blockchains). When preparing a [burn intent](#burn-intent), this blockchain is the `finalDestinationDomain`. * **Withdraw USDC-backed stablecoins on another remote blockchain**: Redeposits let users move USDC-backed stablecoins from one blockchain to another. xReserve releases the USDC reserve for the remote blockchain and redeposits it for the destination blockchain. When preparing a burn intent, this blockchain is the `finalDestinationDomain`. xReserve updates its onchain and offchain ledgers to reflect the change in reserve on the remote and destination blockchains. ## Contracts ### xReserve contract Circle deploys and audits the xReserve contract on source blockchains such as Ethereum and Arc. It holds USDC deposited by users in reserve when USDC-backed stablecoin is minted on a remote chain, and releases USDC when the corresponding token is burned and withdrawn. The full EVM-compatible smart contract source code is [available on GitHub](https://github.com/circlefin/evm-xreserve-contracts). ### Remote blockchain token contract The remote blockchain is responsible for deploying, operating, and securing the smart contract that manages its USDC-backed stablecoins. This contract mints and burns the token and manages token logic. It also defines the infrastructure and security for how tokens are handled on its blockchain. ## Tokens ### USDC [USDC](/stablecoins/what-is-usdc) is issued by Circle on supported blockchains such as Ethereum. It is fully redeemable for fiat with Circle and serves as the official, native representation of the USDC stablecoin. ### USDC reserve USDC reserve represents the USDC held in the xReserve smart contract on the source chain. xReserve uses [Circle Gateway](/gateway) wallets to hold these balances for USDC-backed stablecoins on the [remote chain](#remote-chains). ### USDC-backed stablecoins USDC-backed stablecoins are issued on remote blockchains. These tokens are backed 1:1 by USDC held in xReserve and interoperable with the broader USDC network. Each remote blockchain defines its own USDC-backed stablecoins. ## Attesters An attester is a cryptographic identity represented by a single `secp256k1` keypair. xReserve and remote blockchains operate independent attesters, creating a dual-attestation model that ensures both sides must validate before any funds move. These attesters have distinct responsibilities: * **xReserve attesters** are operated by Circle. They monitor USDC deposits into the xReserve smart contract on the source blockchain and sign deposit attestations. Remote blockchains use these attestations to mint USDC-backed tokens on their blockchain. * **Remote blockchain attesters** are managed by the remote blockchain operator. They monitor burns of USDC-backed stablecoins on their blockchain and sign burn intents. xReserve verifies these burn intents and uses them to release the USDC held in the xReserve contract. ## Deposits ### Deposit intent `DepositIntent` is a structured onchain message created when a user deposits USDC into the xReserve smart contract on the source blockchain. The following table shows the message format: | Field | Offset (bytes) | Solidity Type | Length (bytes) | Description | | - | - | - | - | - | | `magic` | 0 | `uint32*` | 4 | 4-byte constant (`0x5a2e0acd`, subject to change) | | `version` | 4 | `uint32` | 4 | Always `1` | | `amount` | 8 | `uint256` | 32 | Token amount to deposit | | `remoteDomain` | 40 | `uint32` | 4 | Destination domain ID | | `remoteToken` | 44 | `bytes32` | 32 | Token address or identifier on the destination chain | | `remoteRecipient` | 76 | `bytes32` | 32 | Recipient address or identifier on the destination chain | | `localToken` | 108 | `address` | 32 | Source chain token address (left-padded to 32 bytes) | | `localDepositor` | 140 | `address` | 32 | Source chain depositor address (left-padded to 32 bytes) | | `maxFee` | 172 | `uint256` | 32 | Maximum fee amount to pay on the destination chain | | `nonce` | 204 | `bytes32` | 32 | 32-byte replay protection nonce | | `hookDataLen` | 236 | `uint32` | 4 | Length of `hookData` in bytes | | `hookData` | 240 | `bytes` | n | Optional hook payload | For how a USDC-backed stablecoin contract on the remote blockchain should handle this message, see the [USDC-backed Stablecoin Specification](/xreserve/concepts/usdc-backed-stablecoin-specification). ### Deposit attestation A deposit attestation is an offchain message signed by [xReserve attesters](#attesters). It can be used by remote blockchains to independently mint corresponding USDC-backed stablecoins. xReserve constructs a deposit attestation in response to receiving a deposit intent. ## Withdrawals Withdrawals let users redeem USDC-backed stablecoins for USDC held in xReserve. Users can also withdraw USDC-backed stablecoins on another remote blockchain. All withdrawals are initiated on the remote blockchain. **Note**: If you're a remote blockchain partner, you can [initiate a withdrawal on behalf of your users](/xreserve/tutorials/initiate-a-withdrawal-as-a-remote-blockchain). ### Burn intent A `BurnIntent` is a structured message that the remote blockchain creates when a user requests to burn USDC-backed stablecoins on their blockchain. It includes the amount of USDC-backed stablecoins burned and the source blockchain on which the USDC held in xReserve is released. For how a USDC-backed stablecoin contract on the remote blockchain should process the burn data, see the [USDC-backed Stablecoin Specification](/xreserve/concepts/usdc-backed-stablecoin-specification#burn). ### Message hash and burn intent signature The message hash is a 32-byte hash of the burn intent payload. It is derived from the transfer specification, fee settings, and forwarding data. The [`/prepare-withdrawal`](/api-reference/xreserve/all/prepare-withdrawal) endpoint returns a `messageHashToSign` for each burn intent. [Remote blockchain attesters](#attesters) sign that hash with their attester keys, producing the burn intent signature. This signature proves the burn intent is valid. xReserve validates the burn intent and signature before releasing the corresponding [USDC reserve](#usdc-reserve). ### Withdrawal attestation xReserve issues a withdrawal attestation after validating a burn intent signature and independently validating that the burn occurred on the remote blockchain. This attestation is used to release the USDC held in the xReserve smart contract. ### Withdrawal forwarding xReserve lets users withdraw funds on a blockchain other than the source chain without performing an additional crosschain transfer. Because xReserve holds funds in a [Circle Gateway](/gateway) wallet, users can immediately withdraw USDC on any [Gateway supported blockchain](/gateway/references/supported-blockchains). If the [destination chain](#destination-chain) is not supported by Gateway, xReserve can forward the funds in one of two ways: * **CCTP forwarding**: xReserve forwards funds to a [CCTP supported blockchain](/cctp/cctp-supported-blockchains), which lets users withdraw USDC on that blockchain. * **Redeposits** : xReserve redeposits funds, which lets users withdraw USDC-backed stablecoins on another remote blockchain. ## Security audit The xReserve smart contract has been independently audited by two third-party security firms: * [OtterSec (PDF)](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/Public%20Security%20Audit%20Reports/%5BPUBLIC%5D%20%5BOTTERSEC%5D%20circle_xreserve_audit_final.pdf) * [ChainSecurity (PDF)](https://6778953.fs1.hubspotusercontent-na1.net/hubfs/6778953/Public%20Security%20Audit%20Reports/%5BPUBLIC%5D%20%5BCHAINSECURITY%5D%20ChainSecurity_Circle_CircleXReserve_Audit.pdf)