Integration Guide

Submitting a Deterministic Bundle

Use eth_sendDeterministicBundle with the same structure as a regular bundle, plus a watchedAddresses array. The builder handles positioning automatically based on when those addresses are modified.

Python

import requests
from eth_account import Account

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

def send_deterministic_bundle(signed_txs: list[str], block_number: int, watched_addresses: list[str], private_key: str):
    body = {
        "jsonrpc": "2.0",
        "method": "eth_sendDeterministicBundle",
        "params": [{
            "txs": signed_txs,
            "blockNumber": hex(block_number),
            "watchedAddresses": watched_addresses,
        }],
        "id": 1,
    }

    # Sign the payload with Flashbots-style header
    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()

# Example: execute after a Uniswap V3 pool and an oracle are both touched
send_deterministic_bundle(
    signed_txs=["0x02f8..."],
    block_number=20_400_000,
    watched_addresses=[
        "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640",  # USDC/WETH pool
        "0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419",  # Chainlink ETH/USD
    ],
    private_key=private_key,
)

JavaScript

curl

Choosing Watched Addresses

Include the contract addresses whose state changes your bundle depends on. Common examples:

• DEX pools — the pool contract address (e.g., a Uniswap V3 pool)

• Lending protocols — the market or vault contract that holds the position

• Oracles — the oracle contract that pushes price updates

Keep the list focused — only include addresses that are relevant to your strategy.

Replacing a Deterministic Bundle

Use replacementUuid to update the bundle contents up until the block is built. Submit the same UUID with updated txs or watchedAddresses to replace the previously queued bundle. The builder always uses the latest version.

Python

import uuid

replacement_id = str(uuid.uuid4())

def send_replaceable_deterministic_bundle(signed_txs, block_number, watched_addresses, replacement_uuid, private_key):
    body = {
        "jsonrpc": "2.0",
        "method": "eth_sendDeterministicBundle",
        "params": [{
            "txs": signed_txs,
            "blockNumber": hex(block_number),
            "watchedAddresses": watched_addresses,
            "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()

# Submit initial bundle
send_replaceable_deterministic_bundle(
    ["0x02f8..."], 20_400_000,
    ["0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"],
    replacement_id, private_key,
)

# Replace with updated transactions
send_replaceable_deterministic_bundle(
    ["0x02f9..."], 20_400_000,
    ["0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"],
    replacement_id, private_key,
)

JavaScript

curl

Cancelling

To cancel without submitting a replacement:

Python

def cancel_bundle(replacement_uuid, private_key):
    body = {
        "jsonrpc": "2.0",
        "method": "eth_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

Tracking Inclusion

Deterministic bundles return a bundleHash just like regular bundles. Use eureka_getBundleStats to track whether the bundle was included:

Python

def get_bundle_stats(bundle_hash, private_key):
    body = {
        "jsonrpc": "2.0",
        "method": "eureka_getBundleStats",
        "params": [{"bundleHash": bundle_hash}],
        "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

With Refunds

Deterministic bundles support refundPercent and refundRecipient the same as regular bundles. The refund is calculated from the builder's profit attributable to the bundle.