CHANGE LOG

2025-10-31

Support Ethereum Fusaka upgrade

2025-10-11

Updated contract address for mainnet and hoodi

2025-07-08

Update inclusion-preconf cancel-all-orders api
Update inclusion-preconf/markets api by adding validator_type field
Allow user to update its payment address
Allow user to specify its collater per slot for block owner / validator
Rename field fee_recipient to validator_payout_address
Added new api endpoint POST /api/v1/user/payoutAddress
Removed api endpoint POST /api/v1/builder/verify
- Now user can use POST /api/v1/builder/register to register and verify builder public keys with signatures

2025-06-26

Update validator api

2025-06-18

Update builder delegation api

2025-05-14

Add validator fees payout api
Add set User onchain_payout_enabled api
Add contract address for different environments

2025-05-06

Update withdraw api
Rename /api/v1/p/blockchain to /api/v1/p/network

2025-04-16

Add user fees api

2025-04-02

Mainnet v1 launched.
Updated mainnet collateral deposit address

2025-03-28

Updated get wholeblock and inclusion preconf markets API

2025-03-25

Updated Production Hoodi API and WS base url Updated testchain url for example usage Updated Validator API and User deposit collateral API

2025-03-15

Updated Production Hoodi API and WS base url
Updated testchain url for example usage
Updated Validator API and User deposit collateral API

2025-02-21

Update API naming. Added version control (v1)

2025-01-12

Added pricer api for market making and block building api for submitting bundles
Added get user validators api for retrieving a list of validators for the user

2024-12-01

Updated RPC endpoint for Holesky chain

2024-10-01

Ready for Testnet launch

INTRODUCTION

Welcome

Welcome to ETHGas API reference! Our WebSocket and REST APIs provide seamless access to market data, order placement, and more.

We offer REST API call examples in HTTP requests and Python language. You can view the code examples in the panel to the right, and toggle between programming languages with the tabs in upper right corner.

ETHGas APIs can be used in different languages via community supported packages:

Python (python-ethgas)

Please contact us via email or on our Telegram channel if you've any questions or suggestions. We'd love to hear from you!

Environments

Environment	Chain	RPC URL	Chain ID	API base URL	Websocket base URL	Collateral Contract
Mainnet	Ethereum Chain	https://eth.llamarpc.com	1	https://mainnet.app.ethgas.com/api	wss://mainnet.app.ethgas.com/ws	0x3314Fb492a5d205A601f2A0521fAFbD039502Fc3
Testnet	Hoodi Chain	https://ethereum-hoodi-rpc.publicnode.com	0x88BB0	https://hoodi.app.ethgas.com/api	wss://hoodi.app.ethgas.com/ws	0x104Ef4192a97E0A93aBe8893c8A2d2484DFCBAF1

User can get a list of mainnet rpc urls from https://chainlist.org/chain/1(https://chainlist.org/chain/1)

Connecting to ETHGas

from eth_account import messages
import json
import requests
from web3.auto import w3


domain = 'ADD_THE_DOMAIN_HERE'
account_address = 'ADD_YOUR_ETHEREUM_account_ADDRESS_HERE'
private_key = 'ADD_YOUR_PRIVATE_KEY_HERE'
chain_id = 'ADD_THE_CHAIN_ID_HERE'


###########################################
#   STEP 1. Get the login sign message.   #
###########################################

# Login
body = {'addr': account_address}
response = requests.post(domain + '/api/v1/user/login', data=body)
print(response.status_code)
print(response.text)

# Retrieve nonce & response message
nonce = response.json()['data']['nonceHash']
eip712_message = json.loads(response.json()['data']['eip712Message'])

print(eip712_message)
# Make signature
encoded_message = messages.encode_typed_data(full_message=eip712_message)

# Sign message
signed_message = w3.eth.account.sign_message(encoded_message, private_key=private_key)

# Verify login
body = {'addr': account_address, 'nonceHash': nonce, 'signature': w3.to_hex(signed_message.signature)}
response = requests.post(domain + '/api/v1/user/login/verify', data=body)

# Was login successful?
print(f"Login successful? {response.json()['success']}")

#####################################
#   STEP 2. Get the access token.   #
#####################################

# Get access token etc
access_token = response.json()['data']['accessToken']['token']
headers = {'Content-Type': 'application/json', 'Authorization': 'Bearer ' + access_token}
response_cookies = response.cookies

# Test calling a private endpoint
response = requests.get(url=domain + '/api/v1/user/accounts', headers=headers)
print("Here is your list of Ethgas accounts etc:\n")
print(json.dumps(response.json()['data']['accounts'], indent=2))


###########################################################
#   STEP 3. Refresh the access token before it expires.   #
###########################################################

# Refresh token
body = {'refreshToken': access_token}
response = requests.post(domain + '/api/v1/user/login/refresh', cookies=response_cookies, data=body)

# Get latest access token etc
access_token = response.json()['data']['accessToken']['token']
headers = {'Content-Type': 'application/json', 'Authorization': 'Bearer ' + access_token}
response_cookies = response.cookies

# Test calling a private endpoint again
response = requests.get(url=domain + '/api/v1/user/accounts', headers=headers)
print("Here is your list of Ethgas accounts etc:\n")
print(json.dumps(response.json()['data']['accounts'], indent=2))

Endpoints are divided into two categories: /api/v1/p and /api/v1.

/api/v1/p endpoints provide access to market data, order book snapshots, trade history, and more; information that is available to all users. These endpoints are open and do not require authentication, allowing developers to retrieve real-time market data for analysis or display purposes. On the other hand, /api/v1 endpoints require authentication and provide access to account-specific information and trading functionality.

For interacting with our /api/v1 endpoints, a login is required. The login workflow is as follows:

Get the login sign message by calling the endpoint /api/v1/user/login with the appropriate addr.
Sign the login message and call the endpoint /api/v1/user/login/verify with the addr, nonceHash, and signature. You will now receive the JWT access token, as well as user-related data, and now be able to call any private endpoints.
Before the access token has expired, call /api/v1/user/login/refresh to get a new access token.

private session: The JWT access token is valid for 1 hour, after each hour an access token refresh is required. A private REST request needs to include the JWT access token in the request's HEADER, format: Authorization: 'Bearer accessToken'. A private session is valid for 7 days, after 7 days a re-login is required. A private websocket session needs to include the access token in the session header, format: 'Bearer accessToken'

Example python code showing this workflow is on the right under the python tab.

REST API

Response structure

Every API response contains a success flag and a response body.

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

Authentication

Code sample:

curl -X POST /api/v1/user/login?addr=0x8F02425B5f3c522b7EF8EA124162645F0397c478&name=username

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/login"

payload = {
    'addr': '0x5eF1B2c02f5E39C0fF667611C5d7EfFb0E7df305',
    'name': 'username'    
}

headers = {
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "status": "verify",
        "eip712Message": "{\"types\":{\"EIP712Domain\":[{\"name\":\"name\",\"type\":\"string\"},{\"name\":\"version\",\"type\":\"string\"},{\"name\":\"chainId\",\"type\":\"uint256\"},{\"name\":\"verifyingContract\",\"type\":\"address\"}],\"data\":[{\"name\":\"hash\",\"type\":\"string\"},{\"name\":\"message\",\"type\":\"string\"},{\"name\":\"domain\",\"type\":\"string\"}]},\"primaryType\":\"data\",\"message\":{\"hash\":\"52a90c73\",\"message\":\"Please sign this message to verify account ownership\",\"domain\":\"ethgas.com\"},\"domain\":{\"name\":\"ETHGas Login\",\"version\":\"1\",\"chainId\":32382,\"verifyingContract\":\"0x0000000000000000000000000000000000000000\"}}",
        "nonceHash": "52a90c73"
    }
}

Request

Parameter	Required	Type	Description
addr	YES	string	User's EOA account (account) address
name	NO	string	Display name

Response Body

Name	Type	Description
status	string	Login status
eip712Message	object	EIP712 message
nonceHash	string	A unique four-byte nonce to identify this particular login request

Usage

Get the response from /api/v1/user/login and sign the eip712Message and send the signed message through /api/v1/user/login/verify

Code sample:

curl -X POST /api/v1/user/login/verify?addr=0xe61f536f031f77C854b21652aB0F4fBe7CF3196F&nonceHash=517d9272&signature=0xc046037ec795f4cfe7aca33a0c283c0152bae91008b3e14b84be50f91f0e2db714054dee85b840e3edf0e26480231a684447f48337de64ea6697a3552aa9351a1b

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/login/verify"

payload = {
    "addr": "0xe61f536f031f77C854b21652aB0F4fBe7CF3196F",
    "nonceHash": "517d9272",
    "signature": "0xc046037ec795f4cfe7aca33a0c283c0152bae91008b3e14b84be50f91f0e2db714054dee85b840e3edf0e26480231a684447f48337de64ea6697a3552aa9351a1b"  
}

headers = {
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "user": {
            "userId": 78,
            "address": "0xe61f536f031f77c854b21652ab0f4fbe7cf3196f",
            "status": 1,
            "userType": 1,
            "userClass": 1,
            "accounts": [
                {
                    "accountId": 242,
                    "userId": 78,
                    "type": 1,
                    "name": "Current",
                    "status": 1,
                    "updateDate": 1698127521000
                },
                {
                    "accountId": 243,
                    "userId": 78,
                    "type": 2,
                    "name": "Preconf",
                    "status": 1,
                    "updateDate": 1698127521000
                }
            ]
        },
        "accessToken": {
            "data": {
                "header": {
                    "alg": "ES256",
                    "typ": "JWT"
                },
                "payload": {
                    "user": {
                        "userId": 78,
                        "address": "0xe61f536f031f77c854b21652ab0f4fbe7cf3196f",
                        "roles": [
                            "ROLE_USER"
                        ]
                    },
                    "access_type": "access_token",
                    "iat": 1698633225,
                    "exp": 1698636825
                }
            },
            "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6NzgsImFkZHJlc3MiOiIweGU2MWY1MzZmMDMxZjc3Yzg1NGIyMTY1MmFiMGY0ZmJlN2NmMzE5NmYiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk4NjMzMjI1LCJleHAiOjE2OTg2MzY4MjV9.E3aIKqqFsHVBYedAuqn6Jw6bymsWy6RQ6gf_lDXnYNorjngA05uFLaTM0A2ZrN4kJ8nTXEjlrdhLU8crisJcdA"
        }
    }
}

Verify login.

Request

Parameter	Required	Type	Description
addr	YES	string	User's EOA account (account) address
nonceHash	YES	string	Nonce Hash
signature	YES	string	Signature

Response Body

Name	Type	Description
user	User	User details
accessToken	string	Access token

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/login/refresh?refreshToken=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoicmVmcmVzaF90b2tlbiIsImlhdCI6MTY5NzQyNDM0MCwiZXhwIjoxNjk4MDI5MTQwfQ.Y5dtx_VXGDZ4EDt4e6qtaVd811XumXjtDtVMiQeibNCai5zvV1PJJ3R8WCTSZb6NbbxAtFsTglYRD10aigDECA

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/login/refresh"

payload = {
    'refreshToken': 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoicmVmcmVzaF90b2tlbiIsImlhdCI6MTY5NzQyNDM0MCwiZXhwIjoxNjk4MDI5MTQwfQ.Y5dtx_VXGDZ4EDt4e6qtaVd811XumXjtDtVMiQeibNCai5zvV1PJJ3R8WCTSZb6NbbxAtFsTglYRD10aigDECA'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ1MjQyLCJleHAiOjE2OTc0NDg4NDJ9.iPUK1f8QWZLnKPt-fdo-dlrakxSPyo041J5xnIKVLtsOsBIR8gu2hEv8a7S18CtRfViRchT4xhSQfSJj-SxleQ'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "user": {
            "userId": 31,
            "address": "0x5c812c9a67e6900eb20f3f31d0ecce523d6a5c03",
            "userType": 1,
            "status": 1,
            "accounts": [
                {
                    "accountId": 127,
                    "type": 1,
                    "cashTokenIds": [
                        1
                    ],
                },
                {
                    "accountId": 128,
                    "type": 2,
                    "cashTokenIds": [
                        1
                    ]
                }
            ]
        },
        "accessToken": {
            "data": {
                "header": {
                    "alg": "ES256",
                    "typ": "JWT"
                },
                "payload": {
                    "user": {
                        "userId": 31,
                        "address": "0x5c812c9a67e6900eb20f3f31d0ecce523d6a5c03",
                        "roles": [
                            "ROLE_USER"
                        ]
                    },
                    "access_type": "access_token",
                    "iat": 1697449134,
                    "exp": 1697452734
                }
            },
            "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w"
        }
    }
}

Get access token by non-expired refresh token.

Request

Parameter	Required	Type	Description
refreshToken	YES	string	Refresh token

Response Body

Name	Type	Description
user	User	User details
accessToken	object	Access token used for authentication: See Connecting to ETHGas section

POST /api/v1/user/logout

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/logout

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/logout"

headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers)

print(response.text)

Example response:

{}

Log out.

Request

No parameters for this endpoint.

Response Body

No response data for this endpoint.

User

POST /api/v1/user/update

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/update?displayName=NewDisplayName

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/update"

payload = {
    'displayName': 'NewDisplayName'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "user": {
            "userId": 73,
            "address": "0xcc8f16b4e20feb0e7eb5a4725451db6316afa8f",
            "status": 1,
            "userType": 1,
            "userClass": 1,
            "displayName": "XXXXX",
            "payoutAddress": "0xde88f16b4e20feb0525289041db6316afa8f",
            "collateralPerSlot": "0",
            "onchainPayout": true,
            "accounts": [
                {
                    "accountId": 2170,
                    "userId": 73,
                    "type": 1,
                    "name": "Current",
                    "status": 1,
                    "updateDate": 1751854737000
                },
                {
                    "accountId": 2171,
                    "userId": 73,
                    "type": 2,
                    "name": "InPreconf",
                    "status": 1,
                    "updateDate": 1751854737000
                }
            ]
        }
    }
}

Update user display name.

Request

Parameter	Required	Type	Description
displayName	YES	String	Display name

Response Body

Name	Type	Description
user	object	Updated user object
└ userId	long	Unique user ID
└ address	string	User's wallet address
└ status	integer	User status (1 = active)
└ userType	integer	User type
└ userClass	integer	User class
└ displayName	string	User's display name
└ payoutAddress	string	User's payout address
└ collateralPerSlot	string	Collateral per slot amount
└ onchainPayout	boolean	Whether on-chain payout is enabled
└ accounts	object[]	List of user accounts
└└ accountId	long	Unique account ID
└└ userId	long	User ID associated with the account
└└ type	integer	Account type
└└ name	string	Account name
└└ status	integer	Account status
└└ updateDate	long	Last update timestamp in milliseconds

POST /api/v1/user/payoutAddress

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/payoutAddress?payoutAddress=0x1234567890123456789012345678901234567890

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/payoutAddress"

payload = {
    'payoutAddress': '0x1234567890123456789012345678901234567890'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {}
}

Update user payout address.

Request

Parameter	Required	Type	Description
payoutAddress	YES	String	New payout address (hex format)

Response Body

Name	Type	Description
success	boolean	Operation success status

POST /api/v1/user/collateralPerSlot

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/collateralPerSlot?collateralPerSlot=10.5

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/collateralPerSlot"

payload = {
    'collateralPerSlot': '10.5'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {}
}

Update user collateral per slot amount.

Request

Parameter	Required	Type	Description
collateralPerSlot	YES	BigDecimal	Collateral per slot amount (must be >= 0 and <= 100)

Response Body

Name	Type	Description
success	boolean	Operation success status

Error Codes

Code	Description
COLLATERAL_PER_SLOT_NEGATIVE	Collateral per slot cannot be negative
COLLATERAL_PER_SLOT_TOO_LARGE	Collateral per slot cannot exceed 100

GET /api/v1/user/info

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/info

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/info"

payload = {}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "user": {
            "userId": 73,
            "address": "0xcc8f16b4e20feb0e7eb5a4725451db6316afa8f",
            "status": 1,
            "userType": 1,
            "userClass": 1,
            "displayName": "XXXXX",
            "payoutAddress": "0xde88f16b4e20feb0525289041db6316afa8f",
            "collateralPerSlot": "0",
            "onchainPayout": true,
            "accounts": [
                {
                    "accountId": 2170,
                    "userId": 73,
                    "type": 1,
                    "name": "Current",
                    "status": 1,
                    "updateDate": 1751854737000
                },
                {
                    "accountId": 2171,
                    "userId": 73,
                    "type": 2,
                    "name": "InPreconf",
                    "status": 1,
                    "updateDate": 1751854737000
                }
            ]
        }
    }
}

Get user information.

Request

No parameters required.

Response Body

Name	Type	Description
user	object	User object
└ userId	long	Unique user ID
└ address	string	User's wallet address
└ status	integer	User status (1 = active)
└ userType	integer	User type
└ userClass	integer	User class
└ displayName	string	User's display name
└ payoutAddress	string	User's payout address
└ collateralPerSlot	string	Collateral per slot amount
└ onchainPayout	boolean	Whether on-chain payout is enabled
└ accounts	object[]	List of user accounts
└└ accountId	long	Unique account ID
└└ userId	long	User ID associated with the account
└└ type	integer	Account type
└└ name	string	Account name
└└ status	integer	Account status
└└ updateDate	long	Last update timestamp in milliseconds

Account

GET /api/v1/user/accounts

Code sample:

curl  -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/accounts

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/accounts"

headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "accounts": [
            {
                "accountId": 127,
                "userId": 31,
                "type": 1,
                "name": "Current",
                "status": 1,
                "updateDate": 1672903708000,
                "tokens": [
                    {
                        "accountId": 127,
                        "tokenId": 1,
                        "quantity": "0.01",
                        "lockedQuantity": "0",
                        "code": "ETH",
                        "availableQuantity": "0.01"
                    }
                ]
            },
            {
                "accountId": 128,
                "userId": 31,
                "type": 2,
                "name": "Preconf Account",
                "status": 1,
                "updateDate": 1697445293000,
                "tokens": [
                    {
                        "accountId": 128,
                        "tokenId": 1,
                        "quantity": "9999993311.535880667",
                        "lockedQuantity": "1.5628",
                        "code": "ETH",
                        "availableQuantity": "9999993309.973080667"
                    }
                ]
            }
        ]
    }
}

Get list of user accounts.

Request

No parameters for this endpoint.

Response Body

Name	Type	Description
accounts	arrary of object	List of account objects
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ userId	integer	Unique ID for the user, assigned by ETHGas
└ type	integer	Account type: 1 for current account 2 for preconf trading account
└ name	string	Account name Default values are "Current" and "Trading" but these can be changed using the /private/update_account_name endpoint
└ status	integer	Account status: All active accounts have status 1
└ updateDate	integer	Datetime (in UNIX time) the healthscoare and other risk metrics (asset amount, liability amount, etc) were last calculated
└ tokens	object[]	List of tokens in account
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ tokenId	integer	ETHGas Token ID See Token IDs section for list of Token IDs
└ quantity	string	Amount of token in account in USD
└ lockedQuantity	string	Amount of token in account in USD which is covering pending limit orders (and so cannot be transfered out of account)
└ code	string	Token code See Token IDs section for list of token codes
└ tokenType	integer	Token type: Currently all tokens at ETHGas are designated as type 1
└ valueType	integer	Value type: 1 for non-stablecoin tokens 2 for stablecoin tokens
└ tokenValuationProtocol	integer	Platform the complex token comes from (if relevant): See Token Valuation Protocols section
└ availableQuantity	string	Available quantity for using as collateral for buying or for transfering out of the account: Available Quantity = Quantity - Locked Quantity

GET /api/v1/user/account/{accountId}

Code sample:

curl  -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/account/128

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/account/128"


headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "account": {
            "accountId": 128,
            "userId": 31,
            "type": 2,
            "name": "Trading",
            "status": 1,
            "updateDate": 1697445293000,
            "tokens": [
                {
                    "accountId": 128,
                    "tokenId": 1,
                    "quantity": "9999993308.004503191",
                    "lockedQuantity": "0",
                    "code": "ETH",
                    "tokenType": 1,
                    "valueType": 1,
                    "tokenValuationProtocol": 0,
                    "availableQuantity": "9999993308.004503191"
                }
            ]
        }
    }
}

Get account details for a given account ID.

Request

Parameter	Required	Type	Description
accountId	YES	integer	Account ID

Response Body

Name	Type	Description
account	object	Account object
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ userId	integer	Unique ID for the user, assigned by ETHGas
└ type	integer	Account type: 1 for current account 2 for trading account
└ name	string	Account name Default values are "Current" and "Trading" but these can be changed using the /private/update_account_name endpoint.
└ status	integer	Account status: All active accounts have status 1
└ updateDate	integer	Datetime (in UNIX time) the healthscoare and other risk metrics (asset amount, liability amount, etc) were last calculated.
└ tokens	object[]	List of tokens in account
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ tokenId	integer	ETHGas Token ID See Token IDs section for list of Token IDs
└ quantity	string	Amount of token in account in USD
└ lockedQuantity	string	Amount of token in account in USD which is covering pending limit orders (and so cannot be transfered out of account)
└ code	string	Token code See Token IDs section for list of token codes
└ tokenType	integer	Token type: Currently all tokens at ETHGas are designated as type 1
└ valueType	integer	Value type: 1 for non-stablecoin tokens 2 for stablecoin tokens
└ tokenValuationProtocol	integer	Platform the complex token comes from (if relevant): See Token Valuation Protocols section
└ availableQuantity	string	Available quantity for using as collateral for buying or for transfering out of the account: Available Quantity = Quantity - Locked Quantity

GET /api/v1/user/account/{accountId}/txs

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/account/128/txs

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/account/{accountId}/txs


headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "txs": [
            {
                "trxId": 507873974,
                "accountId": 128,
                "tokenId": 1,
                "type": 15,
                "quantity": "-0.141865",
                "balance": "10010502890.372428552",
                "createDate": 1697450286000
            },
            {
                "trxId": 507873973,
                "accountId": 128,
                "tokenId": 1,
                "type": 2,
                "quantity": "-1418.65",
                "balance": "10010502890.514293552",
                "createDate": 1697450286000
            },
            {
                "trxId": 507873970,
                "accountId": 128,
                "tokenId": 1,
                "type": 15,
                "quantity": "-0.00009848",
                "balance": "9999993308.350858416",
                "createDate": 1697450286000
            },
            {
                "trxId": 507873969,
                "accountId": 128,
                "tokenId": 1,
                "type": 2,
                "quantity": "-0.9848",
                "balance": "9999993308.350956896",
                "createDate": 1697450286000
            },
            {
                "trxId": 507873966,
                "accountId": 128,
                "tokenId": 1,
                "type": 15,
                "quantity": "-0.00008252",
                "balance": "9999993309.335674376",
                "createDate": 1697450286000
            },
            {
                "trxId": 507873965,
                "accountId": 128,
                "tokenId": 1,
                "type": 2,
                "quantity": "0.8252",
                "balance": "9999993309.335756896",
                "createDate": 1697450286000
            }
        ]
    }
}

Get account transactions for a given account ID.

Request

Parameter	Required	Type	Description
accountId	YES	integer	Account ID
type	NO	string	Transaction type
startId	NO	integer	Start of transaction ID
limit	NO	integer	Max number of transactions to return

Response Body

Name	Type	Description
txs	object[]	List of transaction objects
└ trxId	integer	Unique ID for the transaction, assigned by ETHGas
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ tokenId	integer	ETHGas Token ID See Token IDs section for list of Token IDs
└ type	integer	Transaction type See Transaction Types section for full list
└ quantity	string	Transaction quantity
└ balance	string	Balance of account after transaction
└ createDate	integer	Transaction datetime stamp (in UNIX time)

GET /api/v1/user/account/txs

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/account/txs

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/account/txs"

headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "txs": [
            {
                "trxId": 507873974,
                "accountId": 128,
                "tokenId": 1,
                "type": 15,
                "quantity": "-0.141865",
                "balance": "10010502890.372428552",
                "createDate": 1697450286000
            }
        ]
    }
}

Get account transactions for the current user.

Request

Parameter	Required	Type	Description
type	NO	string	Transaction type (comma-separated for multiple types)
startId	NO	integer	Start of transaction ID
limit	NO	integer	Max number of transactions to return (default: 20, max: 100)

Response Body

Name	Type	Description
txs	object[]	List of transaction objects
└ trxId	integer	Unique ID for the transaction, assigned by ETHGas
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ tokenId	integer	ETHGas Token ID See Token IDs section for list of Token IDs
└ type	integer	Transaction type See Transaction Types section for full list
└ quantity	string	Transaction quantity
└ balance	string	Balance of account after transaction
└ createDate	integer	Transaction datetime stamp (in UNIX time)

POST /api/v1/user/account/transfer/token

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/account/transfer/token?fromAccountId=128&toAccountId=127&tokenId=1&quantity=0.01

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/account/transfer/token"

params = {
    "fromAccountId": 128,
    "toAccountId": 127,
    "tokenId": 1,
    "quantity": 0.01
}

headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {}
}

Transfer token between accounts.

Request

Parameter	Required	Type	Description
fromAccountId	YES	integer	Source account ID
toAccountId	YES	integer	Destination account ID
tokenId	YES	integer	Token ID
quantity	YES	number	Quantity

Response Body

Name	Type	Description

Funding

GET /api/v1/p/funding/contractAddress

Code sample:

curl -X  GET /api/v1/p/funding/contractAddress

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/funding/contractAddress"


response = requests.get(url)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "contractAddress": "0x818EF032D736B1a2ECC8556Fc1bC65aEBD8482c5"
    }
}

Get deposit collateral address.

Request

Parameter	Required	Type	Description

Response Body

Name	Type	Description
contractAddress	string	deposit collateral address 0x818EF032D736B1a2ECC8556Fc1bC65aEBD8482c5

GET /api/v1/user/funding/deposits

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X  GET /api/v1/user/funding/deposits

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/funding/deposits"

payload = {}
headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "deposits": [
            {
                "eventId": 6,
                "chainId": 1,
                "blockIdx": 123456,
                "blockHash": "0xdd5a8e1742e26ce90feb865f1c6a0fdbf2d8cbed086314fc85281ff47aaea5ee",
                "transactionIdx": 2,
                "transactionHash": "0x866bb046a97243519679183e08e5ce6728d3e1e9976a2535ce8c8887b62997a2",
                "logIdx": 2,
                "senderAddress": "0xd055335192d920ce2de4a88557f232943a901a9f",
                "depositAddress": "0xd055335192d920ce2de4a88557f232943a901a9f",
                "status": 10,
                "deposits": [
                    {
                        "a": "0xdc0b8e3cd3fec447940cb8107957f22e7e320812",
                        "q": 500000000000000000,
                        "s": 10
                    }
                ],
                "actions": [],
                "createDate": 1746005076000
            }
        ]
    }
}

Get fund deposits history.

Request

Parameter	Required	Type	Description
limit	NO	integer	Maximum number of deposits to return
startBlockId	NO	integer	Block start ID

Response Body

Name	Type	Description
deposits	object[]	List of deposits
└ eventId	long	Unique ID for the deposit event
└ chainId	integer	Unique ID for the chain, assigned by ETHGas: Currently only Ethereum (Chain ID 1) is supported.
└ blockIdx	long	Block ID
└ blockHash	byte[]	Block hash
└ transactionIdx	long	Transaction ID
└ transactionHash	byte[]	Transaction hash
└ logIdx	integer	Log ID
└ senderAddress	string	Sender address
└ depositAddress	string	Deposit address
└ status	integer	Deposit status, success = 10
└ deposits	object[]	Deposits
└ actions	string	Actions
└ createDate	date	create date

POST /api/v1/user/funding/withdraw

Code sample:

curl -x POST /api/v1/user/funding/withdraw

[
    {
        "accountId": 12,
        "tokenId": 1,
        "chainId": 1,
        "quantity": "0.05"
    },
    {
        "accountId": 12,
        "tokenId": 2,
        "chainId": 1,
        "quantity": "0.001"
    }
]

import requests
import json

url = "https://mainnet.app.ethgas.com/api/v1/user/funding/withdraw"

payload = json.dumps([
    {
        "accountId": 12,
        "tokenId": 1,
        "chainId": 1,
        "quantity": "0.05"
    }
])

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "submittedRequestIds": [
            4
        ],
        "failedRequests": [
            {
                "accountId": 21,
                "tokenId": 1,
                "chainId": 32382,
                "quantity": "0.001",
                "status": 101,
                "remark": "Unsupported Chain ID."
            }
        ]
    }
}

Request to withdraw funds.

Request

Parameter	Required	Type	Description
requests	YES	object[]	List of withdraw requests
└ accountId	YES	integer	Account ID
└ chainId	YES	integer	Chain ID
└ tokenId	YES	integer	Token ID
└ quantity	YES	string	Quantity to be withdrawn

Response Body

Name	Type	Description
submittedRequestIds	integer[]	List of successful submitted request IDs
failedRequests	object[]	List of failed submitted requests with reason.
└ accountId	integer	Account ID
└ chainId	integer	Chain ID
└ tokenId	integer	Token ID
└ fee	string	Token ID
└ quantity	string	Quantity to be withdrawn
└ status	integer	Status of submitted withdraw request
└ remark	string	Reason of failed request.

GET /api/v1/p/funding/withdraw/dailyWithdrawLimits

Code sample:

curl -X GET /api/v1/p/funding/withdraw/dailyWithdrawLimits

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/funding/withdraw/dailyWithdrawLimits"

response = requests.get(url)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "dailyWithdrawLimits": [
            {
                "tokenId": 1,
                "chainId": 1,
                "tokenAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
                "withdrawFee": "0.01",
                "dailyWithdrawLimit": "50",
                "remainingWithdrawLimit": "49.863"
            }
        ]
    }
}

Get list of token's current on-chain daily withdraw limits

Request

Parameter	Required	Type	Description

Response Body

Name	Type	Description
Name	Type	Description
-----------------------------	---------	--------------------------------------------------------------------------------------------------------------------------------------------
dailyWithdrawLimits	object[]	Block chain details
└ tokenId	integer	Unique ID for the blockchain network assigned by ETHGas, assigned by ETHGas: Currently only Ethereum (Chain ID 1) is supported.
└ chainId	integer	Unique ID for the chain: Currently only Ethereum (Chain ID 1) is supported.
└ tokenAddress	string	Address of ERC-20 token contract (e.g. WETH)
└ withdrawFee	string	Withdrawal fee.
└ dailyWithdrawLimit	string	Daily withdraw limit of ERC-20 token
└ remainingWithdrawLimit	integer	remaining withdraw limit in past 24 hours.

GET /api/v1/user/funding/withdraw/status

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/funding/withdraw/status?requestIds=123%2c456

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/funding/withdraw/status?requestIds=123,456"

params = {
    'requestIds': '123,456'
}

headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "requests": [
            {
                "requestId": 16,
                "userId": 17,
                "accountId": 15,
                "tokenId": 1,
                "chainId": 17000,
                "quantity": "0.005",
                "fee": "0.001",
                "status": 10,
                "txHash": "0x4de9ecf18ea11d8d290a01e759f3b150809f70cccb08bb74ceede7a801e2e9a5",
                "createDate": 1746161880000,
                "updateDate": 1746162105000
            },
            {
                "requestId": 15,
                "userId": 17,
                "accountId": 15,
                "tokenId": 1,
                "chainId": 17000,
                "quantity": "0.005",
                "fee": "0.001",
                "status": 10,
                "txHash": "0xba85584d93dd7a209838308a767c9848535d0ada4f83c17526147f9c74104edd",
                "createDate": 1746160279000,
                "updateDate": 1746160538000
            }
        ]
    }
}

Get fund withdrawal request status (for given list of request IDs).

Request

Parameter	Required	Type	Description
requestIds	YES	integer[]	List of fund withdrawal request IDs

Response Body

Name	Type	Description
requests	object[]	List of withdraw requests with status
└ requestId	integer	Request ID
└ userId	integer	User ID
└ accountId	integer	Account ID
└ chainId	integer	Chain ID
└ tokenId	integer	Token ID
└ fee	string	Token ID
└ quantity	string	Quantity to be withdrawn
└ status	integer	Status of submitted withdraw request
└ quantity	string	Quantity to be withdrawn
└ txHash	string	Transaction hash of submitted withdraw transaction
└ createDate	string	Create date
└ updateDate	string	Last update date

GET /api/v1/user/funding/withdraws

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/funding/withdraws

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/funding/withdraws"

headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "requests": [
            {
                "requestId": 16,
                "userId": 17,
                "accountId": 15,
                "tokenId": 1,
                "chainId": 17000,
                "quantity": "0.005",
                "fee": "0.001",
                "status": 10,
                "txHash": "0x4de9ecf18ea11d8d290a01e759f3b150809f70cccb08bb74ceede7a801e2e9a5",
                "createDate": 1746161880000,
                "updateDate": 1746162105000
            },
            {
                "requestId": 15,
                "userId": 17,
                "accountId": 15,
                "tokenId": 1,
                "chainId": 17000,
                "quantity": "0.005",
                "fee": "0.001",
                "status": 10,
                "txHash": "0xba85584d93dd7a209838308a767c9848535d0ada4f83c17526147f9c74104edd",
                "createDate": 1746160279000,
                "updateDate": 1746160538000
            }
        ]
    }
}

Get list of fund withdrawals.

Request

Parameter	Required	Type	Description
limit	NO	integer	Maximum number of withdrawals to return
startId	NO	integer	Fund withdrawal request start ID

Response Body

Name	Type	Description
requests	object[]	List of withdraw requests
└ requestId	integer	Request ID
└ userId	integer	User ID
└ accountId	integer	Account ID
└ chainId	integer	Chain ID
└ tokenId	integer	Token ID
└ fee	string	Token ID
└ quantity	string	Quantity to be withdrawn
└ status	integer	Status of submitted withdraw request
└ quantity	string	Quantity to be withdrawn
└ txHash	string	Transaction hash of submitted withdraw transaction
└ createDate	string	Create date
└ updateDate	string	Last update date

Network

GET /api/v1/p/network

Code sample:

curl -x GET /api/v1/p/network

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/network"

params = {
    'chainId': 1
}

headers = {}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "network": {
            "networkId": 1,
            "chainId": 11155111,
            "name": "Ethereum",
            "enable": true,
            "visible": true
        }
    }
}

Get network details for a given blockchain ID.

Request

Parameter	Required	Type	Description
chainId	YES	integer	Chain ID

Response Body

Name	Type	Description
network	object	Block chain details
└ networkId	integer	Unique ID for the blockchain network assigned by ETHGas, assigned by ETHGas: Currently only Ethereum (Chain ID 1) is supported.
└ chainId	integer	Unique ID for the chain: Currently only Ethereum (Chain ID 1) is supported.
└ name	string	Name of the blockchain network (e.g. Ethereum)
└ enable	boolean	Whether this chain is enabled within ETHGas: This should always return true.
└ visible	boolean	Whether this chain is visible on ETHGas: This should always return true.

Tokens

GET /api/v1/p/tokens

Code sample:

curl -X GET /api/v1/p/tokens

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/tokens"

headers = {}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "tokens": [
            {
                "tokenId": 1,
                "code": "ETH",
                "name": "Wrapped ETH",
                "tokenAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
                "decimals": 18,
                "nativeToken": false,
                "withdrawFee": "0.01",
                "price": "1582.09761118"
            }
        ]
    }
}

Get details for all tokens.

Request

No parameters for this endpoint.

Response Body

Name	Type	Description
tokens	object[]	List of token objects
└ tokenId	integer	ETHGas Token ID See Token IDs section for list of Token IDs
└ code	string	Token code See Token IDs section for list of token codes
└ name	string	Token code See Token IDs section for list of token names
└ tokenAddress	string	Token chain address
└ decimals	integer	Number of decimal precision for this token
└ withdrawFee	string	Withdrawal fee (in number of tokens)
└ price	string	Latest token price

Fees

GET /api/v1/p/user/fees

Code sample:

curl -x GET /api/v1/p/user/fees

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/user/fees

headers = {}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "buyFeeRate": "0.01",
        "primarySellFeeRate": "0.045", 
        "secondarySellFeeRate": "0.05"
    }
}

Get current trading fees

Request

Parameter	Required	Type	Description

Response Body

Name	Type	Description
buyFeeRate	BigDecimal	Percentage fees charged for buy transaction
primarySellFeeRate	BigDecimal	Percentage fees charged for first time sell transaction
secondarySellFeeRate	BigDecimal	Percentage fees charged for subsequent sell transaction

Whole Block Markets

GET /api/v1/p/wholeblock/markets

Code sample:

curl -X GET /api/v1/p/wholeblock/markets

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/wholeblock/markets

headers = {}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "markets": [
            {
                "marketId": 2000000295209,
                "slot": 295209,
                "instrumentId": "ETH-WB-295209",
                "name": "ETH Whole Block Slot #295209",
                "priceStep": "0.00000000001",
                "minPrice": "0.00000000001",
                "maxPrice": "0.00001",
                "availablePreconf": 17257755,
                "direction": true,
                "price": "0.00000000588",
                "midPrice": "0.00000000564",
                "status": 1,
                "maturityTime": 1751947307000,
                "blockTime": 1751947311000,
                "finalityTime": 1751948079000,
                "updateDate": 1751947297000
            },
            {
                "marketId": 2000000295211,
                "slot": 295211,
                "instrumentId": "ETH-WB-295211",
                "name": "ETH Whole Block Slot #295211",
                "priceStep": "0.00000000001",
                "minPrice": "0.00000000001",
                "maxPrice": "0.00001",
                "availablePreconf": 16587826,
                "direction": true,
                "price": "0.00000000581",
                "status": 1,
                "maturityTime": 1751947331000,
                "blockTime": 1751947335000,
                "finalityTime": 1751948103000,
                "updateDate": 1751947297000
            }
        ]
    }
}

Get active all whole block market details.

Request

Parameter	Required	Type	Description

Response Body

Name	Type	Description
markets	object[]	List of Whole Block Market objects
└ marketId	integer	Whole block market ID
└ slot	integer	Slot number of the block
└ instrumentId	string	Whole block market instrument ID Use endpoint [GET /api/v1/p/wholeblock/markets] to get a list of all available wholeblock markets' instrument IDs
└ name	string	Whole block market name In format: "ETH-WB-xxxxxx"
└ priceStep	string	Minimum increment between valid price levels
└ minPrice	string	Minimum price
└ maxPrice	string	Maximum price
└ availablePreconf	integer	Available preconf quantity for trading
└ direction	boolean	The last trading direction (true = buy, false = sell)
└ price	string	Latest traded market price for this market
└ status	integer	Market status - see the Market Status Codes section for more information
└ maturityTime	integer	Datetime (in UNIX time) when the market will be closed
└ trxSubmitTime	integer	Datetime (in UNIX time) when the market will be closed for submitting transactions
└ blockTime	integer	Datetime (in UNIX time) when the block starts
└ finalityTime	integer	Datetime (in UNIX time) when the block is being finalized
└ updateDate	integer	Datetime (in UNIX time) when the market orderbook was last updated

GET /api/v1/p/wholeblock/positions

Code sample:

curl -X GET /api/v1/p/wholeblock/positions?instrumentId=ETH-WB-9884031&limit=10

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/wholeblock/positions"

params = {
  "instrumentId": "ETH-WB-9884031",
  "limit": 10
}

response = requests.get(url, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "positions": [
              {
                "slot": 296895,
                "quantity": "1",
                "locked": "0",
                "expired": false,
                "updateDate": 1751967044730,
                "available": "1",
                "averagePrice": "0.0000000058"
            }
        ]
    }
}

Get whole block positions.

Request

Parameter	Required	Type	Description
instrumentId	NO	string	Instrument ID
limit	NO	integer	Maximum Number of Positions To Return (default: 10)

Response Body

Name	Type	Description
positions	object[]	List of position object
└ slot	integer	Slot number of the block
└ quantity	string	Position quantity
└ available	string	Position quantity available for trading
└ locked	string	Locked quantity
└ expired	boolean	Position expired or not
└ averagePrice	string	Average price of executed trades
└ updateDate	integer	Datetime (in UNIX time) when the order was last updated

GET /api/v1/p/wholeblock/orders

Code sample:

curl -X GET /api/v1/p/wholeblock/orders?instrumentId=ETH-WB-9884031&onbook=false&done=false&limit=10

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/wholeblock/orders"

params = {
  "instrumentId": "ETH-WB-9884031",
  "onbook": False,
  "done": False,
  "limit": 10
}

response = requests.get(url, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "orders": [
             {
                "orderId": 8522999,
                "marketId": 2000000160031,
                "side": false,
                "orderType": 2,
                "quantity": "1",
                "fulfilled": "1",
                "price": "0.00000000569",
                "fees": "0.0091793925",
                "status": 10,
                "clientOrderId": "b0eeb664",
                "passive": false,
                "createDate": 1750324420793,
                "source": 1,
                "updateDate": 1750324423349,
                "instrumentId": "ETH-WB-160031"
            },
            {
                "orderId": 8523033,
                "marketId": 2000000160031,
                "side": true,
                "orderType": 2,
                "quantity": "1",
                "fulfilled": "1",
                "price": "0.00000000591",
                "fees": "0.002039865",
                "status": 10,
                "clientOrderId": "b274e878",
                "passive": false,
                "createDate": 1750324423349,
                "source": 1,
                "updateDate": 1750324423349,
                "instrumentId": "ETH-WB-160031"
            }
        ]
    }
}

Get whole block orders.

Request

Parameter	Required	Type	Description
instrumentId	YES	string	List whole block Orders for a market
onbook	NO	boolean	Pending Orders Only? (default: false)
done	NO	boolean	Done Orders Only? (default: false)
startId	NO	integer	Order Start ID (default: 0)
asc	NO	boolean	Sort Order Direction, true=asc, false=desc, Default to true=asc
limit	NO	integer	Maximum Number of Orders To Return (default: 10)

Response Body

Name	Type	Description
orders	object[]	List of order object
└ orderId	integer	Unique order ID, assigned by ETHGas
└ marketId	integer	Market ID for this order
└ instrumentId	string	Whole block market instrument ID
└ side	boolean	buy order (true) or sell order (false)
└ orderType	integer	Market order (1) or limit order (2)
└ quantity	string	Order quantity (1 for whole block orders)
└ fulfilled	string	Quantity that has already been executed
└ price	string	Price of the order
└ fees	string	Fees charged for this order
└ status	integer	Order status - see the Order Status Codes section for more information
└ errorCode	integer	Error code if order failed (null if successful)
└ clientOrderId	string	An arbitrary string with max 32 characters (preferably unique) provided by the client when the order was created
└ passive	boolean	Whether the order is a maker order only
└ createDate	integer	Datetime (in UNIX time) when the order was created
└ source	integer	Where the order is originated
└ updateDate	integer	Datetime (in UNIX time) when the order was last updated

GET /api/v1/p/wholeblock/trades

Code sample:

curl -X GET /api/v1/p/wholeblock/trades?instrumentId=ETH-WB-9884031&limit=10

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/wholeblock/trades"

params = {
  "instrumentId": "ETH-WB-9884031",
  "limit": 10
}

response = requests.get(url, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "trades": [
            {
                "instrumentId": "ETH-WB-9884031",
                "trxId": 11675386,
                "side": false,
                "price": "0.00000002",
                "quantity": "1",
                "preconfQuantity": "320000000",
                "date": 1730269305359
            },
            {
                "instrumentId": "ETH-WB-9884031",
                "trxId": 2146182,
                "side": false,
                "price": "0.00000000568",
                "quantity": "1",
                "preconfQuantity": "19005872",
                "date": 1750299601863
            }
        ]
    }
}

Get whole block trades.

Request

Parameter	Required	Type	Description
instrumentId	YES	string	List whole block trades for a market
limit	NO	integer	Maximum Number of Trades To Return (default: 10)

Response Body

Name	Type	Description
trades	object[]	List of trades
└ instrumentId	string	Whole block market instrument ID
└ trxId	integer	Transaction Id
└ side	boolean	Order Side. Buy = true, Sell = false
└ price	string	Latest traded market price for this market
└ quantity	string	Quantity always = 1
└ preconfQuantity	string	Preconf quantity sold with the whole block
└ date	integer	Datetime (in UNIX time) when the trade was executed

Inclusion Preconf Markets

GET /api/v1/p/inclusion-preconf/markets

Code sample:

curl -x GET /api/v1/p/inclusion-preconf/markets

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/inclusion-preconf/markets

headers = {}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "markets": [
           {
                "marketId": 1000000295045,
                "slot": 295045,
                "instrumentId": "ETH-PC-295045",
                "name": "Eth Preconf Inclusion Slot #295045",
                "quantityStep": "1",
                "minQuantity": "1",
                "maxQuantity": "35850000",
                "priceStep": "0.00000000001",
                "minPrice": "0.00000000001",
                "maxPrice": "0.00001",
                "bestBid": "0.00000000015",
                "totalPreconf": 35850000,
                "availablePreconf": 19678280,
                "direction": true,
                "price": "0.00000000002",
                "midPrice": "0.00000000015",
                "status": 1,
                "maturityTime": 1751945339000,
                "trxSubmitTime": 1751945341000,
                "blockTime": 1751945343000,
                "finalityTime": 1751946111000,
                "totalGas": 16171720,
                "validatorType": 0,
                "updateDate": 1751945326000
            },
            {
                "marketId": 1000002880222,
                "slot": 2880222,
                "instrumentId": "ETH-PC-2880222",
                "name": "Eth Preconf Inclusion Slot #2880222",
                "quantityStep": "1",
                "minQuantity": "1",
                "maxQuantity": "30000000",
                "priceStep": "0.00000000001",
                "minPrice": "0.00000000001",
                "maxPrice": "0.00001",
                "collateralPerSlot": "2",
                "totalPreconf": 36000000,
                "availablePreconf": 36000000,
                "direction": true,
                "price": "0.00000001256",
                "midPrice": "0.00000001256",
                "status": 1,
                "maturityTime": 1730465060000,
                "trxSubmitTime": 1730465062000,
                "blockTime": 1730465064000,
                "finalityTime": 1730465832000,
                "totalGas": 29952852,
                "validatorType": 0,
                "updateDate": 1730465041000
            }
        ]
    }
}

Get active all preconf market details.

Request

Parameter	Required	Type	Description

Response Body

Name	Type	Description
markets	object[]	List of Market objects
└ marketId	integer	Preconf market ID
└ slot	integer	Slot number of the block
└ instrumentId	string	Inclusion Preconf Market instrument ID Use endpoint [GET /api/v1/p/inclusion-preconf/markets] to get a list of all available inclusion preconf markets' instrument IDs
└ name	string	Preconf market name In format: "ETH-PC-xxxxxx"
└ quantityStep	string	Minimum increment between different order quantities
└ minQuantity	string	Minimum order quantity
└ maxQuantity	string	Maximum order quantity
└ priceStep	string	Minimum increment between valid price levels
└ minPrice	string	Minimum price
└ maxPrice	string	Maximum price
└ collateralPerSlot	string	ETH reserved by validator as collateral for this slot
└ totalPreconf	integer	Total preconf quantity for this slot
└ availablePreconf	integer	Available preconf quantity for trading
└ direction	boolean	The last trading direction (true = buy, false = sell)
└ price	string	Latest traded market price for this market
└ midPrice	string	Mid price of bid and ask
└ status	integer	Market status - see the Market Status Codes section for more information
└ maturityTime	integer	Datetime (in UNIX time) when the market will be closed
└ trxSubmitTime	integer	Datetime (in UNIX time) when the market will be closed for submitting transactions
└ blockTime	integer	Datetime (in UNIX time) when the block starts
└ finalityTime	integer	Datetime (in UNIX time) when the block is being finalized
└ totalGas	integer	Total gas available for sale in this block
└ validatorType	integer	Type of validator (0 for normal validators, 1 for SSV validators)
└ updateDate	integer	Datetime (in UNIX time) when the market orderbook was last updated

GET /api/v1/p/inclusion-preconf/market

Code sample:

curl -X GET /api/v1/p/inclusion-preconf/market?slot=2880221

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/inclusion-preconf/market"

params = {
    "slot": 2880221
}

headers = {}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "market": {
            "marketId": 1000002880221,
            "slot": 2880221,
            "instrumentId": "ETH-PC-2880221",
            "name": "Eth Preconf Inclusion Slot #2880221",
            "quantityStep": "1",
            "minQuantity": "1",
            "maxQuantity": "30000000",
            "priceStep": "0.00000000001",
            "minPrice": "0.00000000001",
            "maxPrice": "0.00001",
            "collateralPerSlot": "3.996",
            "totalPreconf": 36000000,
            "availablePreconf": 30000000,
            "direction": true,
            "price": "0.00000001302",
            "midPrice": "0.00000001299",
            "status": 1,
            "maturityTime": 1730465048000,
            "trxSubmitTime": 1730465050000,
            "blockTime": 1730465052000,
            "finalityTime": 1730465820000,
            "totalGas": 29982469,
            "validatorType": 1,
            "updateDate": 1730465042000
        }
    }
}

Get preconfs market details for a given slot

Request

Parameter	Required	Type	Description
slot	YES	integer	Slot number

Response Body

Name	Type	Description
market	object	Market object
└ marketId	integer	Preconf market ID
└ slot	integer	Slot number of the block
└ instrumentId	string	Inclusion Preconf Market instrument ID Use endpoint [GET /api/v1/p/inclusion-preconf/markets] to get a list of all available instrument IDs
└ name	string	Preconf market name In format: "ETH-PC-xxxxxx"
└ quantityStep	string	Minimum increment between different order quantities
└ minQuantity	string	Minimum order quantity
└ maxQuantity	string	Maximum order quantity
└ priceStep	string	Minimum increment between valid price levels
└ minPrice	string	Minimum price
└ maxPrice	string	Maximum price
└ collateralPerSlot	string	ETH reserved by validator as collateral for this slot
└ totalPreconf	integer	Total preconf quantity for this slot
└ availablePreconf	integer	Available preconf quantity for trading
└ direction	boolean	The last trading direction (true = buy, false = sell)
└ price	string	Latest traded market price for this market
└ midPrice	string	Mid price of bid and ask
└ status	integer	Market status - see the Market Status Codes section for more information
└ maturityTime	integer	Datetime (in UNIX time) when the market will be closed
└ trxSubmitTime	integer	Datetime (in UNIX time) when the market will be closed for submitting transactions
└ blockTime	integer	Datetime (in UNIX time) when the block starts
└ finalityTime	integer	Datetime (in UNIX time) when the block is being finalized
└ totalGas	integer	Total gas available for sale in this block
└ validatorType	integer	Type of validator (0 for normal validators, 1 for SSV validators)
└ updateDate	integer	Datetime (in UNIX time) when the market orderbook was last updated

GET /api/v1/p/inclusion-preconf/trades

Code sample:

curl -X GET /api/v1/p/inclusion-preconf/trades?instrumentId=ETH-PC-988403

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/inclusion-preconf/trades"

params = {
    "instrumentId": "ETH-PC-988403",
}

headers = {}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "trades": [
        {
            "trxId": "1231310314",
            "instrumentId": "ETH-PC-988403",
            "side": false,
            "price": "0.0501",
            "quantity": "210000",
            "date": 1689833397180
        },
        {
            "trxId": "1231310327",
            "instrumentId": "ETH-PC-988403",            
            "side": false,
            "price": "0.0493",
            "quantity": "400000",
            "date": 1689833043675
        },
        {
            "trxId": "1249310327",
            "instrumentId": "ETH-PC-988403",                        
            "side": true,
            "price": "0.0487",
            "quantity": "100000",
            "date": 1689832827936
        },
        {
            "trxId": "1252310327",
            "instrumentId": "ETH-PC-988403",                       
            "side": false,
            "price": "0.0478",
            "quantity": "350000",
            "date": 1689832426057
        },
        {
            "trxId": "1261310327",
            "instrumentId": "ETH-PC-988403",                        
            "side": false,
            "price": "0.0339",
            "quantity": "21000",
            "date": 1689799385952
        }
    ]
}

Get recent preconf trade details for a given preconf instrument ID.

Request

Parameter	Required	Type	Description
instrumentId	YES	string	Instrument ID
limit	NO	integer	Maximum number of transactions to return

Response Body

Name	Type	Description
trades	object[]	List of trades
└ trxId	string	Transaction ID
└ instrumentId	string	Instrument ID
└ side	integer	Order Side. Buy = 1, Sell = 0
└ price	string	Latest traded market price for this market
└ quantity	integer	Quantity of the preconf bought
└ date	integer	Datetime (in UNIX time) when the trade was executed

GET /api/v1/p/inclusion-preconf/top-sales

Code sample:

curl -X GET /api/v1/p/inclusion-preconf/top-sales?instrumentId=ETH-PC-475423&limit=10

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/inclusion-preconf/top-sales"

params = {
    "instrumentId": "ETH-PC-475423",
    "limit": 10
}

headers = {}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "positions": [
            {
                "positionId": 123456789,
                "instrumentId": "ETH-PC-475423",
                "quantity": "1000",
                "avgPrice": "0.0000000125",
                "status": "ACTIVE"
            }
        ]
    }
}

Get Preconf positions by price.

Request

Parameter	Required	Type	Description
instrumentId	NO	String	Instrument ID
limit	NO	Integer	Maximum number of positions to return (default: 10)

Response Body

Name	Type	Description
positions	object[]	List of positions
└ positionId	long	Position ID
└ instrumentId	string	Instrument ID
└ quantity	string	Position quantity
└ avgPrice	string	Average price
└ status	string	Position status

Whole Block Trading

POST /api/v1/wholeblock/order

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/wholeblock/order&instrumentId=ETH-WB-9884031&accountId=128&side=1&orderType=2&clientOrderId=05d61624&passive=false&price=0.01

import requests

url = "https://mainnet.app.ethgas.com/api/v1/wholeblock/order"

payload = {
    "instrumentId": "ETH-WB-9884031", 
    "accountId": 128,
    "side": 1, 
    "orderType": 2, 
    "clientOrderId": "05d61624",
    "passive": False,
    "price": 0.01
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, json=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "order": {
            "orderId": 204415806,
            "marketId": 2000009884031,
            "instrumentId": "ETH-WB-9884031",
            "side": true,
            "orderType": 2,
            "quantity": "1",
            "fulfilled": "1",
            "price": "0.01",
            "averageTradePrice": "0.01",
            "fees": "0.0001",
            "status": 1,
            "errorCode": null,
            "clientOrderId": "05d61624",
            "preconfQuantity": "3585000",
            "passive": false,
            "createDate": 1697449417659,
            "source": 1,
            "updateDate": 1697449417659
        }
    }
}

Create new whole block order.

Request Body

Parameter	Required	Type	Description
instrumentId	YES	string	Instrument ID
side	YES	boolean	Order Side. Buy = true, Sell = false
orderType	YES	integer	Order Type. Market = 1, Limit = 2, FOK = 3
clientOrderId	YES	string	A client generated random string as orderId
passive	NO	boolean	(Post-only) Whether the order is a maker order only (i.e. can only be lifted, but cannot lift/take any orders from the orderbook itself - in other words, can only add liquidity) If set to false, there are no such restrictions and the order can immediately lift (i.e. take) existing orders in the orderbook if it is crossing the bid/sell price spread
price	NO	string	Price in Ethereum per gas bought. Only applicable to limit, fok order.
quantity	YES	string	Order quantity (1 for whole block orders)

Response Body

Name	Type	Description
order	object	Order object
└ orderId	integer	Unique order ID, assigned by ETHGas
└ marketId	integer	Market ID for this order
└ instrumentId	string	Whole block market instrument ID Use endpoint [GET /api/v1/p/wholeblock/markets] to get a list of all available wholeblock markets' instrument IDs
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ side	boolean	buy order (true) or sell order (false)
└ orderType	integer	Market order (1) or limit order (2) If an order is sent with both a price specified and an orderType of 1, then a maximum slippage order is created
└ quantity	string	Order quantity (1 for whole block orders)
└ fulfilled	string	Quantity that has already been executed
└ price	string	Price of the order The should not be included for a regular market order; however if an order is sent with both a price specified and an orderType of 1, then a maximum slippage order is created
└ averageTradePrice	string	Average price of executed trades
└ fees	string	Fees charged for this order
└ status	integer	Order status - see the Order Status Codes section for more information
└ errorCode	integer	Error code if order failed (null if successful)
└ clientOrderId	string	An arbitrary string with max 32 characters (preferably unique) provided by the client when the order was created
└ passive	boolean	(Post-only) Whether the order is a maker order only (i.e. can only be lifted, but cannot lift/take any orders from the orderbook itself - in other words, can only add liquidity) If set to false, there are no such restrictions and the order can immediately lift (i.e. take) existing orders in the orderbook if it is crossing the bid/sell price spread
└ createDate	integer	Datetime (in UNIX time) when the order was created
└ source	integer	Where the order is originated 1: User interface
└ updateDate	integer	Datetime (in UNIX time) when the order was last updated

POST /api/v1/wholeblock/cancel-all-orders

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/wholeblock/cancel-all-orders?accountId=128&instrumentId=ETH-WB-1012051

import requests

url = "https://mainnet.app.ethgas.com/api/v1/wholeblock/cancel-all-orders"


payload = {
    "accountId": 128,
    "instrumentId": "ETH-WB-1012051"
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=params, json=payload)

print(response.text)

Example response:

{
    "success": false,
    "errorCode": 1002,
    "errorMsgKey": "error.order.doneOrCancelled",
    "data": {}
}

{
    "success": true,
    "data": {}
}

Cancel all whole block orders for a given user account ID for an instrument Id.

Request

Parameter	Required	Type	Description
accountId	YES	integer	Account ID
instrumentId	YES	string	Instrument ID

Response Body

Name	Type	Description

POST /api/v1/wholeblock/cancel-batch-orders

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/wholeblock/cancel-all-orders?accountId=128&instrumentId=ETH-WB-1012051&orderIds=b25ab4023%2c5e885dd

import requests

url = "https://mainnet.app.ethgas.com/api/v1/wholeblock/cancel-batch-oders"


payload = {
    "accountId": 128,
    "instrumentId": "ETH-WB-1012051",
    "orderIds": [
        "b25ab402",
        "5e885ddd"
    ]
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=params, json=payload)

print(response.text)

Example response:

{
    "success": false,
    "errorCode": 1002,
    "errorMsgKey": "error.order.doneOrCancelled",
    "data": {}
}

{
    "success": true,
    "data": {}
}

Cancel whole block orders for a given user account ID, and user order IDs or whole block order IDs.

Request

Parameter	Required	Type	Description
accountId	YES	integer	Account ID
orderIds	YES	List of integer	Order ID
instrumentId	YES	string	Instrument ID

Response Body

Name	Type	Description

POST /api/v1/wholeblock/cancel-order

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/wholeblock/cancel-order?accountId=128&instrumentId=ETH-WB-1012051&orderId=b25ab402

{
    "accountId": 128,
    "instrumentId": "ETH-WB-1012051",
    "orderId": "b25ab402" or "clientOrderId": "64395144"
}

import requests

url = "https://mainnet.app.ethgas.com/api/v1/wholeblock/cancel-order"

payload = {
    "accountId": 128,
    "instrumentId": "ETH-WB-1012051",
    "clientOrderId": "b25ab402" or "orderId" : "64395144"
}

headers = {
   'Content-Type': 'application/json',
   'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": false,
    "errorCode": 1002,
    "errorMsgKey": "error.order.doneOrCancelled",
    "data": {}
}

{
    "success": true,
    "data": {}
}

Cancel whole block order for a given order ID.

Request

Parameter	Required	Type	Description
instrumentId	YES	string	Instrument ID
orderId	YES	integer	Order ID
accountId	YES	integer	Account ID
clientOrderId	YES	string	A client generated random string as orderId

Response Body

Name	Type	Description

GET /api/v1/user/wholeblock/all-orders

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/wholeblock/all-orders?onBook=false&limit=10

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/wholeblock/all-orders"

params = {
  "onBook": False,
  "limit": 10
}

headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "orders": [
            {
                "orderId": 204421028,
                "marketId": 2000009884031,
                "instrumentId": "ETH-WB-9884031",
                "accountId": 128,
                "side": false,
                "orderType": 1,
                "quantity": "1",
                "fulfilled": "1",
                "price": "0.01",
                "averageTradePrice": "0.01",
                "fees": "0.0001",
                "status": 10,
                "errorCode": null,
                "clientOrderId": "y0xja3Xi",
                "passive": false,
                "createDate": 1697449610000,
                "source": 1,
                "updateDate": 1697449609000
            }
        ]
    }
}

Get all user whole block orders for a given user account ID.

Request

Parameter	Required	Type	Description
onBook	NO	boolean	Pending Orders Only? (default: false)
startId	NO	integer	Order Start ID
limit	NO	integer	Maximum Number of Orders To Return (default: 10)
asc	NO	boolean	Sort Order Direction, true=asc, false=desc, Default to true=asc

Response Body

Name	Type	Description
orders	object[]	List of order object
└ orderId	integer	Unique order ID, assigned by ETHGas
└ marketId	integer	Market ID for this order
└ instrumentId	string	Whole block market instrument ID
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ side	boolean	buy order (true) or sell order (false)
└ orderType	integer	Market order (1) or limit order (2)
└ quantity	string	Order quantity (1 for whole block orders)
└ fulfilled	string	Quantity that has already been executed
└ price	string	Price of the order
└ averageTradePrice	string	Average price of executed trades
└ fees	string	Fees charged for this order
└ status	integer	Order status - see the Order Status Codes section for more information
└ errorCode	integer	Error code if order failed (null if successful)
└ clientOrderId	string	An arbitrary string with max 32 characters (preferably unique) provided by the client when the order was created
└ passive	boolean	Whether the order is a maker order only
└ createDate	integer	Datetime (in UNIX time) when the order was created
└ source	integer	Where the order is originated
└ updateDate	integer	Datetime (in UNIX time) when the order was last updated

GET /api/v1/user/wholeblock/orders

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/wholeblock/orders?accountId=128&instrumentId=ETH-WB-9884031

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/wholeblock/orders"

params = {
  "instrumentId": "ETH-WB-9884031"
}

headers = {
   'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "orders": [
            {
                "orderId": 204421028,
                "marketId": 2000009884031,
                "instrumentId": "ETH-WB-9884031",
                "accountId": 128,
                "side": false,
                "orderType": 1,
                "quantity": "1",
                "fulfilled": "1",
                "price": "0.01",
                "averageTradePrice": "0.01",
                "fees": "0.0001",
                "status": 10,
                "errorCode": null,
                "clientOrderId": "y0xja3Xi",
                "passive": false,
                "createDate": 1697449610000,
                "source": 1,
                "updateDate": 1697449609000
            }
        ]
    }
}

Get user whole block orders for a given account ID (and instrument ID).

Request

Parameter	Required	Type	Description
instrumentId	NO	string	Instrument ID
accountId	YES	integer	Account ID
onbook	NO	boolean	Pending Orders Only?
done	NO	boolean	Done Orders Only?
startId	NO	integer	Order Start ID
limit	NO	integer	Maximum Number of Orders To Return

Response Body

Name	Type	Description
orders	object[]	List of order object
└ orderId	integer	Unique order ID, assigned by ETHGas
└ marketId	integer	Market ID for this order
└ instrumentId	string	Whole block market instrument ID Use endpoint [GET /api/v1/wholeblock/markets] to get a list of all available wholeblock markets' instrument IDs
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ side	boolean	buy order (true) or sell order (false)
└ orderType	integer	Market order (1) or limit order (2) If an order is sent with both a price specified and an orderType of 1, then a maximum slippage order is created
└ quantity	string	Order quantity (1 for whole block orders)
└ fulfilled	string	Quantity that has already been executed
└ price	string	Price of the order
└ averageTradePrice	string	Average price of executed trades
└ fees	string	Fees charged for this order
└ status	integer	Order status - see the Order Status Codes section for more information
└ errorCode	integer	Error code if order failed (null if successful)
└ clientOrderId	string	An arbitrary string with max 32 characters (preferably unique) provided by the client when the order was created
└ passive	boolean	(Post-only) Whether the order is a maker order only (i.e. can only be lifted, but cannot lift/take any orders from the orderbook itself - in other words, can only add liquidity) If set to false, there are no such restrictions and the order can immediately lift (i.e. take) existing orders in the orderbook if it is crossing the bid/sell price spread
└ createDate	integer	Datetime (in UNIX time) when the order was created
└ source	integer	Where the order is originated 1: User interface 5: TWAP
└ updateDate	integer	Datetime (in UNIX time) when the order was last updated
└ trades	object[]	List of executed trades for this order
└ side	boolean	Order side - buy (true) or sell (false)
└ rate	string	Price executed
└ quantity	string	Quantity executed
└ date	integer	Datetime (in UNIX time) executed

GET /api/v1/user/wholeblock/positions

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/wholeblock/positions?instrumentId=ETH-WB-9884031&limit=10

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/wholeblock/positions"

params = {
  "instrumentId": "ETH-WB-9884031",
  "limit": 10
}

headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "positions": [
            {
                "positionId": 204421028,
                "instrumentId": "ETH-WB-9884031",
                "accountId": 128,
                "side": false,
                "orderType": 1,
                "quantity": "1",
                "fulfilled": "1",
                "status": 10,
                "clientOrderId": "y0xja3Xi",
                "passive": false,
                "orderDate": 1697449610000,
                "source": 1,
                "updateDate": 1697449609000,
                "averageTradePrice": "0.047",
                "trades": [
                    {
                        "side": false,
                        "price": "0.047",
                        "quantity": "1",
                        "date": 1697449609000
                    }
                ],
            }
        ]
    }
}

Get user wholeblock positions for a given account ID (and instrument ID).

Request

Parameter	Required	Type	Description
instrumentId	NO	string	Instrument ID
accountId	YES	integer	Account ID
startId	NO	integer	Slot start Id
asc	NO	boolean	Sort direction, true = ascending, false = descending, default to false
limit	NO	integer	Maximum Number of Positions To Return

Response Body

Name	Type	Description
positions	object[]	List of position object
└ positionId	integer	Unique position ID, assigned by ETHGas
└ instrumentId	string	Whole block market instrument ID Use endpoint [GET /api/v1/wholeblock/markets] to get a list of all available wholeblock markets' instrument IDs
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ quantity	string	Order quantity
└ status	integer	Order status - see the Order Status Codes section for more information
└ passive	boolean	(Post-only) Whether the order is a maker order only (i.e. can only be lifted, but cannot lift/take any orders from the orderbook itself - in other words, can only add liquidity) If set to false, there are no such restrictions and the order can immediately lift (i.e. take) existing orders in the orderbook if it is crossing the bid/sell price spread
└ createDate	integer	Datetime (in UNIX time) when the position was updated
└ source	integer	Where the order is originated 1: User interface 5: TWAP
└ updateDate	integer	Datetime (in UNIX time) something last occurred to the order
└ trades	object[]	List of executed trades for this order
└ side	boolean	Order side - buy (true) or sell (false)
└ rate	string	Price executed
└ quantity	string	Quantity executed
└ date	integer	Datetime (in UNIX time) executed

GET /api/v1/user/wholeblock/txs

Get the user transactions for wholeblock market

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/wholeblock/txs?instrumentId=ETH-WB-63999&limit=100

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/wholeblock/txs"

params = {
  "instrumentId": "ETH-WB-63999",
  "limit": 10
}

headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}


response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "txs": [
            {   "buyerAccountId": 14,
                "sellerAccountId": 2049,
                "instrumentId": "ETH-WB-63999",
                "trxId": 11675386,
                "side": false,
                "price": "0.00000002",
                "quantity": "1",
                "preconfQuantity": "320000000",
                "date": 1730269305359
            },
            {   "buyerAccountId": 2015,
                "sellerAccountId": 14,
                "instrumentId": "ETH-WB-63999",
                "trxId": 11675385,
                "side": true,
                "price": "0.00000002",
                "quantity": "1",
                "preconfQuantity": "350000000",
                "date": 1730269208878
            }
        ]
    }
}

Request

Parameter	Required	Type	Description
instrumentId	YES	string	Whole block market instrument ID Use endpoint [GET /api/v1/p/wholeblock/markets] to get a list of all available wholeblock markets' instrument IDs
limit	NO	integer	Maximum number of transactions to return

Response Body

Name	Type	Description
txs	object[]	List of trades
└ instrumentId	string	Whole block market instrument ID Use endpoint GET /api/v1/p/wholeblock/markets to get a list of all available whole block markets' instrument IDs
└ trxId	integer	Transaction Id
└ buyerAccountId	integer	Buyer Account Id
└ sellerAccountId	integer	Seller Account Id
└ side	integer	Order Side. Buy = 1, Sell = 0
└ price	string	Latest traded market price for this market
└ quantity	integer	Quantity always = 1
└ preconfQuantity	integer	Preconf quantity sold with the whole block
└ date	integer	Datetime (in UNIX time) when the market orderbook was last updated

Inclusion Preconf Trading

POST /api/v1/inclusion-preconf/cancel-all-orders

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/inclusion-preconf/cancel-all-orders?accountId=128&instrumentId=ETH-PC-1012051

import requests

url = "https://mainnet.app.ethgas.com/api/v1/inclusion-preconf/cancel-all-oders"


payload = {
    "accountId": 128,
    "instrumentId": "ETH-PC-1012051"
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=params, json=payload)

print(response.text)

Example response:

{
    "success": false,
    "errorCode": 1002,
    "errorMsgKey": "error.order.doneOrCancelled",
    "data": {}
}

{
    "success": true,
    "data": {}
}

Cancel all inclusion preconf orders for a given user account ID for an instrument Id.

Request

Parameter	Required	Type	Description
accountId	YES	integer	Account ID
instrumentId	YES	string	Instrument ID

Response Body

Name	Type	Description
accountId	YES	integer
orderId	YES	integer
code	YES	integer

POST /api/v1/inclusion-preconf/cancel-batch-orders

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/inclusion-preconf/cancel-batch-oders?accountId=128&instrumentId=ETH-PC-1012051&orderIds=b25ab4023%2c5e885ddd

import requests

url = "https://mainnet.app.ethgas.com/api/v1/inclusion-preconf/cancel-batch-oders"


payload = {
    "accountId": 128,
    "instrumentId": "ETH-PC-1012051",
    "orderIds": [
        "b25ab402",
        "5e885ddd"
    ]
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=params, json=payload)

print(response.text)

Example response:

{
    "success": false,
    "errorCode": 1002,
    "errorMsgKey": "error.order.doneOrCancelled",
    "data": {}
}

{
    "success": true,
    "data": {}
}

Cancel preconfs orders for a given user account ID, and user order IDs or preconfs order IDs.

Request

Parameter	Required	Type	Description
accountId	YES	integer	account ID
orderIds	YES	List of integer	Order ID
instrumentId	YES	string	Instrument ID

Response Body

Name	Type	Description
accountId	YES	integer
orderId	YES	integer
code	YES	integer

POST /api/v1/inclusion-preconf/cancel-order

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/inclusion-preconf/cancel-order?accountId=128&instrumentId=ETH-PC-1012051&orderId=b25ab402

import requests

url = "https://mainnet.app.ethgas.com/api/v1/inclusion-preconf/cancel-order"

payload = {
    "accountId": 128,
    "instrumentId": "ETH-PC-1012051",
    "orderId": "b25ab402" or "clientOrderId" : "64395144"
}

headers = {
   'Content-Type': 'application/json',
   'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": false,
    "errorCode": 1002,
    "errorMsgKey": "error.order.doneOrCancelled",
    "data": {}
}

{
    "success": true,
    "data": {}
}

Cancel preconfs order for a given order ID.

Request

Parameter	Required	Type	Description
instrumentId	YES	string	Instrument ID
orderId	YES	integer	Order ID
accountId	YES	integer	Account ID
clientOrderId	YES	string	A client generated random string as orderId

Response Body

Name	Type	Description
accountId	YES	integer
orderId	YES	integer
code	YES	integer

POST /api/v1/inclusion-preconf/order

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/inclusion-preconf/order&instrumentId=ETH-PC-9884031&accountId=128&side=1&orderType=2&clientOrderId=05d61624&passive=false&price=0.01&quantity=10000

{
    "instrumentId": 15173,
    "accountId": 128,
    "side": 1,
    "orderType": 2,
    "quantity": 10000,
    "clientOrderId": "05d61624",
    "passive": false,
    "price": 0.01
}

import requests

url = "https://mainnet.app.ethgas.com/api/v1/inclusion-preconf/order"

payload = {
    "instrumentId": "ETH-PC-9884031", 
    "accountId": 128,
    "side": 1, 
    "orderType": 2, 
    "quantity": 10000,
    "clientOrderId": "05d61624",
    "passive": False,
    "price": 0.01
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, json=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "order": {
            "orderId": 204415806,
            "instrumentId": "ETH-PC-9884031",
            "accountId": 128,
            "side": true,
            "orderType": 2,
            "quantity": "10000",
            "fulfilled": "5000",
            "price": "0.01",
            "status": 1,
            "clientOrderId": "05d61624",
            "passive": false,
            "orderDate": 1697449417659,
            "source": 1 
        }
    }
}

Create new preconfs order.

Request

Parameter	Required	Type	Description
instrumentId	NO	string	Instrument ID
accountId	YES	integer	Account ID
side	NO	integer	Order Side. Buy = 1, Sell = 0
orderType	YES	integer	Order Type. Market = 1, Limit = 2, FOK = 3
clientOrderId	YES	string	A client generated random string as orderId
└ passive	boolean	(Post-only) Whether the order is a maker order only (i.e. can only be lifted, but cannot lift/take any orders from the orderbook itself - in other words, can only add liquidity) If set to false, there are no such restrictions and the order can immediately lift (i.e. take) existing orders in the orderbook if it is crossing the bid/sell price spread
price	NO	double	Order price. Only applicable to limit, fok order.
quantity	YES	integer	Quantity to buy or sell

Response Body

Name	Type	Description
order	object	Order object
└ orderId	integer	Unique order ID, assigned by ETHGas
└ instrumentId	string	Inclusion Preconf market instrument ID Use endpoint [GET /api/v1/p/inclusion-preconf/markets] to get a list of all available inclusion preconf markets' instrument IDs
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ side	boolean	buy order (true) or sell order (false)
└ orderType	integer	Market order (1) or limit order (2) If an order is sent with both a price specified and an orderType of 1, then a maximum slippage order is created
└ quantity	string	Order quantity
└ fulfilled	string	Whether the order has already been executed
└ price	string	Price of the preconfirmation The should not be included for a regular market order; however if an order is sent with both a price specified and an orderType of 1, then a maximum slippage order is created
└ status	integer	Order status - see the Order Status Codes section for more information
└ clientOrderId	string	An arbitrary string with max 32 characters (preferably unique) provided by the client when the order was created
└ passive	boolean	(Post-only) Whether the order is a maker order only (i.e. can only be lifted, but cannot lift/take any orders from the orderbook itself - in other words, can only add liquidity) If set to false, there are no such restrictions and the order can immediately lift (i.e. take) existing orders in the orderbook if it is crossing the bid/sell price spread
└ orderDate	integer	Datetime (in UNIX time) when the order was placed
└ source	integer	Where the order is originated 1: User interface

GET /api/v1/user/inclusion-preconf/orders

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/inclusion-preconf/orders?accountId=128&instrumentId=ETH-PC-9884031

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/inclusion-preconf/orders"

params = {
  "accountId": 128,
  "instrumentId": "ETH-PC-9884031"
}

headers = {
   'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "orders": [
            {
                "orderId": 204421028,
                "marketId": 1000009884031,
                "accountId": 128,
                "instrumentId": "ETH-PC-9884031",
                "side": false,
                "orderType": 1,
                "quantity": "994.66",
                "fulfilled": "994.66",
                "price": 0.00000000535,
                "fees": "0",
                "status": 10,
                "clientOrderId": "y0xja3Xi",
                "passive": false,
                "orderDate": 1697449610000,
                "source": 1,
                "updateDate": 1697449609000
            },
            {
                "orderId": 204421029,
                "marketId": 1000009884031,
                "accountId": 126,
                "instrumentId": "ETH-PC-9884031",
                "side": false,
                "orderType": 1,
                "quantity": "20000",
                "fulfilled": "20000",
                "price": 0.00000000535,
                "fees": "0.0000000000013",
                "status": 10,
                "clientOrderId": "abdc2werf",
                "passive": false,
                "orderDate": 1697449630000,
                "source": 1,
                "updateDate": 1697449659000
            }
        ]
    }
}

Get user preconfs orders for a given account ID (and instrument ID).

Request

Parameter	Required	Type	Description
instrumentId	NO	string	Instrument ID
accountId	YES	integer	Account ID
onbook	NO	boolean	Pending Orders Only?
done	NO	boolean	Done Orders Only?
asc	NO	boolean	Sort direction, true = ascending, false = descending, default to false
limit	NO	integer	Maximum Number of Orders To Return

Response Body

Name	Type	Description
orders	object[]	List of order object
└ orderId	integer	Unique order ID, assigned by ETHGas
└ marketId	integer	ETHGas marketId
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ instrumentId	string	Inclusion Preconf market instrument ID Use endpoint [GET /api/v1/inclusion-preconf/markets] to get a list of all available inclusion preconf markets' instrument IDs
└ side	boolean	buy order (true) or sell order (false)
└ orderType	integer	Market order (1) or limit order (2) If an order is sent with both a price specified and an orderType of 1, then a maximum slippage order is created
└ quantity	string	Order quantity
└ fulfilled	string	Quantity executed

└ status|integer|Order status - see the Order Status Codes section for more information └ clientOrderId|string|An arbitrary string with max 32 characters (preferably unique) provided by the client when the order was created └ passive|boolean| (Post-only) Whether the order is a maker order only (i.e. can only be lifted, but cannot lift/take any orders from the orderbook itself - in other words, can only add liquidity)

If set to false, there are no such restrictions and the order can immediately lift (i.e. take) existing orders in the orderbook if it is crossing the bid/sell price spread └ orderDate|integer|Datetime (in UNIX time) when the order was placed └ source|integer|Where the order is originated

1: User interface
5: TWAP └ updateDate |integer| Datetime (in UNIX time) something last occurred to the order

GET /api/v1/user/inclusion-preconf/all-orders

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/inclusion-preconf/all-orders?limit=10

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/inclusion-preconf/all-orders"

params = {
    "limit": 10
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "orders": [
            {
                "orderId": 123456789,
                "clientOrderId": "order123",
                "instrumentId": "ETH-PC-475423",
                "side": true,
                "orderType": 1,
                "quantity": "1000",
                "price": "0.0000000125",
                "status": "ACTIVE"
            }
        ],
        "hasNextPage": true
    }
}

Get all user preconf orders for a given user account ID.

Request

Parameter	Required	Type	Description
onBook	NO	Boolean	Pending orders only (default: false)
startId	NO	Long	Order start ID
limit	NO	Integer	Maximum number of orders to return (default: 10)
asc	NO	Boolean	Sort order direction, true=asc, false=desc (default: true)

Response Body

Name	Type	Description
orders	object[]	List of orders
└ orderId	long	System order ID
└ clientOrderId	string	Client order ID
└ instrumentId	string	Instrument ID
└ side	boolean	Order side (true = buy, false = sell)
└ orderType	integer	Order type
└ quantity	string	Order quantity
└ price	string	Order price
└ status	string	Order status
hasNextPage	boolean	Whether there are more orders available

GET /api/v1/user/inclusion-preconf/positions

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/inclusion-preconf/positions?instrumentId=ETH-PC-9884031&limit=10

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/inclusion-preconf/positions"

params = {
  "instrumentId": "ETH-PC-9884031",
  "limit": 10
}

headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}


response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "positions": [
            {
                "positionId": 204421028,
                "instrumentId": "ETH-PC-9884031",
                "accountId": 128,
                "side": false,
                "orderType": 1,
                "quantity": "994.66",
                "fulfilled": "994.66",
                "status": 10,
                "clientOrderId": "y0xja3Xi",
                "passive": false,
                "orderDate": 1697449610000,
                "source": 1,
                "updateDate": 1697449609000,
                "averageTradePrice": "0.047",
                "trades": [
                    {
                        "side": false,
                        "price": "0.047",
                        "quantity": "994.66",
                        "date": 1697449609000
                    }
                ],
            },
            {
                "positionId": 204421027,
                "instrumentId": "ETH-PC-9884031",
                "accountId": 128,
                "side": true,
                "orderType": 1,
                "quantity": "922.58",
                "fulfilled": "922.58",
                "status": 10,
                "clientOrderId": "f5onoOtR",
                "passive": false,
                "orderDate": 1697449610000,
                "source": 1,
                "updateDate": 1697449609000,
                "averageTradePrice": "0.0338",
                "trades": [
                    {
                        "side": true,
                        "price": "0.0338",
                        "quantity": "922.58",
                        "date": 1697449609000
                    }
                ]
            }
        ]
    }
}

Get user preconfs positions for a given account ID (and instrument ID).

Request

Parameter	Required	Type	Description
instrumentId	NO	string	Instrument ID
accountId	YES	integer	Account ID
startId	NO	integer	Slot start Id
asc	NO	boolean	Sort direction, true = ascending, false = descending, default to false
limit	NO	integer	Maximum Number of Positions To Return

Response Body

Name	Type	Description
positions	object[]	List of position object
└ positionId	integer	Unique position ID, assigned by ETHGas
└ instrumentId	string	Inclusion Preconf market instrument ID Use endpoint [GET /api/v1/inclusion-preconf/markets] to get a list of all available inclusion preconf markets' instrument IDs
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ quantity	string	Order quantity
└ status	integer	Order status - see the Order Status Codes section for more information
└ passive	boolean	(Post-only) Whether the order is a maker order only (i.e. can only be lifted, but cannot lift/take any orders from the orderbook itself - in other words, can only add liquidity) If set to false, there are no such restrictions and the order can immediately lift (i.e. take) existing orders in the orderbook if it is crossing the bid/sell price spread
└ createDate	integer	Datetime (in UNIX time) when the position was updated
└ source	integer	Where the order is originated 1: User interface 5: TWAP
└ updateDate	integer	Datetime (in UNIX time) something last occurred to the order

GET /api/v1/user/inclusion-preconf/txs

Get the user transactions for inclusion preconfs

Code sample:

curl  -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/inclusion-preconf/txs?instrumentId=ETH-PC-9884031&limit=100

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/inclusion-preconf/txs"

params = {
  "instrumentId": "ETH-PC-9884031",
  "limit": 100
}
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "txs": [
            {   "buyerAccountId": 14,
                "sellerAccountId": 2049,
                "instrumentId": "ETH-WB-63999",
                "trxId": 11675386,
                "side": false,
                "price": "0.00000002",
                "quantity": "0",
                "date": 1730269305359
            },
            {   "buyerAccountId": 14,
                "sellerAccountId": 2015,
                "instrumentId": "ETH-WB-63999",
                "trxId": 11675385,
                "side": false,
                "price": "0.00000002",
                "quantity": "0",
                "date": 1730269208878
            },
            {
                "buyerAccountId": 20,
                "sellerAccountId": 14,
                "instrumentId": "ETH-WB-63999",
                "trxId": 11675384,
                "side": false,
                "price": "0.00000002",
                "quantity": "0",
                "date": 1730269152774
            },
            {   "buyerAccountId": 2079,
                "sellerAccountId": 14,
                "instrumentId": "ETH-WB-63999",
                "trxId": 11675383,
                "side": false,
                "price": "0.00000002",
                "quantity": "0",
                "date": 1730269084507
            }
        ]
    }
}

Request

Parameter	Required	Type	Description
instrumentId	YES	string	Preconf Market instrument ID Use endpoint [GET /api/v1/p/inclusion-preconf/markets] to get a list of all available inclusion preconf markets' instrument IDs
limit	NO	integer	number of transactions returned

Response Body

Name	Type	Description
txs	object[]	List of trades
└ instrumentId	string	Preconf Market instrument ID Use endpoint [GET /api/v1/p/inclusion-preconf/markets] to get a list of all available inclusion preconf markets' instrument IDs
└ trxId	integer	Transaction Id
└ buyerAccountId	integer	Buyer Account Id
└ sellerAccountId	integer	Seller Account Id
└ side	integer	Order Side. Buy = 1, Sell = 0
└ price	string	Latest traded market price for this market
└ quantity	integer	Quantity always = 1
└ date	intger	Datetime (in UNIX time) when the market orderbook was last updated

POST /api/v1/user/inclusion-preconf/market/update

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/inclusion-preconf/market/update?instrumentId=ETH-PC-475423&reservedQty=1000

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/inclusion-preconf/market/update"

payload = {
    'instrumentId': 'ETH-PC-475423',
    'reservedQty': 1000
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {}
}

Block owner reserve Inclusion Preconfs.

Request

Parameter	Required	Type	Description
instrumentId	YES	String	Instrument ID
reservedQty	YES	Integer	Reserved quantity

Response Body

Name	Type	Description
success	boolean	Operation success status

Bundle Submission

POST /api/v1/user/bundle/send

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/bundle/send?slot=114713&replacementUuid=01ab2371-84d6-459e-95e7-5edad485f282&txs=[{tx=0x02f885827a6901843b9aca0084773594008252089412643b525cc34282ba84298d32bf2d094448f1c4019945746847617320496e636c7573696f6e20507265636f6e6673c001a0156d9b84193af432f32aef3976417dfca1f0d71f8e015ba8b3d68a11fe388a5ea059eefd7c77489551dfb04a887493617b83a4b78923b7592a992f0ed5c57d520a&canRevert=true},
           {tx=0x02f885827a6901843b9aca0084773594008252089412643b525cc34282ba84298d32bf2d094448f1c4019945746847617320496e636c7573696f6e20507265636f6e6673c001a0156d9b84193af432f32aef3976417dfca1f0d71f8e015ba8b3d68a11fe388a5ea059eefd7c77489551dfb04a887493617b83a4b78923b7592a992f0ed5c57d520a&canRevert=false}]

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/bundle/send"

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

payload = {
    slot: 114713,
    replacementUuid: '01ab2371-84d6-459e-95e7-5edad485f282',
    txs: [{tx: '0x02f885827a6901843b9aca0084773594008252089412643b525cc34282ba84298d32bf2d094448f1c4019945746847617320496e636c7573696f6e20507265636f6e6673c001a0156d9b84193af432f32aef3976417dfca1f0d71f8e015ba8b3d68a11fe388a5ea059eefd7c77489551dfb04a887493617b83a4b78923b7592a992f0ed5c57d520a', canRevert: true},
           {tx: '0x02f885827a6901843b9aca0084773594008252089412643b525cc34282ba84298d32bf2d094448f1c4019945746847617320496e636c7573696f6e20507265636f6e6673c001a0156d9b84193af432f32aef3976417dfca1f0d71f8e015ba8b3d68a11fe388a5ea059eefd7c77489551dfb04a887493617b83a4b78923b7592a992f0ed5c57d520a', 
           ordering: 1,
           canRevert: false}
        ]
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, json=payload)

print(response.text)

Example response:

{ 
    "success": true, 
    "data": {}
}

{
  "success": false,
  "errorCode": 1001,
  "errorMsgKey": 'error.account.insufficientFund',
  "data": {}
}

Send the transaction bundle for a specific slot

Request

Parameter	Required	Type	Description
slotNumber	YES	integer	Slot number of the block
replacementUuid	YES	string	replacementUuid
txs	YES	transactionRequest[]	List of Transaction Requests
└ tx	YES	string	Signed Transaction
└ canRevert	YES	boolean	revertable: true, non-revertable : false
└ ordering	NO	integer	top of the block: 1, bottom of the block : -1

Response Body

Name	Type	Description
success	boolean	Whether API call is successful or not
errorCode	integer	Error Code (if any)
errorMsgKey	string	Error Message
data	object	Response body (usually empty)

Slot Bundles

GET /api/v1/slot/bundles

Retrieve bundles for a given slot.

Request

Parameter	Required	Type	Description
`slot`	YES	integer	Slot ID to retrieve bundles.

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/slot/bundles?slot=123

import requests

url = "https://mainnet.app.ethgas.com/api/v1/slot/bundles"

params = {
    'slot': 123
}

headers = {
    'Authorization': 'Bearer <your-auth-token>'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Response Body

Field	Type	Description
`slot`	integer	Slot ID of the retrieved bundles.
`emptySpace`	integer	Empty preconf reserved by preconf owner.
`isSold`	boolean	The block or preconf has been sold or not.
`builders`	list	List of builder address for that slot.
`isOfac`	boolean	Whether the slot has OFAC (Office of Foreign Assets Control) restrictions.
`feeRecipient`	string	Address of the priority fee receipient (only present when market is expired).
`bundles`	array	List of bundles associated with the slot.
└ replacementUuid	string	Unique identifier for the bundle
└ bidPrice	number	Average bid price for the bundle
└ bundleType	integer	Type of the bundle (optional)
└ ordering	integer	Ordering of the bundle (optional, only present for owner bundles)
└ txs	list	List of transactions
└ tx	string	Signed Transaction (hex encoded)
└ txHash	string	Transaction hash (hex encoded)
└ canRevert	boolean	revertable: true, non-revertable : false

Example response:

{
    "slot": 123,
    "emptySpace": 0,
    "isSold": true,
    "builders": [
        "0x313233313331330000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "0xa1885d66bef164889a2e35845c3b626545d7b0e513efe335e97c3a45e534013fa3bc38c3b7e6143695aecc4872ac52c4"
    ],
    "isOfac": false,
    "feeRecipient": "0xasdfadflj2lwejf...",
    "bundles": [
            {
                "txs": [
                    {
                        "tx": "0x02f86b0180843b9aca00852ecc889a0082520894c87037874aed04e51c29f582394217a0a2b89d808080c080a0a463985c616dd8ee17d7ef9112af4e6e06a27b071525b42182fe7b0b5c8b4925a00af5ca177ffef2ff28449292505d41be578bebb77110dfc09361d2fb56998260",
                        "txHash": "0x87037874aed04e51c29f582394217a0a2b89d808080c080a0a463985c616dd8ee17d7ef9112af4e6e06a27b071525b42182fe7b0b5c8b4925a00af5ca177ffef2ff28449292505d41be578bebb77110dfc09361d2fb56998260",
                        "canRevert": false
                    },
                    {
                        "tx": "0x02f86b0180843b9aca00852ecc889a0082520894c87037874aed04e51c29f582394217a0a2b89d808080c080a0a463985c616dd8ee17d7ef9112af4e6e06a27b071525b42182fe7b0b5c8b4925a00af5ca177ffef2ff28449292505d41be578bebb77110dfc09361d2fb56998260",
                        "txHash": "0x87037874aed04e51c29f582394217a0a2b89d808080c080a0a463985c616dd8ee17d7ef9112af4e6e06a27b071525b42182fe7b0b5c8b4925a00af5ca177ffef2ff28449292505d41be578bebb77110dfc09361d2fb56998260",
                        "canRevert": false
                    }
                ],
                "replacementUuid": "ab592371-84d6-459e-95e7-5edad485f282",
                "bidPrice": 1.2635975E-8
            },
            {
                "txs": [
                    {
                        "tx": "0x02f86b0180843b9aca00852ecc889a0082520894c87037874aed04e51c29f582394217a0a2b89d808080c080a0a463985c616dd8ee17d7ef9112af4e6e06a27b071525b42182fe7b0b5c8b4925a00af5ca177ffef2ff28449292505d41be578bebb77110dfc09361d2fb56998260",
                        "canRevert": false,
                        "createDate": 1730366973413
                    }
                ],
                "replacementUuid": "45727106-d37e-4194-93bc-8650bc135c53fg",
                "bidPrice": 1.0E-11,
            },
            {
                "txs": [
                    {
                        "tx": "0x02f86b0180843b9aca00852ecc889a0082520894c87037874aed04e51c29f582394217a0a2b89d808080c080a0a463985c616dd8ee17d7ef9112af4e6e06a27b071525b42182fe7b0b5c8b4925a00af5ca177ffef2ff28449292505d41be578bebb77110dfc09361d2fb56998260",
                        "canRevert": false,
                        "createDate": 1730366973440
                    }
                ],
                "replacementUuid": "19780112-d37e-4194-93bc-8650bc135c53",
                "bidPrice": 1.0E-11,
                "ordering": 2
            }
        ]
}

GET /api/v1/slot/account/bundles

Retrieve the bundles submitted for a given slot for your inclusion preconf account.

Request

Parameter	Required	Type	Description
`slot`	YES	integer	Slot ID to retrieve bundles.

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/slot/account/bundles?slot=123

import requests

url = "https://mainnet.app.ethgas.com/api/v1/slot/account/bundles"

params = {
    'slot': 123
}

headers = {
    'Authorization': 'Bearer <your-auth-token>'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Response Body

Field	Type	Description
`slot`	integer	Slot ID of the retrieved bundles.
`bundles`	array	List of bundles associated with the slot.
└ replacementUuid	string	Unique identifier for the bundle
└ bidPrice	number	Bid price for the bundle
└ bundleType	integer	Type of the bundle (optional)
└ ordering	integer	Ordering of the bundle (optional, only present for owner bundles)
└ txs	list	List of transactions
└ tx	string	Signed Transaction (hex encoded)
└ txHash	string	Transaction hash (hex encoded)
└ canRevert	boolean	revertable: true, non-revertable : false

Example response:

{
    "slot": 123,
    "bundles": [
            {
                "txs": [
                    {
                        "tx": "0x02f86b0180843b9aca00852ecc889a0082520894c87037874aed04e51c29f582394217a0a2b89d808080c080a0a463985c616dd8ee17d7ef9112af4e6e06a27b071525b42182fe7b0b5c8b4925a00af5ca177ffef2ff28449292505d41be578bebb77110dfc09361d2fb56998260",
                        "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
                        "canRevert": false
                    },
                    {
                        "tx": "0x02f86b0180843b9aca00852ecc889a0082520894c87037874aed04e51c29f582394217a0a2b89d808080c080a0a463985c616dd8ee17d7ef9112af4e6e06a27b071525b42182fe7b0b5c8b4925a00af5ca177ffef2ff28449292505d41be578bebb77110dfc09361d2fb56998260",
                        "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
                        "canRevert": false
                    }
                ],
                "replacementUuid": "ab592371-84d6-459e-95e7-5edad485f282",
                "bidPrice": 1.2635975E-8
            },
            {
                "txs": [
                    {
                        "tx": "0x02f86b0180843b9aca00852ecc889a0082520894c87037874aed04e51c29f582394217a0a2b89d808080c080a0a463985c616dd8ee17d7ef9112af4e6e06a27b071525b42182fe7b0b5c8b4925a00af5ca177ffef2ff28449292505d41be578bebb77110dfc09361d2fb56998260",
                        "txHash": "0xfedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321",
                        "canRevert": false
                    }
                ],
                "replacementUuid": "45727106-d37e-4194-93bc-8650bc135c53fg",
                "bidPrice": 1.0E-11
            },
            {
                "txs": [
                    {
                        "tx": "0x02f86b0180843b9aca00852ecc889a0082520894c87037874aed04e51c29f582394217a0a2b89d808080c080a0a463985c616dd8ee17d7ef9112af4e6e06a27b071525b42182fe7b0b5c8b4925a00af5ca177ffef2ff28449292505d41be578bebb77110dfc09361d2fb56998260",
                        "txHash": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
                        "canRevert": false
                    }
                ],
                "replacementUuid": "19780112-d37e-4194-93bc-8650bc135c53",
                "bidPrice": 1.0E-11,
                "ordering": 1
            }
        ]
}

GET /api/v1/slot/forceEmptyBlockSpace

Preconf owner set unused inclusion preconf gas to be empty for a given slot. It should be set after the inclusion preconf is being bought.

Request

Parameter	Required	Type	Description
`slot`	YES	integer	Slot ID to retrieve the transaction hash.
`enable`	YES	boolean	True to force empty gas space in the slot

Code Sample

GET /api/v1/p/slot/forceEmptyBlockSpace?slot=123&enable=true

import requests

url = "https://mainnet.app.ethgas.com/api/v1/slot/forceEmptyBlockSpace

params = {
    'slot': 123,
    'enable': true
}

response = requests.get(url, params=params)

print(response.text)

Response Body

Field	Type	Description
`success`	boolean	Indicates request status.

Example response:

{
    "success": true,
    "data": { "success": false }
}

Builder

POST /api/v1/builder/register

Request

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.
`ofac`	NO	boolean	OFAC flag for the builders (default: false)

Code Sample

POST /api/v1/builder/register?publicKeys=0x12345...,0x234134...&signatures=2asdfjghadg,xghlktdhj&ofac=false HTTP/1.1
Host: mainnet.app.ethgas.com
Authorization: Bearer <your-auth-token>
Content-Type: application/json

import requests

url = "https://mainnet.app.ethgas.com/api/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)

Example response:

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

Response Fields

Field	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

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

Note: Please refer to look up table to check the builder registration result enum

GET /api/v1/builder/signingMessage

Get the required signing message which will be used to sign the BLS signature by using builder's BLS key.

Request

Parameter	Required	Type	Description
N/A	N/A	N/A	No parameters required.

Code Sample

GET /api/v1/builder/signingMessage HTTP/1.1
Host: mainnet.app.ethgas.com
Authorization: Bearer <your-auth-token>
Content-Type: application/json

import requests

url = "https://mainnet.app.ethgas.com/api/v1/builder/signingMessage"

headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

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

Response Fields

Field	Type	Description
`message`	object	Signing message.
└`eoaAddress`	string	EOA address of current user

POST /api/v1/builder/deregister

Builder deregistering their public keys from Ethgas

Request

Parameter	Required	Type	Description
`publicKeys`	YES	string	Comma separated list of builder bls public keys in hex.

Code Sample

POST /api/v1/builder/deregister?publicKeys=0x12342330def...,0x4a93d70def... HTTP/1.1
Host: mainnet.app.ethgas.com
Authorization: Bearer <your-auth-token>
Content-Type: application/json

import requests

url = "https://mainnet.app.ethgas.com/api/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)

Example response:

{
    "success": true
}

Response Fields

Field	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 /api/v1/p/builders

Retrieve a list of builders and fallback builder key.

Request

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

Code Sample

GET /api/v1/p/builders HTTP/1.1
Host: mainnet.app.ethgas.com
Content-Type: application/json

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/builders"

headers = {
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

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

Response Fields

Field	Type	Description
`builders`	object	List of builder objects.
└ whitelistedBuilders	object	List of whitelisted builders which can be accessed by builder name.
└ unnamedBuilders	List	List of public key of unnamed builder in hex.
└ fallbackBuilder	string	Public key of the ETHGAS fallback builder in hex.

GET /api/v1/user/builder

Retrieve a list of builder public keys submitted by a user

Request

Parameter	Required	Type	Description
N/A	N/A	N/A	No parameters required.

Code Sample

GET /api/v1/user/builder HTTP/1.1
Host: mainnet.app.ethgas.com
Authorization: Bearer <your-auth-token>
Content-Type: application/json

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/builder"

headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

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

Response Fields

Field	Type	Description
`builders`	string[]	List of builder bls keys.

POST /api/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).

Request

Parameter	Required	Type	Description
`publicKeys`	No	string	A list of comma separated bls builder public keys in hex.
`builderName`	No	string	Builder name.
`enable`	Yes	boolean	Delegate or revoke builder delegation.

Code Sample

POST /api/v1/user/delegate/builder?publicKeys=0x12345...,0x2df345...&enable=true HTTP/1.1
Host: mainnet.app.ethgas.com
Authorization: Bearer <your-auth-token>
Content-Type: application/json

import requests

url = "https://mainnet.app.ethgas.com/api/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)

Example response:

{
    "success": true
}

Response Fields

Field	Type	Description
`success`	bool	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 /api/v1/builder/update/ofac

Update OFAC flag for existing builder

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 (default: false)

Code Sample

POST /api/v1/builder/update/ofac?publicKeys=0x12345...,0x2df345...&ofac=true HTTP/1.1
Host: mainnet.app.ethgas.com
Authorization: Bearer <your-auth-token>
Content-Type: application/json

import requests

url = "https://mainnet.app.ethgas.com/api/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)

Example response:

{
    "success": true
}

Response Fields

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

GET /api/v1/user/delegate/builder

Get list of delegated builder keys for the current user.

Request

Parameter	Required	Type	Description
N/A	N/A	N/A	No parameters required.

Code Sample

GET /api/v1/user/delegate/builder HTTP/1.1
Host: mainnet.app.ethgas.com
Authorization: Bearer <your-auth-token>
Content-Type: application/json

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/delegate/builder"

headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

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

Response Fields

Field	Type	Description
`delegatedBuilders`	string[]	List of delegated builder keys

GET /api/v1/p/builder/{slot}

Retrieve a list of builders by slot ID.

Request

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

Code Sample

GET /api/v1/p/builder/123 HTTP/1.1
Host: mainnet.app.ethgas.com
Content-Type: application/json

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/builder/123"

headers = {
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

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

Response Fields

Field	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 /api/v1/builder/delegation

To retrieve a list of user address of those who have delegated to current users' builder keys.

Request

Parameter	Required	Type	Description
N/A	N/A	N/A	No parameters required.

Code Sample

GET /api/v1/builder/delegation HTTP/1.1
Host: mainnet.app.ethgas.com
Authorization: Bearer <your-auth-token>
Content-Type: application/json

import requests

url = "https://mainnet.app.ethgas.com/api/v1/builder/delegation"

headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

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

Response Fields

Field	Type	Description
`builderDelegation`	object	Mapping of builder delegations from corresponding builder key registered by the user
└	string	Corresponding builder key registered by the user
└└	string[]	EOA address who delegated to the builder key

POST /api/v1/builder/bundle/reject/{slot}

Reject bundles for a specific slot

Request

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

Request Body: json { "rejections": [ { "uuid": "bundle-uuid-1", "rejectCode": 1, "txHashList": ["0x123...", "0x456..."], "reason": "Bundle rejection reason" } ] }

Code Sample

POST /api/v1/builder/bundle/reject/123 HTTP/1.1
Host: mainnet.app.ethgas.com
Authorization: Bearer <your-auth-token>
Content-Type: application/json

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

import requests

url = "https://mainnet.app.ethgas.com/api/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)

Example response:

{
    "success": true
}

Response Fields

Field	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 /api/v1/p/builder/bundle/reject/{slot}/{builderAccountId}

Get bundle rejection information for a specific slot and account

Request

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

Code Sample

GET /api/v1/p/builder/bundle/reject/123/456 HTTP/1.1
Host: mainnet.app.ethgas.com
Content-Type: application/json

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/builder/bundle/reject/123/456"

headers = {
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

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

Response Fields

Field	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)

Pricer

POST /api/v1/user/delegate/pricer

Enable or disable the pricer for selling preconf or block.

Request

Parameter	Required	Type	Description
`enable`	YES	boolean	Enable (`true`) or disable (`false`) pricer.

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/delegate/pricer?enable=true

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/delegate/pricer"

payload = {
    'enable': True
}

headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true
}

Response Body

Field	Type	Description
`success`	bool	Indicates whether the request succeeded.

GET /api/v1/user/pricer

Retrieve the pricer's current setting.

Request

Parameter	Required	Type	Description
N/A	N/A	N/A	No parameters are required.

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/pricer

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/pricer"

headers = {
    'Authorization': 'Bearer <your-auth-token>'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "dedicatedPricer": "enabled"
}

Response Body

Field	Type	Description
`delegatedPricer`	string	Indicates whether the pricer is `"enabled"` or `"disabled"`.

GET /api/v1/pricer/account-tokens

Retrieve all account tokens delegated to the pricer.

Request

Parameter	Required	Type	Description
N/A	N/A	N/A	No parameters are required.

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/pricer/account-tokens

import requests

url = "https://mainnet.app.ethgas.com/api/v1/pricer/account-tokens"

headers = {
    'Authorization': 'Bearer <your-auth-token>'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "accountTokens": [
        {
            "tokenId": 1,
            "quantity": "10000",
            "lockedQuantity": "0",
            "code": "ETH",
            "availableQuantity": "10000"
        },
        {
            "tokenId": 2,
            "quantity": "100",
            "lockedQuantity": "0",
            "code": "BTC",
            "availableQuantity": "100"
        }
    ]
}

Response Body

Field	Type	Description
`accountTokens`	object	List of account tokens.
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ tokenId	integer	ETHGas Token ID See Token IDs section for list of Token IDs
└ quantity	string	Amount of token in account in USD
└ lockedQuantity	string	Amount of token in account in USD which is covering pending limit orders (and so cannot be transfered out of account)
└ code	string	Token code See Token IDs section for list of token codes
└ availableQuantity	string	Amount of unlocked tokens in account

GET /api/v1/pricer/inclusion-preconf/orders

Retrieve inclusion preconf orders delegated to the pricer.

Request

Parameter	Required	Type	Description
`accountId`	NO	integer	Account ID for filtering orders.
`instrumentId`	NO	string	Instrument ID for filtering orders.
`pending`	NO	boolean	Whether to include only open orders.
`done`	NO	boolean	Whether to include only completed orders.
`startId`	NO	long	Order start ID for pagination.
`limit`	NO	integer	Maximum number of orders to return.
`asc`	NO	boolean	Sorting order (`true` for asc, `false` for desc).

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/pricer/inclusion-preconf/orders?accountId=123&instrumentId=abc&pending=true&limit=20

import requests

url = "https://mainnet.app.ethgas.com/api/v1/pricer/inclusion-preconf/orders"

params = {
    'accountId': 123,
    'instrumentId': 'abc',
    'pending': True,
    'limit': 20
}

headers = {
    'Authorization': 'Bearer <your-auth-token>'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "orders": [
        {"id": "1", "status": "pending"},
        {"id": "2", "status": "done"}
    ]
}

Response Body

Field	Type	Description
`orders`	object	List of orders.

GET /api/v1/pricer/inclusion-preconf/positions

Retrieve inclusion preconf positions delegated to the pricer.

Request

Parameter	Required	Type	Description
`instrumentId`	NO	string	Instrument ID for filtering positions.
`accountId`	NO	integer	Account ID for filtering positions.

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/pricer/inclusion-preconf/positions?instrumentId=123&accountId=456

import requests

url = "https://mainnet.app.ethgas.com/api/v1/pricer/inclusion-preconf/positions"

params = {
    'instrumentId': '123',
    'accountId': 456
}

headers = {
    'Authorization': 'Bearer <your-auth-token>'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "positions": [
        {"id": "1", "type": "preconf"},
        {"id": "2", "type": "preconf"}
    ]
}

Response Body

Field	Type	Description
`positions`	object	List of positions.

GET /api/v1/pricer/wholeblock/orders

Retrieve whole block orders delegated to the pricer.

Request

Parameter	Required	Type	Description
`accountId`	NO	integer	Account ID for filtering orders.
`instrumentId`	NO	string	Instrument ID for filtering orders.
`pending`	NO	boolean	Whether to include only open orders.
`done`	NO	boolean	Whether to include only completed orders.
`startId`	NO	long	Order start ID for pagination.
`limit`	NO	integer	Maximum number of orders to return.
`asc`	NO	boolean	Sorting order (`true` for asc, `false` for desc).

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/pricer/wholeblock/orders?accountId=123&instrumentId=abc&pending=true&limit=20

import requests

url = "https://mainnet.app.ethgas.com/api/v1/pricer/wholeblock/orders"

params = {
    'accountId': 123,
    'instrumentId': 'abc',
    'pending': True,
    'limit': 20
}

headers = {
    'Authorization': 'Bearer <your-auth-token>'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "orders": [
        {"id": "1", "status": "pending"},
        {"id": "2", "status": "done"}
    ]
}

Response Body

Field	Type	Description
`orders`	object	List of orders.

GET /api/v1/pricer/wholeblock/positions

Retrieve wholeblock positions delegated to the pricer.

Request

Parameter	Required	Type	Description
`instrumentId`	NO	string	Instrument ID for filtering positions.
`accountId`	NO	integer	Account ID for filtering positions.

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/pricer/wholeblock/positions?instrumentId=123&accountId=456

import requests

url = "https://mainnet.app.ethgas.com/api/v1/pricer/wholeblock/positions"

params = {
    'instrumentId': '123',
    'accountId': 456
}

headers = {
    'Authorization': 'Bearer <your-auth-token>'
}

response = requests.get(url, headers=headers, params=params)

print(response.text)

Example response:

{
    "positions": [
        {"id": "1", "type": "wholeblock"},
        {"id": "2", "type": "wholeblock"}
    ]
}

Response Body

Field	Type	Description
`positions`	object	List of positions.

GET /api/v1/pricer/markets/active

Retrieve all active markets that the pricer is responsible for.

Request

Parameter	Required	Type	Description
N/A	N/A	N/A	No parameters are required.

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/pricer/markets/active

import requests

url = "https://mainnet.app.ethgas.com/api/v1/pricer/markets/active"

headers = {
    'Authorization': 'Bearer <your-auth-token>'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "inclusionPreconfMarkets": [
        {
            "marketId": "ETH-USD",
            "status": "active"
        }
    ],
    "wholeBlockMarkets": [
        {
            "marketId": "BTC-USD",
            "status": "active"
        }
    ]
}

Response Body

Field	Type	Description
`inclusionPreconfMarkets`	object	List of active inclusion preconf markets.
`wholeBlockMarkets`	object	List of active whole block markets.

Validator

GET /api/v1/user/validators

Code sample:

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

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/validators"

headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "validators": [
            "0x123125221515xxx",
            "0xsdfx25221515xxx"
        ]
    }
}

