> ## 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.

# How xReserve works

xReserve consists of two main services: an onchain smart contract and an
offchain attestation system. Together, these services and related services on
the remote blockchain let users deposit USDC on the source blockchain to receive
USDC-backed stablecoins on the remote blockchain. Subsequently, users can burn
their USDC-backed stablecoins to withdraw the USDC held in xReserve.

The following diagram shows how xReserve handles deposits and withdrawals.

```mermaid theme={null}
sequenceDiagram
    participant U as User app
    participant X as xReserve smart contract
    participant RL as xReserve attestation service
    participant PB as Remote blockchain token contract
    participant PA as Remote blockchain attestation service

    Note over U,PA: Deposit USDC into xReserve and mint USDC-backed stablecoins
    U->>X: Initiates deposit request
    X->>RL: Emits deposit event
    RL-->>RL: Generates signed deposit attestation
    PA->>RL: Fetches deposit attestation
    RL->>PA: Returns deposit attestation
    PA->>PB: Requests to mint USDC-backed stablecoins
    PB-->>PB: Verifies signature and mints USDC-backed stablecoins
    PB->>PA: Emits mint event
    PB->>U: Deposits USDC-backed stablecoins

    Note over U,PA: Withdraw USDC from xReserve and burn USDC-backed stablecoins
    U->>PB: Initiates withdrawal request
    PB-->>PB: Verifies signature and burns USDC-backed stablecoins
    PB->>PA: Emits burn event
    PA-->>PA: Generates and signs burn intent
    PA->>RL: Submits burn intent and signature
    RL-->>RL: Verifies burn and generates withdrawal attestation
    RL->>X: Releases USDC
    X->>U: Releases USDC
```

## xReserve deposits

These steps occur when a user deposits USDC into xReserve:

1. A user deposits USDC from their wallet app into xReserve smart contract on
   the source blockchain.
2. The xReserve contract emits a deposit event and locks the funds, holding them
   in reserve.
3. The xReserve attestation service generates and signs a deposit attestation.
4. The remote blockchain attestation service fetches the signed deposit
   attestation.
5. The remote blockchain mints USDC-backed stablecoins on their blockchain and
   emits a mint event.
6. The remote blockchain token contract deposits the newly minted USDC-backed
   tokens into the user's wallet app on the remote blockchain.

After completing the deposit process, the user receives an equivalent amount of
USDC-backed stablecoins on the remote blockchain.

## xReserve withdrawals

Subsequently, these steps occur when a user withdraws USDC from xReserve:

1. A user requests to burn USDC-backed stablecoins on the remote blockchain and
   withdraw USDC on the destination blockchain.
2. The remote blockchain token contract burns their USDC-backed stablecoins on
   the remote blockchain and emits a burn event.
3. The remote blockchain attestation service generates and signs a burn intent
   offchain.
4. The remote blockchain attestation service passes the burn intent and
   signature to xReserve.
5. xReserve verifies the burn and issues a withdrawal attestation.
6. xReserve releases USDC to the user's wallet on the destination blockchain.

After completing the withdrawal process, the user receives USDC on the source
blockchain.

<Note>
  As part of the same withdrawal, xReserve can
  [forward funds](/xreserve/concepts/technical-guide#withdrawal-forwarding) to
  another blockchain. This lets users withdraw funds on a blockchain other than
  the source blockchain without performing an additional crosschain transfer.

  When the destination is an xReserve source blockchain (Ethereum or Arc), USDC is
  released directly from the xReserve contract on that blockchain, with no
  crosschain forwarding.
</Note>