@coinbase/cdp-core - Coinbase Developer Documentation

This package contains core business logic for the CDP Frontend SDK. It is intended for non-React applications that use pure Typescript.

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.

# With pnpm
pnpm add @coinbase/cdp-core

# With yarn
yarn add @coinbase/cdp-core

# With npm
npm install @coinbase/cdp-core

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:

import { Config, initialize } from "@coinbase/cdp-core";

const config: Config = {
  // Copy and paste your project ID here.
  projectId: "your-project-id",
}

await initialize(config);

Smart Account Configuration

You can configure the SDK to automatically create Smart Accounts for new users by setting createAccountOnLogin to "evm-smart":

const config: Config = {
  projectId: "your-project-id",
  createAccountOnLogin: "evm-smart", // Creates Smart Accounts instead of EOAs
}

await initialize(config);

When createAccountOnLogin is set to "evm-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

You’re now ready to start calling the APIs provided by the package! The following code signs in an end user:

import { signInWithEmail, verifyEmailOTP } from "@coinbase/cdp-core";

// Send an email to user@example.com with a One Time Password (OTP).
const authResult = await signInWithEmail({
  email: "user@example.com"
});

// Input the OTP sent to user@example.com.
const verifyResult = await verifyEmailOTP({
  flowId: authResult.flowId,
  otp: "123456", // Hardcoded for convenience here.
});

// Get the authenticated end user.
const user = verifyResult.user;

View User Information

Once the end user has signed in, you can display their information in your application:

import { getCurrentUser, isSignedIn } from "@coinbase/cdp-core";

// Check if user is signed in
const signedIn = await isSignedIn();

if (signedIn) {
  // Get the user's information
  const user = await getCurrentUser();
  console.log("User ID:", user.userId);
  console.log("EVM Accounts (EOAs):", user.evmAccounts);
  console.log("EVM Smart Accounts:", user.evmSmartAccounts);

  // Find the user's email address (if they logged in with email/otp)
  const email = user.authenticationMethods.email?.email;
  console.log("Email Address": email)
}

Send a Transaction

We support signing and sending a Blockchain transaction in a single call on the following networks:

Base
Base Sepolia
Ethereum
Ethereum Sepolia
Avalanche
Arbitrum
Optimism
Polygon

import { sendEvmTransaction, getCurrentUser } from "@coinbase/cdp-core";

const user = await getCurrentUser();
const evmAccount = user.evmAccounts[0];

const result = await sendEvmTransaction({
  evmAccount,
  transaction: {
    to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    value: 100000000000000n, // 0.0001 ETH in wei
    nonce: 0,
    gas: 21000n,
    maxFeePerGas: 30000000000n,
    maxPriorityFeePerGas: 1000000000n,
    chainId: 84532, // Base Sepolia
    type: "eip1559",
  }
});

console.log("Transaction Hash:", result.transactionHash);

For networks other than those supported by the CDP APIs, your end user must sign the transaction, and then you must broadcast the transaction yourself. This example uses the public client from viem to broadcast the transaction.

import { signEvmTransaction, getCurrentUser } from "@coinbase/cdp-core";
import { http, createPublicClient } from "viem";
import { tron } from "viem/chains";

const user = await getCurrentUser();
const evmAccount = user.evmAccounts[0];

// Sign the transaction
const { signedTransaction } = await signEvmTransaction({
  evmAccount,
  transaction: {
    to: "0x...",
    value: 100000000000000n,
    nonce: 0,
    gas: 21000n,
    maxFeePerGas: 30000000000n,
    maxPriorityFeePerGas: 1000000000n,
    chainId: 728126428, // Tron
    type: "eip1559",
  }
});

// Broadcast signed transaction to non-Base chain
const client = createPublicClient({
  chain: tron,
  transport: http()
});

const hash = await client.sendRawTransaction({
  serializedTransaction: signedTransaction
});

Smart Account Operations

Smart Accounts provide advanced account abstraction features, including user operations and paymaster support.

Send User Operations

Send user operations from a Smart Account:

import { sendUserOperation, getCurrentUser } from "@coinbase/cdp-core";

const user = await getCurrentUser();
const smartAccount = user.evmSmartAccounts[0];

const result = await sendUserOperation({
  evmSmartAccount: smartAccount,
  network: "base-sepolia",
  calls: [
    {
      to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      value: 1000000000000000000n, // 1 ETH in wei
      data: "0x", // Optional contract interaction data
    }
  ],
  // Optional paymaster for gas sponsorship. Get your free Base paymaster URL [from the CDP Portal](https://portal.cdp.coinbase.com/products/node).
  paymasterUrl: "https://paymaster.example.com",
});

console.log("User Operation Hash:", result.userOperationHash);

Get User Operation Status

After sending a user operation, you can get its status and retrieve the result:

import { getUserOperation } from "@coinbase/cdp-core";

// Get the status of a user operation
const userOperationResult = await getUserOperation({
  userOperationHash: result.userOperationHash,
  evmSmartAccount: smartAccount,
  network: "base-sepolia"
});

console.log("Status:", userOperationResult.status); // "pending", "complete", or "failed"

