Create and attach an automation

This guide creates an automation that converts USDC deposits on any chain into pathUSD on Tempo. The app first creates a reusable automation definition, then attaches it to a source wallet.

Run these examples from a trusted server. Never expose the Privy app secret in client-side code.

Prerequisites

The integration requires:

A Privy app ID and app secret.
Swaps enabled for the Privy app.
A source Privy wallet. Imported or previously exported wallets cannot receive automation attachments.
An authorization signature when the source wallet has an owner.

1. Create the automation

Create an app-scoped automation with POST /v1/wallet_automations. See configure triggers and actions for supported triggers, filters, and actions. The source asset alias below does not specify a chain. It matches supported USDC deployments in Privy’s asset registry. The destination includes a chain because every swap must have one destination. The required owner_id controls changes to the shared automation definition. Set it to null for an app-managed definition. Set it to a key quorum ID to require that quorum’s authorization for updates and deletion.

cURL
Node SDK
Python

curl --request POST 'https://api.privy.io/v1/wallet_automations' \
  --user "$PRIVY_APP_ID:$PRIVY_APP_SECRET" \
  --header "privy-app-id: $PRIVY_APP_ID" \
  --header 'content-type: application/json' \
  --data '{
    "name": "Normalize deposits to Tempo PathUSD",
    "owner_id": null,
    "config": {
      "trigger": {
        "type": "deposit",
        "assets": {
          "mode": "include",
          "values": [
            {"asset": "usdc"}
          ]
        }
      },
      "action": {
        "type": "swap",
        "destination_chain_asset": {
          "asset": "pathusd",
          "chain": "tempo"
        }
      }
    }
  }'

import {PrivyClient} from '@privy-io/node';

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

const automation = await privy.walletAutomations().create({
  name: 'Normalize deposits to Tempo PathUSD',
  owner_id: null,
  config: {
    trigger: {
      type: 'deposit',
      assets: {
        mode: 'include',
        values: [{asset: 'usdc'}]
      }
    },
    action: {
      type: 'swap',
      destination_chain_asset: {asset: 'pathusd', chain: 'tempo'}
    }
  }
});

import os
import requests

app_id = os.environ["PRIVY_APP_ID"]
app_secret = os.environ["PRIVY_APP_SECRET"]

response = requests.post(
    "https://api.privy.io/v1/wallet_automations",
    auth=(app_id, app_secret),
    headers={"privy-app-id": app_id},
    json={
        "name": "Normalize deposits to Tempo PathUSD",
        "owner_id": None,
        "config": {
            "trigger": {
                "type": "deposit",
                "assets": {
                    "mode": "include",
                    "values": [{"asset": "usdc"}],
                },
            },
            "action": {
                "type": "swap",
                "destination_chain_asset": {"asset": "pathusd", "chain": "tempo"},
            },
        },
    },
)
response.raise_for_status()
automation = response.json()

Save the returned id. New automation definitions are enabled by default. API responses contain canonical asset_address and caip2 values for the chain-specific aliases in this example. See the create automation API reference for the complete schema.

2. Attach it to a wallet

An attachment enables the automation for one wallet. Only enabled automation definitions can be attached. In the swap example, the params indicate that its destination_address receives the output of every generated swap. The destination address must be valid for the action’s destination chain. Attaching the same automation again updates its parameters without changing its matching priority.

cURL
Node SDK
Python

curl --request POST \
  "https://api.privy.io/v1/wallets/$WALLET_ID/automations/attach" \
  --user "$PRIVY_APP_ID:$PRIVY_APP_SECRET" \
  --header "privy-app-id: $PRIVY_APP_ID" \
  --header 'content-type: application/json' \
  --header "privy-authorization-signature: $PRIVY_AUTHORIZATION_SIGNATURE" \
  --data "{
    \"automation_ids\": [\"$AUTOMATION_ID\"],
    \"params\": {
      \"destination_address\": \"$DESTINATION_WALLET_ADDRESS\"
    }
  }"

const {data: attachments} = await privy.wallets().attachAutomations(process.env.WALLET_ID!, {
  automation_ids: [automation.id],
  params: {
    destination_address: process.env.DESTINATION_WALLET_ADDRESS!
  },
  authorization_context: {
    signatures: [process.env.PRIVY_AUTHORIZATION_SIGNATURE!]
  }
});

import os
import requests

app_id = os.environ["PRIVY_APP_ID"]

response = requests.post(
    f"https://api.privy.io/v1/wallets/{os.environ['WALLET_ID']}/automations/attach",
    auth=(app_id, os.environ["PRIVY_APP_SECRET"]),
    headers={
        "privy-app-id": app_id,
        "privy-authorization-signature": os.environ[
            "PRIVY_AUTHORIZATION_SIGNATURE"
        ],
    },
    json={
        "automation_ids": [automation["id"]],
        "params": {
            "destination_address": os.environ["DESTINATION_WALLET_ADDRESS"]
        },
    },
)
response.raise_for_status()
attachments = response.json()["data"]

The authorization signature must cover this exact request. Use Privy’s authorization-signature utilities to produce it. An ownerless wallet does not require a wallet-owner signature.

Attaching an automation does not make it a general-purpose wallet signer. Privy authorizes each execution against the attachment’s trigger, action, wallet, and destination.

3. Send a matching deposit

Send USDC to the source wallet on any chain. Privy detects the incoming transfer and evaluates enabled attachments from oldest to newest. Only the first matching automation creates a wallet action. Privy does not fall through to another matching automation if that action fails. Privy reads the current asset balance when the execution runs. Earlier funds held by the wallet can therefore be included in the swap. Attaching an automation does not process a balance already held by the wallet. Send a new matching deposit or reindex the asset to move that balance.

4. Observe the execution

Subscribe to wallet_automation.submitted to receive both the automation execution ID and the generated wallet action ID. The app can also list executions for the source wallet:

cURL
Node SDK
Python

curl --request GET "https://api.privy.io/v1/wallet_automations/executions?wallet_id=$WALLET_ID" \
  --user "$PRIVY_APP_ID:$PRIVY_APP_SECRET" \
  --header "privy-app-id: $PRIVY_APP_ID"

const executions = [];

for await (const execution of privy.walletAutomations().listExecutions({
  wallet_id: process.env.WALLET_ID!
})) {
  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"]

Use the execution’s wallet_action_id to track the final swap through the wallet action lifecycle.

Handle errors

Setup requests can fail when:

The app does not have swaps enabled.
An asset alias, destination chain, or automation owner is invalid.
The wallet-owner authorization signature is missing or does not cover the exact attach request.
The destination address is invalid for the configured destination chain.

An automation can still fail when it executes. Common causes include unavailable routes, insufficient liquidity or gas, policy rejection, and changed app configuration. Inspect failure_reason and the generated wallet action when one exists. After correcting a pre-action failure, reindex the asset.

​Prerequisites

​1. Create the automation

​2. Attach it to a wallet

​3. Send a matching deposit

​4. Observe the execution

​Handle errors

Prerequisites

1. Create the automation

2. Attach it to a wallet

3. Send a matching deposit

4. Observe the execution

Handle errors