Builders & Sequencers

Roles and integration points for builders and sequencers.

Block Building Package

Builder Software Options

Builders may use their own software or the ETHGas-modified rbuilder (preconf-builder) for ETHGas-specific flows:

Stream preconf transactions

Handle preconfirmation transaction streams

Build compliant blocks

Respect bundle positioning and commitments

Fill remaining blockspace

Add mempool transactions to complete blocks

Integration Requirements

Requirements

Builder software

Own implementation or ETHGas preconf-builder

Relay submission

Submit blocks to relay infrastructure

Commitment compliance

Include preconf bundles, respect positioning, payout to block owner

Slot timing performance

Meet strict slot timing requirements

API Endpoints

POST /v1/builder/register

POST /v1/builder/register — Register builder public keys with the ETHGas platform

HTTP
Python

curl -H "Authorization: Bearer {{access_token}}" -X POST "$ETHGAS_API_URL/v1/builder/register?publicKeys=0x12345...,0x234134...&signatures=2asdfjghadg,xghlktdhj"

import os
import requests

ETHGAS_API_URL = os.environ.get("ETHGAS_API_URL", "https://mainnet.app.ethgas.com/api")
url = f"{ETHGAS_API_URL}/v1/builder/register"
payload = {
    'publicKeys': '0x123456789abcdef...,0x234134...',
    'signatures': '2asdfjghadg,xghlktdhj'
}
headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, params=payload)
print(response.text)

Request Parameters

Parameter	Required	Type	Description
publicKeys	Yes	string	Comma separated list of builder BLS public key in hex
signatures	Yes	string	Comma separated list of BLS signatures in hex

Response Example

{
    "success": true,
    "data": {
        "results": [
            {
                "publicKey": "0xa25addc4fc16f72ca667177d7a5533d4287b3574f0127ffc227095e90b0b1fd0dd48c421e04e613d2298fe4dac83a2a5",
                "result": {
                    "result": 0,
                    "description": "Success"
                }
            }
        ]
    }
}

Response Body

Field	Type	Description
success	boolean	Success status of the request
data	object	Response data container
data.results	object[]	Results of builder public key registrations
data.results[].publicKey	string	Public key in the registration
data.results[].result	object	Builder Registration Result
data.results[].result.result	integer	Builder Registration Result Code
data.results[].result.description	string	Builder Registration Result Description

note

Please refer to Builder Registration Result lookup table for result codes.

GET /v1/builder/signingMessage

Get builder signing message

GET /v1/builder/signingMessage — Retrieve the message that needs to be signed by the builder's private key for registration verification

HTTP
Python

curl -H "Authorization: Bearer {{access_token}}" -X GET "$ETHGAS_API_URL/v1/builder/signingMessage"

import os
import requests

ETHGAS_API_URL = os.environ.get("ETHGAS_API_URL", "https://mainnet.app.ethgas.com/api")
url = f"{ETHGAS_API_URL}/v1/builder/signingMessage"
headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
print(response.text)

Response Example

{
    "success": true,
    "data": {
        "message": {
            "eoaAddress": "0xd065335192d920ce2de4a88557f232943a901a9f"
        }
    }
}

Response Body

Field	Type	Description
success	boolean	Success status of the request
data	object	Response data container
data.message	object	Signing message
data.message.eoaAddress	string	EOA address of current user

POST /v1/builder/deregister

Builder deregistering their public keys

POST /v1/builder/deregister — Builder deregistering their public keys

HTTP
Python

curl -H "Authorization: Bearer {{access_token}}" -X POST "$ETHGAS_API_URL/v1/builder/deregister?publicKeys=0x123423qtdgasdg..."

import os
import requests

ETHGAS_API_URL = os.environ.get("ETHGAS_API_URL", "https://mainnet.app.ethgas.com/api")
url = f"{ETHGAS_API_URL}/v1/builder/deregister"
payload = {
    'publicKeys': '0x123456789abcdef...,0x234134...'
}
headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, params=payload)
print(response.text)

Request Parameters

Parameter	Required	Type	Description
publicKeys	Yes	string	List of builder BLS public keys in hex

Response Example

{
    "success": true
}