if (userOperationResult.status === "complete") {
  console.log("Transaction Hash:", userOperationResult.transactionHash);
  console.log("Block Number:", userOperationResult.receipts?.[0]?.blockNumber);
} else if (userOperationResult.status === "failed") {
  console.log("Failure reason:", userOperationResult.receipts?.[0]?.revert?.message);
}

Sign Messages and Typed Data

End users can sign EVM messages, hashes, and typed data to generate signatures for various onchain applications.

import { signEvmMessage, signEvmTypedData, getCurrentUser } from "@coinbase/cdp-core";

const user = await getCurrentUser();
const evmAccount = user.evmAccounts[0];

// Sign a message
const messageResult = await signEvmMessage({
  evmAccount,
  message: "Hello World"
});

// Sign typed data (EIP-712)
const typedDataResult = await signEvmTypedData({
  evmAccount,
  typedData: {
    domain: {
      name: "Example DApp",
      version: "1",
      chainId: 84532,
    },
    types: {
      Person: [
        { name: "name", type: "string" },
        { name: "wallet", type: "address" }
      ]
    },
    primaryType: "Person",
    message: {
      name: "Bob",
      wallet: evmAccount
    }
  }
});

Export Private Key

End users can export their private keys from their embedded wallet, allowing them to import it into an EVM-compatible wallet of their choice.

import { exportEvmAccount, getCurrentUser } from "@coinbase/cdp-core";

const user = await getCurrentUser();
const evmAccount = user.evmAccounts[0];

const { privateKey } = await exportEvmAccount({
  evmAccount
});

// WARNING: Handle private keys with extreme care!
console.log("Private Key:", privateKey);

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 calling createCDPEmbeddedWallet, 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.

import { base, mainnet } from "viem/chains";
import { http } from "viem"

// Basic usage with default configuration
const wallet = createCDPEmbeddedWallet({
  chains:[base, mainnet],
  transports: {
    [base.id]: http(),
    [mainnet.id]: http()
  }
});
const provider = wallet.provider;

// Request account access
const accounts = await provider.request({
  method: "eth_requestAccounts"
});

// Sign a message
const signature = await provider.request({
  method: "personal_sign",
  params: ["Hello, World!", accounts[0]]
});

// Send a transaction
const txHash = await provider.request({
  method: "eth_sendTransaction",
  params: [{
    from: accounts[0],
    to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    value: "0x1000000000000000000"
  }]
});

// Listen for connection events
provider.on("connect", (connectInfo) => {
  console.log("Connected to chain:", connectInfo.chainId);
});

provider.on("disconnect", () => {
  console.log("Disconnected from wallet");
});

Viem Accounts

The core package includes a toViemAccount 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.

import { toViemAccount, getCurrentUser } from "@coinbase/cdp-core";
import { createWalletClient } from "viem";
import { mainnet } from "viem/chains";
import { http } from "viem";

const user = await getCurrentUser();
const evmAccount = user.evmAccounts[0];

const viemAccount = toViemAccount(evmAccount);

const client = createWalletClient({
  account: viemAccount,
  transport: http("https://example.com"),
  chain: mainnet,
});

Functions

initialize()

function initialize(cfg): Promise<void>;

Initializes the core package. Must be called before using any other functions.

Parameters

Parameter	Type	Description
`cfg`	`Config`	The configuration for the core package.

Returns

Promise<void>

Example

await initialize({
  projectId: "your-project-id", // Your project ID from the CDP Portal
});

signInWithEmail()

function signInWithEmail(options): Promise<SignInWithEmailResult>;

Initiates the sign in flow with an email.

Parameters

Parameter	Type	Description
`options`	`SignInWithEmailOptions`	The options for the sign in.

Returns

Promise<SignInWithEmailResult> The result of the sign in.

Example

const result = await signInWithEmail({
  email: "user@example.com"
});

signInWithSms()

function signInWithSms(options): Promise<SignInWithSmsResult>;

Initiates the sign in flow with a phone number via SMS.

Parameters

Parameter	Type	Description
`options`	`SignInWithSmsOptions`	The options for the sign in.

Returns

Promise<SignInWithSmsResult> The result of the sign in.

Example

const result = await signInWithSms({
  phoneNumber: "+14155552671"
});

verifyEmailOTP()

function verifyEmailOTP(options): Promise<VerifyEmailOTPResult>;

Verifies the one-time password (OTP) for the sign in flow with an email.

Parameters

Parameter	Type	Description
`options`	`VerifyEmailOTPOptions`	The options for the verification.

Returns

Promise<VerifyEmailOTPResult> The result of the verification.

Example

const result = await verifyEmailOTP({
  flowId: "flow-id-from-signInWithEmail",
  otp: "123456" // The OTP received in email
});

verifySmsOTP()

function verifySmsOTP(options): Promise<VerifySmsOTPResult>;

Verifies the one-time password (OTP) for the sign in flow with a phone number via SMS.

Parameters

Parameter	Type	Description
`options`	`VerifySmsOTPOptions`	The options for the verification.

Returns

Promise<VerifySmsOTPResult> The result of the verification.

Example

