> For the complete documentation index, see [llms.txt](https://docs.eurekalabs.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eurekalabs.xyz/builder-execution-extension/api.md).

# Overview

## Set up BEX with your coding agent

Copy this prompt into your coding agent:

```
Set up BEX, the Eureka builder's execution extension, for me. Read https://docs.eurekalabs.xyz/builder-execution-extension/agent-setup.md and follow its steps in order. Ask me before submitting a BEX request or sending a transaction. Never print my signer key.
```

Read the [setup prompt](/builder-execution-extension/agent-setup.md), follow the [quick start](/builder-execution-extension/quick-start.md), or use the [integration guide](/builder-execution-extension/integration.md).

## What BEX does

Builder Execution Extension (BEX) runs a read-only compute on live block state. An onchain execute uses the result in the same block.

An action can depend on a balance, price or position size that exists only at execution time. The builder reads that value before the execute. You do not need to choose the result in advance.

The compute can run gas-heavy logic without adding that work to the onchain transaction.

## How It Works

A BEX request targets a specific block and consists of two parts:

**Request envelope**

* `targetBlock`: the block number this request targets

**Compute**: a `staticcall` the builder runs offchain against the block state while it builds the target block. It runs when the builder starts filling the block and again after transactions that write to storage your request read. See [How it works](/builder-execution-extension/api/bex_sendbundle.md#how-it-works) for the timing limits.

* `compute.to`: the contract to call off-chain
* `compute.calldata`: the calldata for the off-chain compute
* `compute.code`: optional [runtime bytecode](/builder-execution-extension/compute-code.md) to run at an empty `compute.to` for this compute only

**Execute** — the on-chain transaction the builder signs and submits using the compute result:

* `execute.to`: the contract to call on-chain
* `execute.selector`: the function to call - 4 byte function selector, hex-encoded with 0x prefix
* `execute.prefixArgs`: fixed arguments prepended before the compute result
* `execute.appendComputeResult`: if `true`, the raw return data from compute is appended

**Replacement fields** (optional, for replaceable bundles):

* `replacementUuid`: a stable UUID identifying a replaceable bundle slot. Requires `X-Flashbots-Signature`.
* `replacementSeqNumber`: a monotonically increasing sequence number. A higher value replaces a lower value for the same (`replacementUuid`, `signer`) pair, and a missing value counts as `0`.

The builder assembles the final calldata as:

```
selector ++ prefixArgs ++ (computeReturnData if appendComputeResult)
```

The resulting transaction is signed by the builder's coinbase key `0xfb74767c1ce1aada0a0e114441173b57f8c1571b`. It is only included if it raises the coinbase balance, so the execute has to pay `block.coinbase` more than its gas fee. See [How it works](/builder-execution-extension/api/bex_sendbundle.md#how-it-works).

## Guides

* [How a BEX request works](/builder-execution-extension/request.md)
* [The compute](/builder-execution-extension/compute.md) and [the execute](/builder-execution-extension/execute.md)
* [Wiring the result](/builder-execution-extension/wiring.md) and [compute code](/builder-execution-extension/compute-code.md)
* [Limits and request lifecycle](/builder-execution-extension/limits.md)
* [Why BEX saves gas](/builder-execution-extension/savings.md)
* [Request status](/builder-execution-extension/status.md) and [FAQ](/builder-execution-extension/faq.md)
* [The bex CLI](/builder-execution-extension/cli.md) and [the manifest](/builder-execution-extension/manifest.md)

## Use Cases

* **Conditional liquidations** — read a position's health factor, execute only if below threshold
* **Dynamic arbitrage** — read current pool reserves, compute the optimal swap amount and execute it
* **Oracle-free settlements** — read live price data and settle a contract without a trusted oracle
* **Rebalancing** — read current allocations and rebalance to target weights in one transaction

## Limits

**`bex_capabilities` is authoritative.** Call it before sizing your request and treat its response as the limit. The table shows the production values at the time of writing.

| Limit              | Production value      | Description                                                                                       |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------- |
| `maxCalldataBytes` | 24,576 bytes (24 KiB) | Maximum size of `compute.calldata`, of `execute.prefixArgs` and of the assembled execute calldata |
| `maxComputeGas`    | 500,000,000           | Gas limit for the compute call                                                                    |
| `maxExecuteGas`    | 2,000,000             | Gas limit of the onchain execute transaction                                                      |

`compute.code` has a separate limit of **24,576 bytes**. Its target must be empty at each evaluation. See [compute code](/builder-execution-extension/compute-code.md).

Requests expire after **60 seconds** if their target block hasn't been built.

## Access Level

**Restricted**: every BEX method except `bex_capabilities` requires a whitelisted signer. See [Endpoint Access Control](/readme.md#endpoint-access-control) for details.

## Authentication

Every BEX method except `bex_capabilities` requires the `X-Flashbots-Signature` header, and your signing address must be in the allowlist. See [Endpoint Access Control](/readme.md#endpoint-access-control) for the signing format. When using `replacementUuid`, the same signer must submit all replacements and cancellations.

Contact the Eureka team to get your address added to the allowlist.

## API Methods

| Method                                                                     | Description                                                          | Response                                                          |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [`bex_sendBundle`](/builder-execution-extension/api/bex_sendbundle.md)     | Submit a BEX compute+execute request                                 | { bundleHash }                                                    |
| [`bex_cancelBundle`](/builder-execution-extension/api/bex_cancelbundle.md) | Cancel a replaceable BEX bundle                                      | true                                                              |
| [`bex_simulate`](/builder-execution-extension/api/bex_simulate.md)         | Simulate a BEX request on top of the latest block without storing it | { accepted, bundleHash, issues, snapshotBlock, compute, execute } |
| [`bex_capabilities`](/builder-execution-extension/api/bex_capabilities.md) | Query builder limits (calldata size, gas caps)                       | { maxCalldataBytes, maxComputeGas, maxExecuteGas }                |

All requests are sent as JSON-RPC 2.0 `POST` to:

```
https://rpc.eurekabuilder.xyz
```