---
title: "Swap Tokens"
method: POST
path: "/v1/wallets/{wallet_id}/swap"
tags: ["Swaps"]
---

# Swap Tokens

`POST /v1/wallets/{wallet_id}/swap`

Execute a token swap within a wallet.

## Path parameters

- `wallet_id` string, required — ID of the wallet.

## Headers

- `privy-app-id` string, required — ID of your Privy app.
- `privy-authorization-signature` string — Request authorization signature. If multiple signatures are required, they should be comma separated.
- `privy-request-expiry` string — Request expiry. Value is a Unix timestamp in milliseconds representing the deadline by which the request must be processed.
- `privy-idempotency-key` string — Idempotency keys ensure API requests are executed only once within a 24-hour window.

## Request body

- SwapRequestBody — Input for executing a token swap.
  - `amount_type` 'exact_input' | 'exact_output' — Whether the amount refers to the input token (exact_input) or output token (exact_output).
  - `base_amount` string, required — Amount in base units (e.g., wei for ETH). Must be a non-negative integer string.
  - `destination` SwapDestination, required — The output side of a swap execution request.
    - `asset_address` string, required — Token contract address to buy, or "native" for the chain's native token.
    - `caip2` string — CAIP-2 chain identifier for the destination. Defaults to source chain if omitted. Specify a different chain for cross-chain swaps.
    - `destination_address` string — Address to receive the output tokens. Defaults to the swapping wallet address. Required when swapping between different chain types (e.g. EVM to Solana).
  - `fee_configuration` object — Optional fee configuration for cross-chain swaps. If omitted, cross-chain swaps only charge provider fees.
    - `type` 'total_fee_bps', required — Discriminator: total fee specified in BPS.
    - `value` integer, required — Total fee in basis points (1 bps = 0.01%).
  - `slippage_bps` integer — Maximum slippage tolerance in basis points (e.g., 50 for 0.5%).
  - `source` SwapSource, required — The input side of a swap request, including token and chain.
    - `asset_address` string, required — Token contract address to sell, or "native" for the chain's native token.
    - `caip2` string, required — CAIP-2 chain identifier (e.g., "eip155:1").

## Response `200`

Swap initiated successfully.