const result = await verifySmsOTP({
  flowId: "flow-id-from-signInWithSms",
  otp: "123456" // The OTP received in SMS
});

getCurrentUser()

function getCurrentUser(): Promise<null | User>;

Gets the currently signed-in user, if any.

Returns

Promise<null | User> The currently signed-in user, or null if no user is signed in.

Example

const user = await getCurrentUser();

isSignedIn()

function isSignedIn(): Promise<boolean>;

Returns whether the user is currently signed in.

Returns

Promise<boolean> Whether the user is currently signed in.

Example

const signedIn = await isSignedIn();
if (signedIn) {
  console.log("User is signed in");
}

signOut()

function signOut(): Promise<void>;

Signs out the end user, clearing all authentication state.

Returns

Promise<void>

Example

await signOut();

getAccessToken()

function getAccessToken(): Promise<null | string>;

Gets the access token for the current user.

Returns

Promise<null | string> The access token for the current user, or null if no user is signed in.

Example

const accessToken = await getAccessToken();

onAuthStateChange()

function onAuthStateChange(callback): void;

Sets a callback function to be called when the authentication state changes, i.e. when a user signs in or out.

Parameters

Parameter	Type	Description
`callback`	`OnAuthStateChangeFn`	The callback function to be called when the authentication state changes.

Returns

void

Example

onAuthStateChange(async (user) => {
  if (user) {
    console.log("User signed in:", user.userId);
  } else {
    console.log("User signed out");
  }
});

signEvmHash()

function signEvmHash(options): Promise<SignEvmHashResult>;

Signs a hash with an EVM account.

Parameters

Parameter	Type	Description
`options`	`SignEvmHashOptions`	The options for the signing.

Returns

Promise<SignEvmHashResult> The result of the signing.

Example

const result = await signEvmHash({
  evmAccount: "0x1234...",
  hash: "0xabcd..." // 32-byte hex string to sign
});

signEvmTransaction()

function signEvmTransaction(options): Promise<SignEvmTransactionResult>;

Signs a hash with an EVM account.

Parameters

Parameter	Type	Description
`options`	`SignEvmTransactionOptions`	The options for the signing.

Returns

Promise<SignEvmTransactionResult> The result of the signing.

Example

const user = await getCurrentUser();
const evmAccount = user?.evmAccounts[0];

const result = await signEvmTransaction({
  evmAccount,
  transaction: {
    to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    value: 100000000000000n, // 0.0001 ETH in wei
    nonce: 0,
    gas: 21000n,
    maxFeePerGas: 30000000000n,
    maxPriorityFeePerGas: 1000000000n,
    chainId: 84532, // Base Sepolia
    type: "eip1559",
  }
});

sendEvmTransaction()

function sendEvmTransaction(options): Promise<SendEvmTransactionResult>;

Sends an EVM transaction.

Parameters

Parameter	Type	Description
`options`	`SendEvmTransactionOptions`	The options for the sending.

Returns

Promise<SendEvmTransactionResult> The transaction hash of the sent transaction.

Example

const user = await getCurrentUser();
const evmAccount = user?.evmAccounts[0];

const result = await sendEvmTransaction({
  evmAccount,
  network: "base-sepolia",
  transaction: {
    to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    value: 100000000000000n, // 0.0001 ETH in wei
    nonce: 0,
    gas: 21000n,
    maxFeePerGas: 30000000000n,
    maxPriorityFeePerGas: 1000000000n,
    chainId: 84532, // Base Sepolia
    type: "eip1559",
  }
});

signEvmMessage()

function signEvmMessage(options): Promise<SignEvmHashResult>;

Signs an EVM message.

Parameters

Parameter	Type	Description
`options`	`SignEvmMessageOptions`	The options for the signing.

Returns

Promise<SignEvmHashResult> The result of the signing.

Example

const user = await getCurrentUser();
const evmAccount = user?.evmAccounts[0];

const result = await signEvmMessage({
  evmAccount,
  message: "Hello World" // Message to sign
});

signEvmTypedData()

function signEvmTypedData(options): Promise<SignEvmTypedDataResult>;

Signs EIP-712 typed data with an EVM account.

Parameters

Parameter	Type	Description
`options`	`SignEvmTypedDataOptions`	The options for the signing.

Returns

Promise<SignEvmTypedDataResult> The result of the signing.

Example

const user = await getCurrentUser();
const evmAccount = user?.evmAccounts[0];

const result = await signEvmTypedData({
  evmAccount,
  typedData: {
    domain: {
      name: "USDC",
      version: "2",
      chainId: 84532,
      verifyingContract: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", // Base Sepolia USDC
    },
    types: {
      EIP712Domain: [
        { name: "name", type: "string" },
        { name: "version", type: "string" },
        { name: "chainId", type: "uint256" },
        { name: "verifyingContract", type: "address" },
      ],
      TransferWithAuthorization: [
        { name: "from", type: "address" },
        { name: "to", type: "address" },
        { name: "value", type: "uint256" },
        { name: "validAfter", type: "uint256" },
        { name: "validBefore", type: "uint256" },
        { name: "nonce", type: "bytes32" },
      ],
    },
    primaryType: "TransferWithAuthorization",
    message: {
      from: evmAccount,
      to: "0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB",
      value: "1000000", // 1 USDC (6 decimals)
      validAfter: 0, // Valid immediately
      validBefore: 2524604400, // Valid until 2050
      nonce: 0
    },
  },
});

