bex_sendBundle

Submit a Builder Execution Extension (BEX) request. The builder will run a read-only off-chain computation against the mid-block state and inject the result into an on-chain execute call within the same block.

Optionally requires the X-Flashbots-Signature header if an allowlist is configured, or when using replacementUuid.

Parameters

A single object:

Field	Type	Required	Description
targetBlock	number	Yes	Block number to target (decimal integer)
replacementUuid	string	No	UUID to enable bundle replacement. Requires X-Flashbots-Signature.
replacementNonce	number	No	Monotonically increasing nonce for replacement ordering
bex	object	Yes	BEX extension containing compute and execute specs (see below)

bex.compute object

Field	Type	Required	Description
to	string	Yes	Contract address to call for the off-chain compute step
calldata	string	Yes	0x-prefixed hex calldata for the compute call

bex.execute object

Field	Type	Required	Description
to	string	Yes	Contract address to call on-chain with the compute result
selector	string	Yes	0x-prefixed 4-byte function selector (e.g. "0xabcdef01")
prefixArgs	string	Yes	0x-prefixed hex arguments prepended before the compute result
appendComputeResult	boolean	Yes	If true, the raw return data from compute is appended after prefixArgs

Request

{
  "jsonrpc": "2.0",
  "method": "bex_sendBundle",
  "params": [{
    "targetBlock": 20000000,
    "bex": {
      "compute": {
        "to": "0x1111111111111111111111111111111111111111",
        "calldata": "0x70a08231000000000000000000000000abcdef1234567890abcdef1234567890abcdef12"
      },
      "execute": {
        "to": "0x2222222222222222222222222222222222222222",
        "selector": "0xa9059cbb",
        "prefixArgs": "0x000000000000000000000000abcdef1234567890abcdef1234567890abcdef12",
        "appendComputeResult": true
      }
    }
  }],
  "id": 1
}

Response

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

Field	Type	Description
bundleHash	string	Deterministic 0x-prefixed hash of the BEX request. Identical inputs always produce the same hash.

How It Works

1. At block-building time, the builder performs a staticcall to compute.to with compute.calldata against the current mid-block state.

2. The return data is optionally appended to execute.prefixArgs to form the final calldata.

3. The builder submits an on-chain transaction calling execute.to with the assembled calldata, signed by the builder's coinbase key.

This pattern lets protocols execute conditional on-chain logic (e.g. liquidations, rebalances, oracle updates) using live state read at execution time, without knowing the exact value ahead of time.

Errors

Code	Message	Cause
-32602	Compute calldata too large	Calldata exceeds the builder's maxCalldataBytes limit
-32602	X-Flashbots-Signature required when allowlist is active	Missing auth header
-32602	Signer not in allowlist	Signer address not authorized
-32602	replacementUuid requires X-Flashbots-Signature	UUID replacement without auth