Create and attach an automation

This guide creates an automation that converts USDC and USDT deposits 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.
A source Privy wallet.
An authorization signature when the source wallet has an owner.
Gas sponsorship.

1. Create the automation

Create an app-scoped automation with POST /v1/wallet_automations. See configure triggers and actions for the complete set of trigger, filter and action semantics we support today. The source asset aliases below do not specify a chain. Privy expands each asset to its supported deployments. The destination includes a chain because every swap must have one destination.

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"},
            {"asset": "usdt"}
          ]
        }
      },
      "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'}, {asset: 'usdt'}]
      }
    },
    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"}, {"asset": "usdt"}],
                },
            },
            "action": {
                "type": "swap",
                "destination_chain_asset": {"asset": "pathusd", "chain": "tempo"},
            },
        },
    },
)
response.raise_for_status()
automation = response.json()

Save the returned id. API responses contain the resolved asset_address and caip2 values instead of input aliases. See the create automation API reference for the complete schema.

2. Attach it to a wallet

An attachment enables the automation for one wallet. In the swap example, the params indicate that its destination_address receives the output of every generated swap.

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 or USDT to the source wallet on a supported chain. Privy detects the deposit and evaluates enabled attachments in creation order. The first matching automation creates a swap wallet action. Privy reads the current asset balance when the execution runs. Earlier funds held by the wallet can therefore be included in the swap.

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.

Controls

Owners & signers

Configuring your wallets

Creating owners & signers

Using owners & signers

Key quorums

Create and attach an automation

Prerequisites

1. Create the automation

2. Attach it to a wallet

3. Send a matching deposit

4. Observe the execution

​Prerequisites

​1. Create the automation

​2. Attach it to a wallet

​3. Send a matching deposit

​4. Observe the execution

Prerequisites

1. Create the automation

2. Attach it to a wallet

3. Send a matching deposit

4. Observe the execution