sendUserOperation()

function sendUserOperation(options): Promise<SendUserOperationResult>;

Sends a user operation from a smart account.

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

const user = await getCurrentUser();
const smartAccount = user?.evmSmartAccounts[0];

const result = await sendUserOperation({
  evmSmartAccount: smartAccount,
  network: "base-sepolia",
  calls: [{
    to: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    value: 0n,
    data: "0x",
  }],
});
console.log("User Operation Hash:", result.userOperationHash);

getUserOperation()

function getUserOperation(options): Promise<EvmUserOperation>;

Gets a user operation by its hash.

Parameters

Parameter	Type	Description
`options`	`GetUserOperationOptions`	The options for getting the user operation.

Returns

Promise<EvmUserOperation> The user operation details.

Example

const result = await getUserOperation({
  userOperationHash: "0x123...",
  evmSmartAccount: "0xabc...",
  network: "base-sepolia"
});
console.log("User Operation Status:", result.transactionHash);

exportEvmAccount()

function exportEvmAccount(options): Promise<ExportEvmAccountResult>;

Exports an EVM account’s private key.

Parameters

Parameter	Type	Description
`options`	`ExportEvmAccountOptions`	The options for the exporting.

Returns

Promise<ExportEvmAccountResult> The result of the export.

Example

const result = await exportEvmAccount({
  evmAccount: "0x1234..."
});

toViemAccount()

function toViemAccount(address): Promise<{
}>;

Converts a CDP EVM account into a Viem-compatible LocalAccount. This enables the CDP account to be used with any library or framework that accepts Viem accounts.

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 accounts

Example

const user = await getCurrentUser();
const evmAccount = user.evmAccounts[0];
const viemAccount = await toViemAccount(evmAccount);

createCDPEmbeddedWallet()

function createCDPEmbeddedWallet<chains>(_parameters): CDPEmbeddedWallet;

Creates the CDP embedded wallet’s 1193 provider. Note: The transports are currently only used for non-Base transactions. For non-Base transactions, the provider internally signs the transaction via the CDP APIs and broadcasts it via the provided transports, whereas for Base transactions the CDP API both signs and broadcasts the transaction. For more information on transports, see Wagmi’s 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

import { createCDPEmbeddedWallet, initialize } from "@coinbase/cdp-core";
import { http } from "viem";
import { baseSepolia, sepolia } from "viem/chains";

// SDK core must be initialized before creating the wallet
await initialize({
  projectId: "your-project-id"
})

// Create a wallet with multiple chains
const wallet = createCDPEmbeddedWallet({
  chains: [baseSepolia, sepolia],
  transports: {
    [baseSepolia.id]: http(),
    [sepolia.id]: http(),
  },
  announceProvider: true, // Announce the provider to window.ethereum
});

// The provider can be accessed via the provider property
const provider = wallet.provider;

// The provider implements the EIP-1193 interface
await provider.request({ method: "eth_requestAccounts" });

// Basic usage with default configuration
const wallet = createCDPEmbeddedWallet();
const provider = wallet.provider;

// Request account access
const accounts = await provider.request({
  method: "eth_requestAccounts"
});

// Sign a message
const signature = await provider.request({
  method: "personal_sign",
  params: ["Hello, World!", accounts[0]]
});

// Send a transaction
const txHash = await provider.request({
  method: "eth_sendTransaction",
  params: [{
    from: accounts[0],
    to: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    value: "0x1000000000000000000" // 1 ETH
  }]
});

// Listen for connection events
provider.on("connect", (connectInfo) => {
  console.log("Connected to chain:", connectInfo.chainId);
});

provider.on("disconnect", () => {
  console.log("Disconnected from wallet");
});

Classes

ModuleResolutionError

Error thrown when required native modules are not available in the React Native environment.

Extends

Error

Constructors

Constructor

new ModuleResolutionError(
   moduleName, 
   requiredFor, 
   message?): ModuleResolutionError;

Creates a new ModuleResolutionError.

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

Error.constructor

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

new APIError(
   statusCode, 
   errorType, 
   errorMessage, 
   correlationId?, 
   errorLink?, 
   cause?): APIError;

Parameters

Parameter	Type
`statusCode`	`number`
`errorType`	`APIErrorType`
`errorMessage`	`string`
`correlationId?`	`string`
`errorLink?`	`string`
`cause?`	`Error`

Returns

APIError

Overrides

Error.constructor

Methods

toJSON()

toJSON(): object;

Returns

object

errorLink?

optional errorLink: string;

correlationId?

optional correlationId: string;

name

name: string;

statusCode

statusCode: number;

errorType

errorType: APIErrorType;

errorMessage

errorMessage: string;

Properties

Property	Type
`statusCode`	`number`
`errorType`	`APIErrorType`
`errorMessage`	`string`
`correlationId?`	`string`
`errorLink?`	`string`

