> For the complete documentation index, see [llms.txt](https://docs.ethgas.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ethgas.com/get-started/searchers/builder-endpoint.md).

# Builder Endpoint

<table><thead><tr><th width="181.88671875">Network</th><th>URL</th></tr></thead><tbody><tr><td>Mainnet</td><td><a href="https://realtime-rpc.ethgas.com/builder">https://realtime-rpc.ethgas.com/builder</a></td></tr><tr><td>Hoodi</td><td><a href="https://realtime-rpc.ethgas.com/hoodi/builder">https://realtime-rpc.ethgas.com/hoodi/builder</a></td></tr><tr><td>Hoodi (test nev)</td><td><a href="https://realtime-rpc.ethgas.com/hoodi/builder">https://realtime-rpc.ethgas.com/hoodi-test/builder</a></td></tr></tbody></table>

### Regional Builder Endpoint (Mainnet)

| Region                       | Mainnet                           |
| ---------------------------- | --------------------------------- |
| `us-east-1`                  | <https://us.builder.ethgas.com>   |
| `eu-central-1`               | <https://eu.builder.ethgas.com>   |
| `ap-northeast-1 (Tokyo, 1a)` | <https://ap.builder.ethgas.com>   |
| `ap-northeast-1 (Tokyo, 1d)` | <https://ap-2.builder.ethgas.com> |

### eth\_sendRawTransaction

{% tabs %}
{% tab title="Request" %}

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "eth_sendRawTransaction”,
  "params": ["0x…"],  // Signed raw tx hex
}

```

{% endtab %}

{% tab title="Response" %}

```json
{"result":200,"error":null,"id":1}
```

{% endtab %}
{% endtabs %}

Submits a raw transaction (serialized and signed) for broadcasting to the network. The transaction data should be encoded as a hexadecimal string starting with `0x`. You can create and sign a transaction externally using libraries like [web3.js](https://web3js.readthedocs.io/) or [ethers.js](https://docs.ethers.org/).

**Note:** For [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) transactions, the raw form must be in the network format, which includes blobs, KZG commitments, and KZG proofs.

### eth\_sendBundle

Submits an ordered bundle of signed transactions to the builder through the endpoints listed above. Transactions are considered together for inclusion, subject to the optional revert and drop rules below.

{% tabs %}
{% tab title="Request" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendBundle",
  "params": [
    {
      txs,                        // Array[String], Signed transactions in execution order. A new bundle must contain at least one transaction. For EIP-4844 transactions, use the network encoding, including blobs, KZG commitments, and KZG proofs. An empty array with a replacement UUID requests cancellation instead.
      blockNumber,                // (Optional) String, Target execution block number in hexadecimal. Omitted or "0x0" targets the current pending block; it does not make the bundle persist across future blocks.
      minTimestamp,               // (Optional) Number, Minimum allowed block timestamp, in seconds since the Unix epoch.
      maxTimestamp,               // (Optional) Number, Maximum allowed block timestamp, in seconds since the Unix epoch. Omitted or 0 means no upper timestamp bound.
      revertingTxHashes,          // (Optional) Array[String], Transaction hashes allowed to revert without invalidating the bundle. Defaults to an empty array. Depending on builder configuration, these transactions may also be skipped if they cannot execute.
      droppingTxHashes,           // (Optional) Array[String], Transaction hashes allowed to be omitted if they cannot execute or would revert. A reverting transaction in this list is dropped rather than included with a reverted receipt. Defaults to an empty array.
      replacementUuid,            // (Optional) String, UUID identifying a bundle that can be replaced or cancelled. Use a fresh UUID, such as a UUID v4, for each independent replacement group.
      replacementSeqNumber,       // (Optional) Number, Alias for replacementNonce. Supply only one of these two fields.
      refundPercent,              // (Optional) Number, Percentage of refundable builder profit to refund. 1 through 99 enables a refund; omitted or 0 disables it. Values of 100 or greater are rejected.
      refundRecipient,            // (Optional) String, Refund recipient address. When a refund is enabled and this field is omitted, the signer of the first transaction is used.
      refundTxHashes,             // (Optional) Array[String], Transaction hash from which refundable profit is calculated. With a refund enabled, at most one hash is supported. Omitted or empty defaults to the final transaction in the bundle.
    }
  ]
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "bundleHash": "0x..."
  }
}
```

