Transaction Broadcasting

Broadcast pre-signed transactions directly to the MultiversX P2P network for faster propagation. This bypasses the public API and delivers transactions directly to validators.

Overview

The broadcast action sends fully signed transactions to the network. Use this when you have:

• Transactions signed by the user's wallet

• Pre-signed transactions from a backend service

• Batches of transactions to submit efficiently

Single Transaction

ws.send(JSON.stringify({
  action: 'broadcast',
  requestId: 'tx-001',
  tx: {
    nonce: 42,
    value: '1000000000000000000',
    receiver: 'erd1qqqqqqqqqqqqqpgq...',
    sender: 'erd1abc...',
    gasPrice: 1000000000,
    gasLimit: 50000000,
    data: 'c3dhcEV4YWN0QW1vdW50SW4=',
    chainID: '1',
    version: 2,
    signature: 'a1b2c3d4...'
  }
}));

Batch Transactions

Send multiple transactions in a single message:

ws.send(JSON.stringify({
  action: 'broadcast',
  requestId: 'batch-001',
  txs: [
    {
      nonce: 42,
      value: '0',
      receiver: 'erd1qqqqqqqqqqqqqpgq...',
      sender: 'erd1abc...',
      gasPrice: 1000000000,
      gasLimit: 50000000,
      data: 'c3dhcA==',
      chainID: '1',
      version: 2,
      signature: 'sig1...'
    },
    {
      nonce: 43,
      value: '0',
      receiver: 'erd1qqqqqqqqqqqqqpgq...',
      sender: 'erd1abc...',
      gasPrice: 1000000000,
      gasLimit: 50000000,
      data: 'c3dhcA==',
      chainID: '1',
      version: 2,
      signature: 'sig2...'
    }
  ]
}));

Transaction Object

Field	Type	Required	Description
nonce	number	Yes	Sender's transaction counter
value	string	Yes	EGLD value in atomic units
receiver	string	Yes	Receiver's bech32 address
sender	string	Yes	Sender's bech32 address
gasPrice	number	Yes	Gas price in atomic units
gasLimit	number	Yes	Maximum gas units
data	string	No	Transaction data payload (function + args)
chainID	string	Yes	Chain identifier ("1" for mainnet)
version	number	Yes	Transaction version (typically 2)
options	number	No	Transaction options flags
signature	string	Yes	Hex-encoded sender signature
guardian	string	No	Guardian address (guarded accounts)
guardianSignature	string	No	Guardian signature

Response

Success Response

{
  "action": "broadcast",
  "status": "completed",
  "requestId": "tx-001",
  "hashes": [
    "a1b2c3d4e5f6..."
  ],
  "failed": []
}

Partial Success (Batch)

{
  "action": "broadcast",
  "status": "partial",
  "requestId": "batch-001",
  "hashes": [
    "a1b2c3d4e5f6..."
  ],
  "failed": [
    {
      "index": 1,
      "reason": "invalid signature"
    }
  ]
}

Complete Failure

{
  "action": "broadcast",
  "status": "failed",
  "requestId": "batch-001",
  "hashes": [],
  "failed": [
    {
      "index": 0,
      "reason": "invalid nonce"
    },
    {
      "index": 1,
      "reason": "insufficient balance"
    }
  ]
}

Response Fields

Field	Type	Description
action	string	Always "broadcast"
status	string	completed, partial, or failed
requestId	string	Your provided request ID
hashes	array	Transaction hashes of successful broadcasts
failed	array	Failed transactions with index and reason

Example: Complete Integration

class TransactionBroadcaster {
  constructor(wsUrl) {
    this.ws = new WebSocket(wsUrl);
    this.pending = new Map();
    this.requestCounter = 0;
    
    this.ws.onmessage = (event) => {
      const msg = JSON.parse(event.data);
      if (msg.action === 'broadcast' && msg.requestId) {
        const resolver = this.pending.get(msg.requestId);
        if (resolver) {
          this.pending.delete(msg.requestId);
          resolver(msg);
        }
      }
    };
  }

  async broadcast(transactions) {
    const requestId = `req-${++this.requestCounter}`;
    
    return new Promise((resolve, reject) => {
      // Set timeout
      const timeout = setTimeout(() => {
        this.pending.delete(requestId);
        reject(new Error('Broadcast timeout'));
      }, 30000);
      
      this.pending.set(requestId, (result) => {
        clearTimeout(timeout);
        resolve(result);
      });
      
      // Send broadcast request
      const txs = Array.isArray(transactions) ? transactions : [transactions];
      this.ws.send(JSON.stringify({
        action: 'broadcast',
        requestId,
        txs
      }));
    });
  }

  async broadcastAndWait(transaction) {
    const result = await this.broadcast(transaction);
    
    if (result.status === 'failed') {
      throw new Error(result.failed[0]?.reason || 'Broadcast failed');
    }
    
    return result.hashes[0];
  }
}

// Usage
const broadcaster = new TransactionBroadcaster('wss://relayer.xoxno.com/ws');

// Wait for connection
await new Promise(resolve => {
  broadcaster.ws.onopen = resolve;
});

// Broadcast a signed transaction
const txHash = await broadcaster.broadcastAndWait({
  nonce: 42,
  value: '1000000000000000000',
  receiver: 'erd1qqqqqqqqqqqqqpgq...',
  sender: 'erd1abc...',
  gasPrice: 1000000000,
  gasLimit: 50000000,
  data: 'swapExactAmountIn@...', // Raw payload (function + args)
  chainID: '1',
  version: 2,
  signature: 'your-signature-here'
});

console.log(`Transaction hash: ${txHash}`);

Batch Processing Example

async function broadcastBatch(broadcaster, signedTxs) {
  const result = await broadcaster.broadcast(signedTxs);
  
  console.log(`Status: ${result.status}`);
  console.log(`Successful: ${result.hashes.length}`);
  console.log(`Failed: ${result.failed.length}`);
  
  // Handle failures
  if (result.failed.length > 0) {
    for (const failure of result.failed) {
      console.error(`TX ${failure.index} failed: ${failure.reason}`);
    }
  }
  
  return result;
}

Error Reasons

Common failure reasons:

Reason	Description
invalid signature	Signature doesn't match sender
invalid nonce	Nonce already used or too high
insufficient balance	Not enough EGLD for value + fees
invalid receiver	Malformed receiver address
gas limit too low	Gas limit below minimum
invalid chain id	Wrong network (testnet vs mainnet)

Broadcast vs Relay

Feature	Broadcast	Relay
Signing	Pre-signed by user	Co-signed by relayer
Use case	Standard transactions	Gasless/meta transactions
Speed	Faster (no signing step)	Slightly slower
Requirements	Full signature	Valid transaction structure

For gasless transactions or relayed execution, use the relay action instead.

Best Practices

1. Include requestId - Always provide a unique requestId to correlate responses

2. Handle partial failures - Check both hashes and failed arrays

3. Validate before sending - Verify signatures and nonces client-side

4. Implement retry logic - Retry failed transactions with corrected parameters

5. Monitor transaction status - Subscribe to tx-status/{hash} after broadcasting

Related Topics

• Transaction Relaying - Co-signed gasless transactions

• Account Subscriptions - Monitor transaction confirmations

• Gas Statistics - Optimize gas pricing

• Troubleshooting - Common transaction errors