Get list of user validators.

Request

No parameters for this endpoint.

Response Body

Name	Type	Description
validators	array of string	List of validator public keys in hexadecimal format (48 bytes each)

GET /api/v1/p/validators

Code sample:

curl -X GET /api/v1/p/validators

import requests

url = "https://mainnet.app.ethgas.com/api/v1/p/validators"

response = requests.get(url, headers=headers)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "validators": [
            {
                "publicKey": "0x123125221515abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
                "collateralPerSlot": "2.5"
            },
            {
                "publicKey": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
                "collateralPerSlot": "1.0"
            }
        ]
    }
}

Get list of all validators.

Request

No parameters for this endpoint.

Response Body

Name	Type	Description
validators	array of object	List of validator objects
└ publicKey	string	Public key of the validator in hexadecimal (48 bytes)
└ collateralPerSlot	string	Collateral amount per slot (read-only field)

POST /api/v1/validator/register

Validator registering their public key into Ethgas

Request

Parameter	Required	Type	Description
`publicKey`	YES	byte	Public key of the validator in hexadecimal.

Code Sample

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

import requests

url = "https://mainnet.app.ethgas.com/api/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)

Example response:

{
    "available": true,
    "verified": false,
    "message": {
         "address": "0x1234567890abcdef1234567890abcdef12345678..."
    }
}

Response Body

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

POST /api/v1/validator/verify

Verify validator public key by verifying with the signed message

Request

Parameter	Required	Type	Description
`publicKey`	YES	string	Public key of the validator in hexadecimal.
`signature`	YES	string	Signature in hexadecimal.

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/validator/verify?publicKey=0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef&signature=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

import requests

url = "https://mainnet.app.ethgas.com/api/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)

Example response:

{
    "result": 0,
    "description": "Success"
}

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 /api/v1/validator/settings

Update validator's collater per block settings

Request

Parameter	Required	Type	Description
`collateralPerSlot`	YES	double	The amount of Eth reserved as collateral per each block sold. Value between 0 to 1000 Eth

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/validator/settings?collateralPerSlot=1.0"

import requests

url = "https://mainnet.app.ethgas.com/api/v1/validator/settings"

params = {
    'collateralPerSlot': '1.0'
}

headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
}

Response Body

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

POST /api/v1/validator/deregister

Validator deregistering their public key from Ethgas

Request

Parameter	Required	Type	Description
`publicKeys`	YES	byte	Comma separated public keys of the validator in hexadecimal.

Code Sample

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/validator/deregister?publicKey=0x123423abcdef1234567890abcdef1234567890,0x3459871234567890abcdef1234567890abcdef1234567890...

import requests

url = "https://mainnet.app.ethgas.com/api/v1/validator/deregister"


payload = {
    'publicKey': '0x123423abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef,0x2345876124567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
}

headers = {
    'Authorization': 'Bearer <your-auth-token>',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
}

Response Body

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

GET /api/v1/validator/fees

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

Code samples

curl -X GET "https://mainnet.app.ethgas.com/api/v1/validator/fees?publicKey=0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" \
     -H "Authorization: Bearer <token>"

import requests

url = "https://mainnet.app.ethgas.com/api/v1/validator/fees"

headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}
params = {"publicKey": 0x1234…}

response = requests.post(url, params=params, headers=headers)

print(response.json())

Example response:

{
    "success": true,
      "data": {
        "fees": [
            {
                "slot" :,
                "accountId" :,
                "publicKey" : "0x1234...",
                "feeRecipient" : "0x46720581234a63db...",
                "quantity" : 0.00023,
                "updatedDate" : 1672903708000
            }
        ]
      }

}

Get list of validator fees.

Request

Response Body

Name	Type	Description
fees	arrary of object	List of validator fee objects
└ slot	integer	Slot number of the block
└ accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
└ publicKey	string	Public key of the validator in hexadecimal.
└ feeRecipient	string	Address of the fee recipient in hexadecimal.
└ quantity	string	Amount of payout in Eth
└ updateDate	integer	Last updated timestamp

GET /api/v1/validator/onchain/payout

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

Code samples

curl -X POST "https://mainnet.app.ethgas.com/api/v1/validator/onchain/payout?enable=0" \
     -H "Authorization: Bearer <token>"

import requests

url = "https://mainnet.app.ethgas.com/api/v1/validator/onchain/payout"
headers = {
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

params = {"enable": 0}

response = requests.post(url, params=params, headers=headers)
print(response.json())

Example response:

{
    "success": true
}

Enable or disable on-chain fee payout for user’s validators.

Request

Name | Type | Description enable | 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

SSV Validator

POST /api/v1/user/ssv/operator/register

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/ssv/operator/register?ownerAddress=0x1234567890123456789012345678901234567890

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/ssv/operator/register"

payload = {
    'ownerAddress': '0x1234567890123456789012345678901234567890'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "available": true,
        "messageToSign": "Register SSV operator: 0x1234567890123456789012345678901234567890"
    }
}

Request verification for SSV operator registration.

Request

Parameter	Required	Type	Description
ownerAddress	YES	String	SSV operator owner address (hex format)

Response Body

Name	Type	Description
available	boolean	Whether the operator address is available for registration
messageToSign	string	Message to sign for verification

Error Codes

Code	Description
SSV_OPERATOR_INVALID_ADDRESS	Invalid operator address format

POST /api/v1/user/ssv/operator/deregister

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/ssv/operator/deregister?ownerAddress=0x1234567890123456789012345678901234567890

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/ssv/operator/deregister"

payload = {
    'ownerAddress': '0x1234567890123456789012345678901234567890'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {}
}

Deregister an SSV operator.

Request

Parameter	Required	Type	Description
ownerAddress	YES	String	SSV operator owner address (hex format)

Response Body

Name	Type	Description
success	boolean	Operation success status

Error Codes

Code	Description
SSV_OPERATOR_INVALID_ADDRESS	Invalid operator address format
SSV_OPERATOR_NOT_REGISTERED	Operator is not registered

POST /api/v1/user/ssv/operator/verify

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/ssv/operator/verify?ownerAddress=0x1234567890123456789012345678901234567890&signature=0x1234567890abcdef&autoImport=1&sync=1

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/ssv/operator/verify"

payload = {
    'ownerAddress': '0x1234567890123456789012345678901234567890',
    'signature': '0x1234567890abcdef',
    'autoImport': '1',
    'sync': '1'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response (with sync=1):

{
    "success": true,
    "data": {
        "validators": [
            "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
        ]
    }
}

Example response (with sync=0):

{
    "success": true,
    "data": {}
}

Verify SSV operator signature and complete registration.

Request

Parameter	Required	Type	Description
ownerAddress	YES	String	SSV operator owner address (hex format)
signature	YES	String	Signature of the message to sign (hex format)
autoImport	NO	Boolean	Whether to automatically import validators (default: false)
sync	NO	Boolean	Whether to return validator list in response (default: false)

Response Body

Name	Type	Description
validators	string[]	List of validator public keys (only returned when sync=true)

Error Codes

Code	Description
SSV_OPERATOR_INVALID_ADDRESS	Invalid operator address format
SSV_OPERATOR_INVALID_SIGNATURE	Invalid signature format or verification failed

GET /api/v1/user/ssv/operators

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/ssv/operators

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/ssv/operators"

payload = {}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "ssvOperators": [
            {
                "ownerId": 1,
                "userId": 73,
                "ownerAddress": "0x1234567890123456789012345678901234567890"
            }
        ]
    }
}

List all SSV operators for the current user.

Request

No parameters required.

Response Body

Name	Type	Description
ssvOperators	object[]	List of SSV operator objects
└ ownerId	integer	Unique owner ID
└ userId	integer	User ID associated with the operator
└ ownerAddress	string	Operator owner address (hex format)

POST /api/v1/user/ssv/operator/validator/register

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/ssv/operator/validator/register?ownerAddress=0x1234567890123456789012345678901234567890&publicKeys=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890,0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/ssv/operator/validator/register"

payload = {
    'ownerAddress': '0x1234567890123456789012345678901234567890',
    'publicKeys': '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890,0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "validators": [
            "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
        ]
    }
}

Register validators with an SSV operator. If no publicKeys are provided, it will refresh the validator list from the SSV network.

Request

Parameter	Required	Type	Description
ownerAddress	YES	String	SSV operator owner address (hex format)
publicKeys	NO	String	Comma-separated list of validator public keys (hex format, max 100). If not provided, refreshes validator list from SSV network

Response Body

Name	Type	Description
validators	string[]	List of successfully added validator public keys

Error Codes

Code	Description
SSV_OPERATOR_INVALID_ADDRESS	Invalid operator address format
SSV_OPERATOR_NOT_REGISTERED	Operator is not registered
SSV_VALIDATORS_REQUIRED	At least one validator public key is required
SSV_VALIDATORS_INVALID	Invalid validator public key format
VALIDATORS_MAX	Maximum 100 validators allowed per request

POST /api/v1/user/ssv/operator/validator/deregister

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/ssv/operator/validator/deregister?ownerAddress=0x1234567890123456789012345678901234567890&publicKeys=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/ssv/operator/validator/deregister"

payload = {
    'ownerAddress': '0x1234567890123456789012345678901234567890',
    'publicKeys': '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "removed": [
            "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
        ]
    }
}

Deregister validators from an SSV operator. If no publicKeys are provided, it will remove all validators for the operator.

Request

Parameter	Required	Type	Description
ownerAddress	YES	String	SSV operator owner address (hex format)
publicKeys	NO	String	Comma-separated list of validator public keys (hex format, max 100). If not provided, removes all validators for the operator

Response Body

Name	Type	Description
removed	string[]	List of successfully removed validator public keys

Error Codes

Code	Description
SSV_OPERATOR_INVALID_ADDRESS	Invalid operator address format
SSV_OPERATOR_NOT_REGISTERED	Operator is not registered
SSV_VALIDATORS_REQUIRED	At least one validator public key is required
SSV_VALIDATORS_INVALID	Invalid validator public key format
VALIDATORS_MAX	Maximum 100 validators allowed per request

GET /api/v1/user/ssv/operator/validators

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/ssv/operator/validators?ownerAddress=0x1234567890123456789012345678901234567890

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/ssv/operator/validators"

payload = {
    'ownerAddress': '0x1234567890123456789012345678901234567890'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "validators": [
            "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
        ]
    }
}

List validators for a specific SSV operator.

Request

Parameter	Required	Type	Description
ownerAddress	YES	String	SSV operator owner address (hex format)

Response Body

Name	Type	Description
validators	string[]	List of validator public keys (hex format)

Error Codes

Code	Description
SSV_OPERATOR_INVALID_ADDRESS	Invalid operator address format
SSV_OPERATOR_NOT_REGISTERED	Operator is not registered

POST /api/v1/user/ssv/operator/validator/update/ofac

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/ssv/operator/validator/update/ofac?publicKeys=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890&ofac=true

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/ssv/operator/validator/update/ofac"

payload = {
    'publicKeys': '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890',
    'ofac': 'true'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {}
}

Update OFAC flag for SSV validators.

Request

Parameter	Required	Type	Description
publicKeys	NO	String	Comma-separated list of validator public keys (hex format, max 100). If not provided, updates all validators for the user
ofac	NO	Boolean	OFAC compliance flag (default: false)

Response Body

Name	Type	Description
success	boolean	Operation success status

Error Codes

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

Obol Validator

POST /api/v1/user/obol/operator/register

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/obol/operator/register?operatorAddress=0x1234567890123456789012345678901234567890

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/obol/operator/register"

payload = {
    'operatorAddress': '0x1234567890123456789012345678901234567890'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "available": true,
        "messageToSign": "Register Obol operator: 0x1234567890123456789012345678901234567890"
    }
}

Request verification for Obol operator registration.

Request

Parameter	Required	Type	Description
operatorAddress	YES	String	Obol operator address (hex format)

Response Body

Name	Type	Description
available	boolean	Whether the operator address is available for registration
messageToSign	string	Message to sign for verification

Error Codes

Code	Description
OBOL_OPERATOR_INVALID_ADDRESS	Invalid operator address format

POST /api/v1/user/obol/operator/deregister

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/obol/operator/deregister?operatorAddress=0x1234567890123456789012345678901234567890

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/obol/operator/deregister"

payload = {
    'operatorAddress': '0x1234567890123456789012345678901234567890'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {}
}

Deregister an Obol operator.

Request

Parameter	Required	Type	Description
operatorAddress	YES	String	Obol operator address (hex format)

Response Body

Name	Type	Description
success	boolean	Operation success status

Error Codes

Code	Description
OBOL_OPERATOR_INVALID_ADDRESS	Invalid operator address format

POST /api/v1/user/obol/operator/verify

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/obol/operator/verify?operatorAddress=0x1234567890123456789012345678901234567890&signature=0x1234567890abcdef&autoImport=1

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/obol/operator/verify"

payload = {
    'operatorAddress': '0x1234567890123456789012345678901234567890',
    'signature': '0x1234567890abcdef',
    'autoImport': '1'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "operator": {
            "operatorId": 1,
            "userId": 73,
            "address": "0x1234567890123456789012345678901234567890",
            "ofac": false,
            "accountId": 2170,
            "collateralPerSlot": "10.5",
            "validatorKey": null,
            "clusterId": null
        }
    }
}

Verify Obol operator signature and complete registration.

Request

Parameter	Required	Type	Description
operatorAddress	YES	String	Obol operator address (hex format)
signature	YES	String	Signature of the message to sign (hex format)
autoImport	NO	Boolean	Whether to automatically import cluster definitions (default: false)

Response Body

Name	Type	Description
operator	object	Registered operator object
└ operatorId	integer	Unique operator ID
└ userId	integer	User ID associated with the operator
└ address	string	Operator address (hex format)
└ ofac	boolean	OFAC compliance status
└ accountId	integer	Associated account ID
└ collateralPerSlot	string	Collateral per slot amount
└ validatorKey	string	Validator key (if any)
└ clusterId	integer	Cluster ID (if any)

Error Codes

Code	Description
OBOL_OPERATOR_INVALID_ADDRESS	Invalid operator address format
OBOL_OPERATOR_INVALID_SIGNATURE	Invalid signature format or verification failed

POST /api/v1/user/obol/operator/refresh

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/obol/operator/refresh?operatorAddress=0x1234567890123456789012345678901234567890

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/obol/operator/refresh"

payload = {
    'operatorAddress': '0x1234567890123456789012345678901234567890'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "clusters": {
            "0xabcdef1234567890": {
                "clusterId": 1,
                "config": "0x1234567890abcdef",
                "operators": ["0x1234567890123456789012345678901234567890"],
                "distributedValidatorKeys": ["0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"]
            }
        }
    }
}

Refresh Obol operator cluster definitions.

Request

Parameter	Required	Type	Description
operatorAddress	YES	String	Obol operator address (hex format)

Response Body

Name	Type	Description
clusters	object	Map of cluster definitions
└ [clusterKey]	object	Cluster definition object
└└ clusterId	integer	Unique cluster ID
└└ config	string	Cluster configuration (hex format)
└└ operators	string[]	List of operator addresses
└└ distributedValidatorKeys	string[]	List of distributed validator keys

Error Codes

Code	Description
OBOL_OPERATOR_INVALID_ADDRESS	Invalid operator address format

GET /api/v1/user/obol/operators

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/obol/operators

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/obol/operators"

payload = {}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "operators": [
            {
                "operatorId": 1,
                "userId": 73,
                "address": "0x1234567890123456789012345678901234567890",
                "ofac": false,
                "accountId": 2170,
                "collateralPerSlot": "10.5",
                "validatorKey": null,
                "clusterId": 1
            }
        ]
    }
}

List all Obol operators for the current user.

Request

No parameters required.

Response Body

Name	Type	Description
operators	object[]	List of operator objects
└ operatorId	integer	Unique operator ID
└ userId	integer	User ID associated with the operator
└ address	string	Operator address (hex format)
└ ofac	boolean	OFAC compliance status
└ accountId	integer	Associated account ID
└ collateralPerSlot	string	Collateral per slot amount
└ validatorKey	string	Validator key (if any)
└ clusterId	integer	Cluster ID (if any)

GET /api/v1/user/obol/operator/validators

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X GET /api/v1/user/obol/operator/validators?operatorAddress=0x1234567890123456789012345678901234567890

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/obol/operator/validators"

payload = {
    'operatorAddress': '0x1234567890123456789012345678901234567890'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.get(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "validators": [
            "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
        ]
    }
}

List validators for a specific Obol operator.

Request

Parameter	Required	Type	Description
operatorAddress	YES	String	Obol operator address (hex format)

Response Body

Name	Type	Description
validators	string[]	List of validator public keys (hex format)

Error Codes

Code	Description
OBOL_OPERATOR_INVALID_ADDRESS	Invalid operator address format

POST /api/v1/user/obol/operator/validator/register

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/obol/operator/validator/register?operatorAddress=0x1234567890123456789012345678901234567890&publicKeys=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890,0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/obol/operator/validator/register"

payload = {
    'operatorAddress': '0x1234567890123456789012345678901234567890',
    'publicKeys': '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890,0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "added": [
            "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
        ]
    }
}

Request

Parameter	Required	Type	Description
operatorAddress	YES	String	Obol operator address (hex format)
publicKeys	YES	String	Comma-separated list of validator public keys (hex format, max 100)

Response Body

Name	Type	Description
added	string[]	List of successfully added validator public keys

Error Codes

Code	Description
OBOL_OPERATOR_INVALID_ADDRESS	Invalid operator address format
OBOL_VALIDATORS_REQUIRED	At least one validator public key is required
OBOL_VALIDATORS_INVALID	Invalid validator public key format
VALIDATORS_MAX	Maximum 100 validators allowed per request

POST /api/v1/user/obol/operator/validator/deregister

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/obol/operator/validator/deregister?operatorAddress=0x1234567890123456789012345678901234567890&publicKeys=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/obol/operator/validator/deregister"

payload = {
    'operatorAddress': '0x1234567890123456789012345678901234567890',
    'publicKeys': '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {
        "removed": [
            "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
        ]
    }
}

Deregister validators from an Obol operator.

Request

Parameter	Required	Type	Description
operatorAddress	YES	String	Obol operator address (hex format)
publicKeys	YES	String	Comma-separated list of validator public keys (hex format, max 100)

Response Body

Name	Type	Description
removed	string[]	List of successfully removed validator public keys

Error Codes

Code	Description
OBOL_OPERATOR_INVALID_ADDRESS	Invalid operator address format
OBOL_VALIDATORS_REQUIRED	At least one validator public key is required
OBOL_VALIDATORS_INVALID	Invalid validator public key format
VALIDATORS_MAX	Maximum 100 validators allowed per request

POST /api/v1/user/obol/operator/validator/update/ofac

Code sample:

curl -H "Authorization: Bearer {{access_token}}" -X POST /api/v1/user/obol/operator/validator/update/ofac?publicKeys=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890&ofac=true

import requests

url = "https://mainnet.app.ethgas.com/api/v1/user/obol/operator/validator/update/ofac"

payload = {
    'publicKeys': '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890',
    'ofac': 'true'
}

headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7InVzZXJJZCI6MzEsImFkZHJlc3MiOiIweDVjODEyYzlhNjdlNjkwMGViMjBmM2YzMWQwZWNjZTUyM2Q2YTVjMDMiLCJyb2xlcyI6WyJST0xFX1VTRVIiXX0sImFjY2Vzc190eXBlIjoiYWNjZXNzX3Rva2VuIiwiaWF0IjoxNjk3NDQ5MTM0LCJleHAiOjE2OTc0NTI3MzR9.reUyFbhlJ6ZXSUypWiWeikaPQdbcRB_ZgB2k4NxcKbJS1K9J1GZnfXl9GrYOmS67L19gC-wfKqSPN4-7T3Xk0w'
}

response = requests.post(url, headers=headers, params=payload)

print(response.text)

Example response:

{
    "success": true,
    "data": {}
}

Update OFAC flag for Obol validators.

Request

Parameter	Required	Type	Description
publicKeys	NO	String	Comma-separated list of validator public keys (hex format, max 100). If not provided, updates all validators for the user
ofac	YES	Boolean	OFAC compliance flag

Response Body

Name	Type	Description
success	boolean	Operation success status

Error Codes

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

Data Types

User

Name	Type	Description
userId	integer	Unique ID for the user assigned by ETHGas
address	string	The user's ethereum account address
userType	integer	User type: Currently all users are type 1
userClass	integer	User class: 1: regular 2: VIP
status	integer	User status: All active users have status 1
accounts	Account[]	List of ETHGas current & trading accounts associated with this user

Account

Name	Type	Description
userId	integer	Unique ID for the user assigned by ETHGas
accountId	integer	Unique ID for each of the user's current & trading accounts assigned by ETHGas
type	integer	Account type 1: current account 2: trading account
name	string	Name of the account "Current" "Trading"
cashTokenIds	integer[]	List of tokens currently in this account See Token IDs section for list of Token IDs
status	integer	Account status 0: inactive 1: active
updateDate	integer	Update timestamp

WEBSOCKET

Path

/ws

The websocket channel provides access of streaming data subscriptions and queries on public/private data.

# A sample python script to connect to our webserver to subscribe to different channels.

import json

import websocket
from websocket import WebSocket

__ws_url = "wss://holesky.app.ethgas.com/ws"


def on_open(ws: WebSocket):
    message = {
        "op": "subscribe",
        "args": [
            {
                "channel": "orderBookUpdate",
                "marketType": "wholeBlock"
            }
        ]
    }
    ws.send(json.dumps(message))


def on_message(ws: WebSocket, message: str):
    print(f"Received message: {message}")


def on_error(ws: WebSocket, error: Exception):
    print(f"Error: {error}")


def on_close(ws: WebSocket, close_status_code: int, close_msg: str):
    print("WebSocket closed")


if __name__ == "__main__":
    ws_app = websocket.WebSocketApp(
        __ws_url,
        on_open=on_open,
        on_message=on_message,
        on_close=on_close,
        on_error=on_error,
    )
    ws_app.run_forever()

