Unified Wallet Addressing on EVM Chains

To provide a seamless wallet experience for your users across multiple EVM blockchains, you may want to offer wallets that maintain the same address on each chain. Unified addressing benefits your users in two key ways:

• It creates a unified experience across chains and reduces the number of wallet addresses users need to manage.
• It provides a recovery path if users accidentally deposit tokens to an address on an unsupported chain.

For User-Controlled Wallets, this happens automatically when you pass the user JWT token during wallet creation.

For Developer-Controlled Wallets, you need to implement the following capabilities:

• Create wallets across multiple EVM chains using a shared walletSetId and refId.
• Derive wallets and add them on-demand for supported chains that users opt into.
• Recover assets from unsupported EVM chains by signing and broadcasting transactions.
• Understand how address indexes work to maintain consistency.
• Follow best practices to manage wallet set limits effectively.

For chains you support by default, use the POST /wallets API to create wallets in batches.

Include the following in your request:

• walletSetId to group wallets that will share an address index.
• An array of blockchains representing the chains to support.
• An array of refIds to associate each wallet back to a user ID in your system.

When a wallet is created with a refId, all EVM wallets sharing that refId in that API call will have the same address. You can retrieve these wallets using the GET /wallets API.

For EVM chains that users can opt into, or in cases where assets are deposited to a chain not enabled by default, use the POST /wallets/{id}/blockchains/{blockchain} API to derive a wallet.

Provide the following in this request:

• Provide the existing walletId and refId for the user.
• Specify the new EVM chain to create the wallet on.

This will generate a wallet on the specified EVM chain with the same address as the existing wallet.

For EVM chains that Circle doesn't support yet:

• Create a wallet with blockchain: EVM.
• Use the Sign transaction API to move the assets out.

This gives you the flexibility to support recovery scenarios across any EVM-compatible chain.

Wallet addresses are derived based on the index in the walletSet. A single index (for example, 0x3) maps to the same address on all EVM chains.

• If you call POST /wallets for a single chain with no existing wallets, it starts at index 0x1 and increments.
• If you call POST /wallets across multiple chains, it uses the latest available index and assigns the same address across chains.
• If you call POST /wallets again for an individual chain, it increments only on that chain.
• If you call POST /wallets for a new chain (no existing wallets), it starts at 0x1.
• Use POST /wallets/{id}/blockchains/{blockchain} to derive wallets and fill address gaps across chains.

The example below illustrates how address indexes work across chains.

Walkthrough of the address derivation logic:

1. Step 1–2: Creating wallets on Ethereum only results in 0x1, then 0x2.
2. Step 3: Creating wallets on Ethereum + Polygon at once results in both getting 0x3.
3. Step 4: Creating a new wallet only on Polygon now returns 0x4.
4. Step 5–6: Creating wallets on Arbitrum (new chain) starts at 0x1, then 0x2.
5. Step 7: Creating wallets across Ethereum, Polygon, and Arbitrum takes the latest index and creates them at 0x5.

To fill gaps in the table, derive wallets using POST /wallets/{id}/blockchains/{blockchain}.

Using Circle's wallet APIs, you can create and manage wallets that share the same address across multiple EVM chains. This unified approach improves the user experience and enables safe asset recovery, even on unsupported chains. By leveraging walletSetId, refId, and the appropriate API endpoints, you can batch-create wallets, add support for new chains on demand, and maintain consistent wallet derivation logic across your application.