EIP1193ProviderError

EIP-1193 provider error.

Extends

Error

Constructors

Constructor

new EIP1193ProviderError(code, message): EIP1193ProviderError;

Creates a new EIP-1193 Provider error.

Parameters

Parameter	Type	Description
`code`	`EIP1193ErrorCode`	The error code from EIP1193ErrorCode enum.
`message`	`string`	The error message.

Returns

EIP1193ProviderError

Overrides

Error.constructor

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

Property	Type	Description
`name?`	`string`	The name of the DApp or protocol.
`version?`	`string`	The version of the DApp or protocol.
`chainId?`	`number`	The chain ID of the EVM network.
`salt?`	`0x${string}`	The optional 32-byte 0x-prefixed hex salt for domain separation.
`verifyingContract?`	`0x${string}`	The verifying contract address.

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

[key: string]: unknown

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

Config

type Config = object;

Configuration for the core package.

Properties

Property	Type	Description
`projectId`	`string`	The CDP Project ID.
`useMock?`	`boolean`	Whether to use the mock implementation.
`debugging?`	`boolean`	Whether to enable debugging.
`basePath?`	`string`	The base path for the API.
`createAccountOnLogin?`	`"evm-eoa"` \| `"evm-smart"`	The account type to automatically create on login. Defaults to “evm-eoa”.

Hex

type Hex = `0x${string}`;

A hex string.

EvmAddress

type EvmAddress = `0x${string}`;

An EVM address.

AuthenticationMethods

type AuthenticationMethods = object;

The authentication methods used by the user.

Properties

Property	Type
`email?`	`EmailAuthentication`
`sms?`	`SmsAuthentication`

User

type User = object;

The User object.

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.

EmailAuthentication

type EmailAuthentication = object;

The email authentication method.

Properties

Property	Type	Description
`type`	`"email"`	The type of authentication method.
`email`	`string`	The email address of the user.

SmsAuthentication

type SmsAuthentication = object;

The SMS authentication method.

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

type SignInWithEmailOptions = object;

Request parameters for signInWithEmail.

Properties

Property	Type
`email`	`string`

SignInWithEmailResult

type SignInWithEmailResult = object;

Result of signInWithEmail.

Properties

Property	Type	Description
`message`	`string`	The message to display to the user.
`flowId`	`string`	The flow ID to use in verifyEmailOTP.

SignInWithSmsOptions

type SignInWithSmsOptions = object;

Request parameters for signInWithSms.

Properties

Property	Type	Description
`phoneNumber`	`string`	The phone number of the end user in E.164 format. Example: “+14155552671”

SignInWithSmsResult

type SignInWithSmsResult = object;

Result of signInWithSms.

Properties

Property	Type	Description
`message`	`string`	The message to display to the user.
`flowId`	`string`	The flow ID to use in verifySmsOTP.

VerifyEmailOTPOptions

type VerifyEmailOTPOptions = object;

Request parameters for verifyEmailOTP.

Properties

Property	Type	Description
`flowId`	`string`	The flow ID to use in verifyEmailOTP.
`otp`	`string`	The OTP to verify.

VerifyEmailOTPResult

type VerifyEmailOTPResult = object;

Result of verifyEmailOTP.

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

type VerifySmsOTPOptions = object;

Request parameters for verifySmsOTP.

Properties

Property	Type	Description
`flowId`	`string`	The flow ID to use in verifySmsOTP.
`otp`	`string`	The OTP to verify.

VerifySmsOTPResult

type VerifySmsOTPResult = object;

Result of verifySmsOTP.

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()

type OnAuthStateChangeFn = (user) => void;

A callback function when authentication state changes.

Parameters

Parameter	Type
`user`	`User` \| `null`

Returns

void

SignEvmHashOptions

type SignEvmHashOptions = object;

Request parameters for signing a hash with an EVM account.

Properties

Property	Type	Description
`evmAccount`	`EvmAddress`	The EVM account to sign the hash with.
`hash`	`Hex`	The hash to sign.

SignEvmHashResult

type SignEvmHashResult = object;

Result of signEvmHash.

Properties

Property	Type	Description
`signature`	`Hex`	The signature.

AllowedEvmTransactionType

type AllowedEvmTransactionType = TransactionSerializableEIP1559;

Request parameters for signing an EVM message.

SignEvmTransactionOptions

type SignEvmTransactionOptions = object;

Request parameters for signing an EVM transaction.

Properties

Property	Type	Description
`evmAccount`	`EvmAddress`	The EVM account to sign the message with.
`transaction`	`AllowedEvmTransactionType`	The transaction to sign.

SignEvmTransactionResult

type SignEvmTransactionResult = object;

Result of signEvmTransaction.

Properties

Property	Type	Description
`signedTransaction`	`Hex`	The signed transaction.

SendEvmTransactionOptions

type SendEvmTransactionOptions = object;

Request parameters for sending an EVM transaction.

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

type SendEvmTransactionResult = object;

Result of sendEvmTransaction.

Properties

Property	Type	Description
`transactionHash`	`Hex`	The transaction hash.

SignEvmMessageOptions

