Integration Guide

Submitting a Bundle

Use eth_sendBundle to submit an atomic group of transactions targeting a specific block:

Python

import requests
from eth_account import Account

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

def send_bundle(signed_txs: list[str], block_number: int, private_key: str):
    body = {
        "jsonrpc": "2.0",
        "method": "eth_sendBundle",
        "params": [{
            "txs": signed_txs,
            "blockNumber": hex(block_number),
        }],
        "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()

JavaScript

curl

The response includes a bundleHash you can use with eureka_getBundleStats to track inclusion.

Replacing a Bundle

To update a bundle before the target block is built, submit a new bundle with the same replacementUuid:

Python

import uuid

replacement_id = str(uuid.uuid4())

def send_replaceable_bundle(signed_txs, block_number, replacement_uuid, private_key):
    body = {
        "jsonrpc": "2.0",
        "method": "eth_sendBundle",
        "params": [{
            "txs": signed_txs,
            "blockNumber": hex(block_number),
            "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_bundle(["0x02f8..."], 20_400_000, replacement_id, private_key)

# Replace with updated transactions
send_replaceable_bundle(["0x02fa..."], 20_400_000, replacement_id, private_key)

JavaScript

curl

The builder discards the old bundle and processes the new one.

Cancelling a Bundle

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

Submitting a Private Transaction

For a single transaction that should be kept private without targeting a specific block:

Python

def send_private_transaction(signed_tx: str, private_key: str):
    body = {
        "jsonrpc": "2.0",
        "method": "eth_sendRawTransaction",
        "params": [signed_tx],
        "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

Bundle Refunds

To receive a portion of the builder's profit back, set refundPercent and refundRecipient:

Python

def send_bundle_with_refund(signed_txs, block_number, refund_percent, refund_recipient, private_key):
    body = {
        "jsonrpc": "2.0",
        "method": "eth_sendBundle",
        "params": [{
            "txs": signed_txs,
            "blockNumber": hex(block_number),
            "refundPercent": refund_percent,
            "refundRecipient": refund_recipient,
        }],
        "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()

send_bundle_with_refund(["0x02f8..."], 20_400_000, 90, "0xYourAddress", private_key)

JavaScript

curl

Use eureka_getBundleRefundInfo to confirm the payout after inclusion.

Allowing Reverts

To prevent a reverting transaction from invalidating the whole bundle, list its hash in revertingTxHashes:

{
  "txs": ["0x02f8...", "0x02f9..."],
  "blockNumber": "0x137f8a0",
  "revertingTxHashes": ["0xabcd..."]
}