Overview
While Embedded Wallets are designed to eliminate the complexity of private key management for users, there are scenarios where developers may need to export private keys for wallet migration, user preference, or other legitimate use cases. This page covers the security considerations, implementation, and best practices for handling private key exports.Private key export is a high-risk operation that should be implemented with extreme caution. Exported private keys provide complete control over wallet funds and should never be logged, displayed, or transmitted insecurely.
Prerequisites
- A CDP Portal account and project
- Embedded Wallets enabled in your project with configured domains
@coinbase/cdp-hooks
installed and configured- User successfully authenticated with embedded wallet
When to consider
Private key export should only be considered in these specific scenarios: Valid use cases:- Wallet migration: Users need to import a wallet into another wallet or application
- User preference: Users specifically request full custody of their private keys
- Account recovery: Users need to recover access when other authentication methods fail
- General export: Users want to export their keys for any legitimate purpose
- Debugging: Never export keys for troubleshooting
- Analytics: Never export keys for analytics or logs
- Backup storage: Don’t export keys to store as backups on your servers
- Default behavior: This should never be automatic or default functionality
Best practices
Critical security principles:
- Private keys provide complete wallet control: Anyone with the private key can access all funds
- This is a high-risk operation: Implement with extreme caution and clear user warnings
-
Never log or store private keys in plaintext
- Avoid console.log, file logging, or unencrypted persistent storage
- Clear private key variables from memory when done
- Let the browser’s garbage collector handle cleanup
-
Require explicit user consent
- Don’t make key export automatic or hidden
- Show clear security warnings before export
- Make the export process deliberate, not accidental
-
Use secure UI patterns
- Clipboard copy is safer than displaying keys on screen
- Provide clear instructions for secure handling
- Consider offering alternatives like asset transfer when appropriate
-
Educate users on security
- Explain what private keys are and why they’re sensitive
- Provide guidance on secure storage options
- Link to general wallet security resources
For users
For comprehensive guidance on private key security and storage best practices, refer to Coinbase’s guide on private key security.Export scenarios
Here are common scenarios where users might need to export their private keys from embedded wallets. Each scenario should be implemented with the security measures outlined above. Wallet migration to external providers:- Users want to import their account into third-party wallet applications
- Copy the exported private key to clipboard for secure transfer
- Provide clear instructions for the import process in the destination wallet
- Users can import the private key into compatible hardware wallets
- Note: This reduces some hardware wallet security benefits since the key was previously software-based
- Recommend this primarily for users who want to upgrade their security model
- Users create offline paper wallets or other cold storage solutions
- Suitable for long-term storage of funds with minimal transaction needs
- Emphasize the importance of secure physical storage
Implementation
1. Add the hook
Use the
useExportEvmAccount
hook from @coinbase/cdp-hooks
:2. Implement export with security measures
What to read next
- React Hooks - Learn about all available hooks for embedded wallet operations
- CDP SDK Documentation - Complete SDK reference and API documentation
- Smart Accounts - Explore account abstraction as an alternative to private key management
- End User Authentication - Understand authentication flows and security models