Note: For unsupported EVM chains, you are responsible for broadcasting the signed transaction to the chain yourself.
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:
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:
walletSetId
and
refId
.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.blockchains
representing the chains to support.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:
walletId
and refId
for the user.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:
blockchain: EVM
.Note: For unsupported EVM chains, you are responsible for broadcasting the signed transaction to the chain yourself.
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.
0x1
and increments.0x1
.POST /wallets/{id}/blockchains/{blockchain}
to derive wallets and fill address gaps across chains.The example below illustrates how address indexes work across chains.
EVM Chain | 0x1 | 0x2 | 0x3 | 0x4 | 0x5 |
---|---|---|---|---|---|
Ethereum | 1 | 2 | 3 | 7 | |
Polygon | 3 | 4 | 7 | ||
Arbitrum | 5 | 6 | 7 |
Walkthrough of the address derivation logic:
0x1
, then 0x2
.0x3
.0x4
.0x1
, then
0x2
.0x5
.To fill gaps in the table, derive wallets using
POST /wallets/{id}/blockchains/{blockchain}
.
Do not assign a unique walletSetId
per user.
You're limited to 1,000 wallet sets total, with up to 10 million wallets
per wallet set. See the
Wallet Sets guide.
Smart Contract Account (SCA) support is also available.
You can derive SCAs across chains just like EOAs. However, if ownership of the
SCA is transferred outside of Circle's infrastructure, same-address derivation
is not possible.
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.