Wallets

A wallet is a collection of addresses on a network. Wallets come with a single default address. Wallets can hold a balance of one or more assets.

A wallet’s assets are controlled via the addresses’ private keys, which in turn are derived from a seed. Think of a seed / private key as the password to a wallet. For more, see What is a private key?.

Wallets created within the CDP SDK can be either Coinbase-Managed or Developer-Managed, based on how the wallet’s private keys are managed. Users can also import existing wallets via the import method and using a seed phrase.

Wallets can create new addresses, list their addresses, list their balances and transfer assets to other addresses or wallets.

Wallets are created on a specific network. Certain features are only available on certain networks. For example, faucets are only available on Base Sepolia and Ethereum Sepolia. Trades are only available on Base Mainnet.

Creating a Wallet

Typescript

SDK Documentation

Refer to the Wallet class SDK docs for a full list of supported methods.

let wallet = await Wallet.create();

A wallet starts with a single defaultAddress. You can also create more addresses in the wallet, and list them:

// Get the default_address in the wallet.
let address = await wallet.getDefaultAddress();
console.log(`Address: ${address}`);

// Create another address in the wallet.
let address2 = await wallet.createAddress();
console.log(`Address: ${address2}`);

// List the two addresses in the wallet.
let addresses = wallet.getAddresses();

By default, wallets are created for Base Sepolia. The CDP SDK also supports creating wallets for the following networks. To do that, pass the network ID as an argument:

Typescript

SDK Documentation

let wallet = Wallet.create({ networkId: Coinbase.networks.BaseMainnet });

Securing a Wallet

There are two types of wallets that can be created using the CDP SDK, depending on how the private keys are managed: Coinbase-Managed (2-of-2) Wallets and Developer-Managed (1-of-1) Wallets. Developer-Managed wallets are best for rapid testing and prototyping, while Coinbase-Managed wallets are recommended for any production environments.

Turn on IP Whitelisting in the CDP Portal

IP whitelisting provides another layer of protection for your wallets and prevents an attacker from using your CDP API key outside of your infrastructure. See API Key Security Best Practices on how to enable IP whitelisting on your secret API keys.

Secure your CDP Secret API Key

• MPC does not safeguard your CDP API keys or account credentials. If your CDP login or API keys are compromised, funds held in API Wallets could potentially be at risk even when using 2-of-2 MPC.
• Coinbase recommends that you store your secret API keys in a dedicated solution such as AWS secret manager, Azure key vault, or some other secure storage option. Your CDP account can be used to mint new secret API keys and should be stored securely using a password manager. Always follow the principle of least privilege when deciding who within your organization can access your CDP account funds.

Coinbase-Managed Wallets

Wallet API offers a state-of-the-art Multi-Party Computation (MPC) option that splits private keys into two shares between Coinbase and the developer, ensuring improved security. Even if a developer’s share of the private key is compromised, assets will not be at risk as long as the CDP API keys and account credentials remain secure.

These Coinbase-Managed (2-of-2) wallets use the Server-Signer, a deployable component that simplifies key management and provides a secure way to sign transactions. For production applications requiring maximal security, we recommend using Coinbase-Managed Wallets.

Developer-Managed Wallets

For Developer-Managed (1-of-1) Wallets, it is your responsibility as the developer to securely store the data required to re-instantiate your wallets. For example, you may choose to store this data in an encrypted database. As with any 1-of-1 wallet solution, losing access to the wallet could result in a loss of funds.

The CDP SDK provides two key pieces of information to persist Developer-Managed (1-of-1) Wallets:

• Seed: a 32-byte hexadecimal string. This seed is used to derive all of the private keys in the wallet and provides access to spend the assets in the wallet.
• Wallet ID: a string used to identify the wallet.

This information is encapsulated in a wallet’s export data, obtained by calling the export method:

Typescript

// Export the data required to re-instantiate the wallet. The data contains the seed and the ID of the wallet.
let data = wallet.export();

// You should implement the "store" method to securely persist the data object,
// which is required to re-instantiate the wallet at a later time. For ease of use,
// the data object is converted to a Hash first.
await store(data);

It is your responsibility as the developer to securely store the seeds and wallet IDs required to re-instantiate your wallets. For example, you may choose to store this data in an encrypted database.

Persisting Locally

For convenience, we provide a method that stores the wallet seed to a local file that you specify.

This is an insecure method of storing wallet seeds and should only be used for development purposes.

To save your wallet seed, run the following:

Typescript

// Pick a file to which to save your wallet seed.
 let filePath = 'my_seed.json';

// Set encrypt to true to encrypt the wallet seed with your CDP secret API key.
w.saveSeed(filePath, true);

console.log(`Seed for wallet ${w.getId()} successfully saved to ${filePath}.`);

To encrypt the local wallet data, set encrypt to true. Note that your CDP secret API key also serves as the encryption key for the seed persisted locally. This is for development purposes only. In production, developers should use their own encryption mechanisms and not rely on CDP API keys, as they can be rotated. To re-instantiate wallets with encrypted data, ensure that your SDK is configured with the same API key when invoking save_seed! and load_seed.

