Skip to main content

​
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"
}
FieldTypeRequiredDescription
transactionsarrayYesArray of transaction objects. Max 25.
transactions[].txHexstringYesSigned sponsored transaction hex.
transactions[].feeAmountstringNoFee in token micro-units. Required for USER_PAYS, omit for DEVELOPER_SPONSORS.
userIdstringNoUser 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
  }
}
FieldDescription
resultsPer-item outcome. Successful items include txid and status. Failed items include error.
summary.totalTotal number of transactions submitted.
summary.succeededNumber successfully sponsored and broadcast.
summary.failedNumber that failed (replay, validation error, etc.).

​
Rate Limits

Batch limits are tighter than single broadcast because one call can sponsor up to 25 transactions.
LimitValue
Per API key5 requests / 60s
Per IP10 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