Quickstart
This guide will help you get started with@coinbase/cdp-core
. You’ll learn how to install the package,
initialize the SDK, and make your first API call.
Installation
First, add the package to your project using your preferred package manager.Gather your CDP Project information
- Sign in or create an account on the CDP Portal
- On your dashboard, select a project from the dropdown at the at the top, and copy the Project ID
Allowlist your local app
- Navigate to the Embedded Wallet Configuration in CDP Portal, and click Add origin to include your local app
- Enter the origin of your locally running app - e.g.,
http://localhost:3000
- Click Add origin again to save your changes
Initialize the SDK
Before calling any methods in the SDK, you must first initialize it:Account Configuration
You can configure the SDK to create different types of accounts for new users: Smart Account Configuration:ethereum.createOnLogin
is set to "smart"
, the SDK will:
- Create an EOA (Externally Owned Account) first
- Use that EOA as the owner to create a Smart Account
- Both accounts will be available on the user object
solana.createOnLogin
is set to true
, the SDK will:
- Create a Solana account for new users
- The Solana account will be available on the
solanaAccounts
property
Sign In a User
You’re now ready to start calling the APIs provided by the package! The following code signs in an end user:View User Information
Once the end user has signed in, you can display their information in your application:Send an EVM Transaction
We support signing and sending an EVM transaction in a single call on the following networks:- Base
- Base Sepolia
- Ethereum
- Ethereum Sepolia
- Avalanche
- Arbitrum
- Optimism
- Polygon
viem
to broadcast the transaction.
Smart Account Operations
Smart Accounts provide advanced account abstraction features, including user operations and paymaster support.Sign a Solana Transaction
When your application is configured withsolana: { createOnLogin: true }
, you can sign Solana transactions:
Sign a Solana Message
You can also sign arbitrary messages with Solana accounts:Send a Solana Transaction
You can sign and send a Solana transaction in a single call on the following Solana networks:- Solana Mainnet
- Solana Devnet
Send User Operations
Send user operations from a Smart Account:Get User Operation Status
After sending a user operation, you can get its status and retrieve the result:Sign Messages and Typed Data
End users can sign EVM messages, hashes, and typed data to generate signatures for various onchain applications.Export Private Keys
End users can export their private keys from their embedded wallet, allowing them to import them into compatible wallets of their choice.Export EVM Private Key
Export Solana Private Key
When your application is configured withsolana: { createOnLogin: true }
, you can export Solana private keys:
EIP-1193 Provider
The core package includes an EIP-1193 compatible provider. This provider can be used to sign and send transactions. The provider is created by callingcreateCDPEmbeddedWallet
, which exposes a .provider
attribute. createCDPEmbeddedWallet
must be called with the desired chains to support as well as the transports for these chains.
The provider will initially connect to the first chain in the chains
array. The transports are typically HTTP RPC endpoints, which are used internally for broadcasting non-Base transactions. For more information on transports, see Wagmi’s createConfig
setup.
Viem Accounts
The core package includes atoViemAccount
utility function that enables wrapping an embedded wallet into a Viem account compatible interface. This allows the account to act as a drop-in replacement for any library or framework that accepts Viem accounts.
Functions
initialize()
Parameters
Parameter | Type | Description |
---|---|---|
cfg | Config | The configuration for the core package. |
Returns
Promise
<void
>
Example
signInWithEmail()
Parameters
Parameter | Type | Description |
---|---|---|
options | SignInWithEmailOptions | The options for the sign in. |
Returns
Promise
<SignInWithEmailResult
>
The result of the sign in.
Example
signInWithSms()
Parameters
Parameter | Type | Description |
---|---|---|
options | SignInWithSmsOptions | The options for the sign in. |
Returns
Promise
<SignInWithSmsResult
>
The result of the sign in.
Example
verifyEmailOTP()
Parameters
Parameter | Type | Description |
---|---|---|
options | VerifyEmailOTPOptions | The options for the verification. |
Returns
Promise
<VerifyEmailOTPResult
>
The result of the verification.
Example
verifySmsOTP()
Parameters
Parameter | Type | Description |
---|---|---|
options | VerifySmsOTPOptions | The options for the verification. |
Returns
Promise
<VerifySmsOTPResult
>
The result of the verification.
Example
getCurrentUser()
Returns
Promise
<null
| User
>
The currently signed-in user, or null if no user is signed in.
Example
isSignedIn()
Returns
Promise
<boolean
>
Whether the user is currently signed in.
Example
signOut()
Returns
Promise
<void
>
Example
getAccessToken()
Returns
Promise
<null
| string
>
The access token for the current user, or null if no user is signed in.
Example
onAuthStateChange()
Parameters
Parameter | Type | Description |
---|---|---|
callback | OnAuthStateChangeFn | The callback function to be called when the authentication state changes. |
Returns
void
Example
signEvmHash()
Parameters
Parameter | Type | Description |
---|---|---|
options | SignEvmHashOptions | The options for the signing. |
Returns
Promise
<SignEvmHashResult
>
The result of the signing.
Example
signEvmTransaction()
Parameters
Parameter | Type | Description |
---|---|---|
options | SignEvmTransactionOptions | The options for the signing. |
Returns
Promise
<SignEvmTransactionResult
>
The result of the signing.
Example
signSolanaTransaction()
Parameters
Parameter | Type | Description |
---|---|---|
options | SignSolanaTransactionOptions | The options for the signing. |
Returns
Promise
<SignSolanaTransactionResult
>
The result of the signing.
Example
sendEvmTransaction()
Parameters
Parameter | Type | Description |
---|---|---|
options | SendEvmTransactionOptions | The options for the sending. |
Returns
Promise
<SendEvmTransactionResult
>
The transaction hash of the sent transaction.
Example
sendSolanaTransaction()
Parameters
Parameter | Type | Description |
---|---|---|
options | SendSolanaTransactionOptions | The options for sending the Solana transaction. |
Returns
Promise
<SendSolanaTransactionResult
>
The transaction signature.
signEvmMessage()
Parameters
Parameter | Type | Description |
---|---|---|
options | SignEvmMessageOptions | The options for the signing. |
Returns
Promise
<SignEvmHashResult
>
The result of the signing.
Example
signSolanaMessage()
Parameters
Parameter | Type | Description |
---|---|---|
options | SignSolanaMessageOptions | The options for the signing. |
Returns
Promise
<SignSolanaMessageResult
>
The result of the signing.
Example
signEvmTypedData()
Parameters
Parameter | Type | Description |
---|---|---|
options | SignEvmTypedDataOptions | The options for the signing. |
Returns
Promise
<SignEvmTypedDataResult
>
The result of the signing.
Example
sendUserOperation()
Parameters
Parameter | Type | Description |
---|---|---|
options | SendUserOperationOptions | The options for sending the user operation. |
Returns
Promise
<SendUserOperationResult
>
Promise that resolves to the user operation hash.
Example
getUserOperation()
Parameters
Parameter | Type | Description |
---|---|---|
options | GetUserOperationOptions | The options for getting the user operation. |
Returns
Promise
<EvmUserOperation
>
The user operation details.
Example
exportEvmAccount()
Parameters
Parameter | Type | Description |
---|---|---|
options | ExportEvmAccountOptions | The options for the exporting. |
Returns
Promise
<ExportEvmAccountResult
>
The result of the export.
Example
exportSolanaAccount()
Parameters
Parameter | Type | Description |
---|---|---|
options | ExportSolanaAccountOptions | The options for exporting the account. |
Returns
Promise
<ExportSolanaAccountResult
>
The result of the export.
Example
toViemAccount()
Parameters
Parameter | Type | Description |
---|---|---|
address | `0x${string}` | The EVM address to create a Viem account for |
Returns
Promise
<{
}>
A Viem LocalAccount that can sign messages and transactions using CDP’s signing functions
Throws
If the user is not authenticated or the address is not in the user’s EVM accountsExample
createCDPEmbeddedWallet()
createConfig
setup.
Type Parameters
Type Parameter |
---|
chains extends readonly [Chain , Chain ] |
Parameters
Parameter | Type | Description |
---|---|---|
_parameters | CDPEmbeddedWalletConfig <chains > | Configuration parameters for the connector - see CDPEmbeddedWalletConfig |
Returns
CDPEmbeddedWallet
A CDP embedded wallet instance
Examples
Classes
ModuleResolutionError
Error thrown when required native modules are not available in the React Native environment.Extends
Error
Constructors
Constructor
Parameters
Parameter | Type | Description |
---|---|---|
moduleName | string | The name of the missing module. |
requiredFor | string | The API or feature that requires the module. |
message? | string | Optional custom error message. |
Returns
ModuleResolutionError
Overrides
Properties
Property | Modifier | Type | Description |
---|---|---|---|
moduleName | public | string | The name of the missing module. |
requiredFor | public | string | The API or feature that requires the missing module. |
APIError
Extends
Error
Constructors
Constructor
Parameters
Parameter | Type |
---|---|
statusCode | number |
errorType | APIErrorType |
errorMessage | string |
correlationId? | string |
errorLink? | string |
cause? | Error |
Returns
APIError
Overrides
Methods
toJSON()
Returns
object
errorLink?
correlationId?
name
statusCode
errorType
errorMessage
Properties
Property | Type |
---|---|
statusCode | number |
errorType | APIErrorType |
errorMessage | string |
correlationId? | string |
errorLink? | string |
EIP1193ProviderError
EIP-1193 provider error.Extends
Error
Constructors
Constructor
Parameters
Parameter | Type | Description |
---|---|---|
code | EIP1193ErrorCode | The error code from EIP1193ErrorCode enum. |
message | string | The error message. |
Returns
EIP1193ProviderError
Overrides
Properties
Property | Modifier | Type | Description |
---|---|---|---|
code | public | EIP1193ErrorCode | The error code from EIP1193ErrorCode enum. |
Interfaces
EIP712Domain
The domain of the EIP-712 typed data.Properties
EIP712Types
A mapping of struct names to an array of type objects (name + type). Each key corresponds to a type name (e.g., “EIP712Domain
”, “PermitTransferFrom
”).
Indexable
EIP712TypedData
The message to sign using EIP-712.Properties
Property | Type | Description |
---|---|---|
domain | EIP712Domain | - |
types | EIP712Types | - |
primaryType | string | The primary type of the message. This is the name of the struct in the types object that is the root of the message. |
message | EIP712Message | The message to sign. The structure of this message must match the primaryType struct in the types object. |
Type Aliases
BaseConfig
Properties
NetworkConfig
Properties
Config
Hex
EvmAddress
SolanaAddress
AuthenticationMethods
Properties
Property | Type |
---|---|
email? | EmailAuthentication |
sms? | SmsAuthentication |
User
Properties
Property | Type | Description |
---|---|---|
userId | string | The user ID. |
authenticationMethods | AuthenticationMethods | The authentication methods used by the user. |
evmAccounts? | EvmAddress [] | The EVM accounts associated with the user. |
evmSmartAccounts? | EvmAddress [] | The EVM smart accounts associated with the user. |
solanaAccounts? | SolanaAddress [] | The Solana accounts associated with the user. |
EmailAuthentication
Properties
Property | Type | Description |
---|---|---|
type | "email" | The type of authentication method. |
email | string | The email address of the user. |
SmsAuthentication
Properties
Property | Type | Description |
---|---|---|
type | "sms" | The type of authentication method. |
phoneNumber | string | The phone number of the end user in E.164 format. |
SignInWithEmailOptions
Properties
Property | Type |
---|---|
email | string |
SignInWithEmailResult
Properties
Property | Type | Description |
---|---|---|
message | string | The message to display to the user. |
flowId | string | The flow ID to use in verifyEmailOTP. |
SignInWithSmsOptions
Properties
Property | Type | Description |
---|---|---|
phoneNumber | string | The phone number of the end user in E.164 format. Example: “+14155552671” |
SignInWithSmsResult
Properties
Property | Type | Description |
---|---|---|
message | string | The message to display to the user. |
flowId | string | The flow ID to use in verifySmsOTP. |
VerifyEmailOTPOptions
Properties
Property | Type | Description |
---|---|---|
flowId | string | The flow ID to use in verifyEmailOTP. |
otp | string | The OTP to verify. |
VerifyEmailOTPResult
Properties
Property | Type | Description |
---|---|---|
user | User | The successfully logged-in user. |
message | string | The message to display to the user. |
isNewUser | boolean | Whether the user is newly signed up. |
VerifySmsOTPOptions
Properties
Property | Type | Description |
---|---|---|
flowId | string | The flow ID to use in verifySmsOTP. |
otp | string | The OTP to verify. |
VerifySmsOTPResult
Properties
Property | Type | Description |
---|---|---|
user | User | The successfully logged-in user. |
message | string | The message to display to the user. |
isNewUser | boolean | Whether the user is newly signed up. |
OnAuthStateChangeFn()
Parameters
Parameter | Type |
---|---|
user | User | null |
Returns
void
SignEvmHashOptions
Properties
Property | Type | Description |
---|---|---|
evmAccount | EvmAddress | The EVM account to sign the hash with. |
hash | Hex | The hash to sign. |
SignEvmHashResult
Properties
Property | Type | Description |
---|---|---|
signature | Hex | The signature. |
AllowedEvmTransactionType
SignEvmTransactionOptions
Properties
Property | Type | Description |
---|---|---|
evmAccount | EvmAddress | The EVM account to sign the message with. |
transaction | AllowedEvmTransactionType | The transaction to sign. |
SignEvmTransactionResult
Properties
Property | Type | Description |
---|---|---|
signedTransaction | Hex | The signed transaction. |
SignSolanaTransactionOptions
Properties
Property | Type | Description |
---|---|---|
solanaAccount | SolanaAddress | The Solana account to sign the transaction with. |
transaction | string | The base64 encoded transaction to sign. |
SignSolanaTransactionResult
Properties
Property | Type | Description |
---|---|---|
signedTransaction | string | The base64 encoded signed transaction. |
SignSolanaMessageOptions
Properties
Property | Type | Description |
---|---|---|
solanaAccount | SolanaAddress | The Solana account to sign the message with. |
message | string | The message to sign (base64 encoded). |
SignSolanaMessageResult
Properties
Property | Type | Description |
---|---|---|
signature | string | The base58 encoded signature. |
SendEvmTransactionOptions
Properties
Property | Type | Description |
---|---|---|
evmAccount | EvmAddress | The EVM account to send the transaction with. |
network | SendEvmTransactionWithEndUserAccountBodyNetwork | The network to send the transaction to. |
transaction | AllowedEvmTransactionType | The transaction to send. |
SendEvmTransactionResult
Properties
Property | Type | Description |
---|---|---|
transactionHash | Hex | The transaction hash. |
SendSolanaTransactionOptions
Properties
Property | Type | Description |
---|---|---|
solanaAccount | SolanaAddress | The Solana account to send the transaction with. |
network | SendSolanaTransactionWithEndUserAccountBodyNetwork | The network to send the transaction to. |
transaction | string | The base64 encoded transaction to send. |
SendSolanaTransactionResult
Properties
Property | Type | Description |
---|---|---|
transactionSignature | string | The transaction signature. |
SignEvmMessageOptions
Properties
Property | Type | Description |
---|---|---|
evmAccount | EvmAddress | The EVM account to sign the message with. |
message | string | The message to sign. |
SignEvmMessageResult
Properties
Property | Type | Description |
---|---|---|
signature | Hex | The signature. |
EIP712Message
primaryType
struct in the types
object.
Index Signature
SignEvmTypedDataOptions
Properties
Property | Type | Description |
---|---|---|
evmAccount | EvmAddress | The EVM account to sign the typed data with. |
typedData | EIP712TypedData | The EIP-712 typed data to sign. |
EvmCall
Properties
Property | Type | Description |
---|---|---|
to | EvmAddress | The target address for the call. |
value? | bigint | The value to send with the call (in wei). |
data? | Hex | The data to send with the call. |
SendUserOperationOptions
Properties
Property | Type | Description |
---|---|---|
evmSmartAccount | EvmAddress | The EVM Smart Account to send the user operation with. |
network | SendEvmTransactionWithEndUserAccountBodyNetwork | The network to send the user operation on. |
calls | EvmCall [] | The calls to make from the user operation. |
useCdpPaymaster? | boolean | Whether to use the CDP Paymaster for the user operation. |
paymasterUrl? | string | The URL of the paymaster to use for the user operation. Get your free Base paymaster URL from the CDP Portal. |
SendUserOperationResult
Properties
Property | Type | Description |
---|---|---|
userOperationHash | Hex | The user operation hash. |
GetUserOperationOptions
Properties
Property | Type | Description |
---|---|---|
userOperationHash | Hex | The user operation hash. |
evmSmartAccount | EvmAddress | The EVM Smart Account that sent the user operation. |
network | SendEvmTransactionWithEndUserAccountBodyNetwork | The network the user operation was sent on. |
GetUserOperationResult
SignEvmTypedDataResult
Properties
Property | Type | Description |
---|---|---|
signature | Hex | The signature. |
ExportEvmAccountOptions
Properties
Property | Type | Description |
---|---|---|
evmAccount | EvmAddress | The EVM account to export. |
ExportEvmAccountResult
Properties
Property | Type | Description |
---|---|---|
privateKey | string | The 32 byte raw private key of the EVM account. |
ExportSolanaAccountOptions
Properties
Property | Type | Description |
---|---|---|
solanaAccount | SolanaAddress | The Solana account to export. |
ExportSolanaAccountResult
Properties
Property | Type | Description |
---|---|---|
privateKey | string | The 32 byte raw private key of the Solana account. |
CDPEmbeddedWalletConfig<chains>
Type Parameters
Type Parameter | Default type | Description |
---|---|---|
chains extends readonly [Chain , ...Chain[] ] | readonly [Chain , ...Chain[] ] | The chains to support |
Properties
Property | Type | Description |
---|---|---|
chains | chains | - |
transports | Record <chains [number ]["id" ], Transport > | The transports to use for each chain |
announceProvider? | boolean | Whether to announce the provider to the wallet |
EIP1193Provider
CDPEmbeddedWallet
Properties
Property | Type |
---|---|
provider | EIP1193Provider |
EIP1193RequestFunctionType
AccountsRequest
Properties
Property | Type |
---|---|
method | "eth_accounts" |
params | [] |
RequestAccountsRequest
Properties
Property | Type |
---|---|
method | "eth_requestAccounts" |
params | [] |
PersonalSignRequest
Properties
Property | Type |
---|---|
method | "personal_sign" |
params | [`0x${string}` , `0x${string}` ] |
SendTransactionRequestParams
SendTransactionRequest
Properties
Property | Type |
---|---|
method | "eth_sendTransaction" |
params | SendTransactionRequestParams |
SignTypedDataRequest
Properties
Property | Type |
---|---|
method | "eth_signTypedData_v4" |
params | [EvmAddress , string ] |
EthSignRequest
Properties
Property | Type |
---|---|
method | "eth_sign" |
params | [Hex , EvmAddress ] |
ChainIdRequest
Properties
Property | Type |
---|---|
method | "eth_chainId" |
params | [] |
WalletDisconnectRequest
Properties
Property | Type |
---|---|
method | "wallet_disconnect" |
params | [] |
SwitchEthereumChainRequest
Properties
Property | Type |
---|---|
method | "wallet_switchEthereumChain" |
params | [{ chainId : string ; }] |
SendCallsRequest
Properties
Property | Type |
---|---|
method | "wallet_sendCalls" |
params | [{ calls : Call []; }] |
GetCallsStatusRequest
Properties
Property | Type |
---|---|
method | "wallet_getCallsStatus" |
params | [`0x${string}` ] |
GetCapabilitiesRequest
Properties
Property | Type |
---|---|
method | "wallet_getCapabilities" |
params | [] |
UnknownRequest
Properties
Property | Type |
---|---|
method | string |
params | unknown [] |
ProviderRequest
ExactPartial<T>
Type Parameters
Type Parameter | Description |
---|---|
T | The type to make partial. |
Returns
The partial type.ProviderState
Properties
Property | Type |
---|---|
chainId | number |
setChainId | (chainId ) => void |
chains | readonly [Chain , ...Chain[] ] |
user | User | null |
setUser | (user ) => void |