Integration Guide

Step 1: Check Builder Capabilities

Before submitting, query the builder's current limits:

Python

import requests
from eth_account import Account

EUREKA_RPC = "https://rpc.eurekabuilder.xyz"

def get_capabilities(private_key: str):
    body = {
        "jsonrpc": "2.0",
        "method": "bex_capabilities",
        "params": [],
        "id": 1,
    }

    message = json.dumps(body)
    account = Account.from_key(private_key)
    signature = account.sign_message(encode_defunct(text=message))
    header_value = f"{account.address}:{signature.signature.hex()}"

    response = requests.post(
        EUREKA_RPC,
        json=body,
        headers={"X-Flashbots-Signature": header_value},
    )
    return response.json()

JavaScript

curl

This returns maxCalldataBytes, maxComputeGas, and maxExecuteGas. Stay within these limits or your request will be rejected.

Step 2: Design Your Compute + Execute Pair

Think in two steps:

1. What do I need to read? — This is your compute spec. It's a staticcall against live mid-block state. Any view function works.

2. What do I need to execute? — This is your execute spec. The builder signs and submits this transaction using the compute result as input.

Example: Read a user's token balance, then transfer exactly that amount.

compute.to       = TokenContract
compute.calldata = balanceOf(userAddress)          → returns uint256

execute.to       = TokenContract
execute.selector = transfer(address,uint256)
execute.prefixArgs  = abi.encode(recipient)        → fixed first arg
execute.appendComputeResult = true                 → balance appended as second arg

Final calldata: transfer(recipient, <live balance>)

Step 3: Validate with bex_simulate

Before submitting for real, use bex_simulate to catch validation issues:

Python

def simulate_bex(target_block: int, compute_to: str, compute_calldata: str,
                 execute_to: str, execute_selector: str, execute_prefix_args: str, private_key: str):
    body = {
        "jsonrpc": "2.0",
        "method": "bex_simulate",
        "params": [{
            "targetBlock": target_block,
            "bex": {
                "compute": {
                    "to": compute_to,
                    "calldata": compute_calldata,
                },
                "execute": {
                    "to": execute_to,
                    "selector": execute_selector,
                    "prefixArgs": execute_prefix_args,
                    "appendComputeResult": True,
                },
            },
        }],
        "id": 1,
    }

    message = json.dumps(body)
    account = Account.from_key(private_key)
    signature = account.sign_message(encode_defunct(text=message))
    header_value = f"{account.address}:{signature.signature.hex()}"

    response = requests.post(
        EUREKA_RPC,
        json=body,
        headers={"X-Flashbots-Signature": header_value},
    )
    return response.json()

JavaScript

curl

If accepted: true, you're good to submit. If accepted: false, fix the issues before proceeding.

Step 4: Submit

Python

def send_bex_bundle(target_block: int, bex_spec: dict, private_key: str):
    body = {
        "jsonrpc": "2.0",
        "method": "bex_sendBundle",
        "params": [{
            "targetBlock": target_block,
            "bex": bex_spec,
        }],
        "id": 1,
    }

    message = json.dumps(body)
    account = Account.from_key(private_key)
    signature = account.sign_message(encode_defunct(text=message))
    header_value = f"{account.address}:{signature.signature.hex()}"

    response = requests.post(
        EUREKA_RPC,
        json=body,
        headers={"X-Flashbots-Signature": header_value},
    )
    return response.json()

bex_spec = {
    "compute": {
        "to": "0x<token contract>",
        "calldata": "0x70a08231...",
    },
    "execute": {
        "to": "0x<token contract>",
        "selector": "0xa9059cbb",
        "prefixArgs": "0x000000000000000000000000<recipient>",
        "appendComputeResult": True,
    },
}

send_bex_bundle(20_000_000, bex_spec, private_key)

JavaScript

curl

The response includes a deterministic bundleHash — same inputs always produce the same hash. Use it to track inclusion via eureka_getBundleStats.

Step 5: Updating Before the Block

To update your BEX request before the target block is built, use replacementUuid:

Python

import uuid

replacement_id = str(uuid.uuid4())

def send_replaceable_bex(target_block, bex_spec, replacement_uuid, private_key):
    body = {
        "jsonrpc": "2.0",
        "method": "bex_sendBundle",
        "params": [{
            "targetBlock": target_block,
            "replacementUuid": replacement_uuid,
            "bex": bex_spec,
        }],
        "id": 1,
    }

    message = json.dumps(body)
    account = Account.from_key(private_key)
    signature = account.sign_message(encode_defunct(text=message))
    header_value = f"{account.address}:{signature.signature.hex()}"

    response = requests.post(
        EUREKA_RPC,
        json=body,
        headers={"X-Flashbots-Signature": header_value},
    )
    return response.json()

JavaScript

curl

Resubmit the same UUID with updated fields to replace the previous request. Requires X-Flashbots-Signature.

To cancel without replacing:

Python

def cancel_bex_bundle(replacement_uuid, private_key):
    body = {
        "jsonrpc": "2.0",
        "method": "bex_cancelBundle",
        "params": [{"replacementUuid": replacement_uuid}],
        "id": 1,
    }

    message = json.dumps(body)
    account = Account.from_key(private_key)
    signature = account.sign_message(encode_defunct(text=message))
    header_value = f"{account.address}:{signature.signature.hex()}"

    response = requests.post(
        EUREKA_RPC,
        json=body,
        headers={"X-Flashbots-Signature": header_value},
    )
    return response.json()

JavaScript

curl

Calldata Encoding Reference

The final on-chain calldata is assembled as:

selector (4 bytes) ++ prefixArgs ++ computeReturnData (if appendComputeResult=true)

All arguments must be ABI-encoded. prefixArgs and the compute return data are concatenated raw — there is no additional ABI wrapping between them.

Example with two fixed args and one dynamic arg from compute:

selector        = 0xabcdef01
prefixArgs      = abi.encode(arg1, arg2)    // two fixed values
computeResult   = abi.encode(dynamicValue)  // returned by compute staticcall
final calldata  = selector ++ prefixArgs ++ computeResult

Tips

• Use bex_simulate whenever you change your compute/execute spec — the bundleHash it returns will match what bex_sendBundle returns, so you can pre-compute it.

• Requests expire after 60 seconds even if the target block hasn't been reached. Resubmit if your strategy is long-running.

• The compute step is a staticcall — it cannot write state or emit events. Pure read operations only.

• The execute transaction is signed by the builder's coinbase key, not yours. Your contract must be designed to accept calls from that address.