Skip to main content

Integrate Base Account with CDP Embedded Wallets

Learn how to build an onchain app that seamlessly supports both existing Base Account users and new users through CDP Embedded Wallets, providing unified authentication and wallet management.

Overview

This integration enables your app to serve two distinct user types:
  • Existing Base users: Connect with their Base Account for a familiar experience
  • New onchain users: Create CDP Embedded Wallets via email, mobile, or social authentication
Both user types get the same app functionality while using their preferred wallet type.

What you’ll build

  • Unified authentication flow: Single sign-in supporting both wallet types
  • Automatic wallet detection: Smart routing based on user’s existing wallet status
  • Consistent user experience: Both wallet types access the same app features

Prerequisites

  • Node.js 18+ installed
  • React application (Next.js recommended)
  • CDP Portal account with Project ID
  • Basic familiarity with Wagmi and React hooks

Installation

Install the required packages for both CDP Embedded Wallets and Base Account support:

Step-by-step implementation

Since native CDP + Base Account integration is under development, this guide uses a dual connector approach where both wallet types are supported through separate, coordinated connectors. You can use the Base Account Wagmi connector alongside CDP’s React provider system to create a unified experience that properly handles wallet persistence for both wallet types.

Step 1: Environment configuration

Create environment variables for your CDP project:
Get your CDP Project ID from the CDP Portal. ⚠️ Critical: Without a valid NEXT_PUBLIC_CDP_PROJECT_ID, the app will fail to load with “Project ID is required” errors. Also configure your domain in CDP Portal → Wallets → Embedded Wallet settings for CORS.

Step 2: Configure Wagmi for Base Account support

Set up Wagmi with the Base Account connector (embedded wallets will be handled separately via CDP React providers):

Step 3: Set up application providers

Wrap your application with the necessary providers. Important: Use CDPHooksProvider to properly manage embedded wallet authentication state:

Step 4: Create unified authentication hook

Build a custom hook to manage both wallet types. Using CDPHooksProvider ensures users get their existing embedded wallets when they sign in again, rather than creating new ones each time.

Step 5: Build authentication component

Create a component that presents both authentication options:

Step 6: Handle transactions for each wallet type

Create a transaction component that adapts to each wallet type:

Step 7: Complete your app

Put everything together in your main application:

Troubleshooting

Common Issues

Base Account connector not appearing
  • Verify the Base Account SDK, @base-org/account, is installed and up-to-date
  • Check wagmi configuration includes Base Account connector
  • Ensure app is running on Base or Base Sepolia network
CDP Embedded Wallet authentication failing
  • Verify CDP Project ID is correct in environment variables
  • Critical: Add your domains (e.g., http://localhost:3000, http://localhost:3001) to CDP Portal → Wallets → Embedded Wallet settings → Allowed domains
  • Ensure all required CDP packages (see above) are installed
New wallet created each time instead of signing into existing wallet
  • Ensure you’re using CDPHooksProvider with proper config in your layout
  • Verify CDP Project ID is correctly configured
  • Check that hooks are imported from @coinbase/cdp-hooks consistently
Users can’t switch between wallet types
  • Implement proper disconnect flow before connecting different type
  • Clear any cached authentication state when switching
  • Provide clear UI guidance for wallet type selection

Enhanced integration coming soon

We are actively working on native Base Account integration with CDP Embedded Wallets that will enable:
  • Unified connector: Single CDP connector to handle both wallet types seamlessly
  • Spend permissions: Sub Accounts will be able to access parent Base Account balance with limits
  • Sub Account creation: Base Account users will be able to create app-specific Sub Accounts

Resources

Monitor the CDP documentation for updates on enhanced Embedded Wallet Base Account integration features.