GET /v1/p/builders

Details

GET /v1/p/builders — Retrieve a list of builder public keys submitted by a user

HTTP
Python

curl -H "Authorization: Bearer {{access_token}}" "$ETHGAS_API_URL/v1/p/builders"

import os
import requests

ETHGAS_API_URL = os.environ.get("ETHGAS_API_URL", "https://mainnet.app.ethgas.com/api")
url = f"{ETHGAS_API_URL}/v1/p/builders"
headers = {
    'Authorization': 'Bearer <your-auth-token>'
}
response = requests.get(url, headers=headers)
print(response.text)

Response Example

{
    "success": true,
    "data": {
        "builders": {
            "whitelistedBuilders": {
                "btcs": ["0x123456789abcdef...", "0xfb3456789abcdef..."]
            },
            "unnamedBuilders": ["0x123456789abcdef...", "0xfb3456789abcdef..."],
            "fallbackBuilder": "0xlhadunabcdef..."
        }
    }
}

Response Body

Field	Type	Description
success	boolean	Success status of the request
data	object	Response data container
data.builders	object	List of builder objects
data.builders.whitelistedBuilders	object	Array of builder objects
data.builders.unnamedBuilders	list	List of public key of unnamed builder in hex
data.builders.fallbackBuilder	string	Public key of the ETHGas fallback builder in hex

GET /v1/user/builder

Get user's builder keys

GET /v1/user/builder — Retrieve a list of builder public keys submitted by a user

HTTP
Python

curl -H "Authorization: Bearer {{access_token}}" "$ETHGAS_API_URL/v1/user/builder"

import os
import requests

ETHGAS_API_URL = os.environ.get("ETHGAS_API_URL", "https://mainnet.app.ethgas.com/api")
url = f"{ETHGAS_API_URL}/v1/user/builder"
headers = {
    'Authorization': 'Bearer <your-auth-token>'
}
response = requests.get(url, headers=headers)
print(response.text)

Response Example

{
    "success": true,
    "data": {
        "builders": [
            "0xa25addc4fc16f72ca667177d7a5533d4287b3574f0127ffc227095e90b0b1fd0dd48c421e04e613d2298fe4dac83a2a5",
            "0xa6745dd64a0a393497d5a7d4904b613aa386f47eb2e3617cf791f059291f2812683305a4bd562d63ec15990b67795e2a",
            "0xaea551245bd0512de5222834db5f3bc9cba1a04a2e8f5de0d4fea843c9fee1af31bb9373ba6b9da08a0820f695c6ab6e"
        ]
    }
}

Response Body

Field	Type	Description
success	boolean	Success status of the request
data	object	Response data container
data.builders	string[]	List of builder BLS keys

POST /v1/user/delegate/builder

Delegate or revoke builder delegation

POST /v1/user/delegate/builder — Delegate or revoke delegation of builder keys

HTTP
Python

curl -H "Authorization: Bearer {{access_token}}" -X POST "$ETHGAS_API_URL/v1/user/delegate/builder?publicKeys=0x12345...,0x2df345...&enable=true"

import os
import requests

ETHGAS_API_URL = os.environ.get("ETHGAS_API_URL", "https://mainnet.app.ethgas.com/api")
url = f"{ETHGAS_API_URL}/v1/user/delegate/builder"
payload = {
    'publicKeys': '0x123456789abcdef...,0x2df345...',
    'enable': True
}
headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, params=payload)
print(response.text)

Request Parameters

Parameter	Required	Type	Description
publicKeys	No	string	Builder's BLS public key to delegate to
builderName	No	string	Builder name
enable	Yes	boolean	Delegate or revoke builder delegation

Response Example

{
    "success": true
}

note

User needs to delegate a new builder 2 seconds before the market close in order to be effective in that epoch.

GET /v1/user/delegate/builder

Get builder delegation settings

GET /v1/user/delegate/builder — Retrieve information about the current user's builder delegation settings

HTTP
Python

curl -H "Authorization: Bearer {{access_token}}" -X GET "$ETHGAS_API_URL/v1/user/delegate/builder"

import os
import requests

