A cryptocurrency wallet is fundamentally a collection of addresses on a blockchain network. Each wallet comes with a single default address and is capable of holding balances of one or more digital assets. The assets within a wallet are controlled through the private keys associated with its addresses, which are derived from a cryptographic seed. Think of this seed or private key as the ultimate password granting access to the wallet's contents.
Core Wallet Types and Key Management
Wallets developed using the CDP SDK fall into two primary categories, determined by how their private keys are managed. Users also have the option to import existing wallets using a seed phrase.
- Coinbase-Managed Wallets: These utilize a sophisticated Multi-Party Computation (MPC) model. The private key is split into two shares—one held by Coinbase and one by the developer. This 2-of-2 structure offers enhanced security, as a compromised developer share alone cannot lead to a loss of funds if the CDP API keys remain secure. This is the recommended choice for production applications.
- Developer-Managed Wallets: In this 1-of-1 model, the developer assumes full responsibility for securely storing the seed and wallet ID. While ideal for rapid testing and prototyping, this option carries the risk of irreversible fund loss if the seed is misplaced or compromised.
👉 Explore more strategies for advanced wallet security
The Role of the Seed Phrase
The seed, a 32-byte hexadecimal string, is the root from which all private keys in a wallet are derived. It is the single point of access to spend assets. For Developer-Managed wallets, this seed, along with a wallet ID, must be securely persisted by the developer, often by exporting the data and storing it in an encrypted database.
How to Create a New Wallet
Creating a wallet is a straightforward process within the SDK. By default, new wallets are created for the Base Sepolia testnet, but the SDK supports other networks by specifying a network ID during creation.
A new wallet begins with a single default address. Developers can then create additional addresses within the same wallet and list them all as needed. This allows for better organization of funds and transactions.
Best Practices for Wallet Security
Securing your wallet is paramount, and the approach differs significantly between the two management types.
For Coinbase-Managed Wallets, security is bolstered by the MPC architecture and the Server-Signer component, which handles key management and transaction signing securely.
For Developer-Managed Wallets, security is entirely your responsibility. The critical action is to securely persist the wallet's export data, which contains the seed and wallet ID. The SDK provides convenience methods to save this seed to a local file, but the ultimate storage solution—such as an encrypted database or a secure hardware module—must be chosen and maintained by the developer.
Re-instantiating and Hydrating a Wallet
To regain access to a wallet in a new session, you must re-instantiate it using the previously exported seed and wallet ID.
A related concept is hydration. A wallet fetched from the server is initially "unhydrated"—it can perform read operations like checking balances but cannot sign transactions or create addresses because it lacks the seed. Hydration is the process of providing the seed to this unhydrated wallet, enabling full functionality.
Importing an Existing Wallet
The CDP SDK allows you to import an existing wallet from other platforms using a standard BIP-39 mnemonic seed phrase. This feature lets you bring wallets from tools like MetaMask into the CDP ecosystem for more complex, programmatic interactions.
- The import process is designed for 1-of-1 (Developer-Managed) security, meaning your seed phrase never leaves your device.
- After the initial import, you can export the wallet data (seed and ID) and use that for future re-instantiation, eliminating the need to repeatedly use the sensitive mnemonic phrase.
Checking Balances and Setting Up Webhooks
You can easily check the assets held in a wallet. The list method returns balances for the top 20 supported assets by symbol, while the get method can be used to query any other specific asset.
To monitor wallet activity in real-time, you can create a webhook. This allows your application to receive instant notifications about events related to all addresses in a wallet, sent directly to a specified callback URL. This is crucial for building responsive applications that need to react to deposits, withdrawals, or other on-chain events.
Exporting for External Use
A key feature of these API wallets is their interoperability. You can export the private key for any address within a wallet in a format compatible with major external wallet providers like Coinbase Wallet and MetaMask. This ensures you are not locked into a single ecosystem and can move your assets as needed.
Frequently Asked Questions
What is the main difference between a Coinbase-Managed and a Developer-Managed wallet?
The core difference lies in key management and security. A Coinbase-Managed wallet uses a 2-of-2 MPC system, splitting key responsibility between you and Coinbase for superior security. A Developer-Managed wallet gives you full control (1-of-1) but also full responsibility for securing the seed, making it riskier for storing significant value.
How do I keep my Developer-Managed wallet secure?
The absolute priority is to securely back up the wallet's export data, which contains the seed and wallet ID. Store this information in multiple secure locations, such as an encrypted database or a hardware security module. Never expose your seed phrase or private keys in your source code or client-side applications.
Can I use a wallet I already have, like my MetaMask wallet, with the CDP SDK?
Yes, you can import an existing wallet using its BIP-39 mnemonic seed phrase. This allows you to leverage your current assets and addresses within the CDP ecosystem for development and more advanced automated operations.
What can an unhydrated wallet do?
An unhydrated wallet, which has been fetched from the server but doesn't have its seed loaded, can perform read-only operations. This includes listing addresses and checking balances. However, it cannot perform any actions that require signing, such as sending funds or creating new addresses, until it is hydrated with its seed.
Why would I create multiple addresses in a single wallet?
Using multiple addresses within one wallet can help with organization and privacy. It allows you to separate transactions for accounting purposes, accept payments from different sources, and enhance privacy by not reusing the same public address for all transactions.
What networks are supported for wallet creation?
The CDP SDK supports wallet creation on several networks. By default, it creates wallets on Base Sepolia. You can also specify other networks by passing the appropriate network ID during the wallet creation process. Certain features, like testnet faucets, are only available on specific networks.