Embedded Wallet Pre-Generation

Overview

Pre-generate embedded wallets for your users before they sign in, enabling you to fund accounts with assets upfront for a seamless first-time experience.

Supported authentication methods: Wallet pre-generation currently supports email, SMS, and Custom (JWT) authentication only. Support for additional authentication methods is coming soon.

Why pre-generate wallets?

Pre-load assets: Fund wallets with loyalty points, gas, or welcome NFTs before users sign in
Zero-friction onboarding: Users see a ready-to-use wallet on first login instead of an empty account
Targeted campaigns: Prepare wallets for specific users (by email, phone, or JWT) before launching marketing campaigns

Prerequisites

Before pre-generating wallets, ensure you have:

CDP API Key - Create one in the CDP Portal → API Keys
Wallet Secret - Generate one in the CDP Portal → Server Wallet → Accounts
CDP SDK - Install the CDP SDK in your project

Common mistake: A standard CDP API key alone is not enough for wallet pre-generation. You must also generate a Wallet Secret from the Server Wallet section of the CDP Portal.

Getting your credentials

Create a CDP API Key

Go to the CDP Portal
Navigate to API Keys in the left sidebar
Click Create API Key and save both the Key ID and Key Secret

Generate a Wallet Secret

In the CDP Portal, go to Server Wallet → Accounts
Click Generate in the Wallet Secret section
Save the secret securely - you won’t be able to view it again

Configure your environment

Add both credentials to your .env file:

CDP_API_KEY_ID=your-api-key-id
CDP_API_KEY_SECRET=your-api-key-secret
CDP_WALLET_SECRET=your-wallet-secret

For more details, see the Authentication documentation and Wallet Secret documentation.

Usage

Use the CDP SDK to create an end user with a specific authentication method. Once created, you can fund the wallet address before the user ever signs in.

Creating an end user

The createEndUser method creates a new end user with an associated wallet. You specify the authentication method (email, SMS, or JWT) that the user will use to sign in later.

Email authentication

TypeScript
Python

import { CdpClient } from "@coinbase/cdp-sdk";
import "dotenv/config";

const cdp = new CdpClient();

try {
  // Create an end user with an email authentication method 
  // and both EVM and Solana accounts.
  const endUser = await cdp.endUser.createEndUser({
    authenticationMethods: [
      { type: "email", email: "[email protected]" }
    ],
    evmAccount: { createSmartAccount: false },
    solanaAccount: { createSmartAccount: false }
  });

  console.log("Created end user:", endUser);

  // The end user's wallet addresses are now available.
  // You can fund these addresses before the user signs in.
  console.log("EVM address:", endUser.evmAccounts?.[0]);
  console.log("Solana address:", endUser.solanaAccounts?.[0]);
} catch (error) {
  console.error("Error creating end user:", error);
}

import asyncio

from cdp import CdpClient
from cdp.openapi_client.models.authentication_method import AuthenticationMethod
from cdp.openapi_client.models.create_end_user_request_evm_account import (
    CreateEndUserRequestEvmAccount,
)
from cdp.openapi_client.models.create_end_user_request_solana_account import (
    CreateEndUserRequestSolanaAccount,
)
from cdp.openapi_client.models.email_authentication import EmailAuthentication
from dotenv import load_dotenv

load_dotenv()


async def main():
    async with CdpClient() as cdp:
        try:
            # Create an end user with an email authentication method
            # and both EVM and Solana accounts.
            end_user = await cdp.end_user.create_end_user(
                authentication_methods=[
                    AuthenticationMethod(EmailAuthentication(type="email", email="[email protected]"))
                ],
                evm_account=CreateEndUserRequestEvmAccount(create_smart_account=False),
                solana_account=CreateEndUserRequestSolanaAccount(create_smart_account=False),
            )

            print("Created end user:", end_user)

            # The end user's wallet addresses are now available.
            # You can fund these addresses before the user signs in.

        except Exception as e:
            print(f"Error creating end user: {e}")
            raise e


asyncio.run(main())

SMS authentication

TypeScript
Python

import { CdpClient } from "@coinbase/cdp-sdk";
import "dotenv/config";

