> ## 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.
**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](/wallets/actions/webhooks) and [polling](/wallets/actions/status). Policy violations
always allow fresh retries.
## 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: Actions
description: Operations related to looking up wallet actions across an app
- name: Aggregations
description: Operations related to aggregations for tracking and measuring metrics
- name: Apps
description: Operations related to app settings and allowlist management
- name: Cards
description: Operations related to stablecoin-backed card issuing
- 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 organizations
- 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: Teams
description: Operations related to dashboard team management
- 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: Wallet Automations
description: Operations related to wallet automations
- 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: tempo
destination:
asset: ousd
chain: tempo
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: ousd
source_amount: '10.5'
source_chain: tempo
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.
custody_options:
$ref: '#/components/schemas/TransferCustodyOptions'
nonce:
$ref: '#/components/schemas/WalletActionNonce'
reference_id:
type: string
minLength: 1
maxLength: 64
description: >-
Developer-provided identifier for this request. Must be unique per
app.
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: ousd
amount: '10.5'
chain: tempo
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.
reference_id:
type:
- string
- 'null'
description: Developer-provided reference ID, if one was included in the request.
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. "tempo", "base").
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: ousd
amount: '10.5'
chain: tempo
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 'tempo' to destination 'base').
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: '#/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
TransferCustodyOptions:
type: object
properties:
initiation:
$ref: '#/components/schemas/TransferInitiation'
required:
- initiation
additionalProperties: false
description: Options for a transfer from a custodial wallet.
title: TransferCustodyOptions
example:
initiation:
channel: other_mobile_payment
subchannel: remote
attestations:
sca:
outcome: not_applicable
x-stainless-model: wallets.transfer_custody_options
WalletActionNonce:
type: string
minLength: 24
maxLength: 255
description: >-
Unique caller-generated nonce used to prevent replaying a signed wallet
action request. Must be at least 24 characters (e.g. a cuid2 or UUID).
title: WalletActionNonce
x-stainless-model: wallets.wallet_action_nonce
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'
- $ref: '#/components/schemas/TempoZoneSettlementWalletActionStep'
discriminator:
propertyName: type
mapping:
evm_transaction: '#/components/schemas/EVMTransactionWalletActionStep'
evm_user_operation: '#/components/schemas/EVMUserOperationWalletActionStep'
svm_transaction: '#/components/schemas/SVMTransactionWalletActionStep'
tvm_transaction: '#/components/schemas/TVMTransactionWalletActionStep'
external_transaction: '#/components/schemas/ExternalTransactionWalletActionStep'
custodian_transaction: '#/components/schemas/CustodianTransactionWalletActionStep'
tempo_zone_settlement: '#/components/schemas/TempoZoneSettlementWalletActionStep'
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: '#/components/schemas/RelayerFee'
privy: '#/components/schemas/PrivyFee'
developer: '#/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: use the top-level
`amount` field instead.
deprecated: true
chain:
type: string
description: >-
The blockchain network on which to perform the transfer. Supported
chains include: 'tempo', 'ethereum', 'base', 'arbitrum', 'polygon',
'solana', and their respective testnets.
asset:
type: string
description: >-
The asset to transfer. Supported: 'usdc', 'usdb', 'usdt', 'eurc',
'ousd', 'pathusd' (stablecoins), 'eth' (native Ethereum), 'sol'
(native Solana).
required:
- 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: ousd
amount: '10.5'
chain: tempo
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: use the top-level
`amount` field instead.
deprecated: true
chain:
type: string
description: >-
The blockchain network on which to perform the transfer. Supported
chains include: 'tempo', '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:
- 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
TransferInitiation:
type: object
properties:
channel:
$ref: '#/components/schemas/TransferInitiationChannel'
subchannel:
$ref: '#/components/schemas/TransferInitiationSubchannel'
attestations:
$ref: '#/components/schemas/TransferInitiationAttestations'
required:
- channel
- subchannel
- attestations
additionalProperties: false
description: >-
Payment initiation context for transfers sourced from wallets that
require initiation data. Captures how the payment was initiated (channel
and subchannel) and whether Strong Customer Authentication was applied
or which SCA exemption was used.
title: TransferInitiation
example:
channel: other_mobile_payment
subchannel: remote
attestations:
sca:
outcome: sca_used
auth_factors:
- category: possession
authenticated_at: '2026-01-15T10:30:00Z'
reference: auth_event_123
- category: knowledge
authenticated_at: '2026-01-15T10:30:00Z'
reference: auth_event_456
x-stainless-model: wallets.transfer_initiation
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.
gas_credits_charged_usd:
type: string
description: Amount charged in USD for gas sponsorship on this step.
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").
transaction_hash:
type:
- string
- 'null'
description: >-
Identifier of the transaction the custodian last reported on the
destination chain. Set on a settled transfer, and also on a failed
one when the custodian had already broadcast a payout that was later
returned. Null until the custodian reports one.
required:
- type
- status
- custodian
- transaction_hash
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
TempoZoneSettlementWalletActionStep:
type: object
properties:
type:
type: string
enum:
- tempo_zone_settlement
failure_reason:
$ref: '#/components/schemas/FailureReason'
caip2:
type:
- string
- 'null'
description: >-
CAIP-2 identifier of the Tempo parent chain, or null when
unavailable.
transaction_hash:
description: Parent-chain settlement transaction hash, or null until completion.
anyOf:
- $ref: '#/components/schemas/Hex'
- type: 'null'
status:
allOf:
- $ref: '#/components/schemas/ExternalTransactionWalletActionStepStatus'
- description: Tempo Zone settlement step status.
required:
- type
- caip2
- transaction_hash
- status
description: >-
A wallet action step representing a Tempo Zone settlement on its parent
chain.
title: TempoZoneSettlementWalletActionStep
x-stainless-model: wallets.actions.tempo_zone_settlement_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
TransferInitiationChannel:
anyOf:
- type: string
enum:
- p2p_mobile_payment
- other_mobile_payment
- other
- type: string
description: >-
How the payment was initiated. Use `p2p_mobile_payment` for peer-to-peer
transfers initiated on a mobile device; `other_mobile_payment` for
non-P2P mobile-initiated payments (e.g. a merchant payment via a mobile
app); `other` for payments not relying on a mobile device.
title: TransferInitiationChannel
example: other_mobile_payment
x-stainless-model: wallets.transfer_initiation_channel
TransferInitiationSubchannel:
anyOf:
- type: string
enum:
- remote
- non_remote
- type: string
description: >-
Whether the payment was made remotely or in person. Use `remote` for
payments initiated from a distance (mobile app, online banking, or
e-commerce checkout); `non_remote` for payments made in person (physical
card, payment terminal, or contactless tap).
title: TransferInitiationSubchannel
example: remote
x-stainless-model: wallets.transfer_initiation_subchannel
TransferInitiationAttestations:
type: object
properties:
sca:
$ref: '#/components/schemas/TransferScaAttestation'
required:
- sca
additionalProperties: false
description: Payment initiation attestations for a transfer.
title: TransferInitiationAttestations
example:
sca:
outcome: sca_used
auth_factors:
- category: possession
authenticated_at: '2026-01-15T10:30:00Z'
reference: auth_event_123
- category: knowledge
authenticated_at: '2026-01-15T10:30:00Z'
reference: auth_event_456
x-stainless-model: wallets.transfer_initiation_attestations
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
Hex:
type: string
maxLength: 300002
description: >-
A hex-encoded string prefixed with '0x', capped at 300002 characters
(150,000 bytes).
title: Hex
x-stainless-model: wallets.hex
TransferScaAttestation:
type: object
properties:
outcome:
$ref: '#/components/schemas/TransferScaOutcome'
auth_factors:
type: array
items:
$ref: '#/components/schemas/TransferScaAuthFactor'
minItems: 2
maxItems: 10
description: >-
Authentication factor metadata. Optional when `outcome` is
`sca_used`; if provided, it must contain at least two entries from
different `category` values (e.g. one `possession` factor and one
`knowledge` factor). Omit this field for any other outcome.
required:
- outcome
additionalProperties: false
description: Strong Customer Authentication attestation for a transfer.
title: TransferScaAttestation
example:
outcome: sca_used
auth_factors:
- category: possession
authenticated_at: '2026-01-15T10:30:00Z'
reference: auth_event_123
- category: knowledge
authenticated_at: '2026-01-15T10:30:00Z'
reference: auth_event_456
x-stainless-model: wallets.transfer_sca_attestation
TransferScaOutcome:
anyOf:
- type: string
enum:
- sca_used
- payment_to_self
- trusted_beneficiaries
- recurring_transaction
- contactless_low_value
- unattended_terminal_for_transport
- low_value
- secure_corporate_payment
- transaction_risk_analysis
- merchant_initiated_transaction
- not_applicable
- other
- type: string
description: >-
Whether Strong Customer Authentication (SCA) was applied or which
regulatory exemption or non-applicability reason covers this payment.
Use `sca_used` when the user authenticated with SCA. Otherwise, choose
the value that applies: `payment_to_self` — payer and payee are the same
person (remote only); `trusted_beneficiaries` — payee is on the user's
pre-approved list; `recurring_transaction` — amount and payee match a
previously SCA-authorized recurring series; `contactless_low_value` —
contactless card payment below the low-value threshold (non-remote
only); `unattended_terminal_for_transport` — automated terminal for
transport fares or parking (non-remote only); `low_value` — remote
payment below the low-value threshold (remote only);
`secure_corporate_payment` — dedicated corporate payment process with
controls equivalent to SCA (remote only); `transaction_risk_analysis` —
PSP has performed real-time risk analysis and the transaction falls
within permitted thresholds (remote only);
`merchant_initiated_transaction` — payment triggered by the merchant
without the payer present, on a pre-authorized mandate (remote only);
`not_applicable` — this flow requires initiation context but SCA and SCA
exemptions do not apply; `other` — another recognized exemption not
listed above.
title: TransferScaOutcome
example: sca_used
x-stainless-model: wallets.transfer_sca_outcome
TransferScaAuthFactor:
type: object
properties:
category:
$ref: '#/components/schemas/TransferScaAuthFactorCategory'
authenticated_at:
type: string
format: date-time
description: The ISO 8601 timestamp when this factor was authenticated.
reference:
type: string
minLength: 1
maxLength: 64
description: >-
Your internal identifier for this authentication event (e.g. a
session ID, transaction ID, or audit log reference). Used for
reconciliation.
required:
- category
- authenticated_at
- reference
additionalProperties: false
description: Authentication factor metadata for a transfer.
title: TransferScaAuthFactor
example:
category: possession
authenticated_at: '2026-01-15T10:30:00Z'
reference: auth_event_123
x-stainless-model: wallets.transfer_sca_auth_factor
TransferScaAuthFactorCategory:
anyOf:
- type: string
enum:
- knowledge
- possession
- inherence
- type: string
description: >-
The type of authentication factor used. Known values are: `knowledge`
(something only the user knows, e.g. a PIN or password), `possession`
(something only the user has, e.g. a phone receiving an OTP or a
hardware token), and `inherence` (something the user is, e.g. a
fingerprint or face scan). When `outcome` is `sca_used`, the two factors
in `auth_factors` must belong to two different categories.
title: TransferScaAuthFactorCategory
example: possession
x-stainless-model: wallets.transfer_sca_auth_factor_category
securitySchemes:
appSecretAuth:
type: http
scheme: basic
description: >-
Basic Auth header with your app ID as the username and your app secret
as the password.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.