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
Connect to the MEV WebSocket endpoint with your API key:
wss://shared.eu-central-1.getblock.io/<ACCESS_TOKEN>transactions
array
Yes
Array of signed raw transactions (hex-encoded)
mev_builders
object
No
Target builders. Use {"all": ""} for all builders, or specify individual builders
blocks_count
integer
No
Number of blocks the bundle remains valid. Default: 5, Maximum: 20
Submit bundles using the mev_sendBundle method:
{
"jsonrpc": "2.0",
"id": 1,
"method": "mev_sendBundle",
"params": {
"transactions": ["0xf86c...", "0xf86c..."],
"mev_builders": { "all": "" },
"blocks_count": 5
}
}A successful submission returns a bundle hash:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"bundleHash": "0x..."
}
}Example
Set up the project
mkdir bundle-example
cd bundle-example
npm init -y
npm install ws ethers dotenvmkdir bundle-example
cd bundle-example
yarn init -y
yarn ws ethers dotenvCreate a new file named index.js. This is where you will make your first call.
Set the ES module "type": "module" in your package.json.
Create .env file and add the following:
ACCESS_TOKEN=your-accelerated-node-endpoint
RPC_URL=your-normal-bsc-node-endppoint //e.g https
PRIVATE_KEY=your-wallet-private-keyAdd 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 = process.env.PRIVATE_KEY;
const RPC_URL = process.env.RPC_URL;
async function submitBundle() {
const provider = new ethers.JsonRpcProvider(RPC_URL);
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("0.001"),
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(process.env.ACCESS_TOKEN);
ws.on("open", () => {
ws.send(
JSON.stringify({
jsonrpc: "2.0",
id: 1,
method: "mev_sendBundle",
params: {
transactions: [tx1.slice(2), tx2.slice(2)],
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();Run the code using this command:
node index.jsSample response
Example: DEX 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:
2. Include a Priority Fee
Adding a fee payment as the final transaction increases the likelihood of bundle inclusion:
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:
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:
Troubleshooting
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
transactionsparameter must be an array;mev_buildersmust be an objectVerify 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
Last updated
Was this helpful?