const cdp = new CdpClient();

try {
  // Create an end user with an SMS authentication method
  // and both EVM and Solana accounts.
  const endUser = await cdp.endUser.createEndUser({
    authenticationMethods: [
      { type: "sms", phoneNumber: "+12055555555" }
    ],
    evmAccount: { createSmartAccount: false },
    solanaAccount: { createSmartAccount: false }
  });

  console.log("Created end user:", endUser);

  // The end user's wallet addresses are now available.
  // You can fund these addresses before the user signs in.
  console.log("EVM address:", endUser.evmAccounts?.[0]);
  console.log("Solana address:", endUser.solanaAccounts?.[0]);
} catch (error) {
  console.error("Error creating end user:", error);
}

import asyncio

from cdp import CdpClient
from cdp.openapi_client.models.authentication_method import AuthenticationMethod
from cdp.openapi_client.models.create_end_user_request_evm_account import (
    CreateEndUserRequestEvmAccount,
)
from cdp.openapi_client.models.create_end_user_request_solana_account import (
    CreateEndUserRequestSolanaAccount,
)
from cdp.openapi_client.models.sms_authentication import SmsAuthentication
from dotenv import load_dotenv

load_dotenv()


async def main():
    async with CdpClient() as cdp:
        try:
            # Create an end user with an SMS authentication method
            # and both EVM and Solana accounts.
            end_user = await cdp.end_user.create_end_user(
                authentication_methods=[
                    AuthenticationMethod(SmsAuthentication(type="sms", phone_number="+12055555555"))
                ],
                evm_account=CreateEndUserRequestEvmAccount(create_smart_account=False),
                solana_account=CreateEndUserRequestSolanaAccount(create_smart_account=False),
            )

            print("Created end user:", end_user)

            # The end user's wallet addresses are now available.
            # You can fund these addresses before the user signs in.

        except Exception as e:
            print(f"Error creating end user: {e}")
            raise e


asyncio.run(main())

Custom (JWT) Authentication

TypeScript
Python

import { CdpClient } from "@coinbase/cdp-sdk";
import "dotenv/config";

const cdp = new CdpClient();

try {
  // Create an end user with a JWT authentication method
  // and both EVM and Solana accounts.
  const endUser = await cdp.endUser.createEndUser({
    authenticationMethods: [
      { type: "jwt", sub: "auth0|69387f18541e0e673845c6b6", kid: "1234567890" }
    ],
    evmAccount: { createSmartAccount: false },
    solanaAccount: { createSmartAccount: false }
  });

  console.log("Created end user:", endUser);

  // The end user's wallet addresses are now available.
  // You can fund these addresses before the user signs in.
  console.log("EVM address:", endUser.evmAccounts?.[0]);
  console.log("Solana address:", endUser.solanaAccounts?.[0]);
} catch (error) {
  console.error("Error creating end user:", error);
}

import asyncio

from cdp import CdpClient
from cdp.openapi_client.models.authentication_method import AuthenticationMethod
from cdp.openapi_client.models.create_end_user_request_evm_account import (
    CreateEndUserRequestEvmAccount,
)
from cdp.openapi_client.models.create_end_user_request_solana_account import (
    CreateEndUserRequestSolanaAccount,
)
from cdp.openapi_client.models.developer_jwt_authentication import DeveloperJWTAuthentication
from dotenv import load_dotenv

load_dotenv()


async def main():
    async with CdpClient() as cdp:
        try:
            # Create an end user with a JWT authentication method
            # and both EVM and Solana accounts.
            end_user = await cdp.end_user.create_end_user(
                authentication_methods=[
                    AuthenticationMethod(DeveloperJWTAuthentication(type="jwt", sub="auth0|69387f18541e0e673845c6b6", kid="1234567890"))
                ],
                evm_account=CreateEndUserRequestEvmAccount(create_smart_account=False),
                solana_account=CreateEndUserRequestSolanaAccount(create_smart_account=False),
            )

            print("Created end user:", end_user)

            # The end user's wallet addresses are now available.
            # You can fund these addresses before the user signs in.

        except Exception as e:
            print(f"Error creating end user: {e}")
            raise e


