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

# Automation lifecycle

> Understand wallet automation matching, execution statuses, and wallet action outcomes.

Privy creates an automation execution after a trigger is matched on an enabled attachment. The execution records why the automation ran and links to the wallet action that it executed.

## Execution flow

```mermaid theme={"system"}
flowchart LR
    pending --> submitted
    pending --> failed
    pending --> skipped
    submitted --> completed
    submitted --> failed
```

| Status | Terminal | Description |
| - | - | - |
| `pending` | No | Privy matched the deposit and is preparing the wallet action. |
| `submitted` | No | Privy created the wallet action and submitted it for processing. |
| `completed` | Yes | The linked wallet action completed successfully. |
| `failed` | Yes | Preparation or the linked wallet action failed. Inspect `failure_reason` and the action. |
| `skipped` | Yes | The trigger matched, but no action was needed. This can occur if another automation already executed. |

## Relationship to wallet actions

The execution's `wallet_action_id` identifies the action created by the automation. The wallet action contains the detailed onchain lifecycle, including steps and transaction identifiers.

The [`wallet_automation.submitted`](/wallets/automations/webhooks) webhook is emitted when the execution reaches `submitted`. It does not indicate that the generated wallet action completed.

To observe the final outcome:

1. Read `action_id` from the submitted webhook or `wallet_action_id` from the execution.
2. Fetch the [wallet action status](/wallets/actions/status).
3. Subscribe to the corresponding [`wallet_action.*` events](/wallets/actions/webhooks).

## List executions

Use `GET /v1/wallet_automations/executions` to list executions across the app. Pass `wallet_id` to restrict results to one source wallet.

<Tabs>
  <Tab title="cURL">
    ```bash theme={"system"}
    curl --request GET "https://api.privy.io/v1/wallet_automations/executions?wallet_id=$WALLET_ID&limit=25" \
      --user "$PRIVY_APP_ID:$PRIVY_APP_SECRET" \
      --header "privy-app-id: $PRIVY_APP_ID"
    ```
  </Tab>

  <Tab title="Node SDK">
    ```ts {skip-check} theme={"system"}
    import {PrivyClient} from '@privy-io/node';

    const privy = new PrivyClient({
      appId: process.env.PRIVY_APP_ID!,
      appSecret: process.env.PRIVY_APP_SECRET!
    });

    const executions = [];

    for await (const execution of privy.walletAutomations().listExecutions({
      wallet_id: process.env.WALLET_ID!,
      limit: 100
    })) {
      executions.push(execution);
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    import os
    import requests

    app_id = os.environ["PRIVY_APP_ID"]
    params = {"wallet_id": os.environ["WALLET_ID"], "limit": 100}
    executions = []

    while True:
        response = requests.get(
            "https://api.privy.io/v1/wallet_automations/executions",
            auth=(app_id, os.environ["PRIVY_APP_SECRET"]),
            headers={"privy-app-id": app_id},
            params=params,
        )
        response.raise_for_status()
        page = response.json()
        executions.extend(page["data"])

        if not page["next_cursor"]:
            break
        params["cursor"] = page["next_cursor"]
    ```
  </Tab>
</Tabs>

Results are ordered from newest to oldest. The Node SDK automatically requests subsequent pages during iteration, and the Python example explicitly follows `next_cursor`. With cURL, pass the returned `next_cursor` as `cursor` in the next request until it is `null`.

Each execution includes:

* The source `wallet_id` and matched `automation_attachment_id`.
* The triggering information (e.g. transaction, block, chain, and asset).
* The linked `wallet_action_id` after submission.
* Status timestamps and an optional `failure_reason`.

The execution response does not contain `automation_id`. Store submitted webhook payloads when the app must retain a direct association between an execution and automation after deletion.

## Recover a missed or failed deposit

Use `POST /v1/wallet_automations/reindex` to recheck a wallet's current balance for one asset. This can recover a deposit that did not create an execution or whose execution failed before creating a wallet action.

```bash theme={"system"}
curl --request POST "https://api.privy.io/v1/wallet_automations/reindex" \
  --user "$PRIVY_APP_ID:$PRIVY_APP_SECRET" \
  --header "privy-app-id: $PRIVY_APP_ID" \
  --header "content-type: application/json" \
  --data "{
    \"wallet_id\": \"$WALLET_ID\",
    \"caip2\": \"eip155:4217\",
    \"asset_address\": \"$ASSET_ADDRESS\"
  }"
```

Identify the wallet with `wallet_id` or `deposit_address`. Identify the chain with `caip2` or a human-readable `chain` name. For a native asset, pass `native` as `asset_address`.

Reindexing does not replay the original deposit amount. Privy reads the asset's current wallet balance and submits a new execution only when the balance is greater than zero and an enabled attachment matches. An existing `pending` or `submitted` execution blocks reindexing for the same wallet and asset.

<Warning>
  A recovered automation acts on the asset's full current wallet balance. Funds received after the
  original deposit can therefore be included.
</Warning>

Each result has one of the following statuses:

| Status | Meaning |
| - | - |
| `submitted` | Privy submitted a new automation execution. |
| `skipped_zero_balance` | The wallet had no balance for the requested asset. |
| `skipped_no_match` | No enabled attachment matched the requested asset. |
| `skipped_existing_execution` | A `pending` or `submitted` execution already exists. |
| `failed` | Privy could not check the balance or submit the execution. |

The endpoint can return HTTP `200` with a `failed` result. Inspect every result rather than treating the HTTP status as the recovery outcome.

See the [reindex API reference](/api-reference/wallet-automations/reindex) for the complete request and response schemas.

## Delivery and concurrency

Privy deduplicates detected deposits by wallet, block, chain, and asset. Multiple deposits of the same asset to one wallet in the same block can produce one full-balance execution. Apps should also process webhook deliveries idempotently by `trigger_id`.

Privy serializes automation matching and wallet-action creation for each wallet. The generated wallet action continues asynchronously after creation, so another automation execution can be submitted before the previous action completes.

Each execution reads the current balance. A later execution can become `skipped` if an earlier wallet action already consumed that balance.

Privy retries transient errors during action preparation. If an execution remains `pending` and does not advance, reindexing cannot replace it. Contact Privy support with the execution and wallet IDs.

## Troubleshooting

| Result | What to inspect |
| - | - |
| No execution | Confirm the automation and attachment are enabled and the trigger matches the asset filter. A pre-existing balance requires a new deposit or [reindex](#recover-a-missed-or-failed-deposit). |
| `pending` | Allow transient retries to complete. Contact Privy support if the execution does not advance. |
| `skipped` | Check whether an earlier execution already swept the balance. |
| `failed` without an action | Inspect `failure_reason`, supported assets and chains, balance availability, and authorization. Reindex after correcting the cause. |
| `failed` with an action | Fetch the wallet action with steps and inspect its policy, simulation, and onchain failure data before reindexing. |