Wallet Actions

Transfer

Transfer tokens from a wallet to a destination address.

post/v1/wallets/{wallet_id}/transfer

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

amountstring

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'exact_input' | 'exact_output'

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

slippage_bpsinteger

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.

Example request

{
  "amount": "10.5",
  "destination": {
    "address": "0xB00F0759DbeeF5E543Cc3E3B07A6442F5f3928a2"
  },
  "source": {
    "amount": "10.5",
    "asset": "usdc",
    "chain": "base"
  }
}

Response

Transfer initiated successfully.

amount_type'exact_input' | 'exact_output'

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

created_atstring date-time required

ISO 8601 timestamp of when the wallet action was created.

destination_addressstring required

Recipient address.

destination_amountstring nullable 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.

destination_assetstring

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

destination_chainstring

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

idstring required

The ID of the wallet action.

source_amountstring

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

source_assetstring

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

source_asset_addressstring

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

source_asset_decimalsinteger

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

source_chainstring required

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

status'pending' | 'succeeded' | 'rejected' | 'failed' required

The current status of the wallet action.

type'transfer' 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.10234

Jul 9, 2026d5a26f68a18a2See the full diff
- ○
  the request property source/anyOf[subschema #1: NamedTokenTransferSource]/amount became optional
  request-property-became-optional
- ○
  the request property source/anyOf[subschema #2: CustomTokenTransferSource]/amount became optional
  request-property-became-optional
Jun 26, 2026c10a42ebeddb15See the full diff
- ▲
  the steps/items/oneOf[subschema #2: EVMUserOperationWalletActionStep]/entrypoint_version response's property type/format changed from string/ to / for status 200
  response-property-type-changed
- ○
  added EVMUserOperationEntrypointVersion subschema #2 to the steps/items/oneOf[subschema #2: EVMUserOperationWalletActionStep]/entrypoint_version response property allOf list for the response status 200
  response-property-all-of-added
- ○
  removed the 0.6 enum value from the steps/items/oneOf[subschema #2: EVMUserOperationWalletActionStep]/entrypoint_version response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the 0.7 enum value from the steps/items/oneOf[subschema #2: EVMUserOperationWalletActionStep]/entrypoint_version response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the 0.8 enum value from the steps/items/oneOf[subschema #2: EVMUserOperationWalletActionStep]/entrypoint_version response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the 0.9 enum value from the steps/items/oneOf[subschema #2: EVMUserOperationWalletActionStep]/entrypoint_version response property for the response status 200
  response-property-enum-value-removed
Jun 23, 20269955c27139f311See the full diff
- ▲
  added TVMTransactionWalletActionStep to the steps/items/ response property oneOf list for the response status 200
  response-property-one-of-added
- ○
  added tvm_transaction discriminator mapping keys to the steps/items/ response property for the response status 200
  response-property-discriminator-mapping-added
Jun 17, 2026468dcf8db5804See the full diff
- ○
  added the new optional request property amount
  new-optional-request-property
- ○
  request property source/anyOf[subschema #1: NamedTokenTransferSource]/amount deprecated
  request-property-deprecated
- ○
  request property source/anyOf[subschema #2: CustomTokenTransferSource]/amount deprecated
  request-property-deprecated
- ○
  added the optional property amount_type to the response with the 200 status
  response-optional-property-added
Jun 12, 2026a8d27de9e15d15See the full diff
- ▲
  added CustodianTransactionWalletActionStep to the steps/items/ response property oneOf list for the response status 200
  response-property-one-of-added
- ○
  added the optional property steps/items/oneOf[subschema #1: EVMTransactionWalletActionStep]/finalized to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property steps/items/oneOf[subschema #2: EVMUserOperationWalletActionStep]/finalized to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property steps/items/oneOf[subschema #3: SVMTransactionWalletActionStep]/finalized to the response with the 200 status
  response-optional-property-added
- ○
  added custodian_transaction discriminator mapping keys to the steps/items/ response property for the response status 200
  response-property-discriminator-mapping-added
- ○
  removed the finalized enum value from the steps/items/oneOf[subschema #3: SVMTransactionWalletActionStep]/status/allOf[subschema #1: SVMWalletActionStepStatus]/ response property for the response status 200
  response-property-enum-value-removed
Jun 9, 202602e9839a74d46See the full diff
- ○
  added the optional property steps/items/oneOf[subschema #2: EVMUserOperationWalletActionStep]/gas_credits_charged_usd to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property steps/items/oneOf[subschema #3: SVMTransactionWalletActionStep]/gas_credits_charged_usd to the response with the 200 status
  response-optional-property-added
- ○
  removed Gas subschema #2 from the estimated_gas response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  removed Gas subschema #2 from the gas response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  added Gas subschema #2 to the estimated_gas response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  added Gas subschema #2 to the gas response property anyOf list for the response status 200
  response-property-any-of-added
Jun 8, 202693c7790da9d371See the full diff
- ▲
  the response property destination_amount became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property estimated_fees became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property estimated_gas/allOf[subschema #2]/ became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property fees became nullable for the status 200
  response-property-became-nullable
- ▲
  the response property gas/allOf[subschema #2]/ became nullable for the status 200
  response-property-became-nullable
- ▲
  the estimated_gas/allOf[subschema #2]/ response's property type/format changed from / to object null/ for status 200
  response-property-type-changed
- ▲
  the gas/allOf[subschema #2]/ response's property type/format changed from / to object null/ for status 200
  response-property-type-changed
- ○
  the response property destination_amount became required for the status 200
  response-property-became-required
Jun 3, 2026b64a233ab9ee8See the full diff
- ○
  added TronAddress to the destination/address request property anyOf list
  request-property-any-of-added
- ○
  added TronAddress to the source/anyOf[subschema #2: CustomTokenTransferSource]/asset_address request property anyOf list
  request-property-any-of-added
- ○
  added the optional property estimated_fees to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property estimated_gas to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property gas to the response with the 200 status
  response-optional-property-added
- ○
  added TronAddress to the fees/items/oneOf[subschema #1: RelayerFee]/recipient response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  added TronAddress to the fees/items/oneOf[subschema #2: PrivyFee]/recipient response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  added TronAddress to the fees/items/oneOf[subschema #3: DeveloperFee]/recipient response property anyOf list for the response status 200
  response-property-any-of-added
May 18, 2026a387f0cce4fa22See the full diff
- ●
  the source/anyOf[subschema #1: NamedTokenTransferSource]/amount request property's maxLength was set to 100
  request-property-max-length-set
- ●
  the source/anyOf[subschema #2: CustomTokenTransferSource]/amount request property's maxLength was set to 100
  request-property-max-length-set
- ○
  added the new optional request property fee_configuration
  new-optional-request-property
- ○
  added the optional property fees to the response with the 200 status
  response-optional-property-added

Full history