Builder

POST /v1/builder/register

HTTP
Python

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

import requests

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

Request

Parameter	Required	Type	Description
publicKeys	YES	string	Comma-separated list of builder BLS public keys in hex
signatures	YES	string	Comma-separated list of BLS signatures in hex
ofac	NO	boolean	OFAC flag for the builders (default: false)

Response Body

Name	Type	Description
results	object[]	Results of builder public key registrations
└ publicKey	string	Public key in the registration
└ result	object	Builder Registration Result
└└ result	integer	Builder Registration Result Code
└└ description	string	Builder Registration Result Description

See Builder Registration Result for result codes.

Error Codes

Code	Description
INVALID_PUBLIC_KEY	Invalid builder public key format
BUILDERS_MAX	Maximum 100 builders allowed per request
BUILDER_SIGNATURE_SIZE_NOT_MATCH_PUBLIC_KEY	Number of signatures must match number of public keys

GET /v1/builder/signingMessage

Get the required signing message used to sign the BLS signature with the builder's BLS key.

HTTP
Python

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

import requests

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)

Request

No parameters required.

Response Body

Name	Type	Description
message	object	Signing message
└ eoaAddress	string	EOA address of current user

POST /v1/builder/deregister

Deregister builder public keys from ETHGas.

HTTP
Python

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

import requests

url = f"{ETHGAS_API_URL}/v1/builder/deregister"
payload = {'publicKeys': '0x12342330def...,0x4a93d70def...'}
headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, params=payload)
print(response.text)

Request

Parameter	Required	Type	Description
publicKeys	YES	string	Comma-separated list of builder BLS public keys in hex

Response Body

Name	Type	Description
success	boolean	Whether API call is successful or not

Error Codes

Code	Description
INVALID_PUBLIC_KEY	Invalid builder public key format
BUILDERS_MAX	Maximum 100 builders allowed per request

GET /v1/p/builders

Retrieve a list of builders and fallback builder key.

HTTP
Python

curl -X GET "$ETHGAS_API_URL/v1/p/builders"

import requests

url = f"{ETHGAS_API_URL}/v1/p/builders"
headers = {'Content-Type': 'application/json'}
response = requests.get(url, headers=headers)
print(response.text)

Request

Parameter	Required	Type	Description
ofac	NO	boolean	Filter by OFAC status (default: false)

Response Body

Name	Type	Description
builders	object	List of builder objects
└ whitelistedBuilders	object	List of whitelisted builders accessible by builder name
└ unnamedBuilders	list	List of public keys of unnamed builders in hex
└ fallbackBuilder	string	Public key of the ETHGas fallback builder in hex

GET /v1/user/builder

Retrieve a list of builder public keys submitted by the current user.

HTTP
Python

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

import requests

url = f"{ETHGAS_API_URL}/v1/user/builder"
headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
print(response.text)

Request

No parameters required.

Response Body

Name	Type	Description
builders	string[]	List of builder BLS keys

POST /v1/user/delegate/builder

Delegate or revoke delegation of builder keys by supplying either a comma-separated list of BLS public keys or a builder name (which applies to all keys under that builder).

HTTP
Python

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

import requests

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

Parameter	Required	Type	Description
publicKeys	NO	string	Comma-separated list of BLS builder public keys in hex
builderName	NO	string	Builder name
enable	YES	boolean	Delegate or revoke builder delegation

Either publicKeys or builderName must be provided.

Response Body

Name	Type	Description
success	boolean	Indicates request status

Error Codes

Code	Description
SYSTEM_VALIDATION	Either publicKeys or builderName must be provided

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

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 requests

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

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

Response Body

Name	Type	Description
success	boolean	Whether API call is successful or not

GET /v1/user/delegate/builder

Get list of delegated builder keys for the current user.

HTTP
Python

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

import requests

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)

Request

No parameters required.

Response Body

Name	Type	Description
delegatedBuilders	string[]	List of delegated builder keys

GET /v1/p/builder/:slot

Retrieve a list of builders by slot ID.

HTTP
Python

curl -X GET "$ETHGAS_API_URL/v1/p/builder/123"

import requests

url = f"{ETHGAS_API_URL}/v1/p/builder/123"
headers = {'Content-Type': 'application/json'}
response = requests.get(url, headers=headers)
print(response.text)

Request

Parameter	Required	Type	Description
slot	YES	integer	Slot ID to retrieve the builder

Response Body

Name	Type	Description
slot	integer	Slot number of the block
builders	string[]	List of available builder keys for the queried slot
fallbackBuilder	string	Public key of the fallback builder in hexadecimal format
ofac	boolean	OFAC status for the slot

GET /v1/builder/delegation

Retrieve a list of user addresses of those who have delegated to the current user's builder keys.

HTTP
Python

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

import requests

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)

Request

No parameters required.

Response Body

Name	Type	Description
builderDelegations	object	Mapping of builder delegations from corresponding builder key registered by the user
└ [builderKey]	string	Corresponding builder key registered by the user
└└	string[]	EOA addresses who delegated to the builder key

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 requests

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)

Request

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

Request Body

Name	Type	Description
rejections	object[]	List of bundle rejections
└ uuid	string	Bundle UUID
└ rejectCode	integer	Rejection code
└ txHashList	string[]	List of transaction hashes
└ reason	string	Rejection reason

Response Body

Name	Type	Description
success	boolean	Whether API call is successful or not

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 for a specific slot and account.

HTTP
Python

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

import requests

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)

Request

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

Response Body

Name	Type	Description
rejections	object[]	List of bundle rejections
└ uuid	string	Bundle UUID
└ rejectCode	integer	Rejection code
└ txHashList	string[]	List of transaction hashes
└ 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)

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​

POST /v1/builder/update/ofac​

GET /v1/user/delegate/builder​

GET /v1/p/builder/:slot​

GET /v1/builder/delegation​

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

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

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

POST /v1/builder/update/ofac

GET /v1/user/delegate/builder

GET /v1/p/builder/:slot

GET /v1/builder/delegation

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

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