type SignEvmMessageOptions = object;

Request parameters for signing an EVM message.

Properties

Property	Type	Description
`evmAccount`	`EvmAddress`	The EVM account to sign the message with.
`message`	`string`	The message to sign.

SignEvmMessageResult

type SignEvmMessageResult = object;

Result of signEvmMessage.

Properties

Property	Type	Description
`signature`	`Hex`	The signature.

EIP712Message

type EIP712Message = object;

The message to sign. The structure of this message must match the primaryType struct in the types object.

Index Signature

[key: string]: unknown

SignEvmTypedDataOptions

type SignEvmTypedDataOptions = object;

Request parameters for signing EIP-712 typed data with an EVM account.

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

type EvmCall = object;

Represents a call in an EVM user operation.

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

type SendUserOperationOptions = object;

Request parameters for sending a user operation.

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

type SendUserOperationResult = object;

Result of sendUserOperation.

Properties

Property	Type	Description
`userOperationHash`	`Hex`	The user operation hash.

GetUserOperationOptions

type GetUserOperationOptions = object;

Request parameters for getting a user operation.

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

type GetUserOperationResult = EvmUserOperation;

Result of getUserOperation.

SignEvmTypedDataResult

type SignEvmTypedDataResult = object;

Result of signEvmTypedData.

Properties

Property	Type	Description
`signature`	`Hex`	The signature.

ExportEvmAccountOptions

type ExportEvmAccountOptions = object;

Request parameters for exporting an EVM account’s private key.

Properties

Property	Type	Description
`evmAccount`	`EvmAddress`	The EVM account to export.

ExportEvmAccountResult

type ExportEvmAccountResult = object;

Result of exportEvmAccount.

Properties

Property	Type	Description
`privateKey`	`string`	The 32 byte raw private key of the EVM account.

CDPEmbeddedWalletConfig<chains>

type CDPEmbeddedWalletConfig<chains> = object;

Config parameters for the CDP embedded wallet 1193 provider. Note: The transports are currently only used for non-Base transactions. For non-Base transactions, the provider internally signs the transaction via the CDP APIs and broadcasts it via the provided transports, whereas for Base transactions the CDP API both signs and broadcasts the transaction.

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

type EIP1193Provider = ox_Provider.Provider;

EIP-1193 Provider interface - we likely will extend this in the future.

CDPEmbeddedWallet

type CDPEmbeddedWallet = object;

A type representing a CDP embedded wallet, for now is just a provider + cleanup function

Properties

Property	Type
`provider`	`EIP1193Provider`

EIP1193RequestFunctionType

type EIP1193RequestFunctionType = ox_Provider.Provider;

AccountsRequest

type AccountsRequest = object;

A request to the eth_accounts method.

Properties

Property	Type
`method`	`"eth_accounts"`
`params`	[]

RequestAccountsRequest

type RequestAccountsRequest = object;

A request to the eth_requestAccounts method.

Properties

Property	Type
`method`	`"eth_requestAccounts"`
`params`	[]

PersonalSignRequest

type PersonalSignRequest = object;

A request to the personal_sign method.

Properties

Property	Type
`method`	`"personal_sign"`
`params`	[`0x${string}`, `0x${string}`]

SendTransactionRequestParams

type SendTransactionRequestParams = [{
  chainId?: `0x${string}`;
  data?: Hex;
  from: EvmAddress;
  to: EvmAddress;
  value: Hex;
  nonce?: Hex;
  gas?: Hex;
  maxFeePerGas?: Hex;
  maxPriorityFeePerGas?: Hex;
  type?: "eip1559";
}];

Transaction parameters for the eth_sendTransaction method.

SendTransactionRequest

type SendTransactionRequest = object;

A request to the eth_sendTransaction method.

Properties

Property	Type
`method`	`"eth_sendTransaction"`
`params`	`SendTransactionRequestParams`

SignTypedDataRequest

type SignTypedDataRequest = object;

A request to the eth_signTypedData_v4 method.

Properties

Property	Type
`method`	`"eth_signTypedData_v4"`
`params`	[`EvmAddress`, `string`]

EthSignRequest

type EthSignRequest = object;

A request to the eth_sign method.

Properties

Property	Type
`method`	`"eth_sign"`
`params`	[`Hex`, `EvmAddress`]

ChainIdRequest

type ChainIdRequest = object;

A request to the eth_chainId method.

Properties

Property	Type
`method`	`"eth_chainId"`
`params`	[]

WalletDisconnectRequest

type WalletDisconnectRequest = object;

A request to the disconnect the wallet

Properties

Property	Type
`method`	`"wallet_disconnect"`
`params`	[]

SwitchEthereumChainRequest

type SwitchEthereumChainRequest = object;

A request to switch to the specified Ethereum chain

Properties

Property	Type
`method`	`"wallet_switchEthereumChain"`
`params`	[{ `chainId`: `string`; }]

SendCallsRequest

type SendCallsRequest = object;

A request to send one or more calls to the specified Ethereum chain

Properties

Property	Type
`method`	`"wallet_sendCalls"`
`params`	[{ `calls`: `Call`[]; }]

GetCallsStatusRequest

