Installation
API Keys
To start, create a CDP API Key. Save theAPI Key ID
and API Key Secret
for use in the SDK. You will also need to create a wallet secret in the Portal to sign transactions.
Usage
Initialization
Load client config from shell
One option is to export your CDP API Key and Wallet Secret as environment variables:Load client config from .env
file
Another option is to save your CDP API Key and Wallet Secret in a .env
file:
.env
file:
Pass the API Key and Wallet Secret to the client
Another option is to directly pass the API Key and Wallet Secret to the client:Creating EVM or Solana accounts
Create an EVM account as follows:
Import an EVM account as follows:
Create a Solana account as follows:
Import a Solana account as follows:
Exporting EVM or Solana accounts
Export an EVM account as follows:
Export a Solana account as follows:
Get or Create an EVM account as follows:
Get or Create a Solana account as follows:
Get or Create a Smart Account as follows:
Creating EVM or Solana accounts with policies
Create an EVM account with policy as follows:
Create a Solana account with policy as follows:
Updating EVM or Solana accounts
Update an EVM account as follows:
Update a Solana account as follows:
Testnet faucet
You can use the faucet function to request testnet ETH or SOL from the CDP.Request testnet ETH as follows:
Request testnet SOL as follows:
Sending transactions
EVM
You can use CDP SDK to send transactions on EVM networks.walletClient
to send transactions.
Solana
You can use CDP SDK to send transactions on Solana. For complete examples, check out sendTransaction.ts, sendManyTransactions.ts, and sendManyBatchedTransactions.ts.EVM Smart Accounts
For EVM, we support Smart Accounts which are account-abstraction (ERC-4337) accounts. Currently there is only support for Base Sepolia and Base Mainnet for Smart Accounts.Create an EVM account and a smart account as follows:
Sending User Operations
In Base Sepolia, all user operations are gasless by default. If you’d like to specify a different paymaster, you can do so as follows:
EVM Swaps
You can use the CDP SDK to swap tokens on EVM networks using both regular accounts (EOAs) and smart accounts. The SDK provides three approaches for performing token swaps:1. All-in-one pattern (Recommended)
The simplest approach for performing swaps. Creates and executes the swap in a single line of code: Regular Account (EOA):2. Get pricing information
UsegetSwapPrice
for quick price estimates and display purposes. This is ideal for showing exchange rates without committing to a swap:
getSwapPrice
does not reserve funds or signal commitment to swap, making it suitable for more frequent price updates with less strict rate limiting - although the data may be slightly less precise.
3. Create and execute separately
Useaccount.quoteSwap()
/ smartAccount.quoteSwap()
when you need full control over the swap process. This returns complete transaction data for execution:
Important: quoteSwap()
signals a soft commitment to swap and may reserve funds on-chain. It is rate-limited more strictly than getSwapPrice
to prevent abuse.
Regular Account (EOA):
When to use each approach:
- All-in-one (
account.swap()
/smartAccount.swap()
): Best for most use cases. Simple, handles everything automatically. - Price only (
getSwapPrice
): For displaying exchange rates, building price calculators, or checking liquidity without executing. Suitable when frequent price updates are needed - although the data may be slightly less precise. - Create then execute (
account.quoteSwap()
/smartAccount.quoteSwap()
): When you need to inspect swap details, implement custom logic, or handle complex scenarios before execution. Note: May reserve funds on-chain and is more strictly rate-limited.
Key differences between Regular Accounts (EOAs) and Smart Accounts:
- Regular accounts (EOAs) return
transactionHash
and execute immediately on-chain - Smart accounts return
userOpHash
and execute via user operations with optional gas sponsorship through paymasters - Smart accounts require an owner account for signing operations
- Smart accounts support batch operations and advanced account abstraction features
Example implementations
To help you get started with token swaps in your application, we provide the following fully-working examples demonstrating different scenarios: Regular account (EOA) swap examples:- Execute a swap transaction using account (RECOMMENDED) - All-in-one regular account swap execution
- Quote swap using account convenience method - Account convenience method for creating quotes
- Two-step quote and execute process - Detailed two-step approach with analysis
- Swap with network hoisting - All-in-one swap and two-step approach swap for EVM chains
- Execute a swap transaction using smart account (RECOMMENDED) - All-in-one smart account swap execution with user operations and optional paymaster support
- Quote swap using smart account convenience method - Smart account convenience method for creating quotes
- Two-step quote and execute process - Detailed two-step approach with analysis
- Smart account swap with network hoisting - All-in-one smart account swap and two-step approach smart account swap for EVM chains
- Execute a swap transaction using viem account - All-in-one swap execution with viem wallets
- Two-step quote and execute process using viem account - Detailed two-step approach with viem wallets
- Execute a swap transaction using viem smart account - All-in-one smart account swap with custom bundler/paymaster setup
- Two-step quote and execute process using viem smart account - Advanced account abstraction integration
permissionless
package) and external service setup (bundler, optional paymaster). For simpler smart account usage, consider CDP’s built-in smart account features instead.
Transferring tokens
EVM
For complete examples, check out evm/account.transfer.ts and evm/smartAccount.transfer.ts. You can transfer tokens between accounts using thetransfer
function:
transfer
function:
transfer
function returns the user operation hash, which is different from the transaction hash. You can use the returned user operation hash in a call to waitForUserOperation
to get the result of the transaction:
parseEther
and parseUnits
from viem.
usdc
or eth
as the token to transfer, or you can pass a contract address directly:
to
parameter:
Solana
For complete examples, check out solana/account.transfer.ts. You can transfer tokens between accounts using thetransfer
function, and wait for the transaction to be confirmed using the confirmTransaction
function from @solana/web3.js
:
network
parameter:
Account Actions
Account objects have actions that can be used to interact with the account. These can be used in place of thecdp
client.
EVM account actions
Here are some examples for actions on EVM accounts. For example, instead of:listTokenBalances
action:
listTokenBalances
requestFaucet
signTransaction
sendTransaction
transfer
listTokenBalances
requestFaucet
sendUserOperation
waitForUserOperation
getUserOperation
transfer
Solana account actions
Here are some examples for actions on Solana accounts.signMessage
action:
requestFaucet
signMessage
signTransaction
Policy Management
You can use the policies SDK to manage sets of rules that govern the behavior of accounts and projects, such as enforce allowlists and denylists.Create a Project-level policy that applies to all accounts
This policy will accept any account sending less than a specific amount of ETH to a specific address.Create an Account-level policy
This policy will accept any transaction with a value less than or equal to 1 ETH to a specific address.Create a Solana Allowlist Policy
List Policies
You can filter by account:Retrieve a Policy
Update a Policy
This policy will update an existing policy to accept transactions to any address except one.Delete a Policy
[!WARNING] Attempting to delete an account-level policy in-use by at least one account will fail.
Validate a Policy
If you’re integrating policy editing into your application, you may find it useful to validate policies ahead of time to provide a user with feedback. TheCreatePolicyBodySchema
and UpdatePolicyBodySchema
can be used to get actionable structured information about any issues with a policy. Read more about handling ZodErrors.
Supported Policy Rules
We currently support the following policy rules:- SignEvmTransactionRule
- SendEvmTransactionRule
- SignEvmMessageRule
- SignEvmTypedDataRule
- SignSolanaTransactionRule
- SendSolanaTransactionRule
- SignEvmHashRule
- PrepareUserOperationRule
- SendUserOperationRule
End-user Management
You can use the End User SDK to manage the users of your applications.Validate Access Token
When your end user has signed in with an Embedded Wallet, you can check whether the access token they were granted is valid, and which of your user’s it is associated with.Authentication tools
This SDK also contains simple tools for authenticating REST API requests to the Coinbase Developer Platform (CDP). See the Auth README for more details.Error Reporting
This SDK contains error reporting functionality that sends error events to CDP. If you would like to disable this behavior, you can set theDISABLE_CDP_ERROR_REPORTING
environment variable to true
.
Usage Tracking
This SDK contains usage tracking functionality that sends usage events to CDP. If you would like to disable this behavior, you can set theDISABLE_CDP_USAGE_TRACKING
environment variable to true
.
License
This project is licensed under the MIT License - see the LICENSE file for details.Support
For feature requests, feedback, or questions, please reach out to us in the #cdp-sdk channel of the Coinbase Developer Platform Discord.Security
If you discover a security vulnerability within this SDK, please see our Security Policy for disclosure information.FAQ
Common errors and their solutions.AggregateError [ETIMEDOUT]
This is an issue in Node.js itself: https://github.com/nodejs/node/issues/54359. While the fix is implemented, the workaround is to set the environment variable:Error [ERR_REQUIRE_ESM]: require() of ES modules is not supported.
Use Node v20.19.0 or higher. CDP SDK depends on jose v6, which ships only ESM. Jose supports CJS style imports in Node.js versions where the require(esm) feature is enabled by default (^20.19.0 || ^22.12.0 || >= 23.0.0). See here for more info.Jest encountered an unexpected token
If you’re using Jest and see an error like this:jest.setup.ts
next to your jest.config
file with the following content:
jest.config
file: