How to use Bundle

This guide explains how to submit transaction bundles on BNB Smart Chain using GetBlock's MEV endpoint.

A bundle is a group of transactions submitted together with a guarantee that either all transactions execute in sequence or none are included. This atomic execution model supports several advanced use cases:

• Arbitrage: Execute a buy on one DEX and a sell on another within the same block, ensuring both trades complete, or neither does

• Liquidations: Check a position's health and liquidate it atomically, preventing front-running

• Complex strategies: Coordinate multi-step transactions with guaranteed execution order

Prerequisites

Before submitting bundles, ensure you have:

• A GetBlock API key with MEV endpoint access

• Node.js v16 or later

• A funded BSC wallet with sufficient BNB for all transactions and gas

Sample Request

Endpoint

Connect to the MEV WebSocket endpoint with your API key:

wss://go.getblock.io/<ACCESS_TOKEN>

Parameters

Request Format

Response Format

Example

1

Set up the project

npm

mkdir bundle-example
cd bundle-example
npm init -y
npm install ws ethers dotenv

yarn

2

Create a new file named index.js. This is where you will make your first call.

3

Set the ES module "type": "module" in your package.json.

4

Add the following code to index.js:

The following example demonstrates a simple BNB transfer with a priority fee:

import WebSocket from 'ws';
import { ethers } from 'ethers';
import 'dotenv/config';

const PRIVATE_KEY = 'YOUR_PRIVATE_KEY';

async function submitBundle() {
  const provider = new ethers.JsonRpcProvider('https://bsc-dataseed.binance.org');
  const wallet = new ethers.Wallet(PRIVATE_KEY, provider);
  
  // Get the current nonce for your wallet
  const nonce = await provider.getTransactionCount(wallet.address);
  
  // Transaction 1: First operation
  const tx1 = await wallet.signTransaction({
    nonce: nonce,
    to: DEX_A,
    value: ethers.parseEther('1.0'),
    data: buyCalldata,
    gasPrice: ethers.parseUnits('3', 'gwei'),
    gasLimit: 300000,
    chainId: 56
  });
  
  // Transaction 2: Second operation (must use nonce + 1)
  const tx2 = await wallet.signTransaction({
    nonce: nonce + 1,
    to: DEX_B,
    value: 0,
    data: sellCalldata,
    gasPrice: ethers.parseUnits('3', 'gwei'),
    gasLimit: 300000,
    chainId: 56
  });
  
  // Connect to the MEV endpoint
  const ws = new WebSocket(`wss://go.getblock.io/${process.env.ACCESS_TOKEN}`);
  
  ws.on('open', () => {
    ws.send(JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'mev_sendBundle',
      params: {
        transactions: [tx1, tx2],
        mev_builders: { all: '' },
        blocks_count: 5
      }
    }));
  });
  
  ws.on('message', (data) => {
    const response = JSON.parse(data);
    
    if (response.result) {
      console.log('Bundle submitted successfully');
      console.log('Bundle Hash:', response.result.bundleHash);
    } else {
      console.error('Submission failed:', response.error);
    }
    
    ws.close();
  });
}

submitBundle();

5

Run the code using this command:

node index.js

6

Sample response

Example: DEX Arbitrage

This example demonstrates a complete arbitrage strategy: buying a token on PancakeSwap V2 and selling on PancakeSwap V3 within the same block, with an optional priority fee.

Reference Addresses

Address	Purpose
0x10ED43C718714eb63d5aA57B78B54704E256024E	PancakeSwap V2 Router
0x13f4EA83D0bd40E75C8222255bc855a974568Dd4	PancakeSwap V3 Router
0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c	WBNB
0x6374Ca2da5646C73Eb444aB99780495d61035f9b	Priority fee recipient

Code Example

const WebSocket = require('ws');
const { ethers } = require('ethers');

const API_KEY = 'YOUR_API_KEY';
const PRIVATE_KEY = 'YOUR_PRIVATE_KEY';

// Contract addresses
const PANCAKE_V2_ROUTER = '0x10ED43C718714eb63d5aA57B78B54704E256024E';
const PANCAKE_V3_ROUTER = '0x13f4EA83D0bd40E75C8222255bc855a974568Dd4';
const FEE_ADDRESS = '0x6374Ca2da5646C73Eb444aB99780495d61035f9b';
const WBNB = '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c';
const TOKEN = '0xYOUR_TOKEN';

async function arbitrage() {
  const provider = new ethers.JsonRpcProvider('https://bsc-dataseed.binance.org');
  const wallet = new ethers.Wallet(PRIVATE_KEY, provider);
  
  const nonce = await provider.getTransactionCount(wallet.address);
  const deadline = Math.floor(Date.now() / 1000) + 300;
  
  // Encode the V2 swap
  const v2ABI = [
    'function swapExactETHForTokens(uint256 amountOutMin, address[] path, address to, uint256 deadline) payable'
  ];
  const v2Router = new ethers.Contract(PANCAKE_V2_ROUTER, v2ABI, wallet);
  
  const buyData = v2Router.interface.encodeFunctionData('swapExactETHForTokens', [
    0,  // amountOutMin (set appropriately in production)
    [WBNB, TOKEN],
    wallet.address,
    deadline
  ]);
  
  // Transaction 1: Buy on PancakeSwap V2
  const tx1 = await wallet.signTransaction({
    nonce: nonce,
    to: PANCAKE_V2_ROUTER,
    value: ethers.parseEther('1.0'),
    data: buyData,
    gasPrice: ethers.parseUnits('3', 'gwei'),
    gasLimit: 300000,
    chainId: 56
  });
  
  // Transaction 2: Sell on PancakeSwap V3
  // Note: V3 uses a different interface; replace with your actual V3 swap calldata
  const tx2 = await wallet.signTransaction({
    nonce: nonce + 1,
    to: PANCAKE_V3_ROUTER,
    value: 0,
    data: '0x...',  // Your V3 swap calldata
    gasPrice: ethers.parseUnits('3', 'gwei'),
    gasLimit: 300000,
    chainId: 56
  });
  
  // Transaction 3: Priority fee (optional but recommended)
  const tx3 = await wallet.signTransaction({
    nonce: nonce + 2,
    to: FEE_ADDRESS,
    value: ethers.parseEther('0.001'),
    gasPrice: ethers.parseUnits('3', 'gwei'),
    gasLimit: 21000,
    chainId: 56
  });
  
  // Submit the bundle
  const ws = new WebSocket(`wss://bsc.getblock.io/mev/ws?api_key=${API_KEY}`);
  
  return new Promise((resolve, reject) => {
    ws.on('open', () => {
      ws.send(JSON.stringify({
        jsonrpc: '2.0',
        id: 1,
        method: 'mev_sendBundle',
        params: {
          transactions: [tx1, tx2, tx3],
          mev_builders: { all: '' },
          blocks_count: 3  // Short validity for time-sensitive arbitrage
        }
      }));
    });
    
    ws.on('message', (data) => {
      const response = JSON.parse(data);
      ws.close();
      
      if (response.result) {
        console.log('Bundle submitted successfully');
        console.log('Bundle Hash:', response.result.bundleHash);
        resolve(response.result.bundleHash);
      } else {
        console.error('Submission failed:', response.error);
        reject(response.error);
      }
    });
  });
}

arbitrage();

Comparing Bundles and Private Transactions

Choose the appropriate method based on your use case:

Aspect	bsc_privateTx	mev_sendBundle
Transaction count	Single	Multiple
Atomicity	Not applicable	All-or-nothing execution
Use cases	Simple transfers, individual swaps	Arbitrage, multi-step operations
Adding priority fees	Via Multicall3	Separate transaction in bundle
mev_builders format	Array: ["all"]	Object: {"all": ""}

Best Practices

1. Use Sequential Nonces

All transactions in a bundle must have consecutive nonces starting from your wallet's current nonce:

const nonce = await provider.getTransactionCount(wallet.address);

// Transaction 1: nonce
// Transaction 2: nonce + 1
// Transaction 3: nonce + 2

2. Include a Priority Fee

Adding a fee payment as the final transaction increases the likelihood of bundle inclusion:

const feeTx = await wallet.signTransaction({
  nonce: lastNonce,
  to: '0x6374Ca2da5646C73Eb444aB99780495d61035f9b',
  value: ethers.parseEther('0.001'),
  gasPrice: ethers.parseUnits('3', 'gwei'),
  gasLimit: 21000,
  chainId: 56
});

Choose an Appropriate blocks_count Value

The blocks_count parameter determines how long your bundle remains valid. Shorter validity periods signal higher urgency to builders:

Use Case	Recommended blocks_count
Time-sensitive arbitrage	2–3
Standard bundles	5
Less urgent operations	10–20

Simulate Before Submitting

Test your transaction logic before submitting a bundle by simulating each transaction:

await provider.call({
  to: tx1.to,
  data: tx1.data,
  value: tx1.value
});

Troubleshooting

Problem	Solution
Bundle Not Included	If your bundle is not included after the specified block count: Increase the priority fee — Add a higher fee payment transaction Verify nonce sequence — Nonces must be strictly consecutive with no gaps Reduce blocks_count — Shorter validity signals higher priority to builders Validate each transaction — Ensure every transaction in the bundle is valid independently
"Invalid bundle" Error	This error indicates a formatting or validation issue: Check parameter format — The transactions parameter must be an array; mev_builders must be an object Verify signatures — All transactions must be properly signed Confirm chain ID — Use chain ID 56 for BSC Mainnet
Partial Execution	Bundles execute atomically, so partial execution should not occur. If you observe partial execution: Contact support — This indicates a potential builder issue Verify using the bundle hash — Check the bundle status on a block explorer