Skip to main content
POST
Transfer
If your app has gas sponsorship configured, usage of the /transfer endpoint will be gas-sponsored by default. There is no need to specify additional parameters for sponsorship.
Cross-chain and cross-asset transfers accept an optional fee_configuration parameter to control fee distribution between Privy and your app. Use the quote endpoint to preview fees before executing a transfer.
Idempotency on errors: This endpoint returns pending immediately. Replaying the same key returns the cached response. On a synchronous 5xx, Privy deletes the record so the same key retries fresh. Action outcomes (rejected, failed, succeeded) arrive via webhooks and polling. Policy violations always allow fresh retries.

Authorizations

Authorization
string
header
required

Basic Auth header with your app ID as the username and your app secret as the password.

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.

Path Parameters

wallet_id
string
required

ID of the wallet.

Body

application/json

Request body for initiating a sponsored token transfer from an embedded wallet.

source
NamedTokenTransferSource · object
required

Source for a transfer identified by a named asset (e.g. "usdc", "eth"). Use this variant for first-class assets maintained by Privy.

Example:
destination
TokenTransferDestination · object
required

The destination address for a token transfer. Optionally specify a different asset or chain for cross-asset or cross-chain transfers.

Example:
amount
string

Amount as a decimal string in the token's standard unit (e.g. "1.5" for 1.5 USDC). For exact_input, the amount to send. For exact_output, the exact amount to receive. Takes precedence over source.amount when both are provided.

Maximum string length: 100
amount_type
enum<string>

Whether the amount refers to the input token or output token.

Available options:
exact_input,
exact_output
slippage_bps
integer

Maximum allowed slippage in basis points (1 bps = 0.01%). Only applicable for cross-chain or cross-asset transfers; omit to use the provider default.

Required range: 0 <= x <= 10000
fee_configuration
FeeConfiguration · object

Optional fee configuration for the transfer. If omitted, cross-chain transfers will not charge additional fees.

Example:

Response

200 - application/json

Transfer initiated successfully.

Response for a transfer action.

id
string
required

The ID of the wallet action.

status
enum<string>
required

The current status of the wallet action.

Available options:
pending,
succeeded,
rejected,
failed
wallet_id
string
required

The ID of the wallet involved in the action.

created_at
string<date-time>
required

ISO 8601 timestamp of when the wallet action was created.

type
enum<string>
required
Available options:
transfer
source_chain
string
required

Chain name (e.g. "tempo", "base").

destination_address
string
required

Recipient address.

destination_amount
string | null
required

Amount received on the destination chain. For exact_output cross-chain transfers, set at creation (the guaranteed exact amount). For exact_input cross-chain transfers, null until fill confirmation.

failure_reason
FailureReason · object

Top-level failure context for the wallet action. Present on rejected or failed actions when available.

steps
(EVMTransactionWalletActionStep · object | EVMUserOperationWalletActionStep · object | SVMTransactionWalletActionStep · object | TVMTransactionWalletActionStep · object | ExternalTransactionWalletActionStep · object | CustodianTransactionWalletActionStep · object)[]

The steps of the wallet action. Only returned if ?include=steps is provided.

A wallet action step consisting of an EVM transaction.

amount_type
enum<string>

Whether the amount refers to the input token or output token.

Available options:
exact_input,
exact_output
source_asset
string

Asset identifier (e.g. "usdc", "eth"). Present when the transfer was initiated with a named asset; omitted for custom-token transfers.

source_asset_address
string

Token contract address (EVM) or mint address (Solana). Present when the transfer was initiated with asset_address.

source_asset_decimals
integer

Number of decimals for the transferred token. Present when the transfer was initiated with asset_address and the decimals were resolved on-chain.

source_amount
string

Decimal amount sent on the source chain (e.g. "1.5"). For exact_output cross-chain transfers, null until fill confirmation.

destination_asset
string

Destination asset for cross-asset transfers. Omitted for same-asset transfers.

destination_chain
string

Destination chain for cross-chain transfers. Omitted for same-chain transfers.

estimated_fees
(RelayerFee · object | PrivyFee · object | DeveloperFee · object)[] | null

Estimated fee breakdown from the provider quote. Only present for cross-chain or cross-asset transfers. Populated after on-chain confirmation.

Estimated fee paid to the relayer.

Example:
estimated_gas
Gas · object | null

Estimated source-chain gas cost from the provider quote. Only present for cross-chain or cross-asset transfers. Populated after on-chain confirmation.

Example:
fees
(RelayerFee · object | PrivyFee · object | DeveloperFee · object)[] | null

Actual fees paid for the transfer. Populated after on-chain confirmation. Only present for cross-chain transfers.

Estimated fee paid to the relayer.

Example:
gas
Gas · object | null

Actual source-chain gas cost. Populated after on-chain confirmation. Only present for cross-chain transfers.

Example: