Validator

GET /v1/user/validators

Get list of user validators.

HTTP

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

Python

import requests

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

Request

No parameters required.

Response Body

Name	Type	Description
validators	object[]	List of validator objects
└ publicKey	string	Validator public key in hexadecimal format (48 bytes)
└ ofac	boolean	OFAC compliance status for this validator

---

GET /v1/p/pools

Get list of pool entities.

HTTP

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

Python

import requests

url = f"{ETHGAS_API_URL}/v1/p/pools"
response = requests.get(url)
print(response.text)

Request

No parameters required.

Response Body

Name	Type	Description
poolEntities	object[]	List of pool entities
└ poolEntityId	integer	Pool entity ID
└ name	string	Pool name

---

POST /v1/p/validator/checkIsOfac

Check whether one or more validator public keys are flagged as OFAC.

HTTP

curl -X POST "$ETHGAS_API_URL/v1/p/validator/checkIsOfac?publicKeys=0xabc...,0xdef..."

Python

import requests

url = f"{ETHGAS_API_URL}/v1/p/validator/checkIsOfac"
params = {"publicKeys": "0xabc...,0xdef..."}
response = requests.post(url, params=params)
print(response.text)

Request

Parameter	Required	Type	Description
publicKeys	YES	string	Comma-separated validator public keys (hex, max 100)

Response Body

Name	Type	Description
ofacValidator	string[]	Subset of publicKeys that are OFAC-flagged

---

POST /v1/validator/register

Validator registering their public key into ETHGas.

HTTP

curl -H "Authorization: Bearer {{access_token}}" -X POST "$ETHGAS_API_URL/v1/validator/register?publicKey=0x123423abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef..."

Python

import requests

url = f"{ETHGAS_API_URL}/v1/validator/register"
payload = {'publicKey': '0x123423abcdef1234567890abcdef1234567890a...'}
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
publicKey	YES	string	Public key of the validator in hexadecimal

Response Body

Field	Type	Description
available	boolean	Indicates whether the request succeeded.
verified	boolean	Indicates if the validator is verified (present when available is true).
message	object	Verification message for validator to sign.

---

POST /v1/validator/verify

Verify validator public key by verifying with the signed message.

HTTP

curl -H "Authorization: Bearer {{access_token}}" -X POST "$ETHGAS_API_URL/v1/validator/verify?publicKey=0x1234567890abcdef...&signature=0xabcdef1234567890..."

Python

import requests

url = f"{ETHGAS_API_URL}/v1/validator/verify"
payload = {
    'publicKey': '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
    'signature': '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
}
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
publicKey	YES	string	Public key of the validator in hexadecimal
signature	YES	string	Signature in hexadecimal

Response Body

Field	Type	Description
result	int	Ordinal value representing the outcome of the verification
description	string	Human-readable message detailing the verification result

---

POST /v1/validator/deregister

Validator deregistering their public key from ETHGas.

HTTP

curl -H "Authorization: Bearer {{access_token}}" -X POST "$ETHGAS_API_URL/v1/validator/deregister?publicKeys=0x123423abcdef...,0x3459871234567890abcdef..."

Python

import requests

url = f"{ETHGAS_API_URL}/v1/validator/deregister"
payload = {
    'publicKeys': '0x123423abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef,0x2345876124567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
}
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 public keys of the validator in hexadecimal

Response Body

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

---

GET /v1/validator/fees

Retrieve the list of fee payouts for a given validator key.

HTTP

curl -H "Authorization: Bearer {{access_token}}" -X GET "$ETHGAS_API_URL/v1/validator/fees?publicKey=0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

Python

import requests