asyncio.run(main())

The sub value you use must match the sub claim in the JWTs your identity provider issues for this user.

Pre-generate wallet with an existing private key

If you already have access to your end users’ private keys, you can import them directly into Embedded Wallets. This is useful when migrating users from other wallet solutions—such as Server Wallets—to Embedded Wallets.

When to use import: Use this method when you have existing private keys for your users and want to preserve their wallet addresses during migration. The import flow is end-to-end encrypted, ensuring keys are never exposed outside of the SDK and the secure enclave.

The import API supports both EVM and Solana key types. Set keyType to either "evm" (hex-encoded private key) or "solana" (base58-encoded private key).

Email authentication

TypeScript
Python

import { CdpClient } from "@coinbase/cdp-sdk";
import "dotenv/config";

const cdp = new CdpClient();

try {
  // Import an end user with an existing private key.
  // For Solana: use keyType: "solana" with a base58-encoded private key.
  const endUser = await cdp.endUser.importEndUser({
    authenticationMethods: [
      { type: "email", email: "[email protected]" }
    ],
    privateKey: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    keyType: "evm",
  });

  console.log("Imported end user:", endUser);
  console.log("EVM accounts:", endUser.evmAccountObjects);
} catch (error) {
  console.error("Error importing end user:", error);
}

import asyncio

from cdp import CdpClient
from cdp.openapi_client.models.authentication_method import AuthenticationMethod
from cdp.openapi_client.models.email_authentication import EmailAuthentication
from dotenv import load_dotenv

load_dotenv()


async def main():
    async with CdpClient() as cdp:
        try:
            # Import an end user with an existing private key.
            # For Solana: use key_type="solana" with a base58-encoded private key.
            end_user = await cdp.end_user.import_end_user(
                authentication_methods=[
                    AuthenticationMethod(EmailAuthentication(type="email", email="[email protected]"))
                ],
                private_key="0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
                key_type="evm",
            )

            print("Imported end user:", end_user)
            print("EVM accounts:", end_user.evm_account_objects)

        except Exception as e:
            print(f"Error importing end user: {e}")
            raise e


asyncio.run(main())

SMS authentication

TypeScript
Python

import { CdpClient } from "@coinbase/cdp-sdk";
import "dotenv/config";

const cdp = new CdpClient();

try {
  // Import an end user with an existing private key.
  // For Solana: use keyType: "solana" with a base58-encoded private key.
  const endUser = await cdp.endUser.importEndUser({
    authenticationMethods: [
      { type: "sms", phoneNumber: "+12055555555" }
    ],
    privateKey: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    keyType: "evm",
  });

  console.log("Imported end user:", endUser);
  console.log("EVM accounts:", endUser.evmAccountObjects);
} catch (error) {
  console.error("Error importing end user:", error);
}

import asyncio

from cdp import CdpClient
from cdp.openapi_client.models.authentication_method import AuthenticationMethod
from cdp.openapi_client.models.sms_authentication import SmsAuthentication
from dotenv import load_dotenv

load_dotenv()


async def main():
    async with CdpClient() as cdp:
        try:
            # Import an end user with an existing private key.
            # For Solana: use key_type="solana" with a base58-encoded private key.
            end_user = await cdp.end_user.import_end_user(
                authentication_methods=[
                    AuthenticationMethod(SmsAuthentication(type="sms", phone_number="+12055555555"))
                ],
                private_key="0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
                key_type="evm",
            )

            print("Imported end user:", end_user)
            print("EVM accounts:", end_user.evm_account_objects)

        except Exception as e:
            print(f"Error importing end user: {e}")
            raise e


asyncio.run(main())

Custom (JWT) authentication

TypeScript
Python

import { CdpClient } from "@coinbase/cdp-sdk";
import "dotenv/config";

const cdp = new CdpClient();

try {
  // Import an end user with an existing private key.
  // For Solana: use keyType: "solana" with a base58-encoded private key.
  const endUser = await cdp.endUser.importEndUser({
    authenticationMethods: [
      { type: "jwt", sub: "auth0|69387f18541e0e673845c6b6", kid: "1234567890" }
    ],
    privateKey: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    keyType: "evm",
  });

  console.log("Imported end user:", endUser);
  console.log("EVM accounts:", endUser.evmAccountObjects);
} catch (error) {
  console.error("Error importing end user:", error);
}

