Skip to main content
Execute a swap using the swap endpoint. Privy automates token approvals and transaction submission. The response is a wallet action that starts in pending status and can be polled for confirmation.
View the full API reference for the swap endpoint.

Usage

Use the swap method from the useSwap hook to swap tokens from a user’s embedded wallet.
useSwap is supported starting in @privy-io/react-auth@3.51.4.

React and React Native parameters

In both SDKs, swap(walletId, params) accepts the embedded wallet’s ID, not its blockchain address, and an object with the body fields below. Replace the example token placeholders with contracts deployed on Tempo. base_amount uses the token’s smallest unit, not a human-readable decimal amount. The hook signs the request with the user’s signer. Never include app secrets or authorization private keys in client-side code. It returns a Promise for a SwapActionResponse with status: 'pending', without waiting for onchain confirmation. Use action.id with getAction from useWalletActions to track completion. For a cross-chain swap from Tempo to Solana, use the following destination in either SDK example:
destination.destination_address is required when swapping between EVM and Solana. See supported routes.

Body

The SDK params object and REST request body accept the following fields:
object
required
The source token and chain.
object
required
The destination token and chain.
string
required
Amount in base units (e.g., wei for ETH, lamports for SOL, or the token’s smallest unit).
'exact_input' | 'exact_output'
Whether base_amount refers to the input or output token. Defaults to exact_input.
number
Maximum slippage tolerance in basis points (e.g., 50 for 0.5%). If omitted, auto-slippage is used.
object
Optional developer fee configuration. Only applies to cross-chain swaps.
When using auto-slippage (omitting slippage_bps), an appropriate tolerance is determined based on the tokens and current market conditions. For large swaps or volatile token pairs, consider setting an explicit slippage_bps value and reviewing the minimum_output_amount from the quote response before executing.

Response

string
The ID of the wallet action.
'pending' | 'succeeded' | 'rejected' | 'failed'
The current status of the wallet action.
string
The ID of the wallet involved in the swap.
string
CAIP-2 identifier for the source chain.
string
Token address being sold.
string
Token address being bought.
string
Amount of input token in base units. Populated after confirmation.
string
Amount of output token received in base units. Populated after confirmation.
string
CAIP-2 identifier for the destination chain. Present for cross-chain swaps only.
string
The address receiving output tokens on the destination chain. Present when destination.destination_address was specified. Cross-chain swaps only.
FeeLineItem[]
Estimated fee breakdown at the time of execution. Each item has a type (relayer, or developer) and an amount in USD. Items of type developer include a recipient address. Present for cross-chain swaps only.
object
Estimated gas cost at the time of execution. Contains base_amount, amount, and gas_asset fields. Present for cross-chain swaps only.
FeeLineItem[]
Actual fees paid. Populated after the swap is confirmed. Same structure as estimated_fees. Present for cross-chain swaps only.
object
Actual gas paid. Populated after the swap is confirmed. Same structure as estimated_gas. Present for cross-chain swaps only.