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

To execute a swap via REST API, make a POST request to:
https://api.privy.io/v1/wallets/{wallet_id}/swap

​
Body

​
caip2
string
required
Chain identifier in CAIP-2 format (e.g., eip155:8453 for Base). See supported chains.
​
input_token
string
required
Token address to sell, or "native" for the chain’s native token.
​
output_token
string
required
Token address to buy, or "native" for the chain’s native token. Must be different from input_token.
​
amount
string
required
Amount in base units (e.g., wei for ETH).
​
amount_type
'exact_input' | 'exact_output'
Whether amount refers to the input or output token. Defaults to exact_input.
​
slippage_bps
number
Maximum slippage tolerance in basis points (e.g., 50 for 0.5%). If omitted, auto-slippage is used.
​
recipient
string
Address to receive the output tokens. Defaults to the wallet address if not specified.
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

The response includes the following fields:
​
id
string
The ID of the wallet action.
​
status
'pending' | 'succeeded' | 'rejected' | 'failed'
The current status of the wallet action.
​
wallet_id
string
The ID of the wallet involved in the swap.
​
caip2
string
Chain identifier.
​
input_token
string
Token address being sold.
​
output_token
string
Token address being bought.
​
input_amount
string
Amount of input token in base units.

​
Example

Wallets with explicit owners or signers must provide an authorization signature as a request header.
curl -X POST https://api.privy.io/v1/wallets/{wallet_id}/swap \
  -u "<your-app-id>:<your-app-secret>" \
  -H "privy-app-id: <your-app-id>" \
  -H "privy-authorization-signature: <authorization-signature>" \
  -H "Content-Type: application/json" \
  -d '{
    "caip2": "eip155:8453",
    "input_token": "native",
    "output_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "1000000000000000000",
    "amount_type": "exact_input"
  }'
Example response
{
  "id": "cm7oxq1el000e11o8iwp7d0d0",
  "status": "pending",
  "wallet_id": "fmfdj6yqly31huorjqzq38zc",
  "caip2": "eip155:8453",
  "input_token": "native",
  "output_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "input_amount": "1000000000000000000"
}