> ## 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.
# Transfer
> Transfer tokens from a wallet to a destination address.
If your app has gas sponsorship configured, usage of the `/transfer` endpoint will be
[gas-sponsored by default](/wallets/actions/overview#gas-management). 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](/api-reference/wallets/transfer/quote) to preview fees before executing a transfer.
## OpenAPI
````yaml post /v1/wallets/{wallet_id}/transfer
openapi: 3.1.0
info:
version: 0.0.1
title: Privy API
description: >-
REST API for Privy's wallet infrastructure — provision and manage wallets
across EVM, Solana, and Bitcoin, authenticate users, sign transactions, and
configure programmable policies and authorization intents.
contact:
name: Privy
url: https://www.privy.io/
email: support@privy.io
servers:
- url: https://api.privy.io
security: []
tags:
- name: Accounts
description: Operations related to asset accounts
- name: Aggregations
description: Operations related to aggregations for tracking and measuring metrics
- name: Apps
description: Operations related to app settings and allowlist management
- name: Client Auth
description: OAuth token exchange and device authorization operations
- name: Condition Sets
description: Operations related to condition sets
- name: Embedded wallets
description: Operations related to embedded wallet creation and authentication
- name: Fiat
description: Operations related to fiat onramping and offramping
- name: Intents
description: Operations related to authorization intents for wallet actions
- name: Key quorums
description: Operations related to key quorums
- name: Kraken Embed
description: >-
Operations for Kraken Embed integration, including quotes, trades, user
management, and portfolio operations
- name: OAuth
description: >-
OAuth 2.0 endpoints including Device Authorization Grant (RFC 8628) for
CLI and limited-input device login flows
- name: Organizations
description: Operations related to organization secret management
- name: Policies
description: Operations related to policies
- name: Shared
description: Common schemas shared across resources
- name: Swaps
description: Operations for swapping tokens within wallets
- name: Transactions
description: Operations related to transactions
- name: User signers
description: Operations related to user signers
- name: Users
description: Operations related to users
- name: Wallet Actions
description: Operations related to wallet actions
- name: Wallets
description: Operations related to wallets
- name: Webhooks
description: >-
Webhook events that Privy sends to your configured endpoint when specific
actions occur in your app
- name: Yield
description: >-
Operations for depositing and withdrawing funds from ERC-4626 yield vaults
(Morpho, Aave)
paths:
/v1/wallets/{wallet_id}/transfer:
post:
tags:
- Wallet Actions
summary: Transfer
description: Transfer tokens from a wallet to a destination address.
operationId: transfer
parameters:
- schema:
type: string
description: ID of the wallet.
required: true
name: wallet_id
in: path
- schema:
type: string
description: ID of your Privy app.
required: true
name: privy-app-id
in: header
- schema:
type: string
description: >-
Request authorization signature. If multiple signatures are
required, they should be comma separated.
required: false
name: privy-authorization-signature
in: header
- schema:
type: string
description: >-
Request expiry. Value is a Unix timestamp in milliseconds
representing the deadline by which the request must be processed.
required: false
name: privy-request-expiry
in: header
- schema:
type: string
description: >-
Idempotency keys ensure API requests are executed only once within
a 24-hour window.
required: false
name: privy-idempotency-key
in: header
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransferRequestBody'
example:
amount_type: exact_input
source:
asset: usdc
amount: '10.5'
chain: base
destination:
asset: usdc
chain: base
address: '0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2'
slippage_bps: 100
responses:
'200':
description: Transfer initiated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/TransferActionResponse'
example:
id: 550e8400-e29b-41d4-a716-446655440000
status: pending
wallet_id: fmfdj6yqly31huorjqzq38zc
type: transfer
source_asset: usdc
source_amount: '10.5'
source_chain: base
destination_address: '0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2'
security:
- appSecretAuth: []
components:
schemas:
TransferRequestBody:
type: object
properties:
amount:
type: string
maxLength: 100
description: >-
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.
amount_type:
$ref: '#/components/schemas/AmountType'
source:
$ref: '#/components/schemas/TokenTransferSource'
destination:
$ref: '#/components/schemas/TokenTransferDestination'
slippage_bps:
type: integer
minimum: 0
maximum: 10000
description: >-
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.
fee_configuration:
allOf:
- $ref: '#/components/schemas/FeeConfiguration'
- description: >-
Optional fee configuration for the transfer. If omitted,
cross-chain transfers will not charge additional fees.
required:
- source
- destination
additionalProperties: false
description: >-
Request body for initiating a sponsored token transfer from an embedded
wallet.
title: TransferRequestBody
example:
amount: '10.5'
source:
asset: usdc
amount: '10.5'
chain: base
destination:
address: '0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2'
x-stainless-model: wallets.transfer_request_body
TransferActionResponse:
type: object
properties:
id:
type: string
description: The ID of the wallet action.
status:
allOf:
- $ref: '#/components/schemas/WalletActionStatus'
- description: The current status of the wallet action.
wallet_id:
type: string
description: The ID of the wallet involved in the action.
created_at:
type: string
format: date-time
description: ISO 8601 timestamp of when the wallet action was created.
failure_reason:
allOf:
- $ref: '#/components/schemas/FailureReason'
- description: >-
Top-level failure context for the wallet action. Present on
rejected or failed actions when available.
steps:
type: array
items:
$ref: '#/components/schemas/WalletActionStep'
description: >-
The steps of the wallet action. Only returned if `?include=steps` is
provided.
type:
type: string
enum:
- transfer
amount_type:
$ref: '#/components/schemas/AmountType'
source_asset:
type: string
description: >-
Asset identifier (e.g. "usdc", "eth"). Present when the transfer was
initiated with a named asset; omitted for custom-token transfers.
source_asset_address:
type: string
description: >-
Token contract address (EVM) or mint address (Solana). Present when
the transfer was initiated with `asset_address`.
source_asset_decimals:
type: integer
description: >-
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:
type: string
description: >-
Decimal amount sent on the source chain (e.g. "1.5"). For
exact_output cross-chain transfers, null until fill confirmation.
source_chain:
type: string
description: Chain name (e.g. "base", "ethereum").
destination_address:
type: string
description: Recipient address.
destination_asset:
type: string
description: >-
Destination asset for cross-asset transfers. Omitted for same-asset
transfers.
destination_chain:
type: string
description: >-
Destination chain for cross-chain transfers. Omitted for same-chain
transfers.
destination_amount:
type:
- string
- 'null'
description: >-
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.
estimated_fees:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/FeeLineItem'
description: >-
Estimated fee breakdown from the provider quote. Only present for
cross-chain or cross-asset transfers. Populated after on-chain
confirmation.
estimated_gas:
description: >-
Estimated source-chain gas cost from the provider quote. Only
present for cross-chain or cross-asset transfers. Populated after
on-chain confirmation.
anyOf:
- $ref: '#/components/schemas/Gas'
- type: 'null'
fees:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/FeeLineItem'
description: >-
Actual fees paid for the transfer. Populated after on-chain
confirmation. Only present for cross-chain transfers.
gas:
description: >-
Actual source-chain gas cost. Populated after on-chain confirmation.
Only present for cross-chain transfers.
anyOf:
- $ref: '#/components/schemas/Gas'
- type: 'null'
required:
- id
- status
- wallet_id
- created_at
- type
- source_chain
- destination_address
- destination_amount
description: Response for a transfer action.
title: TransferActionResponse
x-stainless-model: wallets.actions.transfer_action_response
AmountType:
type: string
enum:
- exact_input
- exact_output
description: Whether the amount refers to the input token or output token.
title: AmountType
x-stainless-model: wallets.amount_type
TokenTransferSource:
anyOf:
- $ref: '#/components/schemas/NamedTokenTransferSource'
- $ref: '#/components/schemas/CustomTokenTransferSource'
description: >-
The source asset, amount, and chain for a token transfer. Specify either
`asset` (named) or `asset_address` (custom), not both.
title: TokenTransferSource
example:
asset: usdc
amount: '10.5'
chain: base
x-stainless-model: wallets.token_transfer_source
TokenTransferDestination:
type: object
properties:
address:
anyOf:
- type: string
- type: string
- $ref: '#/components/schemas/TronAddress'
description: >-
Recipient address (hex for EVM, base58 for Solana, base58check for
Tron)
asset:
type: string
description: >-
The destination asset. Required for cross-asset transfers (e.g.,
source 'usdt' to destination 'usdc').
chain:
type: string
description: >-
The destination blockchain network. Required for cross-chain
transfers (e.g., source 'base' to destination 'arbitrum').
required:
- address
additionalProperties: false
description: >-
The destination address for a token transfer. Optionally specify a
different asset or chain for cross-asset or cross-chain transfers.
title: TokenTransferDestination
example:
address: '0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2'
x-stainless-model: wallets.token_transfer_destination
FeeConfiguration:
oneOf:
- $ref: '#/components/schemas/TotalFeeConfigurationBps'
discriminator:
propertyName: type
mapping:
total_fee_bps:
$ref: '#/components/schemas/TotalFeeConfigurationBps'
description: >-
How transfer fees are specified. If omitted, a default fee configuration
is applied.
title: FeeConfiguration
example:
type: total_fee_bps
value: 50
x-stainless-model: wallets.fee_configuration
WalletActionStatus:
type: string
enum:
- pending
- succeeded
- rejected
- failed
description: Status of a wallet action.
title: WalletActionStatus
x-stainless-model: wallets.actions.wallet_action_status
FailureReason:
type: object
properties:
message:
type: string
description: Human-readable failure message.
details:
description: Additional error details, if available.
x-stainless-any: true
required:
- message
description: >-
A description of why a wallet action (or a step within a wallet action)
failed.
title: FailureReason
x-stainless-model: wallets.actions.failure_reason
WalletActionStep:
oneOf:
- $ref: '#/components/schemas/EVMTransactionWalletActionStep'
- $ref: '#/components/schemas/EVMUserOperationWalletActionStep'
- $ref: '#/components/schemas/SVMTransactionWalletActionStep'
- $ref: '#/components/schemas/TVMTransactionWalletActionStep'
- $ref: '#/components/schemas/ExternalTransactionWalletActionStep'
- $ref: '#/components/schemas/CustodianTransactionWalletActionStep'
discriminator:
propertyName: type
mapping:
evm_transaction:
$ref: '#/components/schemas/EVMTransactionWalletActionStep'
evm_user_operation:
$ref: '#/components/schemas/EVMUserOperationWalletActionStep'
svm_transaction:
$ref: '#/components/schemas/SVMTransactionWalletActionStep'
tvm_transaction:
$ref: '#/components/schemas/TVMTransactionWalletActionStep'
external_transaction:
$ref: '#/components/schemas/ExternalTransactionWalletActionStep'
custodian_transaction:
$ref: '#/components/schemas/CustodianTransactionWalletActionStep'
description: A step within a wallet action, representing a single onchain action.
title: WalletActionStep
x-stainless-model: wallets.actions.wallet_action_step
FeeLineItem:
oneOf:
- $ref: '#/components/schemas/RelayerFee'
- $ref: '#/components/schemas/PrivyFee'
- $ref: '#/components/schemas/DeveloperFee'
discriminator:
propertyName: type
mapping:
relayer:
$ref: '#/components/schemas/RelayerFee'
privy:
$ref: '#/components/schemas/PrivyFee'
developer:
$ref: '#/components/schemas/DeveloperFee'
description: An individual fee assessed on a transfer.
title: FeeLineItem
example:
type: privy
amount: '0.20'
x-stainless-model: wallets.fee_line_item
Gas:
type: object
properties:
base_amount:
type: string
description: Gas cost in the gas token's base units (e.g. wei).
amount:
type: string
description: >-
Gas cost in the gas token as a human-readable decimal string (e.g.
"0.0001").
gas_asset:
type: string
description: Gas token symbol (e.g. "ETH", "USDC").
required:
- base_amount
- amount
- gas_asset
additionalProperties: false
description: >-
Gas cost for a blockchain action. Includes both raw base-unit amount and
a human-readable decimal string, plus the gas token symbol.
title: Gas
example:
base_amount: '100000000000000'
amount: '0.0001'
gas_asset: ETH
x-stainless-model: wallets.gas
NamedTokenTransferSource:
type: object
properties:
amount:
type: string
maxLength: 100
description: >-
Amount as a decimal string in the token's standard unit (e.g. "1.5"
for 1.5 USDC, "0.01" for 0.01 ETH). For exact_input, specifies the
amount to send. Not in the smallest on-chain unit (wei, lamports,
etc.). Maximum 100 characters.
deprecated: true
chain:
type: string
description: >-
The blockchain network on which to perform the transfer. Supported
chains include: 'ethereum', 'base', 'arbitrum', 'polygon', 'solana',
and their respective testnets.
asset:
type: string
description: >-
The asset to transfer. Supported: 'usdc', 'usdb', 'usdt'
(stablecoins), 'eth' (native Ethereum), 'sol' (native Solana).
required:
- amount
- chain
- asset
additionalProperties: false
description: >-
Source for a transfer identified by a named asset (e.g. "usdc", "eth").
Use this variant for first-class assets maintained by Privy.
title: NamedTokenTransferSource
example:
asset: usdc
amount: '10.5'
chain: base
x-stainless-model: wallets.named_token_transfer_source
CustomTokenTransferSource:
type: object
properties:
amount:
type: string
maxLength: 100
description: >-
Amount as a decimal string in the token's standard unit (e.g. "1.5"
for 1.5 USDC, "0.01" for 0.01 ETH). For exact_input, specifies the
amount to send. Not in the smallest on-chain unit (wei, lamports,
etc.). Maximum 100 characters.
deprecated: true
chain:
type: string
description: >-
The blockchain network on which to perform the transfer. Supported
chains include: 'ethereum', 'base', 'arbitrum', 'polygon', 'solana',
and their respective testnets.
asset_address:
anyOf:
- type: string
- type: string
- $ref: '#/components/schemas/TronAddress'
description: >-
The token contract address (EVM) or mint address (Solana) of the
asset to transfer.
required:
- amount
- chain
- asset_address
additionalProperties: false
description: >-
Source for a transfer identified by a token contract address (EVM) or
mint address (Solana). Use this variant for tokens that are not
first-class assets.
title: CustomTokenTransferSource
example:
asset_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
amount: '10.5'
chain: base
x-stainless-model: wallets.custom_token_transfer_source
TronAddress:
type: string
pattern: ^T[1-9A-HJ-NP-Za-km-z]{33}$
description: 'Tron address: base58check-encoded, starting with T, 34 characters.'
title: TronAddress
x-stainless-model: shared.tron_address
TotalFeeConfigurationBps:
type: object
properties:
type:
type: string
enum:
- total_fee_bps
description: 'Discriminator: total fee specified in BPS.'
value:
type: integer
minimum: 0
maximum: 10000
description: Total fee in basis points (1 bps = 0.01%).
required:
- type
- value
additionalProperties: false
description: Total fees assessed on a transfer, in BPS
title: TotalFeeConfigurationBps
example:
type: total_fee_bps
value: 50
x-stainless-model: wallets.total_fee_configuration_bps
EVMTransactionWalletActionStep:
type: object
properties:
type:
type: string
enum:
- evm_transaction
failure_reason:
$ref: '#/components/schemas/FailureReason'
finalized:
type: boolean
description: >-
Whether this step has reached on-chain finality. Absent until
finality is confirmed.
status:
allOf:
- $ref: '#/components/schemas/EVMWalletActionStepStatus'
- description: EVM transaction status.
caip2:
type: string
description: CAIP-2 chain identifier of the transaction, containing the chain ID.
transaction_hash:
type:
- string
- 'null'
description: >-
The transaction hash for this step. May change while the step status
is non-terminal.
required:
- type
- status
- caip2
- transaction_hash
description: A wallet action step consisting of an EVM transaction.
title: EVMTransactionWalletActionStep
x-stainless-model: wallets.actions.evm_transaction_wallet_action_step
EVMUserOperationWalletActionStep:
type: object
properties:
type:
type: string
enum:
- evm_user_operation
failure_reason:
$ref: '#/components/schemas/FailureReason'
finalized:
type: boolean
description: >-
Whether this step has reached on-chain finality. Absent until
finality is confirmed.
gas_credits_charged_usd:
type: string
description: Amount charged in USD for gas sponsorship on this step.
status:
allOf:
- $ref: '#/components/schemas/EVMWalletActionStepStatus'
- description: User operation status.
user_operation_hash:
type:
- string
- 'null'
description: >-
The user operation hash for this step. May change while the step
status is non-terminal.
bundle_transaction_hash:
type:
- string
- 'null'
description: >-
Transaction hash of the bundle in which this user operation was
included. Null until included by a bundler.
caip2:
type: string
description: >-
CAIP-2 network identifier, containing the chain ID of the user
operation.
entrypoint_version:
allOf:
- $ref: '#/components/schemas/EVMUserOperationEntrypointVersion'
- description: The entrypoint version of the user operation.
required:
- type
- status
- user_operation_hash
- bundle_transaction_hash
- caip2
- entrypoint_version
description: A wallet action step consisting of an EVM user operation.
title: EVMUserOperationWalletActionStep
x-stainless-model: wallets.actions.evm_user_operation_wallet_action_step
SVMTransactionWalletActionStep:
type: object
properties:
type:
type: string
enum:
- svm_transaction
failure_reason:
$ref: '#/components/schemas/FailureReason'
finalized:
type: boolean
description: >-
Whether this step has reached on-chain finality. Absent until
finality is confirmed.
gas_credits_charged_usd:
type: string
description: Amount charged in USD for gas sponsorship on this step.
status:
allOf:
- $ref: '#/components/schemas/SVMWalletActionStepStatus'
- description: SVM transaction status.
caip2:
type: string
description: CAIP-2 chain identifier for the Solana network.
transaction_signature:
type:
- string
- 'null'
description: >-
The Solana transaction signature (base58-encoded). Null until
broadcast.
required:
- type
- status
- caip2
- transaction_signature
description: A wallet action step consisting of an SVM (Solana) transaction.
title: SVMTransactionWalletActionStep
x-stainless-model: wallets.actions.svm_transaction_wallet_action_step
TVMTransactionWalletActionStep:
type: object
properties:
type:
type: string
enum:
- tvm_transaction
failure_reason:
$ref: '#/components/schemas/FailureReason'
status:
allOf:
- $ref: '#/components/schemas/TVMWalletActionStepStatus'
- description: TVM transaction status.
caip2:
type: string
description: CAIP-2 chain identifier for the Tron network.
transaction_id:
type:
- string
- 'null'
description: The Tron transaction ID. Null until broadcast.
required:
- type
- status
- caip2
- transaction_id
description: A wallet action step consisting of a TVM (Tron) transaction.
title: TVMTransactionWalletActionStep
x-stainless-model: wallets.actions.tvm_transaction_wallet_action_step
ExternalTransactionWalletActionStep:
type: object
properties:
type:
type: string
enum:
- external_transaction
failure_reason:
$ref: '#/components/schemas/FailureReason'
status:
allOf:
- $ref: '#/components/schemas/ExternalTransactionWalletActionStepStatus'
- description: External transaction step status.
required:
- type
- status
description: >-
A wallet action step representing a cross-chain/cross-asset fill by an
external provider.
title: ExternalTransactionWalletActionStep
x-stainless-model: wallets.actions.external_transaction_wallet_action_step
CustodianTransactionWalletActionStep:
type: object
properties:
type:
type: string
enum:
- custodian_transaction
failure_reason:
$ref: '#/components/schemas/FailureReason'
status:
allOf:
- $ref: '#/components/schemas/CustodianTransactionWalletActionStepStatus'
- description: Custodian transaction step status.
custodian:
type: string
description: >-
Identifier of the custodian executing this transaction (e.g.
"bridge").
required:
- type
- status
- custodian
description: >-
A wallet action step representing a transaction executed by a custodian
(e.g. Bridge).
title: CustodianTransactionWalletActionStep
x-stainless-model: wallets.actions.custodian_transaction_wallet_action_step
RelayerFee:
type: object
properties:
type:
type: string
enum:
- relayer
recipient:
anyOf:
- type: string
- type: string
- $ref: '#/components/schemas/TronAddress'
amount:
type: string
description: Amount in USD (in decimals).
required:
- type
- amount
additionalProperties: false
description: Estimated fee paid to the relayer.
title: RelayerFee
example:
type: relayer
recipient: '0x1234567890abcdef1234567890abcdef12345678'
amount: '0.20'
x-stainless-model: wallets.relayer_fee
PrivyFee:
type: object
properties:
type:
type: string
enum:
- privy
recipient:
anyOf:
- type: string
- type: string
- $ref: '#/components/schemas/TronAddress'
amount:
type: string
description: Amount in USD (in decimals).
required:
- type
- amount
additionalProperties: false
description: Estimated fee paid to Privy.
title: PrivyFee
example:
type: privy
amount: '0.20'
x-stainless-model: wallets.privy_fee
DeveloperFee:
type: object
properties:
type:
type: string
enum:
- developer
recipient:
anyOf:
- type: string
- type: string
- $ref: '#/components/schemas/TronAddress'
amount:
type: string
description: Amount in USD (in decimals).
required:
- type
- amount
additionalProperties: false
description: Estimated fee paid to the developer.
title: DeveloperFee
example:
type: developer
recipient: '0x1234567890abcdef1234567890abcdef12345678'
amount: '0.20'
x-stainless-model: wallets.developer_fee
EVMWalletActionStepStatus:
type: string
enum:
- preparing
- queued
- pending
- retrying
- confirmed
- rejected
- reverted
- replaced
- abandoned
description: Status of an EVM step in a wallet action.
title: EVMWalletActionStepStatus
x-stainless-model: wallets.actions.evm_wallet_action_step_status
EVMUserOperationEntrypointVersion:
type: string
enum:
- '0.6'
- '0.7'
- '0.8'
- '0.9'
description: The ERC-4337 entrypoint contract version used by the user operation.
title: EVMUserOperationEntrypointVersion
x-stainless-model: wallets.actions.evm_user_operation_entrypoint_version
SVMWalletActionStepStatus:
type: string
enum:
- preparing
- queued
- pending
- confirmed
- rejected
- reverted
- failed
description: Status of an SVM step in a wallet action.
title: SVMWalletActionStepStatus
x-stainless-model: wallets.actions.svm_wallet_action_step_status
TVMWalletActionStepStatus:
type: string
enum:
- preparing
- queued
- pending
- confirmed
- rejected
- reverted
- failed
description: Status of a TVM (Tron) step in a wallet action.
title: TVMWalletActionStepStatus
x-stainless-model: wallets.actions.tvm_wallet_action_step_status
ExternalTransactionWalletActionStepStatus:
type: string
enum:
- preparing
- queued
- pending
- confirmed
- rejected
- failed
description: Status of an external transaction step in a wallet action.
title: ExternalTransactionWalletActionStepStatus
x-stainless-model: wallets.actions.external_transaction_wallet_action_step_status
CustodianTransactionWalletActionStepStatus:
type: string
enum:
- preparing
- queued
- custodian_reviewing
- pending
- confirmed
- rejected
- failed
description: Status of a custodian transaction step in a wallet action.
title: CustodianTransactionWalletActionStepStatus
x-stainless-model: wallets.actions.custodian_transaction_wallet_action_step_status
securitySchemes:
appSecretAuth:
type: http
scheme: basic
description: >-
Basic Auth header with your app ID as the username and your app secret
as the password.
````