import asyncio

from cdp import CdpClient
from cdp.openapi_client.models.authentication_method import AuthenticationMethod
from cdp.openapi_client.models.developer_jwt_authentication import DeveloperJWTAuthentication
from dotenv import load_dotenv

load_dotenv()


async def main():
    async with CdpClient() as cdp:
        try:
            # Import an end user with an existing private key.
            # For Solana: use key_type="solana" with a base58-encoded private key.
            end_user = await cdp.end_user.import_end_user(
                authentication_methods=[
                    AuthenticationMethod(DeveloperJWTAuthentication(type="jwt", sub="auth0|69387f18541e0e673845c6b6", kid="1234567890"))
                ],
                private_key="0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
                key_type="evm",
            )

            print("Imported end user:", end_user)
            print("EVM accounts:", end_user.evm_account_objects)

        except Exception as e:
            print(f"Error importing end user: {e}")
            raise e


asyncio.run(main())

Security: Private keys should be handled with extreme care. Ensure you transmit keys securely and never log or expose them in your application. The import flow uses end-to-end encryption to protect keys during transmission.

Account Configuration

By default, pre-generated wallets are created as EOA (Externally Owned Accounts). You can configure the account type and features using the evmAccount and solanaAccount parameters.

Smart accounts are only supported for EVM. Solana accounts must have createSmartAccount set to false.

Smart Accounts

Create an EVM smart account instead of an EOA by setting createSmartAccount: true.

TypeScript
Python

import { CdpClient } from "@coinbase/cdp-sdk";
import "dotenv/config";

const cdp = new CdpClient();

try {
  const endUser = await cdp.endUser.createEndUser({
    authenticationMethods: [
      { type: "email", email: "[email protected]" }
    ],
    evmAccount: { createSmartAccount: true },
    solanaAccount: { createSmartAccount: false }
  });

  console.log("Created end user with smart account:", endUser);
  
  // Access the smart account object
  const smartAccount = endUser.evmSmartAccountObjects?.[0];
  console.log("Smart account address:", smartAccount?.address);
  console.log("Owner addresses:", smartAccount?.ownerAddresses);
  console.log("Solana address:", endUser.solanaAccounts?.[0]);
} catch (error) {
  console.error("Error creating end user:", error);
}

import asyncio

from cdp import CdpClient
from cdp.openapi_client.models.authentication_method import AuthenticationMethod
from cdp.openapi_client.models.create_end_user_request_evm_account import (
    CreateEndUserRequestEvmAccount,
)
from cdp.openapi_client.models.create_end_user_request_solana_account import (
    CreateEndUserRequestSolanaAccount,
)
from cdp.openapi_client.models.email_authentication import EmailAuthentication
from dotenv import load_dotenv

load_dotenv()


async def main():
    async with CdpClient() as cdp:
        try:
            end_user = await cdp.end_user.create_end_user(
                authentication_methods=[
                    AuthenticationMethod(EmailAuthentication(type="email", email="[email protected]"))
                ],
                evm_account=CreateEndUserRequestEvmAccount(create_smart_account=True),
                solana_account=CreateEndUserRequestSolanaAccount(create_smart_account=False),
            )

            print("Created end user with smart account:", end_user)
            
            smart_account = end_user.evm_smart_account_objects[0]
            print(f"Smart account address: {smart_account.address}")
            print(f"Owner addresses: {smart_account.owner_addresses}")
            print(f"Solana address: {end_user.solana_accounts[0]}")

        except Exception as e:
            print(f"Error creating end user: {e}")
            raise e


asyncio.run(main())

Spend permissions allow you to grant allowances to specific addresses, enabling delegated transactions without requiring user signatures for each action. Learn more in the Spend Permissions documentation.

Spend Permissions

Enable spend permissions on an EVM smart account by setting enableSpendPermissions: true. This requires createSmartAccount: true.

TypeScript
Python

