📘

Supported on BSC mainnet & testnet.

Overview

These APIs provide enhanced transaction privacy and atomicity for the BNB Smart Chain (BSC) network. By implementing the BEP322 standard, the following capabilities are provided:

• Privacy. All transactions sent through this API will not be propagated on the P2P network, hence, they won't be detected by any third parties. This effectively prevents transactions from being targeted by sandwich attacks.
• Batch transaction. Multiple transactions can be consolidated into a single 'bundle', which can then be transmitted through just one API call. The sequence of transactions within a block, as well as the order within a bundle, can be assured to maintain impeccable consistency.
• Atomicity. Transactions within a bundle either all get included on the chain, or none at all. There's no such scenario where only a portion of the transactions are included on chain.
• Gas protection. If a single transaction within a bundle fails, the entire bundle is guaranteed not to be packaged onto the blockchain. This mechanism safeguards users from unnecessary gas expenditure.
  This API service is built on top of BSC MEV. Explore here for more details.

How to Subscribe

These APIs are only available for Growth or above tiers who subscribe to this package.

What is Bundle

A bundle refers to a collection of transactions, which are either successfully validated on the blockchain together, or altogether rejected eventually. In this API service, the 'Bundle' is the fundamental unit. Developers is able to send bundles and check the status of these bundles.

What is Bundle Price

Unlike sorting in the tx pool based on tx gas prices, the acceptance of a bundle is determined by its overall gas price, not the gas price of a single transaction. If the overall bundle price is too low, it will be rejected by the network. The rules for calculating the bundle price are as follows:
bundlePrice = sum(gasFee of each transaction) / sum(gas used of each transaction)
Developers should ensure that the bundlePrice always exceeds the value returned by the eth_bundlePrice API endpoint.

API Endpoint

The format of an RPC endpoint is
https://bsc-mainnet.nodereal.io/{{apiKey}}

https://bsc-testnet.nodereal.io/{{apiKey}}

API List

eth_bundlePrice

Query the gas price floor of a bundle.

Request Params

• No request params

Response Params

• bundlePrice - integer - average bundle price in recent blocks

// request
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_bundlePrice"
}

// response
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": 1000000000
}

eth_sendBundle

Send bundle, and get bundle hash as a receipt.

Request Params

• bundle, object  - The bundle object which contains the following fields:
  • txs - list - Signed raw transactions in order
  • maxBlockNumber - uint64 - Allowed max confirmed block number, can be 0
  • minTimestamp - uint64 - Allowed min confirmed time, can be null
  • maxTimestamp - uint64 - Allowed max confirmed time, can be null
  • revertingTxHashes - list - whitelist of revert allowed txs hash. Transactions in the bundle are not allowed to be reverted by default unless the hash of the reverted transaction is set in this field.
    Notice: if maxBlockNumber is 0 and maxTimestamp is null, the maxBlockNumber will set as 100 blocks after the current block

Response Params

• bundle hash - string - identity of the bundle

// request
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_sendBundle",
    "params": [
        {
            "txs": [
               // signed raw txs
               "0x...", 
               "0x..."
            ],
            "maxBlockNumber": 0,
            "minTimestamp": 1714460826,
            "maxTimestamp": 1714460826,
            "revertingTxHashes": null
        }
    ]
}

// response
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        // bundle hash
        "0x..."
    ]
}

// failed response
{
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
        "code": -32000,
        "message": "no valid sim result"
    }
}

eth_queryBundle

Query bundle by bundle hash.

Request Params

• bundle hash - string - bundle hash returned by eth_sendBundle api

Response Params

• bundle - object - bundle info
  • hash - string - bundle hash
  • txs - list - txs hash in bundle
  • maxBlockNumber - uint64 - Allowed max confirmed block number
  • maxTimestamp - uint64 - Allowed max confirmed timestamp
  • status - integer - Bundle status, 0: pending; 1: confirmed; 2: failed
  • gasFee - string - Total gasFee of bundle
  • builder - string - Builder that confirmed the bundle
  • confirmedBlockNumber - uint64 - Block Number of the bundle confirmed(when status is 1) or failed (when status is 2)
  • confirmedDate - uint64 - Date of the bundle confirmed(at 0 clock)

// request
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_queryBundle",
    "params": [
        "0x..."
    ]
}

// response
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "Hash": "0x.....",
        "Txs": [
          // tx hashes
          ...
        ],
        "MaxBlockNumber": 39915767,
        "MaxTimestamp": 0,
        "Status": 1,
        "GasFee": "0x775f05a074000",
        "Builder": "0x79102db16781dddff63f301c9be557fd1dd48fa0",
        "ConfirmedBlockNumber": 39915671,
        "ConfirmedDate": 1714435200
    }
}

eth_builders

Return builder lists, which are configured in a bundle.

Request Params

• No request params

Response Params

• builders - list - builder address list

// request
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_builders"
}

// response
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        // builder's addresses
        "0x79102db16781dddff63f301c9be557fd1dd48fa0"
    ]
}

eth_validators

Return validator lists, which are configured in a bundle.

Request Params

• No request params

Response Params

• validators - list - validator address list

// request
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_validators"
}

// response
{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        // validator addresses
        "0xbdcc079bbb23c1d9a6f36aa31309676c258abac7",
        "0x5009317fd4f6f8feea9dae41e5f0a4737bb7a7d5",
        "0xb4647b856cb9c3856d559c885bed8b43e0846a47"
    ]
}