Skip to main content
EVMSolana

​
General

​
What is an Embedded Wallet?

A self-custodial crypto wallet built into your app. Users sign in with email OTP instead of managing seed phrases while maintaining full control of their assets. Wallets are created in under 500ms.

​
How is this different from MetaMask?

Embedded Wallets integrate directly into your app’s UI—no browser extensions or pop-ups. Users authenticate with email, SMS, or social login instead of seed phrases.

​
Who controls the assets?

Users have full control. Embedded Wallets are self-custodial—only the user can access their private keys. Users can export keys anytime. Coinbase cannot access user funds.

​
Can I support both embedded and external wallets?

Yes. You can support both Embedded Wallets and external wallets (like MetaMask) in the same application.

​
Authentication

​
What authentication methods are available?

  • Email OTP: 6-digit codes, expire after 10 minutes
  • SMS OTP: 6-digit codes for select countries, expire after 5 minutes
  • Social login: Google OAuth 2.0
Developer-delegated auth coming soon.

​
Which countries support SMS?

Brazil, Canada, Colombia, India, Kenya, Mexico, Philippines, United Arab Emirates, United Kingdom, United States of America. Contact Discord for additional regions.

​
How long do sessions last?

Sessions last up to 7 days with automatic refresh. Access tokens expire after 15 minutes, refresh tokens after 7 days.

​
Can I customize authentication?

Yes. Use the pre-built AuthButton, React hooks for custom UI, or direct methods from @coinbase/cdp-core for non-React frameworks. See Implementation Guide.

​
Is SMS authentication secure?

SMS is vulnerable to SIM swapping attacks. Email OTP is recommended as the primary method.

​
Security

​
How secure are embedded wallets?

Cryptographic operations occur in secure, isolated environments. Device-specific keys are generated locally and never exposed to Coinbase. True self-custody with support for up to 5 devices. See Security and compliance.

​
What is domain allowlisting?

Required security feature that prevents unauthorized use of your project credentials. Configure allowed domains in CDP Portal before production deployment. See Security Configuration.

​
Can users export private keys?

Yes. Users can export private keys for wallet migration to MetaMask, hardware wallets, or other applications. See Security & Export.

​
Is HTTPS required?

Yes. HTTPS is required in production to protect credentials and prevent attacks.

​
How do I validate sessions server-side?

Always validate access tokens on your backend for sensitive operations using the CDP SDK. See Server-side validation.

​
Technical

​
What networks are supported?

All EVM-compatible chains (Base, Ethereum, Arbitrum, Polygon, Optimism), Solana (mainnet and devnet), and testnets. See Supported Networks.

​
How fast is wallet creation?

Under 500ms for instant user onboarding.

​
Can I import existing addresses?

No. Embedded Wallets creates new addresses for security. Use Server Wallets for backend key import.

​
What frameworks are supported?

React, React Native, and Next.js have full support. Other frameworks use @coinbase/cdp-core for vanilla JS/TS, Vue, Angular, Svelte, etc.

​
Can I customize the UI?

Yes. Use pre-built components, theming options, or build completely custom UI with hooks. See Theming.

​
Are there rate limits?

Yes. Authentication endpoints have rate limiting. Implement additional rate limiting on your endpoints as best practice.

​
Pricing & Features

​
How much does it cost?

See Pricing page.

​
What features are included?

User authentication, wallet creation, transaction signing (EVM and Solana), onramp/offramp, USDC Rewards (3.85% for US developers across Embedded Wallets including Smart Accounts, and Server Wallets), and multi-device support (up to 5).

​
Can I use onramp/offramp?

Yes. Built-in onramp/offramp lets users buy crypto with fiat and cash out to bank accounts. See Onramp Integration.

​
What are USDC Rewards?

US developers earn 3.85% on USDC balances across CDP Embedded Wallets (including Smart Accounts) and Server Wallets. Built-in, no integration required. See USDC Rewards.

​
Troubleshooting

​
Why am I getting “User is already authenticated” errors?

This error occurs when calling verifyEmailOTP or verifySmsOTP while a user is already signed in. Always check authentication state before starting a new auth flow: 
const user = await getCurrentUser();
if (user) {
  // User already authenticated, no need to verify
  return;
}
See Best Practices.

​
What causes invalid or expired OTP errors?

  • Email OTPs expire after 10 minutes
  • SMS OTPs expire after 5 minutes
  • User entered wrong code
  • Network delays prevented timely entry
Request a new OTP if the code has expired.

​
Why are sessions expiring unexpectedly?

Sessions last up to 7 days with automatic token refresh. Unexpected expiration usually means:
  • User cleared browser storage/cookies
  • Multiple devices exceeded the 5-device limit (oldest session terminated)
  • User manually signed out on another device
Implement onAuthStateChange() to detect and handle session changes gracefully. See Session Management.

​
Why is my domain being rejected?

Ensure your domain is allowlisted in CDP Portal. Common issues:
  • Domain not added to allowlist
  • Using HTTPS in Portal but HTTP locally (or vice versa)
  • Subdomain mismatch (added app.example.com but using www.example.com)
  • Localhost not configured for development
See Security Configuration.

​
How do I test in development?

  1. Add localhost:3000 (or your dev port) to allowed domains in CDP Portal
  2. Use testnet networks: Base Sepolia, Ethereum Sepolia, Solana Devnet
  3. Get testnet funds from Base Faucet
  4. Test in incognito mode to simulate new users
  5. Test with multiple browsers to ensure cross-browser compatibility

​
Where can I get help?

Quickstart Guide or Discord.
⌘I