`bundleHash` is a builder-computed, `0x`-prefixed 32-byte bundle identifier. The value above is a placeholder. It is distinct from the replacement UUID and is not a transaction hash or inclusion receipt.
{% endtab %}
{% endtabs %}

`params` contains one bundle object. Transaction bytes, transaction hashes, and addresses use `0x`-prefixed hexadecimal strings. Timestamps and replacement sequence numbers use JSON numbers.

**Replacing a bundle**

Submit another `eth_sendBundle` request with the same `replacementUuid` and the updated transactions. When supplying explicit sequence numbers, increase `replacementSeqNumber` for each update. Use explicit sequence numbers consistently for a replacement group; the automatic counter is local to each RPC server, is not synchronized with caller-supplied values, and resets when the server restarts.

Replacement and cancellation are keyed by UUID alone in this implementation.

**Cancelling through `eth_sendBundle`**

An empty `txs` array with the same replacement UUID submits a cancellation command:

{% tabs %}
{% tab title="Request" %}

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "eth_sendBundle",
  "params": [
    {
      "txs": [],
      "replacementUuid": "550e8400-e29b-41d4-a716-446655440000",
      "replacementSeqNumber": 2
    }
  ]
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": 200
}
```

{% endtab %}
{% endtabs %}

Use a sequence number greater than the preceding bundle update when supplying explicit sequence numbers. An empty bundle without a replacement UUID is rejected.

**Errors and acknowledgement**

Invalid parameter shapes or types produce a JSON-RPC parameter error. Bundle decoding or validation failures return error code `-32602`, message `"failed to decode bundle"`, and a `data.reason` describing the failure. Examples include an invalid signed transaction, an unsupported version, a field incompatible with `v1`, or an invalid refund percentage. If tracing is enabled for the target block, the error data can also contain `bundleHash`.

The success response is an RPC acknowledgement. Internal queue timeouts or a closed order-input channel are not propagated as RPC errors, so the response does not prove that the bundle reached the building pipeline.

### eth\_cancelBundle

Requests cancellation of a replaceable bundle by its `replacementUuid`. Use the UUID supplied when submitting the bundle, rather than the `bundleHash` returned in the response. A bundle submitted without a replacement UUID cannot be cancelled with this method.

{% tabs %}
{% tab title="Request" %}

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "eth_cancelBundle",
  "params": [
    {
      replacementUuid,            // (Required) String, UUID identifying the replacement group to cancel. The uuid alias accepted by eth_sendBundle is not supported here.
    }
  ]
}
```

The request above shows the parameter schema. Replace field names with quoted JSON keys and their values, and remove comments before sending.
{% endtab %}

{% tab title="Response" %}

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": null
}
```

{% endtab %}
{% endtabs %}

`params` contains one cancellation object.

**Cancellation behavior**

The cancellation has no target block and is forwarded to all active block-building subscriptions. It uses the maximum unsigned 64-bit replacement sequence number (`18446744073709551615`), superseding earlier updates for the UUID. Use a new UUID for subsequent submissions after cancelling with this method. The order pool retains cancellation records for approximately 60 seconds, removing expired records when the head updates.

Cancellation can affect work still being built; it cannot undo transactions already included on chain. The `null` result does not confirm that a matching bundle existed or that cancellation completed. In this implementation, malformed cancellation parameters are logged and also return `null`, and internal queue delivery failures are not surfaced to the caller.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ethgas.com/get-started/searchers/builder-endpoint.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
