> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute a swap

> Execute a token swap with automated token approvals and transaction submission

Execute a swap using the swap endpoint. Privy automates token approvals and transaction submission. The response is a [wallet action](/wallets/actions/overview) that starts in `pending` status and can be polled for confirmation.

<Info>
  View the full [API reference](/api-reference/wallets/swap/tokens) for the swap endpoint.
</Info>

## Usage

To execute a swap, make a `POST` request to:

```bash theme={"system"}
https://api.privy.io/v1/wallets/{wallet_id}/swap
```

Wallets with explicit [owners or signers](/controls/authorization-keys/owners/overview) must provide
an [authorization signature](/api-reference/authorization-signatures) as a request header.

<View title="REST API" icon="terminal">
  ### Body

  <ParamField body="source" type="object" required>
    The source token and chain.

    <Expandable title="properties" defaultOpen>
      <ParamField body="source.caip2" type="string" required>
        CAIP-2 identifier for the source chain (e.g., `eip155:8453` for Base). See [supported
        chains](/wallets/actions/swap/overview#supported-chains).
      </ParamField>

      <ParamField body="source.asset_address" type="string" required>
        Token address to sell, or `"native"` for the chain's native token.
      </ParamField>
    </Expandable>
  </ParamField>

  <ParamField body="destination" type="object" required>
    The destination token and chain.

    <Expandable title="properties" defaultOpen>
      <ParamField body="destination.asset_address" type="string" required>
        Token address to receive, or `"native"` for the chain's native token.
      </ParamField>

      <ParamField body="destination.caip2" type="string">
        CAIP-2 identifier for the destination chain. Omit for a same-chain swap. Set to a different
        chain for a cross-chain swap. See [supported
        routes](/wallets/actions/swap/overview#cross-chain-swaps).
      </ParamField>

      <ParamField body="destination.destination_address" type="string">
        Address to receive the output tokens on the destination chain. Required when swapping between
        different chain types (e.g. EVM and Solana). Defaults to the source wallet address otherwise.
      </ParamField>
    </Expandable>
  </ParamField>

  <ParamField body="base_amount" type="string" required>
    Amount in base units (e.g., wei for ETH, lamports for SOL, or the token's smallest unit).
  </ParamField>

  <ParamField body="amount_type" type="'exact_input' | 'exact_output'">
    Whether `base_amount` refers to the input or output token. Defaults to `exact_input`.
  </ParamField>

  <ParamField body="slippage_bps" type="number">
    Maximum slippage tolerance in basis points (e.g., `50` for 0.5%). If omitted, auto-slippage is
    used.
  </ParamField>

  <ParamField body="fee_configuration" type="object">
    Optional developer fee configuration. Only applies to cross-chain swaps.

    <Expandable title="properties">
      <ParamField body="fee_configuration.type" type="'total_fee_bps'" required>
        The fee model to apply. Currently only `total_fee_bps` is supported.
      </ParamField>

      <ParamField body="fee_configuration.value" type="number" required>
        Total fee cap in basis points (0–10000). Relayer and developer fees must fit within this cap.
        For example, `80` represents 0.8%.
      </ParamField>
    </Expandable>
  </ParamField>

  <Warning>
    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](/wallets/actions/swap/get-quote) before executing.
  </Warning>

  ### Response

  <ResponseField name="id" type="string">
    The ID of the wallet action.
  </ResponseField>

  <ResponseField name="status" type="'pending' | 'succeeded' | 'rejected' | 'failed'">
    The current status of the wallet action.
  </ResponseField>

  <ResponseField name="wallet_id" type="string">
    The ID of the wallet involved in the swap.
  </ResponseField>

  <ResponseField name="caip2" type="string">
    CAIP-2 identifier for the source chain.
  </ResponseField>

  <ResponseField name="input_token" type="string">
    Token address being sold.
  </ResponseField>

  <ResponseField name="output_token" type="string">
    Token address being bought.
  </ResponseField>

  <ResponseField name="input_amount" type="string">
    Amount of input token in base units. Populated after confirmation.
  </ResponseField>

  <ResponseField name="output_amount" type="string">
    Amount of output token received in base units. Populated after confirmation.
  </ResponseField>

  <ResponseField name="destination_caip2" type="string">
    CAIP-2 identifier for the destination chain. Present for cross-chain swaps only.
  </ResponseField>

  <ResponseField name="destination_address" type="string">
    The address receiving output tokens on the destination chain. Present when
    `destination.destination_address` was specified. Cross-chain swaps only.
  </ResponseField>

  <ResponseField name="estimated_fees" type="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.
  </ResponseField>

  <ResponseField name="estimated_gas" type="object">
    Estimated gas cost at the time of execution. Contains `base_amount`, `amount`, and `gas_asset`
    fields. Present for cross-chain swaps only.
  </ResponseField>

  <ResponseField name="fees" type="FeeLineItem[]">
    Actual fees paid. Populated after the swap is confirmed. Same structure as `estimated_fees`.
    Present for cross-chain swaps only.
  </ResponseField>

  <ResponseField name="gas" type="object">
    Actual gas paid. Populated after the swap is confirmed. Same structure as `estimated_gas`. Present
    for cross-chain swaps only.
  </ResponseField>

  ### Examples

  <Tabs>
    <Tab title="Same-chain">
      ```bash theme={"system"}
      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 '{
          "source": {
            "caip2": "eip155:8453",
            "asset_address": "native"
          },
          "destination": {
            "asset_address": "0x<erc20-token-address>"
          },
          "base_amount": "1000000000000000000",
          "amount_type": "exact_input"
        }'
      ```

      ```json Example response theme={"system"}
      {
        "id": "cm7oxq1el000e11o8iwp7d0d0",
        "status": "pending",
        "wallet_id": "fmfdj6yqly31huorjqzq38zc",
        "caip2": "eip155:8453",
        "input_token": "native",
        "output_token": "0x<erc20-token-address>",
        "input_amount": null,
        "output_amount": null
      }
      ```
    </Tab>

    <Tab title="Cross-chain">
      ```bash theme={"system"}
      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 '{
          "source": {
            "caip2": "eip155:8453",
            "asset_address": "native"
          },
          "destination": {
            "caip2": "eip155:42161",
            "asset_address": "native"
          },
          "base_amount": "1000000000000000000",
          "amount_type": "exact_input"
        }'
      ```

      ```json Example response theme={"system"}
      {
        "id": "cm7oxq1el000e11o8iwp7d0d0",
        "status": "pending",
        "wallet_id": "fmfdj6yqly31huorjqzq38zc",
        "caip2": "eip155:8453",
        "input_token": "native",
        "output_token": "native",
        "input_amount": null,
        "output_amount": null,
        "destination_caip2": "eip155:42161",
        "estimated_fees": [{ "type": "relayer", "amount": "0.50" }],
        "estimated_gas": {
          "base_amount": "210000000000000",
          "amount": "0.00021",
          "gas_asset": "ETH"
        }
      }
      ```
    </Tab>
  </Tabs>
</View>