ETHGAS_API_URL = os.environ.get("ETHGAS_API_URL", "https://mainnet.app.ethgas.com/api")
url = f"{ETHGAS_API_URL}/v1/user/delegate/builder"
headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
print(response.text)

Response Example

{
    "success": true,
    "data": {
        "delegatedBuilders": [
            "0x123456789abcdef...",
            "0xfb3456789abcdef..."
        ]
    }
}

Response Body

Field	Type	Description
success	boolean	Success status of the request
data	object	Response data container
data.delegatedBuilders	string[]	The delegated builder public key

GET /v1/p/builder/:slot

Get builder for slot

GET /v1/p/builder/{slot} — Retrieve information about the builder assigned to a specific slot

HTTP
Python

curl "$ETHGAS_API_URL/v1/p/builder/123"

import os
import requests

ETHGAS_API_URL = os.environ.get("ETHGAS_API_URL", "https://mainnet.app.ethgas.com/api")
url = f"{ETHGAS_API_URL}/v1/p/builder/123"
headers = {
    'Authorization': 'Bearer <your-auth-token>'
}
response = requests.get(url, headers=headers)
print(response.text)

Path Parameters

Parameter	Required	Type	Description
slot	Yes	integer	The Slot ID to query the builder

Response Example

{
    "success": true,
    "data": {
        "slot": 123,
        "builders": ["0x123456789abcdef...", "0x156256789ad4fef..."],
        "fallbackBuilder": "0xdsfa56789abcdef..."
    }
}

Response Body

Field	Type	Description
success	boolean	Success status of the request
data	object	Response data container
data.slot	integer	The slot number
data.builders	string[]	List of available builder keys for the queried slot
data.fallbackBuilder	string	Public key of the fallback builder in hexadecimal format

GET /v1/builder/delegation

Get builder delegation info

GET /v1/builder/delegation — Retrieve comprehensive information about builder delegations and relationships

HTTP
Python

curl -H "Authorization: Bearer {{access_token}}" -X GET "$ETHGAS_API_URL/v1/builder/delegation"

import os
import requests

ETHGAS_API_URL = os.environ.get("ETHGAS_API_URL", "https://mainnet.app.ethgas.com/api")
url = f"{ETHGAS_API_URL}/v1/builder/delegation"
headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
print(response.text)

Response Example

{
    "success": true,
    "data": {
        "builderDelegations": {
            "0xefefdffaddfeefef000...": ["0xabadba...", "0x2asdfadv..."],
            "0xdfg2345dfg0efefdffa...": ["0x58de13...", "0x2ab05ed1..."]
        }
    }
}

Response Body

Field	Type	Description
success	boolean	Success status of the request
data	object	Response data container
data.builderDelegation	object	Mapping of builder delegations from corresponding builder key registered by the user

POST /v1/builder/update/ofac

Update OFAC flag for existing builder

POST /v1/builder/update/ofac — Update OFAC flag for existing builder

HTTP
Python

curl -H "Authorization: Bearer {{access_token}}" -X POST "$ETHGAS_API_URL/v1/builder/update/ofac?publicKeys=0x12345...,0x2df345...&ofac=true"

import os
import requests

ETHGAS_API_URL = os.environ.get("ETHGAS_API_URL", "https://mainnet.app.ethgas.com/api")
url = f"{ETHGAS_API_URL}/v1/builder/update/ofac"
payload = {
    'publicKeys': '0x123456789abcdef...,0x2df345...',
    'ofac': True
}
headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, params=payload)
print(response.text)

Request Parameters

Parameter	Required	Type	Description
publicKeys	No	string	Comma separated list of builder BLS public keys in hex. If not provided, updates all builders for the user
ofac	Yes	boolean	OFAC flag for the builders (default: false)

Response Example

{
    "success": true
}

POST /v1/builder/bundle/reject/:slot

Reject bundles for a specific slot

POST /v1/builder/bundle/reject/{slot} — Reject bundles for a specific slot

HTTP
Python

curl -H "Authorization: Bearer {{access_token}}" -X POST "$ETHGAS_API_URL/v1/builder/bundle/reject/123" \
  -H "Content-Type: application/json" \
  -d '{
    "rejections": [
      {
        "uuid": "bundle-uuid-1",
        "rejectCode": 1,
        "txHashList": ["0x123...", "0x456..."],
        "reason": "Bundle rejection reason"
      }
    ]
  }'

import os
import requests

ETHGAS_API_URL = os.environ.get("ETHGAS_API_URL", "https://mainnet.app.ethgas.com/api")
url = f"{ETHGAS_API_URL}/v1/builder/bundle/reject/123"
payload = {
    "rejections": [
        {
            "uuid": "bundle-uuid-1",
            "rejectCode": 1,
            "txHashList": ["0x123...", "0x456..."],
            "reason": "Bundle rejection reason"
        }
    ]
}
headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, json=payload)
print(response.text)

Path Parameters

Parameter	Required	Type	Description
slot	Yes	integer	Slot ID to reject bundles for

Request Body

Field	Required	Type	Description
rejections	Yes	array	List of bundle rejections
rejections[].uuid	Yes	string	Bundle UUID
rejections[].rejectCode	Yes	integer	Rejection code
rejections[].txHashList	Yes	string[]	List of transaction hashes
rejections[].reason	Yes	string	Rejection reason

Response Example

{
    "success": true
}

Error Codes

Code	Description
INVALID_SLOT	Invalid slot ID (must be >= 0)
BUNDLE_REJECTION_EMPTY	Rejections list cannot be empty

GET /v1/p/builder/bundle/reject/:slot/:builderAccountId

Get bundle rejection information

GET /v1/p/builder/bundle/reject/{slot}/{builderAccountId} — Get bundle rejection information for a specific slot and account

HTTP
Python

curl "$ETHGAS_API_URL/v1/p/builder/bundle/reject/123/456"

import os
import requests

ETHGAS_API_URL = os.environ.get("ETHGAS_API_URL", "https://mainnet.app.ethgas.com/api")
url = f"{ETHGAS_API_URL}/v1/p/builder/bundle/reject/123/456"
headers = {
    'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
print(response.text)

Path Parameters

Parameter	Required	Type	Description
slot	Yes	integer	Slot ID to retrieve rejections
builderAccountId	Yes	integer	Builder account ID

Response Example

{
    "success": true,
    "data": {
        "rejections": [
            {
                "uuid": "bundle-uuid-1",
                "rejectCode": 1,
                "txHashList": ["0x123...", "0x456..."],
                "reason": "Bundle rejection reason"
            }
        ]
    }
}

Response Body

Field	Type	Description
success	boolean	Success status of the request
data	object	Response data container
data.rejections	object[]	List of bundle rejections
data.rejections[].uuid	string	Bundle UUID
data.rejections[].rejectCode	integer	Rejection code
data.rejections[].txHashList	string[]	List of transaction hashes
data.rejections[].reason	string	Rejection reason

Error Codes

Code	Description
INVALID_SLOT	Invalid slot ID (must be > 0)
INVALID_ACCOUNT_ID	Invalid account ID (must be > 0)

Block Building Package​

Builder Software Options​

Integration Requirements​

Requirements​

API Endpoints​

POST /v1/builder/register​

GET /v1/builder/signingMessage​

POST /v1/builder/deregister​

GET /v1/p/builders​

GET /v1/user/builder​

POST /v1/user/delegate/builder​

GET /v1/user/delegate/builder​

GET /v1/p/builder/:slot​

GET /v1/builder/delegation​

POST /v1/builder/update/ofac​

POST /v1/builder/bundle/reject/:slot​

GET /v1/p/builder/bundle/reject/:slot/:builderAccountId​

Block Building Package

Builder Software Options

Integration Requirements

Requirements

API Endpoints

POST /v1/builder/register

GET /v1/builder/signingMessage

POST /v1/builder/deregister

GET /v1/p/builders

GET /v1/user/builder

POST /v1/user/delegate/builder

GET /v1/user/delegate/builder

GET /v1/p/builder/:slot

GET /v1/builder/delegation

POST /v1/builder/update/ofac

POST /v1/builder/bundle/reject/:slot

GET /v1/p/builder/bundle/reject/:slot/:builderAccountId