Batch Broadcast

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:

x-api-key: YOUR_API_KEY
Content-Type: application/json

Body:

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

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

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

Introduction

Protocol Architecture

Developer Implementation

Relayer API Reference

Infrastructure Reference

Batch Broadcast

Overview

Request

Response

Rate Limits

SDK Usage

Use Cases

​Overview

​Request

​Response

​Rate Limits

​SDK Usage

​Use Cases

Overview

Request

Response

Rate Limits

SDK Usage

Use Cases