Wallet action lifecycle

When your application executes a wallet action via one of the available action APIs, Privy creates a wallet action resource that models the action asynchronously. This page covers how a wallet action progresses from creation to completion, the statuses it occupies, and the steps it executes along the way.

Action statuses

Every wallet action has a top-level status field that represents its overall progress. Privy derives this status from the outcomes of the action’s individual steps.

Status	Description	Terminal	Safe to retry
`pending`	Privy created the action and is preparing or executing it. At least one step has not yet reached a terminal state.	No	—
`succeeded`	All steps completed successfully. The action is fully executed on-chain.	Yes	—
`rejected`	Privy rejected the action before any on-chain effects occurred. Common causes include policy violations, insufficient balance detected during simulation, or invalid parameters.	Yes	Yes
`failed`	One or more steps failed during execution. There may be partial on-chain effects (e.g., an approval transaction succeeded but the subsequent swap reverted).	Yes	Inspect steps

Generally, the overall wallet action status should be sufficient. However, your application can use the get wallet action endpoint with ?include=steps to inspect step-level details when a wallet action fails.

Status transitions

A wallet action begins in pending and transitions to exactly one terminal state: succeeded, rejected, or failed.

Step types

Each wallet action is composed of one or more steps. A step represents a discrete operation, typically mapping to a single on-chain state change (e.g., a transaction or user operation). Privy executes steps sequentially — the next step begins only after the previous one confirms. To include step details in the response, your application passes ?include=steps as a query parameter when fetching the wallet action status.

Step type	Description
`evm_transaction`	A standard EVM transaction signed and broadcast by the wallet.
`evm_user_operation`	An ERC-4337 user operation submitted via a bundler. Privy uses this when the wallet has gas sponsorship enabled or uses a smart contract account.
`svm_transaction`	A Solana transaction signed and broadcast by the wallet.
`external_transaction`	A cross-chain or cross-asset fill executed by an external provider (e.g., a bridge relay). The wallet does not sign this step directly.

Step statuses

Each step has its own status field indicating where it is in its execution lifecycle. The available statuses vary by step type, since different blockchain environments have different failure modes.

EVM step statuses (`evm_transaction` and `evm_user_operation`)

Status	Terminal	Description
`queued`	No	Waiting for a previous step to complete before this step begins.
`preparing`	No	Building the transaction data (constructing calldata, estimating gas, fetching nonce).
`pending`	No	Privy broadcasted the transaction to the network and is awaiting inclusion in a block.
`confirmed`	Yes	The network mined and executed the transaction successfully on-chain.
`rejected`	Yes	Failed before broadcast — typically due to a policy violation, simulation failure, or signing error.
`reverted`	Yes	The network mined the transaction but execution reverted on-chain (e.g., a smart contract require statement failed).
`replaced`	Yes	A different transaction confirmed at the same nonce, invalidating this one.
`abandoned`	Yes	Privy broadcasted the transaction, but the network never included it on-chain for unknown reasons.

SVM step statuses (`svm_transaction`)

Status	Terminal	Description
`queued`	No	Waiting for a previous step to complete before this step begins.
`preparing`	No	Building the Solana transaction (fetching recent blockhash, constructing instructions).
`pending`	No	Privy broadcasted the transaction and is awaiting confirmation.
`confirmed`	Yes	The network included the transaction in a confirmed slot and executed it successfully.
`rejected`	Yes	Failed before broadcast — typically due to a policy violation or simulation failure.
`reverted`	Yes	The network included the transaction on-chain but an instruction error caused it to fail.
`failed`	Yes	Transaction timed out (e.g., the blockhash expired before inclusion).

External transaction step statuses (`external_transaction`)

Status	Terminal	Description
`queued`	No	Waiting for a previous step to complete.
`preparing`	No	Setting up the cross-chain fill with the external provider.
`pending`	No	The external provider is processing the fill.
`confirmed`	Yes	The fill completed successfully on the destination chain.
`rejected`	Yes	The provider rejected the fill before execution.
`failed`	Yes	The fill failed during execution (e.g., provider timeout or liquidity issues).

Steps by action type

Privy treats the specific steps for each action type as an implementation detail, subject to change. This allows Privy to optimize how transactions land on-chain most effectively. Your application should be robust to varying steps for any wallet action type.

How Privy derives the top-level status

Privy computes the top-level wallet action status from the statuses of its steps:

succeeded: All steps reached confirmed.
rejected: Privy rejected the action during preparation (before creating any steps), or a step reached rejected without any post-broadcast failures.
failed: At least one step reached a post-broadcast failure state (reverted, replaced, abandoned, or failed).
pending: None of the above conditions apply — the action is still in progress.

Webhooks

Your application can subscribe to wallet action webhooks to receive real-time notifications when an action reaches a terminal state, rather than polling for status updates.

Wallet actions

Transfer

Swap

Earn

Wallet action lifecycle

Action statuses

Status transitions

Step types

Step statuses

EVM step statuses (`evm_transaction` and `evm_user_operation`)

SVM step statuses (`svm_transaction`)

External transaction step statuses (`external_transaction`)

Steps by action type

How Privy derives the top-level status

Webhooks

​Action statuses

​Status transitions

​Step types

​Step statuses

​EVM step statuses (evm_transaction and evm_user_operation)

​SVM step statuses (svm_transaction)

​External transaction step statuses (external_transaction)

​Steps by action type

​How Privy derives the top-level status

​Webhooks

Action statuses

Status transitions

Step types

Step statuses

EVM step statuses (`evm_transaction` and `evm_user_operation`)

SVM step statuses (`svm_transaction`)

External transaction step statuses (`external_transaction`)

Steps by action type

How Privy derives the top-level status

Webhooks