Re-instantiating a Wallet

The seed and the ID of the wallet are required to re-instantiate a wallet when a new session is started. This data is encapsulated in the export data of a wallet, which should be securely persisted by the developer.

The following code demonstrates how to import the data required to re-instantiate a wallet.

Typescript

// You should implement the "fetch" method to retrieve the securely persisted data object,
// keyed by the wallet ID.
let fetchedData = await fetch(wallet.getId());


// importedWallet will be equivalent to wallet.
let importedWallet = await Wallet.import(fetchedData);

Hydrating a Wallet

Another method of re-instantiating a wallet is to “hydrate” it. Hydration consists of two parts:

• Fetching the wallet from the server
• Setting the correct seed on the wallet

A wallet that is fetched from the server is at first unhydrated, because only you, the developer, have access to the wallet’s seed, and the wallet is unaware of its own seed. Unhydrated wallets can perform read operations, such as viewing balances and addresses, but not write operations, such as creating new addresses or transferring funds.

The code below demonstrates the process of fetching an unhydrated wallet, and hydrating it with a seed:

Typescript

// Get the unhydrated wallet from the server.
const fetchedWallet = await Wallet.fetch(wallet.getId());

// The fact that fetchedWallet is unhydrated is encapsulated by the canSign method.
// For example, calling fetchedWallet.createAddress() would throw an error.
console.log(`fetchedWallet is hydrated: ${fetchedWallet.canSign()}`);

// To hydrate the wallet, set the correct seed on it.
fetchedWallet.setSeed(fetchedData.seed);

// The wallet is now hydrated, and can create addresses and sign transactions.
console.log(`fetchedWallet is hydrated: ${fetchedWallet.canSign()}`);

Hydrating Locally

Typescript

If you used the saveSeed function to persist a wallet’s seed to a local file, then you can first fetch the unhydrated wallet from the server, and then use the loadSeed method to re-instantiate the wallet.

// Get the unhydrated wallet from the server.
const fetchedWallet = await Wallet.fetch(w.getId());

// You can now load the seed into the wallet from the local file.
// fetchedWallet will be equivalent to importedWallet.
await fetchedWallet.loadSeed(filePath);

If you set encrypt to true when calling saveSeed, ensure that your SDK is configured with the same API key when calling loadSeed.

Importing a Wallet

The CDP SDK allows you to import your own wallet via a mnemonic seed phrase, so that you can bring your existing wallets into the CDP ecosystem.

• Easily import wallets from other tools: Use your BIP-39 mnemonic seed phrase to import your existing wallet (ie, from MetaMask, Coinbase Wallet app, etc.) into the CDP ecosystem, allowing you to create complex, programmatic, or agentic interactions.
• 1-of-1 (Developer-Managed) security: Your wallet’s seed and seed phrase will not leave your device.

To import a wallet, use the following commands. Please note that defining your seed phrase within an environment variable is recommended for security.

Remember to back up your seed phrase. Coinbase is not responsible for any loss of your seed phrase.

Typescript

// Import your wallet using your BIP-39 mnemonic seed phrase.
// NOTE: for security reasons, we recommend storing your seed phrase in an environment variable.
let importedWallet = await Wallet.import({ mnemonicPhrase: process.env.MNEMONIC_PHRASE }, Coinbase.networks.BaseSepolia );

Once your wallet has been imported, you won’t need to import it again:

• Export your wallet data (includes your seed and wallet ID) to your desired storage medium.
• Re-instantiate your wallet at any time using your exported wallet data, without needing to use your mnemonic seed phrase.

Retrieving Balances

To view the amount of assets held in a wallet, call the following:

Typescript

let balance = await wallet.listBalances();

Or, to obtain the balance of a specific asset, call the following:

let balance = await wallet.getBalance(Coinbase.assets.Eth);

Note that list method only returns balances for the top 20 assets supported by symbol. For other assets, use get as follows.

Typescript

let balance = await wallet.getBalance("0x036CbD53842c5426634e7929541eC2318f3dCF7e")

Creating webhook

You can create a webhook for the current wallet.

The webhook allow you to receive real-time notifications of wallet activity directly to your application via a specified callback notification URL. By creating a webhook, you can monitor events related to all the addresses for a wallet. See Webhook page for more details on supported event types, event payload and supported networks.

Typescript

let webhook = await wallet.createWebhook('https://call_back_uri_for_webhook')

Exporting wallets to an external provider

API Wallets provide exportable private keys compatible with all major wallet providers, such as Coinbase Wallet and MetaMask. To export the private key for an address that can be imported into an external provider, use the following code snippet:

Typescript

let privateKey = address.export();

What to read next

• Faucets: An overview of CDP Faucets and how to claim testnet funds onchain
• Addresses: Create and manage addresses in your wallet
• Assets: View and manage assets in your wallet