- SwapActionResponse — Response for a swap action.
  - `caip2` string, required — CAIP-2 chain identifier for the swap.
  - `created_at` string, date-time, required — ISO 8601 timestamp of when the wallet action was created.
  - `destination_address` string — 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_caip2` string — Destination chain CAIP-2 identifier. Present for cross-chain swaps.
  - `estimated_fees` FeeLineItem[], nullable — Estimated fee breakdown from the provider quote. Only present for cross-chain swaps. Populated after on-chain confirmation.
    - union — An individual fee assessed on a transfer.
      - object — Estimated fee paid to the relayer.
        - `amount` string, required — Amount in USD (in decimals).
        - `recipient` union
          - string
          - string
          - string — Tron address: base58check-encoded, starting with T, 34 characters.
        - `type` 'relayer', required
      - object — Estimated fee paid to Privy.
        - `amount` string, required — Amount in USD (in decimals).
        - `recipient` union
          - string
          - string
          - string — Tron address: base58check-encoded, starting with T, 34 characters.
        - `type` 'privy', required
      - object — Estimated fee paid to the developer.
        - `amount` string, required — Amount in USD (in decimals).
        - `recipient` union
          - string
          - string
          - string — Tron address: base58check-encoded, starting with T, 34 characters.
        - `type` 'developer', required
  - `estimated_gas` Gas — Gas cost for a blockchain action. Includes both raw base-unit amount and a human-readable decimal string, plus the gas token symbol.
    - `amount` string, required — Gas cost in the gas token as a human-readable decimal string (e.g. "0.0001").
    - `base_amount` string, required — Gas cost in the gas token's base units (e.g. wei).
    - `gas_asset` string, required — Gas token symbol (e.g. "ETH", "USDC").
  - `failure_reason` object — Top-level failure context for the wallet action. Present on rejected or failed actions when available.
    - `details` unknown
    - `message` string, required — Human-readable failure message.
  - `fees` FeeLineItem[], nullable — Actual fees paid for the swap. Populated after on-chain confirmation. Only present for cross-chain swaps.
    - union — An individual fee assessed on a transfer.
      - object — Estimated fee paid to the relayer.
        - `amount` string, required — Amount in USD (in decimals).
        - `recipient` union
          - string
          - string
          - string — Tron address: base58check-encoded, starting with T, 34 characters.
        - `type` 'relayer', required
      - object — Estimated fee paid to Privy.
        - `amount` string, required — Amount in USD (in decimals).
        - `recipient` union
          - string
          - string
          - string — Tron address: base58check-encoded, starting with T, 34 characters.
        - `type` 'privy', required
      - object — Estimated fee paid to the developer.
        - `amount` string, required — Amount in USD (in decimals).
        - `recipient` union
          - string
          - string
          - string — Tron address: base58check-encoded, starting with T, 34 characters.
        - `type` 'developer', required
  - `gas` Gas — Gas cost for a blockchain action. Includes both raw base-unit amount and a human-readable decimal string, plus the gas token symbol.
    - `amount` string, required — Gas cost in the gas token as a human-readable decimal string (e.g. "0.0001").
    - `base_amount` string, required — Gas cost in the gas token's base units (e.g. wei).
    - `gas_asset` string, required — Gas token symbol (e.g. "ETH", "USDC").
  - `id` string, required — The ID of the wallet action.
  - `input_amount` string, nullable, required — Exact base-unit amount of input token. Populated after on-chain confirmation.
  - `input_token` string, required — Token address or "native" for the token being sold.
  - `output_amount` string, nullable, required — Exact base-unit amount of output token. Populated after on-chain confirmation.
  - `output_token` string, required — Token address or "native" for the token being bought.
  - `status` 'pending' | 'succeeded' | 'rejected' | 'failed', required — The current status of the wallet action.
  - `steps` WalletActionStep[] — The steps of the wallet action. Only returned if `?include=steps` is provided.
    - union — A step within a wallet action, representing a single onchain action.
      - object — A wallet action step consisting of an EVM transaction.
        - `caip2` string, required — CAIP-2 chain identifier of the transaction, containing the chain ID.
        - `failure_reason` FailureReason — A description of why a wallet action (or a step within a wallet action) failed.
          - `details` unknown
          - `message` string, required — Human-readable failure message.
        - `finalized` boolean — Whether this step has reached on-chain finality. Absent until finality is confirmed.
        - `status` 'preparing' | 'queued' | 'pending' | 'retrying' | 'confirmed' | 'rejected' | 'reverted' | 'replaced' | 'abandoned', required — EVM transaction status.
        - `transaction_hash` string, nullable, required — The transaction hash for this step. May change while the step status is non-terminal.
        - `type` 'evm_transaction', required
      - object — A wallet action step consisting of an EVM user operation.
        - `bundle_transaction_hash` string, nullable, required — Transaction hash of the bundle in which this user operation was included. Null until included by a bundler.
        - `caip2` string, required — CAIP-2 network identifier, containing the chain ID of the user operation.
        - `entrypoint_version` '0.6' | '0.7' | '0.8' | '0.9', required — The entrypoint version of the user operation.
        - `failure_reason` FailureReason — A description of why a wallet action (or a step within a wallet action) failed.
          - `details` unknown
          - `message` string, required — Human-readable failure message.
        - `finalized` boolean — Whether this step has reached on-chain finality. Absent until finality is confirmed.
        - `gas_credits_charged_usd` string — Amount charged in USD for gas sponsorship on this step.
        - `status` 'preparing' | 'queued' | 'pending' | 'retrying' | 'confirmed' | 'rejected' | 'reverted' | 'replaced' | 'abandoned', required — User operation status.
        - `type` 'evm_user_operation', required
        - `user_operation_hash` string, nullable, required — The user operation hash for this step. May change while the step status is non-terminal.
      - object — A wallet action step consisting of an SVM (Solana) transaction.
        - `caip2` string, required — CAIP-2 chain identifier for the Solana network.
        - `failure_reason` FailureReason — A description of why a wallet action (or a step within a wallet action) failed.
          - `details` unknown
          - `message` string, required — Human-readable failure message.
        - `finalized` boolean — Whether this step has reached on-chain finality. Absent until finality is confirmed.
        - `gas_credits_charged_usd` string — Amount charged in USD for gas sponsorship on this step.
        - `status` 'preparing' | 'queued' | 'pending' | 'confirmed' | 'rejected' | 'reverted' | 'failed', required — SVM transaction status.
        - `transaction_signature` string, nullable, required — The Solana transaction signature (base58-encoded). Null until broadcast.
        - `type` 'svm_transaction', required
      - object — A wallet action step consisting of a TVM (Tron) transaction.
        - `caip2` string, required — CAIP-2 chain identifier for the Tron network.
        - `failure_reason` FailureReason — A description of why a wallet action (or a step within a wallet action) failed.
          - `details` unknown
          - `message` string, required — Human-readable failure message.
        - `status` 'preparing' | 'queued' | 'pending' | 'confirmed' | 'rejected' | 'reverted' | 'failed', required — TVM transaction status.
        - `transaction_id` string, nullable, required — The Tron transaction ID. Null until broadcast.
        - `type` 'tvm_transaction', required
      - object — A wallet action step representing a cross-chain/cross-asset fill by an external provider.
        - `failure_reason` FailureReason — A description of why a wallet action (or a step within a wallet action) failed.
          - `details` unknown
          - `message` string, required — Human-readable failure message.
        - `status` 'preparing' | 'queued' | 'pending' | 'confirmed' | 'rejected' | 'failed', required — External transaction step status.
        - `type` 'external_transaction', required
      - object — A wallet action step representing a transaction executed by a custodian (e.g. Bridge).
        - `custodian` string, required — Identifier of the custodian executing this transaction (e.g. "bridge").
        - `failure_reason` FailureReason — A description of why a wallet action (or a step within a wallet action) failed.
          - `details` unknown
          - `message` string, required — Human-readable failure message.
        - `status` 'preparing' | 'queued' | 'custodian_reviewing' | 'pending' | 'confirmed' | 'rejected' | 'failed', required — Custodian transaction step status.
        - `type` 'custodian_transaction', required
  - `type` 'swap', required
  - `wallet_id` string, required — The ID of the wallet involved in the action.

---

[API](https://skmtc.net/privy-io/apis/privy-api.md) · [All operations](https://skmtc.net/privy-io/apis/privy-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/privy-io/privy-api/revisions/bb2eb34156cc/schema)