type GetCallsStatusRequest = object;

A request to get the status of one or more calls

Properties

Property	Type
`method`	`"wallet_getCallsStatus"`
`params`	[`0x${string}`]

GetCapabilitiesRequest

type GetCapabilitiesRequest = object;

A request to get the capabilities of the wallet

Properties

Property	Type
`method`	`"wallet_getCapabilities"`
`params`	[]

UnknownRequest

type UnknownRequest = object;

A request to the EIP-1193 provider that we can’t strongly type

Properties

Property	Type
`method`	`string`
`params`	`unknown`[]

ProviderRequest

type ProviderRequest = 
  | AccountsRequest
  | RequestAccountsRequest
  | PersonalSignRequest
  | SendTransactionRequest
  | SignTypedDataRequest
  | EthSignRequest
  | ChainIdRequest
  | WalletDisconnectRequest
  | SwitchEthereumChainRequest
  | SendCallsRequest
  | GetCallsStatusRequest
  | GetCapabilitiesRequest;

A type representing all supported EIP-1193 requests, strongly typed

ExactPartial<T>

type ExactPartial<T> = { [P in keyof T]?: T[P] extends object ? ExactPartial<T[P]> : T[P] };

A type that makes all properties of an object optional.

Type Parameters

Type Parameter	Description
`T`	The type to make partial.

Returns

The partial type.

ProviderState

type ProviderState = object;

The attributes/methods representing the state of the provider

Properties

Property	Type
`chainId`	`number`
`setChainId`	(`chainId`) => `void`
`chains`	readonly [`Chain`, `...Chain[]`]
`user`	`User` \| `null`
`setUser`	(`user`) => `void`

ProviderStoreInstance

type ProviderStoreInstance = Mutate<StoreApi<ProviderState>, [["zustand/subscribeWithSelector", never], ["zustand/persist", ProviderState]]>;

The instance of the Zustand provider store

WalletCapabilities

type WalletCapabilities = object;

The capabilities of the wallet by chainId. If the wallet does not support Smart Account operations on a chain, it will not be included in the object.

Index Signature

[chainId: `0x${string}`]: object

See

https://eips.ethereum.org/EIPS/eip-5792#wallet_getcapabilities

APIErrorType

type APIErrorType = 
  | ErrorType
  | HttpErrorType;

ErrorType

type ErrorType = typeof ErrorType[keyof typeof ErrorType];

HttpErrorType

type HttpErrorType = typeof HttpErrorType[keyof typeof HttpErrorType];

SendEvmTransactionWithEndUserAccountBodyNetwork

type SendEvmTransactionWithEndUserAccountBodyNetwork = typeof SendEvmTransactionWithEndUserAccountBodyNetwork[keyof typeof SendEvmTransactionWithEndUserAccountBodyNetwork];

EIP1193ErrorCode

type EIP1193ErrorCode = typeof STANDARD_ERROR_CODES["provider"][keyof typeof STANDARD_ERROR_CODES["provider"]];

EIP1193-defined error codes

RPCErrorCode

type RPCErrorCode = typeof STANDARD_ERROR_CODES["rpc"][keyof typeof STANDARD_ERROR_CODES["rpc"]];

Standard JSON-RPC error codes

Variables

ErrorType

ErrorType: object;

Type declaration

already_exists

readonly already_exists: "already_exists";

bad_gateway

readonly bad_gateway: "bad_gateway";

faucet_limit_exceeded

readonly faucet_limit_exceeded: "faucet_limit_exceeded";

forbidden

readonly forbidden: "forbidden";

idempotency_error

readonly idempotency_error: "idempotency_error";

internal_server_error

readonly internal_server_error: "internal_server_error";

invalid_request

readonly invalid_request: "invalid_request";

invalid_sql_query

readonly invalid_sql_query: "invalid_sql_query";

invalid_signature

readonly invalid_signature: "invalid_signature";

malformed_transaction

readonly malformed_transaction: "malformed_transaction";

not_found

readonly not_found: "not_found";

payment_method_required

readonly payment_method_required: "payment_method_required";

rate_limit_exceeded

readonly rate_limit_exceeded: "rate_limit_exceeded";

request_canceled

readonly request_canceled: "request_canceled";

service_unavailable

readonly service_unavailable: "service_unavailable";

timed_out

readonly timed_out: "timed_out";

unauthorized

readonly unauthorized: "unauthorized";

policy_violation

readonly policy_violation: "policy_violation";

policy_in_use

readonly policy_in_use: "policy_in_use";

account_limit_exceeded

readonly account_limit_exceeded: "account_limit_exceeded";

network_not_tradable

readonly network_not_tradable: "network_not_tradable";

guest_permission_denied

readonly guest_permission_denied: "guest_permission_denied";

guest_region_forbidden

readonly guest_region_forbidden: "guest_region_forbidden";

guest_transaction_limit

readonly guest_transaction_limit: "guest_transaction_limit";

guest_transaction_count

readonly guest_transaction_count: "guest_transaction_count";

phone_number_verification_expired

readonly phone_number_verification_expired: "phone_number_verification_expired";

document_verification_failed

