---
title: "Batch Transaction API"
slug: "batched-transactions-api"
description: "Learn how to queue, retrieve, and manage crypto transactions with Stackup's Batch Transaction API. Streamline treasury operations and automate payments with simple API calls and approval workflows."
updated: 2025-09-20T05:11:53Z
published: 2025-09-20T05:11:53Z
canonical: "docs.stackup.fi/batched-transactions-api"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackup.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

> [!WARNING]
> Important
> 
> This API queues transactions for approval in your dashboard—it does not submit them directly to the blockchain.

## Prerequisites

- An [API token](/v1/docs/creating-an-api-key)
- 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.

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

#### URL Parameters

| Parameter | Description |
| --- | --- |
| `walletAddress` | Your wallet's address |

#### Request Body

| Field | Type | Description |
| --- | --- | --- |
| `chainID` | string | Blockchain network ID (e.g., "1" for Ethereum mainnet) |
| `actions` | Array | List of actions to include in this batch |

#### Action Types

**Native Token Transfer**

```json
{
  "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**

```json
{
  "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
}
```

> [!NOTE]
> 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

```json
{
  "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

| Status | Description |
| --- | --- |
| 200 | Success |
| 400 | Bad request (invalid parameters) |
| 401 | Unauthorized |
| 404 | Wallet not found |

#### Success Response (200 OK)

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

#### Error Response

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

### Get a Batch Transaction

Retrieve details about a specific batch transaction.

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

#### URL Parameters

| Parameter | Description |
| --- | --- |
| `walletAddress` | Your wallet's address |
| `id` | Batch transaction ID |

#### Responses

| Status | Description |
| --- | --- |
| 200 | Success |
| 401 | Unauthorized |
| 404 | Wallet or transaction not found |

#### Success Response (200 OK)

```json
{
  "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.

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

#### URL Parameters

| Parameter | Description |
| --- | --- |
| `walletAddress` | Your wallet's address |

#### Query Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `page` | number | Page number (default: 1) |
| `limit` | number | Items per page (default: 10) |
| `status` | string | Filter by status: "pending", "success", or "failed" |

#### Responses

| Status | Description |
| --- | --- |
| 200 | Success |
| 401 | Unauthorized |
| 404 | Wallet not found |

#### Success Response (200 OK)

```json
[
  {
    "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.

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

#### URL Parameters

| Parameter | Description |
| --- | --- |
| `walletAddress` | Your wallet's address |
| `id` | Batch transaction ID to delete |

#### Responses

| Status | Description |
| --- | --- |
| 200 | Success |
| 401 | Unauthorized |
| 404 | Wallet or transaction not found |

#### Success Response (200 OK)

```json
{
  "success": true
}
```

#### Error Response

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

## Data Types

### BatchTransaction

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique transaction identifier |
| `chainID` | string | Target blockchain network ID |
| `type` | string | Status: "pending", "success", or "failed" |
| `actions` | Array | List of actions in this batch |
| `timeCreated` | string | Creation timestamp (ISO 8601) |
| `timeExecuted` | string | Execution timestamp (ISO 8601, for completed transactions) |
| `txHash` | string | On-chain transaction hash (for completed transactions) |
| `userOpHash` | string | ERC-4337 UserOperation hash (for completed transactions) |

### Action Types

**Native Token Transfer**

| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Always "native" |
| `to` | object | Recipient information |
| `to.address` | string | Recipient wallet address |
| `to.name` | string | Optional recipient name |
| `value` | string | Amount in decimal format |
| `note` | string | Optional internal note |

**ERC20 Token Transfer**

| Field | Type | Description |
| --- | --- | --- |
| `type` | string | Always "erc20" |
| `to` | object | Recipient information |
| `to.address` | string | Recipient wallet address |
| `to.name` | string | Optional recipient name |
| `value` | string | Amount in decimal format |
| `token` | string | Token symbol (e.g., "USDC") |
| `note` | string | Optional internal note |

## Notifications on update

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

| Data field | Type | Description |
| --- | --- | --- |
| `id` | string | Batch transaction ID |
| `status` | string | Latest status of the batch. One of `scheduled`, `success`, `failed`. |
| `userOperationHash` | string, null | A `null` value if scheduled and not yet onchain. Otherwise a `hex` string to identify the UserOperation that executed the batch. |
| `txHash` | string, null | A `null` value if scheduled and not yet onchain. Otherwise a `hex` string to identify the transaction that bundled the UserOperation. |
| `txTimestamp` | string, null | A `null` value if scheduled and not yet onchain. Otherwise an ISO 8601 date string of the block time the batch was included in. |

```json
{
   "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](/v1/docs/contact-support)