Integration Guide

Tracking a Submitted Bundle

After calling eth_sendBundle, poll eureka_getBundleStats with the returned bundleHash to track the bundle's status:

Python

import requests
from eth_account import Account

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

def get_bundle_stats(bundle_hash: str, private_key: str):
    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

The status field progresses through these states:

Status	Meaning
received	Bundle arrived and is queued for simulation
simulated	Bundle passed simulation and is eligible for inclusion
included	Bundle was included in a block by this builder
failed	Bundle failed simulation (check error field)
expired	Target block was built without including this bundle

Checking Refunds

If your bundle used refundPercent and refundRecipient, call eureka_getBundleRefundInfo after inclusion to confirm the payout:

Python

def get_bundle_refund_info(bundle_hash: str, private_key: str):
    body = {
        "jsonrpc": "2.0",
        "method": "eureka_getBundleRefundInfo",
        "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

The payoutTxHash field contains the on-chain transaction that sent the refund.

Inspecting a Block

To see all bundles included in a specific block:

Python

def get_block_bundles(block_number: int, private_key: str):
    body = {
        "jsonrpc": "2.0",
        "method": "eureka_getBlockBundles",
        "params": [{"blockNumber": block_number}],
        "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 is useful for post-hoc analysis of block composition and competitive dynamics.

Looking Up Bundles by Transaction

To find which bundle(s) a transaction was part of:

Python

def get_bundles_by_tx(tx_hash: str, private_key: str):
    body = {
        "jsonrpc": "2.0",
        "method": "eureka_getBundlesByTx",
        "params": [{"txHash": tx_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