Usage

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 assets), 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.

id · 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

Use the transfer convenience method on the wallets service to transfer tokens from a wallet.

const response = await privy.wallets().transfer('insert-wallet-id', {
  amount: '10.0',
  source: {
    asset: 'usdc',
    chain: 'tempo'
  },
  destination: {
    address: '0xRecipientAddress'
  },
  fee_configuration: {
    type: 'total_fee_bps',
    value: 80
  },
  authorization_context: {
    authorization_private_keys: ['<authorization-private-key>']
  }
});

The method returns a TransferActionResponse with the pending wallet action. See wallet action lifecycle to track the status.

Exact output example

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

const response = await privy.wallets().transfer('insert-wallet-id', {
  amount: '100.0',
  amount_type: 'exact_output',
  source: {
    asset: 'usdc',
    chain: 'tempo'
  },
  destination: {
    address: '0xRecipientAddress',
    chain: 'arbitrum'
  },
  authorization_context: {
    authorization_private_keys: ['<authorization-private-key>']
  }
});

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.