import { CdpClient } from "@coinbase/cdp-sdk";
import "dotenv/config";

const cdp = new CdpClient();

try {
  const endUser = await cdp.endUser.createEndUser({
    authenticationMethods: [
      { type: "email", email: "[email protected]" }
    ],
    evmAccount: { 
      createSmartAccount: true,
      enableSpendPermissions: true
    },
    solanaAccount: { createSmartAccount: false }
  });

  console.log("Created end user with spend permissions:", endUser);
  
  const smartAccount = endUser.evmSmartAccountObjects?.[0];
  console.log("Smart account address:", smartAccount?.address);
  
  // When spend permissions are enabled, there are 2 owner addresses:
  // 1. User's owner address
  // 2. Spend Permission Manager address
  console.log("Owner addresses:", smartAccount?.ownerAddresses);
  console.log("Solana address:", endUser.solanaAccounts?.[0]);
} catch (error) {
  console.error("Error creating end user:", error);
}

import asyncio

from cdp import CdpClient
from cdp.openapi_client.models.authentication_method import AuthenticationMethod
from cdp.openapi_client.models.create_end_user_request_evm_account import (
    CreateEndUserRequestEvmAccount,
)
from cdp.openapi_client.models.create_end_user_request_solana_account import (
    CreateEndUserRequestSolanaAccount,
)
from cdp.openapi_client.models.email_authentication import EmailAuthentication
from dotenv import load_dotenv

load_dotenv()


async def main():
    async with CdpClient() as cdp:
        try:
            end_user = await cdp.end_user.create_end_user(
                authentication_methods=[
                    AuthenticationMethod(EmailAuthentication(type="email", email="[email protected]"))
                ],
                evm_account=CreateEndUserRequestEvmAccount(
                    create_smart_account=True, 
                    enable_spend_permissions=True
                ),
                solana_account=CreateEndUserRequestSolanaAccount(create_smart_account=False),
            )

            print("Created end user with spend permissions:", end_user)
            
            smart_account = end_user.evm_smart_account_objects[0]
            print(f"Smart account address: {smart_account.address}")
            
            # When spend permissions are enabled, there are 2 owner addresses:
            # 1. User's owner address
            # 2. Spend Permission Manager address
            print(f"Owner addresses: {smart_account.owner_addresses}")
            print(f"Solana address: {end_user.solana_accounts[0]}")

        except Exception as e:
            print(f"Error creating end user: {e}")
            raise e


asyncio.run(main())

Authentication Methods

Learn about email OTP, SMS OTP, and social login options

Implementation Guide

Integrate authentication into your frontend application

Quickstart

Get started with embedded wallets in your React app

CDP SDK Reference

Explore the full SDK documentation

GET STARTED

PAYMENTS

TRADING

WALLETS

ONCHAIN TOOLS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

Overview

Why pre-generate wallets?

Prerequisites

Getting your credentials

Usage

Creating an end user

Email authentication

SMS authentication

Custom (JWT) Authentication

Pre-generate wallet with an existing private key

Email authentication

SMS authentication

Custom (JWT) authentication

Account Configuration

Smart Accounts

Spend Permissions

What to read next

Authentication Methods

Implementation Guide

Quickstart

CDP SDK Reference

GET STARTED

PAYMENTS

TRADING

WALLETS

ONCHAIN TOOLS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

​Overview

​Why pre-generate wallets?

​Prerequisites

​Getting your credentials

​Usage

​Creating an end user

​Email authentication

​SMS authentication

​Custom (JWT) Authentication

​Pre-generate wallet with an existing private key

​Email authentication

​SMS authentication

​Custom (JWT) authentication

​Account Configuration

​Smart Accounts

​Spend Permissions

​What to read next

Authentication Methods

Implementation Guide

Quickstart

CDP SDK Reference

Overview

Why pre-generate wallets?

Prerequisites

Getting your credentials

Usage

Creating an end user

Email authentication

SMS authentication

Custom (JWT) Authentication

Pre-generate wallet with an existing private key

Email authentication

SMS authentication

Custom (JWT) authentication

Account Configuration

Smart Accounts

Spend Permissions

What to read next