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

# Key management

> How Circle Wallets secures keys with MPC and passkeys across developer-controlled, user-controlled, and modular wallets.

Circle Wallets secures keys differently depending on the
[wallet product you choose](/wallets/account-types). Developer-controlled and
user-controlled wallets use
[multi-party computation (MPC)](#multi-party-computation-mpc). Modular wallets
use [passkeys](#passkeys).

## Custody models

Circle Wallets supports two custody models: direct custody and non-custodial. In
direct custody, you hold key material on your users' behalf. In non-custodial
arrangements, users control their own keys. Circle does not offer fully
custodial arrangements where it holds keys on behalf of users.

| Wallet type | Custody model | Key type | Who controls the key | Where keys live |
| - | - | - | - | - |
| **Developer-controlled** | Direct custody | MPC | You, using the entity secret | Circle-hosted MPC nodes, or self-hosted |
| **User-controlled** | Non-custodial | MPC | Your user, using their key shard credential | Circle-hosted MPC nodes |
| **Modular** | Non-custodial | Passkey | Your user | Your user's device (with optional cloud backup) |

## Multi-party computation (MPC)

MPC splits the private key into shards held by separate parties, so no single
party ever holds the complete key. This means a compromised server or stolen
credential alone cannot leak the full key.

### Developer-controlled wallets

Developer-controlled wallets use 2-of-2 MPC. You can let Circle host both nodes,
share hosting with Circle, or host both nodes yourself.

* **Circle hosts both nodes (default):** Signing is protected by an
  [entity secret](/wallets/dev-controlled/entity-secret-management#entity-secret-ciphertext)
  that you create and store on your server. The entity secret is required to
  create wallets and sign transactions. This option is ideal for getting started
  with minimum setup effort.

* **Shared node hosting:** You and Circle each host one MPC node. Circle
  provides a keyguard service that you host on your servers to authorize signing
  before every transaction. This splits private key management across two
  parties on different servers.

* **You host both nodes:** You host both MPC nodes with the keyguard service
  authorizing signing for every transaction. This setup may be required in
  certain regulatory jurisdictions and is available to enterprise customers.

The following diagram shows how signing is split across two servers in shared
node hosting.

```mermaid theme={null}
flowchart TB
  subgraph circle["Circle"]
    direction TB
    cw["Circle Wallets"]
    kms["Key management service (KMS)"]
    node1["Circle MPC node"]
    cw --> kms
    kms -->|"Circle's key share"| node1
  end

  subgraph you["You"]
    direction TB
    server["Your server"]
    verify["Your verification logic"]
    kg["Circle keyguard service"]
    node2["Your MPC node"]
    server -.->|"Transaction details"| verify
    kg -.->|"Transaction details"| verify
    verify -->|"Approval"| kg
    kg -->|"Your key share"| node2
  end

  server -->|"API request to create a transaction"| cw
  node1 <-->|"Message queue"| node2
```

**Backup and recovery:** Your entity secret is the only credential that can
authorize signing for all wallets in a wallet set. Losing it without a backup
means permanent loss of access to those wallets. For self-service rotation and
backup procedures, see
[Entity secret management](/wallets/dev-controlled/entity-secret-management).

<Tip>
  Circle offers a key backup and recovery tool.
  [Contact Circle](https://help.circle.com/s/submit-ticket?language=en_US) to
  learn more about this tool, or to set up shared or self-hosted node hosting.
</Tip>

### User-controlled wallets

Circle uses 2-of-2 MPC for user-controlled wallets and hosts both nodes. Only
your users can sign after they
[authenticate](/wallets/user-controlled/authentication-methods) with social
login, email + OTP, or PIN.

**Backup and recovery:** If your users forget their PIN, they can recover
account access by answering security questions. See
[Recover an account](/wallets/user-controlled/recover-account).

## Passkeys

Modular wallets use passkeys as signers. Passkeys live in the secure enclave (a
dedicated security chip on the user's device), so only your users can sign
transactions.

**Backup and recovery:** Your users can back up their passkeys using the FIDO2
backup standard supported by iCloud, Google Drive, and password managers like
1Password.