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

# Batch Broadcast

> Sponsor and broadcast up to 25 transactions in a single API call

## Overview

`POST /api/v1/broadcast/batch` co-signs and broadcasts up to **25 sponsored transactions** in one request. Each transaction is processed concurrently and independently — one failure does not abort the rest.

The endpoint always returns HTTP `200`. Check each item's `error` field for per-item failures.

***

## Request

**Headers:**

```http theme={null}
x-api-key: YOUR_API_KEY
Content-Type: application/json
```

**Body:**

```json theme={null}
{
  "transactions": [
    { "txHex": "0x..." },
    { "txHex": "0x...", "feeAmount": "250000" }
  ],
  "userId": "optional-user-id"
}
```

| Field                      | Type     | Required | Description                                                                        |
| :------------------------- | :------- | :------- | :--------------------------------------------------------------------------------- |
| `transactions`             | `array`  | Yes      | Array of transaction objects. Max 25.                                              |
| `transactions[].txHex`     | `string` | Yes      | Signed sponsored transaction hex.                                                  |
| `transactions[].feeAmount` | `string` | No       | Fee in token micro-units. Required for `USER_PAYS`, omit for `DEVELOPER_SPONSORS`. |
| `userId`                   | `string` | No       | User identifier override. Falls back to the API key owner.                         |

***

## Response

```json theme={null}
{
  "results": [
    { "index": 0, "txid": "0xabc...", "status": "sponsored" },
    { "index": 1, "error": "Transaction already processed (replay detected)" },
    { "index": 2, "txid": "0xdef...", "status": "sponsored" }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  }
}
```

| Field               | Description                                                                                   |
| :------------------ | :-------------------------------------------------------------------------------------------- |
| `results`           | Per-item outcome. Successful items include `txid` and `status`. Failed items include `error`. |
| `summary.total`     | Total number of transactions submitted.                                                       |
| `summary.succeeded` | Number successfully sponsored and broadcast.                                                  |
| `summary.failed`    | Number that failed (replay, validation error, etc.).                                          |

***

## Rate Limits

Batch limits are tighter than single broadcast because one call can sponsor up to 25 transactions.

| Limit       | Value             |
| :---------- | :---------------- |
| Per API key | 5 requests / 60s  |
| Per IP      | 10 requests / 60s |

Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header.

***

## SDK Usage

```typescript theme={null}
import { VelumXClient } from '@velumx/sdk';

const velumx = new VelumXClient({
  paymasterUrl: '/api/velumx/proxy',
  network: 'mainnet',
});

// DEVELOPER_SPONSORS — users pay nothing
const result = await velumx.sponsorBatch([
  { txHex: signedTx1 },
  { txHex: signedTx2 },
  { txHex: signedTx3 },
]);

result.results.forEach(item => {
  if ('error' in item) {
    console.error(`TX ${item.index} failed:`, item.error);
  } else {
    console.log(`TX ${item.index} sponsored:`, item.txid);
  }
});

console.log(result.summary);
// { total: 3, succeeded: 2, failed: 1 }
```

***

## Use Cases

* **Airdrops** — distribute tokens to multiple users in one call
* **Queue processing** — drain a backlog of pending sponsored transactions
* **Multi-step flows** — execute a sequence of contract calls on behalf of multiple users simultaneously