Automation lifecycle

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

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 webhook is emitted when the execution reaches submitted. It does not indicate that the generated wallet action completed. To observe the final outcome:

Read action_id from the submitted webhook or wallet_action_id from the execution.
Fetch the wallet action status.
Subscribe to the corresponding wallet_action.* events.

List executions

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

cURL
Node SDK
Python

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"

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);
}

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"]

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.

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.

A recovered automation acts on the asset’s full current wallet balance. Funds received after the original deposit can therefore be included.

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

​Execution flow

​Relationship to wallet actions

​List executions

​Recover a missed or failed deposit

​Delivery and concurrency

​Troubleshooting

Execution flow

Relationship to wallet actions

List executions

Recover a missed or failed deposit

Delivery and concurrency

Troubleshooting