How to Create Custodial Wallets on Ethereum

Creating custodial wallets for your users on the Ethereum blockchain can significantly streamline their Web3 onboarding experience. By allowing users to access blockchain features through familiar identifiers like an email address or a user ID, you remove the traditional complexities of private key management. This guide provides a clear, step-by-step approach to setting this up efficiently.

Understanding Custodial Wallets

A custodial wallet is a type of cryptocurrency wallet where a third party—in this case, you, the service provider—holds and manages the user’s private keys. This setup offers a familiar and user-friendly experience, as it abstracts away the technical hurdles of seed phrases and self-custody. Users can interact with Ethereum-based applications without needing deep blockchain knowledge, making it ideal for mainstream adoption.

The primary benefit is a seamless onboarding flow. Instead of asking users to install a separate browser extension or create a new wallet, they can simply use their existing email to get started. This is particularly powerful for applications aiming to integrate Web3 features invisibly into a traditional web or mobile interface.

Initial Setup and Requirements

Before you can create wallets, you need access to the necessary development tools. The process involves interacting with a service’s API, which handles the secure generation and custody of the wallet keys on your behalf.

You will be working with two environments: a staging environment for testing on testnets and a production environment for live operations on the Ethereum mainnet. It is highly recommended to begin your development and testing in the staging environment, as it uses testnet funds and does not incur real costs. Once you are confident, you can switch to the production environment.

Generating Your API Credentials

Your first step is to acquire the API keys that will authenticate your application’s requests. This process typically involves:

1. Creating a Developer Account: Sign up for a developer account on the platform you are using.
2. ️ Navigating to the API Section: Once logged into the developer console, locate the section dedicated to API key management.
3. Selecting Key Type and Scopes: Generate a new Server-side API Key. During creation, you must assign it the specific permissions, or "scopes," required for wallet operations. The essential scopes for this task are wallets.create and wallets.read.

Properly securing these API keys is critical. They should never be exposed in client-side code or public repositories, as they grant significant access to your project's resources.

Step-by-Step: Creating an Ethereum Wallet

With your API key ready, you can now proceed to create a custodial wallet for a user. The core of this operation is a single API call that sends a request containing the user’s identifier and the target blockchain.

The following JavaScript code demonstrates how to make this API call using the fetch function. This code is intended to run in a secure, server-side environment.

const options = {
  method: 'POST',
  headers: {
    'X-API-KEY': 'YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]',
    chain: 'ethereum'
  })
};

fetch('https://api-service.com/v1/wallets', options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(err => console.error('Error:', err));

Code Explanation and Variables:

• API Key: Replace YOUR_API_KEY_HERE with the actual server-side API key you generated earlier.
• User Identifier: Replace [email protected] with the actual email address of the user you are onboarding. The service will create a wallet and associate it with this email.
• Chain Parameter: The value ethereum specifies that the wallet should be created on the Ethereum blockchain.

Alternatively, if you prefer not to use an email address, you can identify a user with a unique ID from your own system.

body: JSON.stringify({
  userId: 'your_internal_user_id_123',
  chain: 'ethereum'
})

Executing the Code and Interpreting the Response

Save the code to a file (e.g., createWallet.js) and run it from your terminal using Node.js:

node createWallet.js

A successful API call will return a JSON response similar to this:

{
  "chain": "ethereum",
  "publicKey": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
}

The publicKey in the response is the newly generated Ethereum wallet address. You can now use this address to perform on-chain actions for your user, such as receiving funds or NFTs. The private key for this address is securely managed by the custodial service, so your user does not have to worry about it.

👉 Explore more wallet creation strategies

Best Practices for Wallet Management

Creating the wallet is just the beginning. Effective management is key to providing a robust user experience.

• User Identification: Ensure your system has a secure and reliable way to map your users to their blockchain wallets. This is crucial for displaying their assets and transaction history correctly.
• Security: Although the service manages private keys, your application must still implement standard security practices. Protect user data, secure your API keys, and use HTTPS everywhere.
• Cost Management: Be aware that on the mainnet, transactions like transferring assets into these wallets will require gas fees. Plan your application’s economics accordingly.

Frequently Asked Questions

What is the difference between custodial and non-custodial wallets?
A custodial wallet is managed by a third-party service that holds the user's private keys, offering a simpler user experience. A non-custodial wallet gives the user full control and responsibility over their private keys, which is considered more secure but less user-friendly for beginners.

Is it safe to create wallets using an email address?
Yes, when using a reputable and secure service. The email acts as a user identifier and a recovery mechanism. The security of the underlying wallet and its assets depends on the service's security infrastructure, which typically employs enterprise-grade measures.

Can I create wallets for users on other blockchains with a similar method?
Absolutely. Most modern wallet infrastructure services support a wide array of Ethereum Virtual Machine (EVM) compatible chains like Polygon, Arbitrum, and Optimism, as well as non-EVM chains such as Solana. The API call is often similar, requiring only a change to the chain parameter.

What happens if a user wants to export their wallet later?
Policies vary by service. Some custodial services allow users to export their private keys or seed phrases to migrate to a self-custody wallet, while others may not. It's important to check the features and limitations of your chosen provider.

Who is responsible for the gas fees on these wallets?
The wallet owner is responsible for gas fees. For any transaction initiated from the custodial wallet (e.g., sending ETH or an NFT), the gas fee must be paid from the assets within that wallet. The application developer often needs to handle this complexity for the user.

How do users access the wallet I create for them?
Access is typically provided through your application's interface. The service's API will allow you to query for a user's assets and initiate transactions on their behalf after authentication, all without the user needing to see a complex wallet interface.