> ## 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 the entity secret works > Learn how the entity secret secures developer-controlled wallets and how it is used in API requests. Developer-controlled wallets depend on a single developer-held cryptographic key: the entity secret. Because Circle never stores it, you retain exclusive control over your wallets and bear sole responsibility for its security. ## The entity secret and ciphertext These two terms are distinct but inseparable: the entity secret is the key itself, and the ciphertext is the encrypted form you send in API requests. ### Entity secret The entity secret is a randomly generated 32-byte private key that authorizes sensitive wallet operations under your Circle account. **What to know:** * Scoped to your Circle account, not to individual API keys. API keys authenticate requests; the entity secret authorizes the wallet operations those requests perform. * Circle never stores a copy. Only you can authorize operations on your developer-controlled wallets. * Losing it without a recovery file means permanent loss of access to your wallets and funds. ### Entity secret ciphertext The entity secret ciphertext is the encrypted form of the entity secret, passed as `entitySecretCiphertext` in API request bodies. **What to know:** * Produced by encrypting the entity secret with Circle's public RSA key before each request. Circle decrypts it server-side to verify authenticity and authorize the operation. For the encryption implementation, see the [entity secret sample code](https://github.com/circlefin/w3s-entity-secret-sample-code) on GitHub. * Each ciphertext is single-use. Reusing one causes the request to be rejected, which prevents replay attacks. * When you use the [Circle Node.js SDK](/sdks/developer-controlled-wallets-nodejs-sdk) or [Python SDK](/sdks/developer-controlled-wallets-python-sdk), re-encryption happens automatically before every call. If you make direct API calls without an SDK, you are responsible for re-encrypting for each request. ## Wallet set A wallet set is a hierarchical deterministic (HD) wallet. Every wallet in the set is derived from the same cryptographic root, the entity secret. **What to know:** * One entity secret backs every wallet set in your Circle account. Each wallet set backs the wallets you create inside it. * You can create up to 1,000 wallet sets per account, with up to 10 million wallets in each set. For most use cases, one wallet set is enough. * Multiple wallet sets are useful for scaling (for example, one set per tenant or product line), but they aren't a security boundary. The same entity secret authorizes operations on every set. * On EVM blockchains, wallets in the same set can share the same address across blockchains. See [Unified wallet addressing on EVM blockchains](/wallets/unified-wallet-addressing-evm) for how to create and derive wallets that share an address. ## The recovery file When you register your entity secret, Circle generates a recovery file tied to that secret. The recovery file is the only mechanism for resetting your entity secret through [Circle Console](https://console.circle.com/) if it is ever lost. **What to know:** * Without the recovery file, there is no path to recover access to your developer-controlled wallets or the funds they hold. * The recovery file itself is the credential. There is no separate password or passphrase protecting it. * A recovery file covers every wallet backed by its entity secret, including wallets you create after the file was issued. * A successful entity secret rotation or reset invalidates the current recovery file and issues a new one. ## Best practices * **Store the entity secret securely.** Use a secrets manager, hardware security module (HSM), or encrypted password manager. Never commit the entity secret to version control, include it in application configuration files, or allow it to appear in logs. * **Save the recovery file immediately after registration.** The recovery file can only be downloaded once, during the registration flow. If you skip this step, you must rotate your entity secret to generate a new one. Store it in a separate, secure location from the entity secret itself. * **Rotate periodically.** Rotating the entity secret limits exposure if it is ever silently compromised. Rotate on a regular schedule, such as every 180 days. Rotation takes effect immediately. Any in-flight API requests using the old entity secret will fail. Plan rotations during low-traffic periods and reinitialize pending requests afterward. Rotate in [Circle Console](https://console.circle.com/). * **Reset if compromised or lost.** If your entity secret is lost or you suspect it has been compromised, use your recovery file to reset it in [Circle Console](https://console.circle.com/). After a reset, the old entity secret is invalidated immediately and a new recovery file is generated. * **Overwrite your stored recovery file after any rotation or reset.** Circle issues a new recovery file each time, and your old one becomes invalid. * **Group wallets into shared wallet sets, not one per user.** Wallet sets are organizational boundaries for scaling (for example, one set per tenant or product line), not per-user containers. Creating one wallet set per user will exhaust the 1,000-set account limit. Group users into shared sets and identify each user with a `refId` on the wallet. If both the entity secret and the recovery file are lost, you cannot create new developer-controlled wallets or initiate transactions from existing wallets. There is no recovery path. Store both in separate, secure locations.