Batch Transaction API

Overview

Batch transactions let you queue multiple blockchain actions for approval before execution. This is particularly useful for:

• Automating regular payment runs

• Managing treasury operations that require final approval

• Integrating with your existing financial workflows

• Creating complex transaction sequences that execute together

Important

This API queues transactions for approval in your dashboard—it does not submit them directly to the blockchain.

Prerequisites

• An API token

• A Stackup wallet address

You can view and approve batch transactions on your organization’s dashboard under Pay.

Endpoints

Create a Batch Transaction

Queue a new batch transaction containing multiple actions for later approval.

POST /v1/wallet/{walletAddress}/batch-transactions

URL Parameters

Request Body

Action Types

Native Token Transfer

{
  "type": "native",
  "to": {
    "address": "0x123...",
    "name": "Vendor Name"    // Optional
  },
  "value": "1",              // In regular decimal units (e.g., 1 = 1 ETH)
  "note": "April payment"    // Optional
}

ERC20 Token Transfer

{
  "type": "erc20",
  "to": {
    "address": "0x456...",
    "name": "Employee Name"  // Optional
  },
  "value": "100",            // In regular decimal units (e.g., 100 = 100 USDC)
  "token": "USDC",
  "note": "Salary payment"   // Optional
}

Formatting of the value field

The value field uses human-readable decimal formatting. For example, use "1" to send 1 ETH or "100" to send 100 USDC—the API handles conversion to the appropriate base units.

Example Request

{
  "chainID": "1",
  "actions": [
    {
      "type": "native",
      "to": {
        "address": "0x4a23C1b2F3d4C56a7B8E9D4de3F87F2d07dd57c0",
        "name": "Marketing Agency"
      },
      "value": "0.5",
      "note": "Monthly retainer"
    },
    {
      "type": "erc20",
      "to": {
        "address": "0x8B4C35c3DBd93033Ba94c3144DaF215b84F1D7b1",
        "name": "Development Team"
      },
      "value": "5000",
      "token": "USDC",
      "note": "Project milestone payment"
    }
  ]
}

Responses

Success Response (200 OK)

{
  "result": "1234567890abcdef"  // The generated batch transaction ID
}

Error Response

{
  "error": "unsupported chainID: 1234"
}

Get a Batch Transaction

Retrieve details about a specific batch transaction.

GET /v1/wallet/{walletAddress}/batch-transactions/{id}

URL Parameters

Responses

Success Response (200 OK)

{
  "id": "1234567890abcdef",
  "type": "pending",
  "chainID": "1",
  "actions": [
    {
      "type": "native",
      "to": {
        "address": "0x4a23C1b2F3d4C56a7B8E9D4de3F87F2d07dd57c0",
        "name": "Marketing Agency"
      },
      "value": "0.5",
      "note": "Monthly retainer"
    }
  ],
  "timeCreated": "2025-04-08T10:30:00Z"
}

List Batch Transactions

Retrieve a list of batch transactions for your wallet.

GET /v1/wallet/{walletAddress}/batch-transactions

URL Parameters

Query Parameters

Responses

Success Response (200 OK)

[
  {
    "id": "1234567890abcdef",
    "type": "pending",
    "chainID": "1",
    "actions": [
      {
        "type": "native",
        "to": {
          "address": "0x4a23C1b2F3d4C56a7B8E9D4de3F87F2d07dd57c0",
          "name": "Marketing Agency"
        },
        "value": "0.5",
        "note": "Monthly retainer"
      }
    ],
    "timeCreated": "2025-04-08T10:30:00Z"
  },
  {
    "id": "0987654321fedcba",
    "type": "success",
    "chainID": "1",
    "txHash": "0x7a23c1b2f3d4c56a7b8e9d4de3f87f2d07dd57c01234567890abcdef01234567",
    "userOpHash": "0x8b4c35c3dbd93033ba94c3144daf215b84f1d7b11234567890abcdef01234567",
    "actions": [
      {
        "type": "erc20",
        "to": {
          "address": "0x8B4C35c3DBd93033Ba94c3144DaF215b84F1D7b1",
          "name": "Development Team"
        },
        "value": "5000",
        "token": "USDC",
        "note": "Project milestone payment"
      }
    ],
    "timeCreated": "2025-04-08T09:15:00Z",
    "timeExecuted": "2025-04-08T11:20:00Z"
  }
]

Delete a Pending Batch Transaction

Remove a queued transaction before it's approved.

DELETE /v1/wallet/{walletAddress}/batch-transactions/{id}

URL Parameters

Responses

Success Response (200 OK)

{
  "success": true
}

Error Response

{
  "error": "id not found: 0987654321fedcba"
}

Data Types

BatchTransaction

Action Types

Native Token Transfer

ERC20 Token Transfer

Notifications on update

If webhook is configured, the following event will be pushed on all updates to a batch transaction.

{
   "id":"evt_123",
   "type":"payout.updated",
   "version":"1.0",
   "timestamp":"2024-08-08T12:34:56Z",
   "data":{
      "id":"1234567890abcdef",
      "status":"success",
      "userOperationHash":"0x...",
      "txHash":"0x...",
      "txTimestamp":"2024-08-08T12:34:56Z"
   }
}

Implementation Guide

Common Use Cases

1. Automating regular payments Create a batch for all monthly vendor payments, then approve them with a single signature.

2. Managing team expenses Let team members queue transactions that require approval before execution.

3. Treasury operations Schedule token transfers between wallets or exchanges with final approval by authorized signers.

Best Practices

• Use descriptive notes for easier reconciliation later

• Include contact names when possible for better transaction history

• For high-value transactions, double-check addresses before submission

Need Help?

If you have questions or need assistance with the Batch Transactions API, contact our support team