url = f"{ETHGAS_API_URL}/v1/validator/fees"
params = {"publicKey": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"}
headers = {'Authorization': 'Bearer <your-auth-token>'}
response = requests.get(url, params=params, headers=headers)
print(response.text)

Request

Parameter	Required	Type	Description
publicKey	NO	string	Public key for validators
startSlot	NO	integer	Start slot number
limit	NO	integer	Max number of records to return
asc	NO	boolean	true for asc order, default false for desc

Response Body

Name	Type	Description
fees	object[]	List of validator fee objects
└ slot	integer	Slot number of the block
└ accountId	integer	Unique ID for each of the user's current and trading accounts assigned by ETHGas
└ publicKey	string	Public key of the validator in hexadecimal
└ validatorPayoutAddress	string	Address of the fee recipient in hexadecimal
└ txHash	string	Transaction hash of payout transaction
└ quantity	string	Payout quantity of the slot in Eth
└ amount	string	Payout amount in payout transaction in Eth
└ gasFee	string	Gas fee charged in payout transaction
└ updateDate	integer	Last updated timestamp
└ batchPayoutSlots	integer[]	Included previous slots

note

• Gas fee is calculated based on base fee of last block of incoming slot.
• Payout amount will include extra payouts which were not paid in previous slot; validator will receive more than payout quantity in payout transaction.

---

POST /v1/validator/onchain/payout

Enable or disable on-chain fee payouts for the authenticated user's validator.

HTTP

curl -H "Authorization: Bearer {{access_token}}" -X POST "$ETHGAS_API_URL/v1/validator/onchain/payout?enable=0"

Python

import requests

url = f"{ETHGAS_API_URL}/v1/validator/onchain/payout"
params = {"enable": 0}
headers = {'Authorization': 'Bearer <your-auth-token>'}
response = requests.post(url, params=params, headers=headers)
print(response.text)

Request

Parameter	Required	Type	Description
enable	YES	boolean	Whether onchain payout is enabled for the user's validators. Default = true

Response Body

Name	Type	Description
success	boolean	Whether API call is successful or not
data	object	Response body (empty on success)

---

POST /v1/validator/update/ofac

Update OFAC flag for the authenticated user's validators. If publicKeys is omitted, it updates all validators for the user.

HTTP

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

Python

import requests

url = f"{ETHGAS_API_URL}/v1/validator/update/ofac"
params = {"publicKeys": "0xabc...,0xdef...", "ofac": True}
headers = {'Authorization': 'Bearer <your-auth-token>'}
response = requests.post(url, headers=headers, params=params)
print(response.text)

Request

Parameter	Required	Type	Description
publicKeys	NO	string	Comma-separated validator public keys (hex, max 100). If omitted, updates all user validators
ofac	NO	boolean	OFAC flag (default: false)

Response Body

Name	Type	Description
success	boolean	Whether API call is successful or not
data	object	Response body (empty on success)

Error Codes

Code	Description
INVALID_PUBLIC_KEY	Invalid validator public key format
VALIDATORS_MAX	Maximum 100 validators allowed per request

---

POST /v1/validator/verify/batch

Verify multiple validator BLS signatures in one request.

HTTP

curl -H "Authorization: Bearer {{access_token}}" -X POST "$ETHGAS_API_URL/v1/validator/verify/batch?publicKeys=0xabc...,0xdef...&signatures=0xsig1...,0xsig2..."

Python

import requests

url = f"{ETHGAS_API_URL}/v1/validator/verify/batch"
params = {
    "publicKeys": "0xabc...,0xdef...",
    "signatures": "0xsig1...,0xsig2..."
}
headers = {'Authorization': 'Bearer <your-auth-token>'}
response = requests.post(url, headers=headers, params=params)
print(response.text)

Request

Parameter	Required	Type	Description
publicKeys	YES	string	Comma-separated validator public keys (hex, max 100)
signatures	YES	string	Comma-separated BLS signatures (hex), must match publicKeys count

Response Body

Name	Type	Description
data	object	Map of publicKey to verification result

Error Codes

Code	Description
INVALID_PUBLIC_KEY	Invalid validator public key format
INVALID_SIGNATURE	Invalid signature format
VALIDATOR_SIGNATURE_SIZE_NOT_MATCH_PUBLIC_KEY	publicKeys and signatures size mismatch
VALIDATOR_SIGNATURE_MAX	Too many signatures (max 100)