Message Structure

Request

Field	Required	Type	Description
op	YES	string	operation type
args	YES	object[]	list of operation arguments

Operation Types

subscribe
unsubscribe
query
login

Response

Field	Type	Description
e	string	Event type
E	integer	Event timestamp
s	string	Instrument ID
P	object	Data of corresponding event type

Commands

Subscribe to one or multiple topics

{
    "op": "subscribe",
    "args": [
        {
            "channel": "preconfMarketUpdate",
            "marketType": "inclusionPreconf"
        },
        {
            "channel": "candlestickUpdate",
            "marketType": "wholeBlock"
        },
        {
            "channel": "recentTradeUpdate",
            "marketType": "inclusionPreconf"
        },
        {
            "channel": "orderBookUpdate",
            "marketType": "inclusionPreconf"
        },
        {
            "channel": "tickerUpdate",
            "marketType": "inclusionPreconf"
        },
        {
            "channel": "inclusionPreconfSaleUpdate"
        },
        {
            "channel": "blockBuilderUpdate"
        }
    ]
}

unsubscribe

Unsubscribe from one or multiple topics

{
    "op": "unsubscribe",
    "args": [
        {
            "channel": "preconfMarketUpdate",
            "marketType": "inclusionPreconf"
        },
        {
            "channel": "candlestickUpdate",
            "marketType": "wholeBlock"
        },
        {
            "channel": "recentTradeUpdate",
            "marketType": "inclusionPreconf"
        },
        {
            "channel": "orderBookUpdate",
            "marketType": "inclusionPreconf"
        },
        {
            "channel": "tickerUpdate",
            "marketType": "inclusionPreconf"
        },
        {
            "channel": "inclusionPreconfSaleUpdate"
        },
        {
            "channel": "blockBuilderUpdate"
        }
    ]
}

query

Query data from a topic

Example

{
    "op": "query",
    "args": [
        {
            "queryType": "currentSlot"
        },
        {
            "queryType": "preconfMarketss"
        },
        {
            "queryType": "orderBook"
        }
    ]
}

Example Request

{
    "op": "login",
    "args": [
        {
            "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
        }
    ]
}

Example Response

{
    "event": "login",
    "code": 0,
    "msg": "",
    "connId": "25f9ee2c"
}

Channel

Within a channel, you can subscribe to topics needed to receive real time updates.

Public Channel

Preconf Market Update

Example Request

{
    "op": "subscribe",
    "args": [
        {
            "channel": "preconfMarketUpdate",
            "marketType": "inclusionPreconf"
        }
    ]
}

Example Response

{
    "e": "preconfMarketUpdate",
    "E": 1744684899022,
    "s": "ETH-PC-603410",
    "a": "NewEpoch",
    "P": {
        "m": 1000000603410,
        "T": "inclusionPreconf",
        "s": 603410,
        "i": "ETH-PC-603410",
        "n": "Eth Preconf Inclusion Slot #603410",
        "M": 1744685494000,
        "f": 1744686266000,
        "b": 1744685498000,
        "q": "1",
        "mQ": "1",
        "MQ": "36000000",
        "PS": "0.00000000001",
        "mP": "0.00000000001",
        "MP": "0.00001",
        "C": "3.99996",
        "A": 36000000,
        "r": 0,
        "S": 0,
        "e": 1,
        "a": 1744685496000,
        "c": 1744684899000,
        "u": 1744684899000,
        "tp": 36000000
    }
}

Request

Name	Type	Description
`op`	string	e.g. `subscribe`
`args`	object	Arguments
└ `channel`	string	channel name, e.g. preconfMarketUpdate`
└ `marketType`	string	Market type, e.g., inclusionPreconf`.

Response Body

Name	Type	Description
`e`	string	Event type, e.g.`preconfMarketUpdate`
`E`	integer	Event time in milliseconds.
`s`	string	Instrument ID of the market, e.g. `ETH-PC-42093`.
`a`	string	Action type, e.g. `NewEpoch`
`P`	object	Payload data containing market details.
└ `m`	integer	Market ID.
└ `T`	string	Market type, e.g. `inclusionPreconf`
└ `s`	integer	Slot ID.
└ `i`	string	Instrument ID.
└ `n`	string	Market name, e.g. `Eth Preconf Inclusion Slot #42093`.
└ `M`	integer	Market expiry time in milliseconds.
└ `a`	integer	Bundle submission deadline in milliseconds. (Optional)
└ `f`	integer	Block finality time in milliseconds.
└ `b`	integer	Block time in milliseconds.
└ `mQ`	string	Minimum order quantity allowed in the market. (Optional)
└ `MQ`	string	Maximum order quantity allowed in the market. (Optional)
└ `q`	string	Precision step of order quantity. (Optional)
└ `PS`	string	Precision step of order price.
└ `mP`	string	Minimum price allowed in the market.
└ `MP`	string	Maximum price allowed in the market.
└ `p`	string	Last traded price of the market
└ `PC`	float	Price change percentage.
└ `d`	boolean	Market direction.
└ `BB`	string	Best bid price.
└ `BA`	string	Best ask price.
└ `o`	string	Open price.
└ `C`	string	Collateral per slot in ETH.
└ `A`	integer	Available preconf for sale.
└ `r`	integer	Block owner reserved preconf not for sale.
└ `S`	integer	Block owner submitted preconf not for sale.
└ `e`	integer	Market status.
└ `c`	integer	Market Creation time in milliseconds.
└ `u`	integer	Last market update time in milliseconds.
└ `tp`	integer	Total amount of preconf allowed to sell in the market

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Precision Values: Prices and quantities are represented with high precision for accurate calculations.
Market Status: The e field indicates whether the market is open or expired.

Candlestick Update

Example Request

{
    "op": "subscribe",
    "args": [
        {
            "channel": "candlestickUpdate",
            "marketType": "inclusionPreconf"
        }
    ]
}

Example Response

{
    "e": "candlestickUpdate",
    "E": 1736742241012,
    "s": "ETH-PC-117",
    "P": {
        "I": "ETH-PC-117",
        "m": 1000000000117,
        "t": 1736742240000,
        "i": 1000,
        "o": "0",
        "h": "0",
        "l": "0",
        "c": "0",
        "v": "0",
        "F": true
    }
}

Request

Name	Type	Description
`op`	string	e.g. `subscribe`
`args`	object	Arguments
└ `channel`	string	Channel name, e.g., candlestickUpdate`.
└ `marketType`	string	Market type, e.g., inclusionPreconf`.

Response Body

Name	Type	Description
`e`	string	Event type, e.g. `candlestickUpdate`.
`E`	integer	Event timestamp in milliseconds.
`s`	string	Instrument ID of the market, e.g., ETH-PC-117`.
`P`	object	Payload data containing market price history details.
└ `I`	string	Instrument ID, e.g., ETH-PC-117`.
└ `m`	integer	Market ID.
└ `t`	integer	Timestamp of the price data in milliseconds.
└ `i`	integer	Interval of the candlestick in milliseconds.
└ `o`	string	Open price during the interval.
└ `h`	string	High price during the interval.
└ `l`	string	Low price during the interval.
└ `c`	string	Close price during the interval.
└ `v`	string	Volume during the interval.
└ `F`	boolean	Indicates if the data is final (`true`) or incomplete (`false`).

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Precision Values: Prices and volumes are represented with high precision for accurate calculations.
Finalized Data: The F field indicates whether the price history data is finalized or still being updated.

Recent Trades Update

Example Request

{
    "op": "subscribe",
    "args": [
        {
            "channel": "recentTradeUpdate",
            "marketType": "inclusionPreconf"
        }
    ]
}

Example Response

{
    "e": "recentTradeUpdate",
    "E": 1739528277074,
    "s": "ETH-PC-173649",
    "P": {
        "i": "ETH-PC-173649",
        "p": "0.00000000006",
        "q": "1702005",
        "s": true,
        "d": 1739528277070,
        "t": 683198
    }
}

Request

Name	Type	Description
`op`	string	e.g. `subscribe`
`args`	object	Arguments
└ `channel`	string	Channel name, e.g., `recentTradeUpdate`
└ `marketType`	string	Market type, e.g., `inclusionPreconf`.

Response Body

Name	Type	Description
`e`	string	Event type, e.g., `recentTradeUpdate`.
`E`	integer	Event timestamp in milliseconds.
`s`	string	Instrument ID.
`P`	object	Payload data containing recent trades details.
└ `i`	string	Instrument ID .
└ `p`	string	Traded price of the trade
└ `q`	string	Traded quantity of the trade
└ `s`	integer	Trading side of taker
└ `d`	integer	Timestamp of the trade in milliseconds.
└ `t`	integer	Trade index.

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Trades Index: The t field shows current index of the trade. It is independent in each websocket connection.

Order Book Update

Example Request

{
    "op": "subscribe",
    "args": [
        {
            "channel": "orderBookUpdate",
            "marketType": "inclusionPreconf"
        }
    ]
}

Example Response

{
    "e": "orderBookUpdate",
    "E": 1736751224943,
    "s": "ETH-PC-863",
    "P": {
        "a": [],
        "b": [
            {
                "p": "0.00000000005",
                "q": "5861476"
            }
        ],
        "I": "ETH-PC-863",
        "t": 1736751224941
    }
}

Request

Name	Type	Description
`op`	string	e.g. `subscribe`
`args`	object	Arguments
└ `channel`	string	Channel name, e.g., `orderBookUpdate`.
└ `marketType`	string	Market type, e.g., `inclusionPreconf`.

Response Body

Name	Type	Description
`e`	string	Event type, e.g., `orderBookUpdate`.
`E`	integer	Event timestamp in milliseconds.
`s`	string	Instrument ID of the market, e.g., `ETH-PC-863`.
`P`	object	Payload data containing order book details.
└ `a`	array	List of ask orders (empty in the example).
└ `b`	array	List of bid orders.
└└ `p`	string	Price of the bid order.
└└ `q`	string	Quantity of the bid order.
└ `I`	string	Instrument ID, e.g., `ETH-PC-863`.
└ `t`	integer	Timestamp of the order book update in milliseconds.

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Order Details: The a field contains ask orders, and the b field contains bid orders, each with a price (p) and quantity (q).
Instrument ID: The I field represents the specific market instrument being updated.

Ticker Update

Example Request

{
    "op": "subscribe",
    "args": [
        {
            "channel": "tickerUpdate",
            "marketType": "inclusionPreconf"
        }
    ]
}

Example Response

{
    "e": "tickerUpdate",
    "E": 1743667424734,
    "s": "ETH-PC-518598",
    "P": {
        "d": false,
        "p": "0.00000000002",
        "b": "0.00000000002",
        "M": "0.00000000002",
        "A": 18855242,
        "g": 17144758,
        "P": 1.0,
        "u": 1743667299000
    }
}

Request

Name	Type	Description
`op`	string	e.g. `subscribe`
`args`	object	Arguments
└ `channel`	string	Channel name, e.g., `tickerUpdate`.
└ `marketType`	string	Market type, e.g., `inclusionPreconf`.

Response Body

Name	Type	Description
`e`	string	Event type, e.g., `tickerUpdate`.
`E`	integer	Event timestamp in milliseconds.
`s`	string	Instrument ID of the market, e.g., `ETH-PC-856`.
`P`	object	Payload data containing market information.
└ `d`	boolean	Market direction (`true` for buy, `false` for sell).
└ `p`	string	Last traded price.
└ `b`	string	Best bid price.
└ `a`	string	Best ask price.
└ `M`	string	Mid price in orderbook.
└ `A`	string	Available preconf gas amount in the slot.
└ `g`	string	Total gas purchased in the market. (optional)
└ `P`	string	Percentage price change in the market.
└ `u`	integer	Timestamp of the last update in milliseconds.

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Price Details: Includes last trade price (p), best bid (b), ask (a) prices, and mid (M) prices.

Inclusion Preconf Top Sales

Example Request

{
    "op": "subscribe",
    "args": [
        {
            "channel": "inclusionPreconfSaleUpdate"
        }
    ]
}

Example Response

{
    "e": "inclusionPreconfSaleUpdate",
    "E": 1739765044256,
    "P": {
        "s": 193373,
        "g": "11288799",
        "S": [
            {
                "p": "0.0000000001",
                "q": "11078799"
            }
        ]
    }
}

Request

Name	Type	Description
`op`	string	e.g. `subscribe`
`args`	object	Arguments
└ `channel`	string	Channel name, e.g., `inclusionPreconfSaleUpdate`.

Response Body

Name	Type	Description
`e`	string	Event type, e.g., `inclusionPreconfSaleUpdate`.
`E`	integer	Event timestamp in milliseconds.
`P`	object	Payload data containing block builder update details.
└ `s`	integer	slot
└ `g`	string	gas purchased
└ `S`	array	array of top 10 preconf sales
└└ `p`	string	purchased gas price
└└ `q`	string	gas unit

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Slot ID: The s field represents the current slot being updated.

Block Builder Update

Example Request

{
    "op": "subscribe",
    "args": [
        {
            "channel": "blockBuilderUpdate"
        }
    ]
}

Example Response

{
    "e": "blockBuilderUpdate",
    "E": 1739527942002,
    "a": "MarketExpiry",
    "P": {
        "s": 173614,
        "p": "0x00000000000000000000000000000000caf14edec47d16536506af7a6d69eac6b1a66a042205f7ca768655a481038ae5",
        "f": "0xa1885d66bef164889a2e35845c3b626545d7b0e513efe335e97c3a45e534013fa3bc38c3b7e6143695aecc4872ac52c4"
    }
}

Request

Name	Type	Description
`op`	string	e.g. `subscribe`
`args`	object	Arguments
└ `channel`	string	Channel name, e.g., `blockBuilderUpdate`.

Response Body

Name	Type	Description
`e`	string	Event type, e.g., `blockBuilderUpdate`
`E`	integer	Event timestamp in milliseconds.
`a`	integer	Action type. e.g. `MarketExpiry`
`P`	object	Payload data containing block builder update details.
└ `s`	integer	slot ID.
└ `p`	string	Builder public key of corresponding slot
└ `f`	string	Fallback builder public key

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Slot ID: The s field represents the current slot being updated.

Private Channel

Account Order Update

Example Request

{
    "op": "subscribe",
    "args": [
        {
             "channel": "accountOrderUpdate",
             "marketType": "inclusionPreconf",
             "pricerOnly": false
        }
    ]
}

Example Response

{
    "e": "accountOrderUpdate",
    "E": 1742288403296,
    "s": "ETH-PC-403684",
    "P": {
        "o": 173639360,
        "c": "613ec528",
        "a": 2049,
        "C": 53,
        "t": 2,
        "i": "ETH-PC-403684",
        "m": 1000000403684,
        "p": "0.00000000001",
        "q": "3181683",
        "F": "3181683",
        "fp": "0.00003181683",
        "f": "0.0000028635147",
        "s": false,
        "P": false,
        "S": 10,
        "d": 1742288403289,
        "u": 1742288403289
    }
}

Request

Name	Type	Description
`op`	string	e.g. `subscribe`
`args`	object	Arguments
└ `channel`	string	Channel name, e.g., `accountOrderUpdate`.
└ `marketType`	string	Market type, e.g., `inclusionPreconf`.
└ `pricerOnly`	boolean	Flag for only displaying pricer information. Optional. Default to `false`.

Response Body

Name	Type	Description
`e`	string	Event type, e.g., `accountOrderUpdate`
`E`	integer	Event timestamp in milliseconds.
`P`	array	Array of order objects.
└ `o`	integer	Order ID, e.g., `1234`.
└ `c`	string	Client Order ID, e.g., `43f4159e`.
└ `a`	integer	Account ID.
└ `C`	integer	User ID who created this order. For pricer only.
└ `t`	boolean	Order Type.
└ `i`	string	Instrument ID.
└ `m`	integer	Market Id.
└ `p`	string	Order price.
└ `q`	string	Order total quantity.
└ `F`	string	Order filled quantity .
└ `fp`	string	Order filled price * quantity.
└ `f`	fee	Order fee.
└ `s`	boolean	Order side.
└ `P`	boolean	Flag for post-only order.
└ `S`	integer	Order Status.
└ `d`	integer	Timestamp of order creation time.
└ `u`	integer	Timestamp of last update time.

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.

Account Transaction Update

Example Request

{
    "op": "subscribe",
    "args": [
        {
            "channel": "accountTransactionUpdate",
            "marketType": "inclusionPreconf"
        }
    ]
}

Example Response

{
    "e": "accountTransactionUpdate",
    "E": 1742288580882,
    "s": "ETH-PC-403699",
    "P": {
        "t": 146600149,
        "i": "ETH-PC-403699",
        "o": 173651088,
        "a": 2049,
        "s": true,
        "p": "0.00000000001",
        "q": "1248972",
        "f": "0.0000011240748",
        "d": 1742288580863
    }
}

Request

Name	Type	Description
`op`	string	e.g. `subscribe`
`args`	object	Arguments
└ `channel`	string	Channel name, e.g., `accountTransactionUpdate`.
└ `marketType`	string	Market type, e.g., `inclusionPreconf`.

Response Body

Name	Type	Description
`e`	string	Event type, e.g., `accountTransactionUpdate`
`E`	integer	Event timestamp in milliseconds.
`P`	object	Payload data containing block builder update details.
`s`	string	Instrument ID, e.g., `ETH-PC-403699`.
└ `t`	integer	Transaction ID, e.g., `123456`.
└ `i`	string	Instrument ID, e.g., `ETH-PC-403699`.
└ `o`	integer	Order ID of the trade executed, e.g., `123456`.
└ `a`	integer	Account ID of the trade executed, e.g., `123`.
└ `s`	boolean	Traded Side, e.g., `true`.
└ `p`	string	Traded price, e.g., `0.00000000001`.
└ `q`	string	Traded quantity, e.g., `1248972`.
└ `f`	string	Trading fee, e.g., `0.0000011240748`.
└ `d`	timestamp	Timestamp of the trade execution, e.g., `1742288580863`.

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.

Account Position Update

Example Request

{
    "op": "subscribe",
    "args": [
        {
            "channel": "accountPositionUpdate",
            "marketType": "inclusionPreconf",
            "pricerOnly": true
        }
    ]
}

Example Response

{
    "e": "accountPositionUpdate",
    "E": 1742288402217,
    "P": {
        "a": 2049,
        "s": 403684,
        "m": 1,
        "q": "20427356",
        "l": "0",
        "p": "0",
        "e": false,
        "b": false,
        "c": 1742288355000,
        "u": 1742288402000,
        "A": "20427356"
    }
}

Request

Name	Type	Description
`op`	string	e.g. `subscribe`
`args`	object	Arguments
└ `channel`	string	Channel name, e.g., `accountPositionUpdate`.
└ `marketType`	string	Market type, e.g., `inclusionPreconf`.
└ `pricerOnly`	boolean	Flag for only displaying pricer information. Optional. Default to `false`.

Response Body

Name	Type	Description
`e`	string	Event type, e.g., `accountPositionUpdate`
`E`	integer	Event timestamp in milliseconds.
`P`	object	Payload data containing account position update details.
└ `a`	integer	Account Id.
└ `s`	integer	Slot number of the position.
└ `m`	integer	Market type of the position.
└ `q`	string	Position's total quantity.
└ `l`	string	Position's locked quantity
└ `p`	string	Position purchased price.
└ `e`	boolean	Expired flag.
└ `b`	integer	Builder fill enable flag.
└ `c`	integer	Position create timestamp.
└ `u`	integer	Position last updated timestamp.
└ `A`	integer	Position's available quantity.

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.

Preconf Bundle Update

Example Request

{
    "op": "subscribe",
    "args": [
        {
            "channel": "preconfBundleUpdate"
        }
    ]
}

Example Response

{
    "e": "preconfBundleUpdate",
    "E": 1743674748083,
    "P": {
        "s": 519181,
        "e": 1260000,
        "bu": [
            {
                "u": "456a8e9d-ce47-421d-8135-9ed9680ab57e",
                "B": 1,
                "o": 1,
                "txs": [
                    {
                        "r": false,
                        "tx": "0x02f88b827e7e8302bcff8084773594008303345094f37512b7c630890c500b02724671cf3ae5607563843b9aca009b45746847617320496e636c7573696f6e20507265636f6e66732e20c001a007797cf3e30a7d45ef43ab9b76d309b76db5f3704cb4936890245b374bad5925a00ad6fa6556dd1448beaf39fc6c5faa097eaf615144905f7d60fb72b15ded30e4",
                        "h": "0x653304b826eca4f48510d29e8ac2a9fcad6ecf3ef3bc3ca3a837718f3d6fa368"
                    },
                    {
                        "r": false,
                        "tx": "0x02f88b827e7e8302bd008084773594008303345094f37512b7c630890c500b02724671cf3ae5607563843b9aca009b45746847617320496e636c7573696f6e20507265636f6e66732e20c080a03b1a7ca0651410d37aedef11740e4e902a9bcb106bcb3bb1f98f18d9ed2bda25a02fabfa492e172ac244cb809d0d035c75ed4b04e5f7e92258781e7cd55daabef9",
                        "h": "0x3076010ac7607ae41a9dacb14b55bba5a91ca4aad1189ed90e5adac638f7d43c"
                    }
                ],
                "p": "0.00000000597"
            }
        ],
        "r": "0x8f02425b5f3c522b7ef8ea124162645f0397c478"
    }
}

Request

Name	Type	Description
`op`	string	e.g. `subscribe`
`args`	object	Arguments
└ `channel`	string	Channel name, e.g., `preconfBundleUpdate`.

Response Body

Name	Type	Description
`e`	string	Event type, e.g., `preconfBundleUpdate`
`E`	integer	Event timestamp in milliseconds.
`P`	object	Payload data containing block builder update details.
└ `s`	integer	slot ID.
└ `e`	integer	Empty block space in the slot (For block owner only.)
└ `bu`	array	Array of preconf bundles in the slot.
└└ `u`	string	UUID of the bundle.
└└ `p`	string	Gas price of the bundle.
└└ `txs`	array	Array of transaction in the bundle
└└└ `r`	boolean	Whether this ethereum tranasaction can be reverted.
└└└ `tx`	string	Raw ethereum transaction data in the bundle
└└└ `h`	string	Transaction hash of transaction data

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Slot ID: The s field represents the current slot being updated.

