eth_sendBundle

Submit a bundle of Ethereum transactions for ordered execution within a block. Transactions execute in the order submitted, with explicit controls for revertable and optional transactions.

Endpoint

See Getting Started for regional endpoints.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendBundle",
  "params": [
    {
      "txs": ["0x...", "0x..."],
      "blockNumber": "0x1234567",
      "minTimestamp": 1234567890,
      "maxTimestamp": 1234567899,
      "revertingTxHashes": ["0x..."],
      "droppingTxHashes": ["0x..."],
      "replacementUuid": "uuid-string",
      "replacementSeqNumber": 1,
      "refundPercent": 50,
      "refundRecipient": "0x...",
      "refundTxHashes": ["0x..."]
    }
  ]
}

Parameters

Execution Semantics

Transactions within a bundle execute in the order submitted.

By default, any transaction failure invalidates the bundle. The two hash sets relax that, and they grant two separate permissions:

Strict all-or-nothing behavior therefore applies only to transactions that are not listed in revertingTxHashes or droppingTxHashes.

Refunds

When refundPercent is greater than zero, Bombora pays a refund to refundRecipient in a separate transfer. The gas cost of that transfer is deducted from the refund:

refund = (anchor_profit * refundPercent / 100) - transfer_cost

anchor_profit is the combined coinbase profit of the refund anchor transactions (from refundTxHashes, or the last tx by default), not the profit of the whole bundle. It includes priority fees and direct coinbase transfers. The percentage is applied first and rounded down to the wei, then the transfer cost is subtracted.

transfer_cost is the gas the refund transfer uses multiplied by the block's base fee:

transfer_cost = transfer_gas_used * base_fee

Refunds to the same recipient in one block are summed and paid with a single transfer, so the transfer cost is deducted once.

Examples

Refund transfers are sent through the payment forwarder contract 0xFEEEEEE44046c3f61a8CC081E0918eF0de0a7ffC. The forwarder pays with SELFDESTRUCT, so no recipient code runs. A transfer through it uses 29,022 gas, or 25,000 more when the recipient account is empty. All examples assume a non-empty recipient and a base fee of 1 gwei, so a transfer costs 29,022 gas * 1 gwei = 0.000029022 ETH.

One anchor. The bundle's last transaction pays the builder 0.01 ETH in priority fees and coinbase transfers, and refundPercent is 90:

anchor_profit = 0.01 ETH
refund        = 0.01 * 90 / 100 - 0.000029022 = 0.008970978 ETH

Several anchors. The bundle is [A, B, C] with refundTxHashes set to [B, C]. A pays the builder 0.002 ETH, B pays 0.004 ETH, and C pays 0.006 ETH. A is not an anchor:

anchor_profit = 0.004 + 0.006 = 0.01 ETH
refund        = 0.01 * 90 / 100 - 0.000029022 = 0.008970978 ETH

Two bundles refunding the same recipient. Both bundles land in the same block and name the same refundRecipient. Bundle 1's anchor profit is 0.01 ETH at refundPercent 90, and bundle 2's is 0.00002 ETH at refundPercent 50. Both are paid with one transfer:

bundle 1 = 0.01    * 90 / 100 = 0.009 ETH
bundle 2 = 0.00002 * 50 / 100 = 0.00001 ETH
refund   = 0.009 + 0.00001 - 0.000029022 = 0.008980978 ETH

Bundle 2's 0.00001 ETH could not pay a transfer on its own, but it lands because it joins bundle 1's transfer.

If any refund anchor transaction (from refundTxHashes, or the last tx by default) is never evaluated, or the refund cannot cover the cost of a transfer and there is no transfer to the same recipient for it to join, the bundle is dropped.

Replacement and Cancellation

Submitting a new bundle with the same replacementUuid replaces the previous bundle. Submitting an empty txs array with a replacementUuid is treated as a cancellation. You can also use eth_cancelBundle to cancel by UUID.

When multiple replacements may be in flight, set replacementSeqNumber to a monotonically increasing value so the builder can order them deterministically instead of relying on receive time. A bundle with a sequence number lower than or equal to one already seen for the same replacementUuid is dropped.

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "bundleHash": "0x..."
  }
}

A successful response means the bundle was accepted for inclusion. It does not guarantee the bundle will be included in a block.