readonly document_verification_failed: "document_verification_failed";

recipient_allowlist_violation

readonly recipient_allowlist_violation: "recipient_allowlist_violation";

recipient_allowlist_pending

readonly recipient_allowlist_pending: "recipient_allowlist_pending";

travel_rules_recipient_violation

readonly travel_rules_recipient_violation: "travel_rules_recipient_violation";

HttpErrorType

const HttpErrorType: object;

Type declaration

unexpected_error

readonly unexpected_error: "unexpected_error";

unauthorized

readonly unauthorized: "unauthorized";

not_found

readonly not_found: "not_found";

bad_gateway

readonly bad_gateway: "bad_gateway";

service_unavailable

readonly service_unavailable: "service_unavailable";

unknown

readonly unknown: "unknown";

SendEvmTransactionWithEndUserAccountBodyNetwork

SendEvmTransactionWithEndUserAccountBodyNetwork: object;

Type declaration

base

readonly base: "base";

base-sepolia

readonly base-sepolia: "base-sepolia";

ethereum

readonly ethereum: "ethereum";

ethereum-sepolia

readonly ethereum-sepolia: "ethereum-sepolia";

avalanche

readonly avalanche: "avalanche";

polygon

readonly polygon: "polygon";

optimism

readonly optimism: "optimism";

arbitrum

readonly arbitrum: "arbitrum";

STANDARD_ERROR_CODES

const STANDARD_ERROR_CODES: object;

Standard error codes for EIP1193 providers and JSON-RPC methods

Type declaration

rpc

rpc: object;

Type declaration

rpc.invalidInput

invalidInput: -32000;

rpc.resourceNotFound

resourceNotFound: -32001;

rpc.resourceUnavailable

resourceUnavailable: -32002;

rpc.transactionRejected

transactionRejected: -32003;

rpc.methodNotSupported

methodNotSupported: -32004;

rpc.limitExceeded

limitExceeded: -32005;

rpc.parse

parse: -32700;

rpc.invalidRequest

invalidRequest: -32600;

rpc.methodNotFound

methodNotFound: -32601;

rpc.invalidParams

invalidParams: -32602;

rpc.internal

internal: -32603;

provider

provider: object;

Type declaration

provider.userRejectedRequest

userRejectedRequest: 4001;

provider.unauthorized

unauthorized: 4100;

provider.unsupportedMethod

unsupportedMethod: 4200;

provider.disconnected

disconnected: 4900;

provider.chainDisconnected

chainDisconnected: 4901;

provider.unsupportedChain

unsupportedChain: 4902;

SDKs

BUILD ONCHAIN

CONSUMER APIs

INSTITUTIONAL APIs

​Quickstart

​Installation

​Gather your CDP Project information

​Allowlist your local app

​Initialize the SDK

​Smart Account Configuration

​Sign In a User

​View User Information

​Send a Transaction

​Smart Account Operations

​Send User Operations

​Get User Operation Status

​Sign Messages and Typed Data

​Export Private Key

​EIP-1193 Provider

​Viem Accounts

​Functions

​initialize()

​Parameters

​Returns

​Example

​signInWithEmail()

​Parameters

​Returns

​Example

​signInWithSms()

​Parameters

​Returns

​Example

​verifyEmailOTP()

​Parameters

​Returns

​Example

​verifySmsOTP()

​Parameters

​Returns

​Example

​getCurrentUser()

​Returns

​Example

​isSignedIn()

​Returns

​Example

​signOut()

​Returns

​Example

​getAccessToken()

​Returns

​Example

​onAuthStateChange()

​Parameters

​Returns

​Example

​signEvmHash()

​Parameters

​Returns

​Example

​signEvmTransaction()

​Parameters

​Returns

​Example

​sendEvmTransaction()

​Parameters

​Returns

​Example

​signEvmMessage()

​Parameters

​Returns

​Example

​signEvmTypedData()

​Parameters

​Returns

​Example

​sendUserOperation()

​Parameters

​Returns

Quickstart

Installation

Gather your CDP Project information

Allowlist your local app

Initialize the SDK

Smart Account Configuration

Sign In a User

View User Information

Send a Transaction

Smart Account Operations

Send User Operations

Get User Operation Status

Sign Messages and Typed Data

Export Private Key

EIP-1193 Provider

Viem Accounts

Functions

initialize()

Parameters

Returns

Example

signInWithEmail()

Parameters

Returns

Example

signInWithSms()

Parameters

Returns

Example

verifyEmailOTP()

Parameters

Returns

Example

verifySmsOTP()

Parameters

Returns

Example

getCurrentUser()

Returns

Example

isSignedIn()

Returns

Example

signOut()

Returns

Example

getAccessToken()

Returns

Example

onAuthStateChange()

Parameters

Returns

Example

signEvmHash()

Parameters

Returns

Example

signEvmTransaction()

Parameters

Returns

Example

sendEvmTransaction()

Parameters

Returns

Example

signEvmMessage()

Parameters

Returns

Example

signEvmTypedData()

Parameters

Returns

Example

sendUserOperation()

Parameters

Returns

Example

getUserOperation()

Parameters

Returns