Query

In a websocket session, you can query public or private data using the query command.

Public Query

Preconf Markets Query

Example Request

{
    "op": "query",
    "args": [
        {
            "queryType": "preconfMarkets",
            "marketType": "inclusionPreconf"
        }
    ]
}

Example Response

{
    "q": "preconfMarkets",
    "s": "ETH-PC-603391",
    "P": {
        "m": 1000000603391,
        "T": "inclusionPreconf",
        "s": 603391,
        "i": "ETH-PC-603391",
        "n": "Eth Preconf Inclusion Slot #603391",
        "M": 1744685266000,
        "f": 1744686038000,
        "b": 1744685270000,
        "q": "1",
        "mQ": "1",
        "MQ": "36000000",
        "PS": "0.00000000001",
        "mP": "0.00000000001",
        "MP": "0.00001",
        "d": false,
        "BB": "0.00000000001",
        "o": "0.00000000001",
        "C": "3.99996",
        "A": 36000000,
        "r": 0,
        "S": 0,
        "e": 1,
        "a": 1744685268000,
        "c": 1744684515000,
        "u": 1744684845000,
        "tp": 36000000
    }
}

Request

Name	Type	Description
`op`	string	e.g. `query`
`args`	object	Arguments
└ `queryType`	string	Query type, e.g., `preconfMarkets`.
└ `marketType`	string	Market type, e.g., `inclusionPreconf`.

Response Body

Name	Type	Description
`q`	string	Query type, e.g., `preconfMarkets`.
`s`	string	Instrument ID of the market, e.g., `ETH-PC-1151`.
`P`	object	Payload data containing market information.
└ `m`	integer	Market ID.
└ `T`	string	Market type, e.g. `inclusionPreconf`
└ `s`	integer	Slot ID.
└ `i`	string	Instrument ID.
└ `n`	string	Market name, e.g. `Eth Preconf Inclusion Slot #42093`.
└ `M`	integer	Market expiry time in milliseconds.
└ `a`	integer	Bundle submission deadline in milliseconds. (Optional)
└ `f`	integer	Block finality time in milliseconds.
└ `b`	integer	Block time in milliseconds.
└ `mQ`	string	Minimum order quantity allowed in the market. (Optional)
└ `MQ`	string	Maximum order quantity allowed in the market. (Optional)
└ `q`	string	Precision step of order quantity. (Optional)
└ `PS`	string	Precision step of order price.
└ `mP`	string	Minimum price allowed in the market.
└ `MP`	string	Maximum price allowed in the market.
└ `p`	string	Last traded price of the market
└ `PC`	float	Price change percentage.
└ `d`	boolean	Market direction.
└ `BB`	string	Best bid price.
└ `BA`	string	Best ask price.
└ `o`	string	Open price.
└ `C`	string	Collateral per slot in ETH.
└ `A`	integer	Available preconf for sale.
└ `r`	integer	Block owner reserved preconf not for sale.
└ `S`	integer	Block owner submitted preconf not for sale.
└ `e`	integer	Market status.
└ `c`	integer	Market Creation time in milliseconds.
└ `u`	integer	Last market update time in milliseconds.
└ `tp`	integer	Total amount of preconf allowed to sell in the market

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Precision Values: Prices and quantities are represented with high precision for accurate calculations.
Market Status: The e field indicates whether the market is open or expired.

Order Books Query

Example Request

{
    "op": "query",
    "args": [
        {
            "queryType": "orderBook",
            "marketType": "wholeBlock"
        }
    ]
}

Example Response

{
    "q": "orderBook",
    "s": "ETH-WB-1535",
    "P": {
        "a": [],
        "b": [
            {
                "q": "1",
                "p": "0.00000000567"
            },
            {
                "q": "2",
                "p": "0.00000000566"
            }
        ],
        "t": 1736759161542,
        "I": "ETH-WB-1535"
    }
}

Request

Name	Type	Description
`op`	string	e.g. `query`
`args`	object	Arguments
└ `queryType`	string	Query type, e.g., `orderBook`.
└ `marketType`	string	Market type, e.g., `wholeBlock`.

Response Body

Name	Type	Description
`q`	string	Query type, e.g., `orderBook`.
`s`	string	Instrument ID of the market, e.g., `ETH-WB-1535`.
`P`	object	Payload data containing order book information.
└ `a`	array	List of ask orders (empty in the example).
└ `b`	array	List of bid orders.
└└ `q`	string	Quantity of the bid order.
└└ `p`	string	Price of the bid order.
└ `t`	integer	Timestamp of the order book query in milliseconds.
└ `I`	string	Instrument ID, e.g., `ETH-WB-1535`.

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Order Details: The a field contains ask orders, and the b field contains bid orders, each with a price (p) and quantity (q).
Instrument ID: The I field represents the specific market instrument being queried.

Current Slot Query

Example Request

{
    "op": "query",
    "args": [
        {
            "queryType": "currentSlot"
        }
    ]
}

Example Response

{
    "q": "currentSlot",
    "P": {
        "t": 1736759362264,
        "s": 1497,
        "r": 1736
    }
}

Request

Name	Type	Description
`op`	string	e.g. `query`
`args`	object	Arguments
└ `queryType`	string	Query type, e.g., `currentSlot`.

Response Body

Name	Type	Description
`q`	string	Query type, e.g., `currentSlot`.
`P`	object	Payload data containing slot information.
└ `t`	integer	Timestamp of the current slot in milliseconds.
└ `s`	integer	Current slot ID.
└ `r`	integer	Total number of updates in the current slot.

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Slot ID: Slot can only be queried for the incoming 2 epochs (max 64 slots).
Update Count: The r field shows the total number of updates in the current slot.

Candlesticks Query

Example Request

{
    "op": "query",
    "args": [
        {
            "queryType": "candlesticks",
            "interval": 1000,
            "instrumentId": "ETH-PC-1567"
        }
    ]
}

Example Response

{
    "q": "candlesticks",
    "s": "ETH-PC-1567",
    "P": [
        {
            "I": "ETH-PC-1567",
            "m": 1000000001567,
            "t": 1736759832000,
            "i": 1000,
            "o": "0.00000000009",
            "h": "0.00000000009",
            "l": "0.00000000009",
            "c": "0.00000000009",
            "v": "0",
            "F": false
        },
        {
            "I": "ETH-PC-1567",
            "m": 1000000001567,
            "t": 1736759831000,
            "i": 1000,
            "o": "0.00000000009",
            "h": "0.00000000009",
            "l": "0.00000000009",
            "c": "0.00000000009",
            "v": "0",
            "F": true
        },
        {
            "I": "ETH-PC-1567",
            "m": 1000000001567,
            "t": 1736759830000,
            "i": 1000,
            "o": "0.00000000008",
            "h": "0.00000000009",
            "l": "0.00000000008",
            "c": "0.00000000009",
            "v": "2912472",
            "F": true
        }
    ]
}

Request

Name	Type	Description
`op`	string	e.g. `query`
`args`	object	Arguments
└ `queryType`	string	Query type, e.g., `candlesticks`.
└ `interval`	integer	Interval for price history in milliseconds, e.g., `1000`.
└ `instrumentId`	string	Instrument ID to query price history, e.g., `ETH-PC-1567`.

Response Body

Name	Type	Description
`q`	string	Query type, e.g., `candlesticks`.
`s`	string	Instrument ID of the queried market, e.g., `ETH-PC-1567`.
`P`	array	Array of market price history objects.
└ `I`	string	Instrument ID, e.g., `ETH-PC-1567`.
└ `m`	integer	Market ID.
└ `t`	integer	Timestamp of the price data in milliseconds.
└ `i`	integer	Interval of the data.
└ `o`	string	Open price during the interval.
└ `h`	string	High price during the interval.
└ `l`	string	Low price during the interval.
└ `c`	string	Close price during the interval.
└ `v`	string	Volume during the interval.
└ `F`	boolean	Indicates if the data is final (`true`) or incomplete (`false`).

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Price Details: Includes open (o), high (h), low (l), and close (c) prices along with volume (v).
Finalized Data: The F field indicates whether the price history data is finalized or still being updated.

Recent Trades Query

Example Request

{
    "op": "query",
    "args": [
        {
            "queryType": "recentTrades",
            "instrumentId": "ETH-PC-1567",
            "limit": 10
        }
    ]
}

Example Response

{
    "q": "recentTrades",
    "s": "ETH-PC-1567",
    "P": [
        {
            "i": "ETH-PC-1567",
            "p": "0.00000000021",
            "q": "1534591",
            "s": true,
            "d": 1736760078290,
            "t": 89130
        },
        {
            "i": "ETH-PC-1567",
            "p": "0.00000000021",
            "q": "270409",
            "s": false,
            "d": 1736760078369,
            "t": 89216
        }
    ],
    "l": 10
}

Request

Name	Type	Description
`op`	string	e.g. `query`
`args`	object	Arguments
└ `queryType`	string	Query type, e.g., `recentTrades`.
└ `instrumentId`	string	Instrument ID, e.g., `ETH-PC-1567`.
└ `limit`	integer	(Optional) Maximum number of trades to return (default is `100`).

Response Body

Name	Type	Description
`q`	string	Query type, e.g., `recentTrades`.
`s`	string	Instrument ID of the queried market, e.g., `ETH-PC-1567`.
`l`	integer	The limit applied to the query.
`P`	array	Array of recent trade objects.
└ `i`	string	Instrument ID, e.g., `ETH-PC-1567`.
└ `p`	string	Price at which the trade occurred.
└ `q`	string	Traded quantity .
└ `s`	boolean	Trade side (`true` for buy, `false` for sell).
└ `d`	integer	Timestamp of the trade in milliseconds.
└ `t`	integer	Trade ID.

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Trade Details: Each trade object includes price (p), quantity (q), and trade side (s).
Limit Parameter: The limit field in the request allows you to restrict the number of returned trades, with a default of 100.

Inclusion Preconf Top Sales Query

Example Request

{
    "op": "query",
    "args": [
        {
            "queryType": "inclusionPreconfTopSales"
        }
    ]
}

Example Response

{
    "q": "inclusionPreconfTopSales",
    "P": {
        "s": 403973,
        "g": 18662236,
        "S": [
            {
                "p": "0.00000000009",
                "q": "12662236"
            }
        ]
    }
}

Request

Name	Type	Description
`op`	string	e.g. `query`
`args`	object	Arguments
└ `queryType`	string	Query type, e.g., `inclusionPreconfTopSales`.

Response Body

Name	Type	Description
`q`	string	Query type, e.g., `inclusionPreconfTopSales`.
`P`	object	Payload data containing inclusion preconf top sales information.
└ `s`	integer	Slot ID.
└ `g`	integer	Total gas purchased in this slot.
└ `S`	array	Array of top gas sales.
└└ `p`	string	Purchased price in average
└└ `q`	string	Purchased gas quantity

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.

Current Block Builder Query

Example Request

{
    "op": "query",
    "args": [
        {
            "queryType": "currentBlockBuilder",
            "slot": 123456
        }
    ]
}

Example Response

{
    "q": "currentBlockBuilder",
    "P": {
        "s": 402361,
        "p": "0xA25ADDC4FC16F72CA667177D7A5533D4287B3574F0127FFC227095E90B0B1FD0DD48C421E04E613D2298FE4DAC83A2A5",
        "f": "0xa1885d66bef164889a2e35845c3b626545d7b0e513efe335e97c3a45e534013fa3bc38c3b7e6143695aecc4872ac52c4"
    }
}

Request

Name	Type	Description
`op`	string	e.g. `query`
`args`	object	Arguments
└ `queryType`	string	Query type, e.g., `currentBlockBuilder`.
└ `slot`	integer	Slot, e.g., `123456`. Optional. Use next slot if not specified.

Response Body

Name	Type	Description
`q`	string	Query type, e.g., `currentBlockBuilder`.
`s`	string	Instrument ID of the market, e.g., `ETH-WB-1631`.
`P`	object	Payload data containing block builder information.
└ `s`	integer	slot.
└ `p`	string	Block builder public key. optional if market owner does not delegate a builder
└ `f`	string	Fallback builder public key.

Notes

Slot ID: Slot can only be queried for the incoming 2 epochs (max 64 slots).

Private Query

Open Orders Query

Example Request

  {
    "queryType": "openOrders", 
    "accountId": 1234,
    "instrumentId": "ETH-PC-123456}",
    "pricerOnly": true,
    "startId": 0
}

Example Response


{
    "q": "openOrders",
    "s": "ETH-PC-194361",
    "P": [
        {
            "o": 61702036,
            "c": "43f4159e",
            "a": 2049,
            "C": 53,
            "t": 2,
            "i": "ETH-PC-194361",
            "m": 1000000194361,
            "p": "0.00000000001",
            "q": "1907125",
            "F": "1907125",
            "fp": "0.00001907125",
            "f": "0.0000017164125",
            "s": false,
            "P": false,
            "S": 10,
            "d": 1739776227777,
            "u": 1739776227777
        },
        {
            "o": 61702196,
            "c": "454057b4",
            "a": 2049,
            "C": 53,
            "t": 2,
            "i": "ETH-PC-194361",
            "m": 1000000194361,
            "p": "0.00000000001",
            "q": "1864896",
            "F": "1864896",
            "fp": "0.00001864896",
            "f": "0.0000016784064",
            "s": false,
            "P": false,
            "S": 10,
            "d": 1739776229952,
            "u": 1739776229952
        }
    ],
    "a": 2049
}

Request

Name	Type	Description
`op`	string	e.g. `query`
`args`	object	Arguments
└ `queryType`	string	Query type, e.g., `openOrders`.
└ `instrumentId`	string	Instrument ID, e.g., `ETH-PC-1567`.
└ `startId`	integer	(Optional) starting order ID in the query.

Response Body

Name	Type	Description
`q`	string	Query type, e.g., `openOrders`.
`s`	string	Instrument ID of the queried market, e.g., `ETH-PC-1567`.
`a`	string	Account ID, e.g., `1234`.
`P`	array	Array of order objects.
└ `o`	integer	Order ID, e.g., `1234`.
└ `c`	string	Client Order ID, e.g., `43f4159e`.
└ `a`	integer	Account ID.
└ `C`	integer	User ID who created this order. For pricer only.
└ `t`	boolean	Order Type.
└ `i`	string	Instrument ID.
└ `m`	integer	Market Id.
└ `p`	string	Order price.
└ `q`	string	Order total quantity.
└ `F`	string	Order filled quantity .
└ `fp`	string	Order filled price * quantity.
└ `f`	fee	Order fee.
└ `s`	boolean	Order side.
└ `P`	boolean	Flag for post-only order.
└ `S`	integer	Order Status.
└ `d`	integer	Timestamp of order creation time.
└ `u`	integer	Timestamp of last update time.

Notes

Timestamp Fields: All timestamps are in milliseconds since the Unix epoch.
Trade Details: Each trade object includes price (p), quantity (q), and trade side (s).
Limit Parameter: The limit field in the request allows you to restrict the number of returned trades, with a default of 100.

Account Positions Query

Example Request

        {
            "queryType": "accountPositions",
            "marketType": "inclusionPreconf",
            "accountId": 1234,
            "pricerOnly": true
        }

Example Response

{
    "q": "accountPositions",
    "P": [
        {
            "a": 2049,
            "s": 403776,
            "m": 1,
            "q": "0",
            "l": "0",
            "p": "0",
            "e": false,
            "b": false,
            "c": 1742289507000,
            "u": 1742289508000,
            "A": "0"
        },
        {
            "a": 2049,
            "s": 403780,
            "m": 1,
            "q": "0",
            "l": "0",
            "p": "0",
            "e": false,
            "b": false,
            "c": 1742289507000,
            "u": 1742289508000,
            "A": "0"
        }
    ]
}

Request

Name	Type	Description
`op`	string	e.g. `query`
`args`	object	Arguments
└ `queryType`	string	Query type, e.g., `accountPositions`.
└ `marketType`	string	Market type, e.g., `inclusionPreconf`.
└ `accountId`	integer	Account ID, e.g., `1234`.
└ `pricerOnly`	boolean	Flag for only displaying pricer information. Optional. Default to `false`.

Response Body

Name	Type	Description
`q`	string	Query type, e.g., `accountPositions`.
`s`	string	Instrument ID of the market, e.g., `ETH-WB-1631`.
`P`	array	Payload data containing position information.
└ `a`	integer	Account Id.
└ `s`	integer	Slot number of the position.
└ `m`	integer	Market type of the position.
└ `q`	string	Position's total quantity.
└ `l`	string	Position's locked quantity
└ `p`	string	Position purchased price.
└ `e`	boolean	Expired flag.
└ `b`	integer	Builder fill enable flag.
└ `c`	integer	Position create timestamp.
└ `u`	integer	Position last updated timestamp.
└ `A`	integer	Position's available quantity.

Preconf Bundles Query

Example Request

{
    "op": "query",
    "args": [
        {
            "queryType": "preconfBundles",
            "slot": 123456
        }
    ]
}

Example Response

{
    "q": "preconfBundles",
    "P": {
        "s": 194265,
        "bu": [
            {
                "u": "c439371a-7095-4de6-82ce-6bf4fc6fd693",
                "txs": [
                    {
                        "r": false,
                        "tx": "0x02f88a827e7e82088b808477359400830334509412643b525cc34282ba84298d32bf2d094448f1c4843b9aca009b45746847617320496e636c7573696f6e20507265636f6e66732e20c080a03b39cc9c4a92f32f8d4bc88546e2655378d4e87468ba74b0d20164ed9c346838a01bdbe85274f17b2c87e4689996089affd2d7d8c542616ef7020f5975bf4ddb52",
                        "h": "0xeb1bca2f601eb124563286455544cc87a1b04b28bd5bed6fb28be81417c4a0de"
                    }
                ],
                "p": "0.00000000013"
            }
        ]
    }
}

Request

Name	Type	Description
`op`	string	e.g. `query`
`args`	object	Arguments
└ `queryType`	string	Query type, e.g., `preconfBundles`.
└ `slot`	integer	Slot, e.g., `1234`. Optional. Use next slot if not specified.

Response Body

Name	Type	Description
`q`	string	Query type, e.g., `preconfBundles`.
`P`	array	Payload data containing block builder information.
└ `s`	integer	Slot ID.
└ `bu`	array	Array of preconf bundles in the slot.
└└ `u`	string	UUID of the bundle.
└└ `p`	string	Gas price of the bundle.
└└ `txs`	array	Array of transaction in the bundle
└└└ `r`	boolean	Whether this ethereum tranasaction can be reverted.
└└└ `tx`	string	Raw ethereum transaction data in the bundle
└└└ `h`	string	Transaction hash of transaction data

LOOKUP TABLES

Error Codes

Ethgas Trade uses the following error codes:

Error code	Description
1	Success
2	Permission Denied
99	Unexpected Error
1000	Pemission Denied
1001	Validation Error
1002	Operation Failed
9999	Unexpected Error
10000	Invalid account (Deposit)
10001	Invalid Token (Deposit)
10010	Invalid account (Withdraw)
10011	Invalid Token (Withdraw)
10012	Not Enough Funds to Withdraw

Order API error codes table

Error code	Description
102	INVALID_ACCOUNT
104	TIMEOUT
107	MINIMUM_QUANTITY_NOT_REACH
108	NO_ORDER
109	ORDER_DONE_OR_CANCELLED
110	TRADE_SERVER_PARSE
111	TRADE_SERVER_ORDER_BOOK_ERROR
112	TRADE_SERVER_DB
113	TRADE_SERVER_DB_CONNECTION
114	MARKET_EXPIRED
115	RATE_TRANSACTION_ERROR
120	QUANTITY_STEP_NOT_MATCH
122	INVALID_DEDUPLICATE_STRING
191	ORDER_AUTO_CANCELLED
192	ORDER_MANUALLY_CANCELLED

Markets

Market Status Codes

Status Code	Status	Description
0	NOT_STARTED	Pending to be started
1	ENABLE	Market enabled
2	EXPIRED	Market expired
3	TRX_SUBMISSION_ENDED	Transaction submission time ended
4	FINALIED	Market finalized

Orders

Order Sides

Boolean	Side
0 (False)	Sell
1 (True)	Buy

Order Status Codes

Status Code	Status	Description
0	STATUS_PENDING	Pending (i.e. Not yet sent to market)
1	STATUS_ONBOOK	On Book (i.e. Live order in market)
10	STATUS_DONE	Done (i.e. Fully executed)
11	STATUS_MANUALLY_CANCELLED	Manually cancelled
12	STATUS_AUTO_CANCELLED	Auto cancelled
13	STATUS_PARTIALLY_FILLED	Partially Filled
14	STATUS_EXPIRED	Market expired
99	STATUS_ERROR	Error

Order Types

Type Code	Meaning
1	Market Order
2	Limit Order
3	Fill-Or-Kill Order

Response Codes

Code	Description
200	OK
403	Forbidden
500	Internal Server Error or Invalid Response
503	Service Unavailable

Token IDs

These are the tokens currently supported on Ethgas.

Code	Name	Token ID	Quantity Step	Minimum Quantity	Pricer Step
ETH	ETH	1	0.00001	0.001	0.0001

Transaction Types

Code	Meaning
1	Buy
2	Sell
3	Borrow
4	Lend
5	Interest
6	Transfer In (Between accounts)
7	Transfer Out (Between accounts)
8	External Transfer In (Deposit)
9	External Transfer Out (Withdrawal)
10	Trade
14	Withdrawal Fee
15	Transaction Fee

Market Types

Code	Market
1	Inclusion Preconf Market
2	Whole Block Market

Action Types

Action Type returned in some websocket messages.

Type
NewEpoch
MarketExpiry
Snapshot
BlockBuilderChanged
BundleSubmissionDeadline

Builder

Builder Registration Result

Code	Reason
0	OK
1	NOT_FOUND
2	SIGNATURE_INVALID
3	ALREADY_REGISTERED