Sign in

v46

latestOpenAPI 3.1.0raw.githubusercontent.com2026-07-211591,0051.4 MB
Swaps

Swap Tokens

Execute a token swap within a wallet.

post/v1/wallets/{wallet_id}/swap

Path parameters

wallet_idstring required

ID of the wallet.

Headers

privy-app-idstring required

ID of your Privy app.

privy-authorization-signaturestring

Request authorization signature. If multiple signatures are required, they should be comma separated.

privy-request-expirystring

Request expiry. Value is a Unix timestamp in milliseconds representing the deadline by which the request must be processed.

privy-idempotency-keystring

Idempotency keys ensure API requests are executed only once within a 24-hour window.

Request body

amount_type'exact_input' | 'exact_output'

Whether the amount refers to the input token (exact_input) or output token (exact_output).

base_amountstring required

Amount in base units (e.g., wei for ETH). Must be a non-negative integer string.

slippage_bpsinteger

Maximum slippage tolerance in basis points (e.g., 50 for 0.5%).

Example request

{
  "amount_type": "exact_input",
  "base_amount": "1000000000000000000",
  "destination": {
    "asset_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "caip2": "eip155:1"
  },
  "slippage_bps": 50,
  "source": {
    "asset_address": "native",
    "caip2": "eip155:1"
  }
}

Response

Swap initiated successfully.

caip2string required

CAIP-2 chain identifier for the swap.

created_atstring date-time required

ISO 8601 timestamp of when the wallet action was created.

destination_addressstring

Recipient address on the destination chain. Present for cross-chain swaps. May differ from the source wallet address when swapping between chain types (e.g. EVM to Solana).

destination_caip2string

Destination chain CAIP-2 identifier. Present for cross-chain swaps.

idstring required

The ID of the wallet action.

input_amountstring nullable required

Exact base-unit amount of input token. Populated after on-chain confirmation.

input_tokenstring required

Token address or "native" for the token being sold.

output_amountstring nullable required

Exact base-unit amount of output token. Populated after on-chain confirmation.

output_tokenstring required

Token address or "native" for the token being bought.

status'pending' | 'succeeded' | 'rejected' | 'failed' required

The current status of the wallet action.

type'swap' required
wallet_idstring required

The ID of the wallet involved in the action.

Example response

{
  "estimated_fees": [
    {
      "amount": "0.20",
      "recipient": "0x1234567890abcdef1234567890abcdef12345678",
      "type": "relayer"
    }
  ],
  "estimated_gas": {
    "amount": "0.0001",
    "base_amount": "100000000000000",
    "gas_asset": "ETH"
  },
  "fees": [
    {
      "amount": "0.20",
      "recipient": "0x1234567890abcdef1234567890abcdef12345678",
      "type": "relayer"
    }
  ],
  "gas": {
    "amount": "0.0001",
    "base_amount": "100000000000000",
    "gas_asset": "ETH"
  }
}