Usage - Privy Docs

To execute a transfer, make a POST request to /v1/wallets/{wallet_id}/transfer.

Body

In the body of the request, pass the following parameters.

source

object

required

The source asset, amount, and chain for the transfer. Specify either asset (for named assets) or asset_address (for custom tokens), not both.

Hide properties

source.asset

string

The named asset to transfer. Must be one of the listed well-known assets. Provide either asset or asset_address.

source.asset_address

string

The token contract address (EVM) or mint address (Solana) of the asset to transfer. Use this field for tokens that are not first-class named assets. Provide either asset or asset_address.

source.amount

string

required

The amount of tokens to transfer, as a decimal string in standard units (e.g. "10.0" for 10 USDC). The API handles decimal precision based on the asset — most stablecoins like USDC use 6 decimal places, while native tokens like ETH use 18 and SOL uses 9. There is no need to convert to the smallest unit (e.g. wei, lamports, or micro-units) before sending the request.

source.chain

string

required

The chain to transfer from. Must be one of the listed supported chains.

destination

object

required

The destination for the transfer.

Hide properties

destination.address

string

required

The recipient wallet address. Use a hex address for EVM chains and a base58 address for Solana.

destination.asset

string

The destination asset. Must be one of the listed well-known assets. Required for cross-asset transfers (e.g. transferring usdt on the source and receiving usdc on the destination).

destination.chain

string

The destination chain. Must be one of the listed supported chains. Required for cross-chain transfers (e.g. transferring from tempo and receiving on arbitrum).

amount

string

Amount as a decimal string in standard units (e.g. "10.0" for 10 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.

amount_type

'exact_input' | 'exact_output'

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

exact_input — the specified amount is deducted from the source wallet; the destination amount varies based on fees and bridge pricing.
exact_output — the recipient receives exactly the specified amount; the source amount is determined by the bridge provider and may be higher due to fees.

Exact output is only supported for cross-chain or cross-asset (DADC) transfers on EVM source chains. Solana is not supported as a source chain for exact output.

slippage_bps

integer

The maximum allowed slippage in basis points (1 bps = 0.01%). Must be between 0 and 10000. Only applies to cross-chain and cross-asset transfers. If omitted, an appropriate slippage tolerance is automatically determined based on current market conditions. See slippage for details.

fee_configuration

object

Optional fee configuration for cross-chain transfers.

Show properties

fee_configuration.type

'total_fee_bps'

required

The fee model to apply. Currently only total_fee_bps is supported.

fee_configuration.value

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%.

Response

The endpoint returns a 200 response with a pending wallet action resource.

The transfer action is processed asynchronously. The response contains a pending wallet action resource with status: "pending" that Privy processes in the background.

string

The unique identifier for the wallet action.

status

'pending' | 'succeeded' | 'rejected' | 'failed'

The current status of the action.

wallet_id

string

The ID of the wallet initiating the transfer.

created_at

string

The ISO 8601 timestamp for when the action was created.

type

'transfer'

The type of action. For transfers, this is always transfer.

amount_type

'exact_input' | 'exact_output'

The amount type used for this transfer. Omitted when the default exact_input was used.

source_asset

string

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

source_asset_address

string

The token contract address (EVM) or mint address (Solana) of the transferred asset. Present when the transfer was initiated with asset_address.

source_asset_decimals

integer

The 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

The amount sent on the source chain as a decimal string (e.g. "1.5"). Omitted for exact_output cross-chain transfers until the source amount is determined.

source_chain

string

The chain the transfer is sent from (e.g. "tempo", "ethereum").

destination_address

string

The recipient wallet address.

destination_asset

string

The destination asset for cross-asset transfers. Omitted for same-asset transfers.

destination_chain

string

The destination chain for cross-chain transfers. Omitted for same-chain transfers.

destination_amount

string

The amount received on the destination chain. Populated immediately for exact_output transfers, or after fill confirmation for exact_input cross-chain transfers.

fees

FeeLineItem[]

Fees paid for the transfer. Each item has a type (relayer or developer) and an amount in USD. Items of type developer include a recipient address.

failure_reason

object

Present on rejected or failed actions when available. Contains a message string with a human-readable description of the failure, and an optional details field with additional context.

To track the status of a transfer, see wallet action lifecycle.

Examples

Exact input example

Exact output example

To send exactly 100 USDC to a recipient on Arbitrum from a Tempo wallet:

For exact_output cross-chain transfers, source_amount is null at creation because the exact source amount is determined by the bridge provider at execution time. It is populated once the transfer is confirmed on-chain.

API reference

See the API reference for more details.

​Body

​Response

​Examples

​API reference

Body

Response

Examples

API reference