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"
  }
}

Changes

Changed in 9 of the 46 revisions of this API.10226

Jun 26, 2026c10a42ebeddb16See the full diff
- ▲
  the /// response's property type changed from string to no type for status
  response-property-type-changed
- ○
  added the new optional header request parameter privy-request-expiry
  new-optional-request-parameter
- ○
  added subschema #2 to the /// response property allOf list for the response status
  response-property-all-of-added
- ○
  removed the 0.6 enum value from the /// response property for the response status
  response-property-enum-value-removed
- ○
  removed the 0.7 enum value from the /// response property for the response status
  response-property-enum-value-removed
- ○
  removed the 0.8 enum value from the /// response property for the response status
  response-property-enum-value-removed
- ○
  removed the 0.9 enum value from the /// response property for the response status
  response-property-enum-value-removed
Jun 23, 20269955c27139f311See the full diff
- ▲
  added to the / response property oneOf list for the response status
  response-property-one-of-added
- ○
  added tvm_transaction discriminator mapping keys to the / response property for the response status
  response-property-discriminator-mapping-added
Jun 16, 20268f9eb26a22481See the full diff
- ○
  added the optional property to the response with the status
  response-optional-property-added
Jun 12, 2026a8d27de9e15d15See the full diff
- ▲
  added to the / response property oneOf list for the response status
  response-property-one-of-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added custodian_transaction discriminator mapping keys to the / response property for the response status
  response-property-discriminator-mapping-added
- ○
  removed the finalized enum value from the //// response property for the response status
  response-property-enum-value-removed
Jun 9, 202602e9839a74d46See the full diff
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  added the optional property /// to the response with the status
  response-optional-property-added
- ○
  removed subschema #2 from the response property allOf list for the response status
  response-property-all-of-removed
- ○
  removed subschema #2 from the response property allOf list for the response status
  response-property-all-of-removed
- ○
  added subschema #2 to the response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the response property anyOf list for the response status
  response-property-any-of-added
Jun 8, 202693c7790da9d36See the full diff
- ▲
  the response property became nullable for the status
  response-property-became-nullable
- ▲
  the response property / became nullable for the status
  response-property-became-nullable
- ▲
  the response property became nullable for the status
  response-property-became-nullable
- ▲
  the response property / became nullable for the status
  response-property-became-nullable
- ▲
  the / response's property type changed from no type to object null for status
  response-property-type-changed
- ▲
  the / response's property type changed from no type to object null for status
  response-property-type-changed
Jun 5, 20262e6aabd41a3c12See the full diff
- ▲
  the request property type changed from number to integer
  request-property-type-changed
- ●
  the request property's max was set to 10000.00
  request-property-max-set
- ●
  the request property's min was set to 0.00
  request-property-min-set
Jun 3, 2026b64a233ab9ee4See the full diff
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
May 29, 202659011037f1253See the full diff
- ○
  added the new optional request property /
  new-optional-request-property
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the optional property to the response with the status
  response-optional-property-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history