Overview
An onchain trade (otherwise known as a swap) is a transaction that exchanges one token for another. In this guide, you will learn how to:- Estimate a swap price
- Execute a swap with regular accounts (EOAs) or Smart Accounts
The Beta launch of our Trade API supports Ethereum and Base mainnet networks only - stay tuned for additional network support!
Price estimation
The SDK provides two methods for estimating swap prices:Method | Use Case | Function |
---|---|---|
Quick estimate | UI displays, real-time rates, liquidity checks | - getSwapPrice (Ts)- get_swap_price (Py) |
Swap quote | Pre-execution, approvals, custom handling | - quoteSwap (Ts)- quote_swap (Py) |
CDP vs. external libraries
You can execute swaps using either:-
CDP Wallet Integration (Recommended for most use cases)
- Use our managed wallet infrastructure
- Automatic transaction signing and submission
- Built-in security and compliance features
- Smart Account support with gas sponsorship via paymasters
- See the Server Wallet v2 guide for details on setup and the Server Wallet Swaps guide for more information on executing swaps
- External Library Integration (For custom infrastructure)
Slippage
Slippage is the difference between the expected price of a trade and the actual price at which it executes.More on slippage protection
More on slippage protection
In these examples, we set a 1% slippage tolerance (using
slippageBps: 100
in TypeScript or slippage_bps: 100
in Python), meaning the trade will only execute if the final price is within 1% of the expected price.This protects you from unfavorable trades if the price moves significantly between when you submit the transaction and when itβs executed.Prerequisites
It is assumed you have:- Node.js 22.x+ if using Typescript
- Python 3.10+ if using Python
- Created and signed in to an existing CDP account
- Created the necessary keys to authenticate requests (see the prerequisites section in v2 Server Wallet for setup instructions)
- (Optional) For Smart Accounts: Understanding of account abstraction (ERC-4337) concepts
Regular Accounts (EOAs)
1. Estimate a swap price
To begin, letβs walk through an example of how to estimate a swap price with a regular account (EOA).getSwapPrice
for Typescript and get_swap_price
for Python provide estimates only and do not reserve funds. They are suitable for frequent price updates but may be less precise than creating a swap quote.2. Create a swap quote
Once youβre ready to commit to a swap, you can create a swap quote using the CDP API. This gives you the transaction data needed for execution as opposed to the quick price estimate that we demonstrated above.Creating a swap quote may reserve funds onchain. This action is strictly rate-limited.
3. Execute a swap
Now that we have a swap quote, we can execute it onchain. The easiest way to do this is by using CDP Wallets. We also offer a smoother developer experience using our Server Wallet. Read the Server Wallet Swaps guide for more information.All-in-one swapYou can also create and execute a swap in a single call using
account.swap()
:- Quote & Execute: TypeScript | Python
- All-in-one: TypeScript | Python
Smart Accounts
Smart Accounts provide additional features like gas sponsorship and batch operations. The key differences are:- Use the Smart Account address (not the ownerβs EOA) as the
taker
- Transactions return
userOpHash
instead oftransactionHash
- Must wait for user operations to complete
1. Estimate a swap price
When estimating prices for Smart Accounts, use the Smart Account address as thetaker
:
2. Create a swap quote
Once youβre ready to commit to a swap, you can create a swap quote using the CDP API. This gives you the transaction data needed for execution as opposed to the quick price estimate that we demonstrated above.Creating a swap quote may reserve funds onchain. This action is strictly rate-limited.
3. Execute a swap
Now that we have a swap quote, we can execute it onchain. The easiest way to do this is by using CDP Wallets. Executing swaps with Smart Accounts returns a user operation hash instead of a transaction hash. You must wait for the user operation to complete:All-in-one swapYou can also create and execute a swap in a single call using
smartAccount.swap()
:- Quote & Execute: TypeScript | Python
- All-in-one: TypeScript | Python
Smart Account Benefits
- Gas Sponsorship: Use paymasters to pay gas fees on behalf of users
- Batch Operations: Combine multiple swaps or operations in one transaction
- Account Abstraction: Enhanced UX with features like session keys and social recovery
- Security: Multi-signature capabilities and spending limits
Using External Wallets
If you prefer to use your own wallet, signing infrastructure, and node for broadcasting transactions, you can use the core Trade APIs (likegetSwapPrice
and quoteSwap
) without a CDP account.
π Full examples: TypeScript | Python
Custom Wallet IntegrationIf youβre using your own wallet infrastructure (e.g., viem, web3.py, etc.), you can execute swaps using the transaction data from the quote. For Smart Accounts with external wallets, additional ERC-4337 infrastructure setup is required.
What to read next
- Welcome: Read why Trade API is easier to use than traditional aggregator solutions.
- API Reference: Explore the full CDP API v2 documentation.
- Server Wallet v2: Learn more about our new Server Wallet, including account management and transaction signing.
- USDC Rewards: Learn how to earn 4.1% rewards on USDC balances in your CDP wallets.