API Integration Guide – Ethereum
1. Introduction
GlobalStake provides a comprehensive API to support integration for partners seeking to allocate validators, manage staking operations, and access information from GlobalStake’s services. This guide provides detailed instructions for setting up your access token, connecting with our API endpoints, and utilizing our operational resources.
2. Operations
2.1 Obtaining an API Token
An authorized API token is required to use GlobalStake’s API. Please contact the GlobalStake support team to request an API token for your account. Once issued, this token will be unique to your organization and should be stored securely, as it cannot be retrieved if lost. If your token is misplaced or compromised, reach out to support to revoke and replace it.
2.2 Using the API Token
GlobalStake’s API token, auth_token, is implemented exclusively as a query parameter within the URL. This ensures that each request you make is securely authenticated. To use your token in requests, include it as a query parameter within the URL.
For example:
https://api.globalstake.io/v1/validators/status?auth_token=your_token_here
2.3 Headers
To ensure proper data formatting, all requests to GlobalStake’s API should include the following headers:
- Accept: application/json – Required for all requests to specify that the response will be in JSON format.
- Content-Type: application/json – Required for all requests that submit data, to ensure JSON data formatting.
2.4 Response Codes
GlobalStake’s API uses standard HTTP response codes to indicate the outcome of requests. Here are the common codes and their meanings:
- 200 – Success. The request was successfully processed (e.g., a successful GET request).
- 400 – Bad Request. The request could not be processed due to missing or incorrect data.
- 401 – Unauthorized. The request failed due to a missing or invalid auth_token.
- 404 – Not Found. The requested resource was not found (e.g., an invalid validator ID).
- 500 – Server Error. The request could not be processed due to an internal error on the API server, possibly during maintenance.
2.5 Revoking the API Token
If your API token is compromised or needs to be replaced, contact GlobalStake’s support team for assistance in revoking and regenerating a new token.
2.6 Obtaining Deposit Data for a Validator
To initiate an Ethereum validator in the GlobalStake ecosystem, deposit data must first be obtained. This data includes key information that enables staking and sets up withdrawal credentials. A request for deposit data can be made as follows:
Method: POST
Path: /get_deposit_data
The request body should contain a JSON object identifying the validator and specifying the withdrawal credentials. The required fields are as follows:
- num_of_validators: A number representing the number of validators the client wants to create. Please remember that each Ethereum validator requires 32 staked ETH to earn rewards.
- withdrawal_address: A hex string representing the public key of the withdrawal keypair.
Sample Request:
{
“num_of_validators”: “1”,
“withdrawal_address”: “0xa9ca9cf7…eb282c00”
}
If the request is successful, a JSON response will be returned with deposit data formatted as required for a deposit transaction. Ensure all data checks are completed before submitting a deposit.
2.7 Broadcasting a Validator Deposit Transaction to the Ethereum Network
Once you have obtained the necessary deposit data for your Ethereum validator(s) through the /get_deposit_data endpoint, you must broadcast this transaction to the Ethereum network to complete the validator setup.
Step 1: Prepare the Deposit Transaction
Ensure the deposit data returned from the API includes the required fields, such as the deposit amount, validator public key, withdrawal credentials, and other essential details. Review these carefully to confirm all data is correct and matches your intended validator setup.
Step 2: Use the Staking Deposit CLI Tool
The Ethereum Staking Deposit CLI Tool provides a convenient method for submitting validator deposits. Follow these steps to broadcast the transaction:
Install the Deposit CLI Tool:
pip install ethereum-staking-deposit-cli
Run the Deposit Command:
Use the tool to submit the deposit with your prepared JSON data. You will specify the network, validator count, and withdrawal address. If you have multiple validators, adjust num_validators accordingly.
eth2deposit –num_validators 1 –withdrawal_address 0xa9ca9cf7…eb282c00 –amount 32
Complete the Deposit Process:
Follow the prompts to finalize and broadcast the transaction. This will send your deposit transaction to the Ethereum 2.0 deposit contract, initiating the validator activation process.
Step 3: Verify the Transaction
Once the transaction has been broadcast, monitor its status on an Ethereum block explorer, such as Etherscan, by searching for your deposit transaction hash. Confirm that your validator is set up and ready to start earning rewards.
By following these steps, you ensure that your validator deposit is accurately processed on the Ethereum network, completing the setup for your validator node.
2.8 Obtaining a Validator Exit Transaction
To initiate an exit for one or more Ethereum validators in the GlobalStake ecosystem, users must submit a request with the public keys of the validators they wish to exit.
Method: POST
Path: /withdrawal
Request Body:
The request body should include an array of validator public keys in JSON format, as shown below:
{
“validator_addresses”: [
“0x974ec5bce4653f1f440ad07c5b363ad3b1616520e9680ff837f9ff7a8c10e3cc
67dd49aa5089f714ed45d7ad56bc758a”
]
}
- validator_addresses: An array of hex strings, each representing the public key of a validator to be exited from the Ethereum network.
Sample Request:
{
“validator_addresses”: [
“0x974ec5bce4653f1f440ad07c5b363ad3b1616520e9680ff837f9ff7a8c10e3cc
67dd49aa5089f714ed45d7ad56bc758a”,
“0xa45b9cf5d86d2f2b1b1c6f5db5d93bb15b3a9f0b8ff5d5a3f3ebef45c5b3927b”
]
}
Response:
If the request is successful, the response will include an encrypted exit transaction for each validator in the following format:
{
“exit_transactions”: [
{
“validator_address”: “0x974ec5bce4653f1f440ad07c5b363ad3b1616520e9680ff837f9ff
7a8c10e3cc67dd49aa5089f714ed45d7ad56bc758a”,
“exit_transaction”: “0x9eb3d204…cacc433e”,
“fork_version”: “0x00002009”
}
]
}
- validator_address: The public key of the validator that is being exited.
- exit_transaction: A hex string representing the encrypted exit transaction for the validator, which can be decrypted with the corresponding private PGP key.
- fork_version: The fork version that applies to the exit transaction data.
2.9 Broadcasting a Validator Withdrawal Transaction to the Ethereum Network
Once you have prepared a signed withdrawal transaction for your Ethereum validator(s) via the GlobalStake API, it must be broadcast to the Ethereum network to complete the withdrawal process.
Step 1: Verify the Withdrawal Transaction
Before broadcasting, review the withdrawal transaction details. This data, obtained from the GlobalStake API, should include all necessary fields for the validator withdrawal, such as the validator public key, withdrawal credentials, and signature.
Step 2: Use a Broadcasting Tool
To broadcast the withdrawal transaction, you can use either a command-line tool or an Ethereum-compatible wallet that supports raw transaction broadcasting.
Option A: Using ethdo CLI
ethdo is a convenient command-line tool for broadcasting Ethereum transactions, including validator withdrawals.
Install ethdo (if not already installed):
brew install ethdo
Broadcast the Withdrawal Transaction:
Use the following command to broadcast the withdrawal transaction, substituting signed_withdrawal_tx.json with your file containing the signed transaction data:
ethdo validator withdraw –json='{“exit”:{…}}’ –network=mainnet
Adjust the –network flag if broadcasting on a testnet.
Option B: Using an Ethereum-Compatible Wallet
Alternatively, you can use an Ethereum wallet (e.g., MetaMask) that supports custom RPC and raw transaction broadcasting. Follow these steps:
- Open the wallet, navigate to the “Send” or “Broadcast” option, and look for the “Raw Transaction” field.
- Copy and paste the raw transaction data from your signed withdrawal transaction.
- Confirm and send the transaction.
Step 3: Verify the Withdrawal on the Ethereum Network
After broadcasting, you can monitor the transaction status via Etherscan or another Ethereum block explorer by entering the transaction hash. This confirmation verifies the withdrawal’s success, ensuring that funds are securely returned to the specified withdrawal address.
By following these steps, you can securely and efficiently broadcast your validator’s withdrawal transaction to the Ethereum network.