> ## 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.

# Wallet action lifecycle

> Understand how wallet actions progress through statuses, steps, and terminal states

When your application executes a wallet action via one of the [available action APIs](/wallets/actions/overview#available-actions), 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 |

<Info>
  Generally, the overall wallet action status should be sufficient. However, your application can
  use the [get wallet action](/wallets/actions/status) endpoint with `?include=steps` to inspect
  step-level details when a wallet action fails.
</Info>

### Status transitions

```mermaid theme={"system"}
flowchart LR
    pending --> succeeded
    pending --> rejected
    pending --> failed
```

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](/wallets/actions/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. |
| `tempo_zone_settlement` | Settlement of a Tempo Zone withdrawal on its parent chain, including any callback execution. |

## 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). |

### Tempo Zone settlement step statuses (`tempo_zone_settlement`)

Tempo Zone settlement steps use the same status values as [external transaction steps](#external-transaction-step-statuses-external_transaction).
The step stays `pending` while awaiting settlement and the originating zone's import of the parent block.
It becomes `confirmed` when settlement succeeds, or `failed` if settlement fails or polling times out.

These steps include two additional fields:

* `caip2`: The Tempo parent chain's CAIP-2 identifier as a string, or `null` when unavailable.
* `transaction_hash`: The parent-chain settlement hash, or `null` when unavailable. A failed settlement can also have a transaction hash.

## 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.

Tempo Zone withdrawals, including zone Earn operations, typically have an `evm_transaction` step followed by a `tempo_zone_settlement` step.
Confirming the zone transaction alone does not complete the action; settlement must also succeed.

## 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](/wallets/actions/webhooks) to receive real-time notifications when an action reaches a terminal state, rather than polling for status updates.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.