Main Menu

<< APIs

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 Ethereum API Endpoints

2.6.1 Get Ethereum Deposit Transaction

Endpoint: /ethereum/get_deposit_data

Method: POST

Description: Generates an unsigned Ethereum deposit transaction.

Request Parameters:

 • withdrawal_address (string) – Ethereum address where the deposit withdrawal is directed.
 • num_of_validators (number) – Number of validators being deposited.
 • chain (string) – Ethereum network type (MainnetEth or TestnetEth).

Success Response: Unsigned raw transaction JSON

Error cases:

 • Invalid withdrawal address format.
 • num_of_validators is not a positive integer.
 • Unsupported chain value.

Endpoint: /ethereum/get_validators

Method: POST

Description: Fetches validator details for a given address.

Request Parameters:

 • address (string) – Ethereum address associated with the validators.

Success Response: Unsigned raw transaction JSON

Error cases:

 • Invalid Ethereum address.
 • No validators found for the given address.

Endpoint: /ethereum/withdrawal

Method: POST

Description: Generates an unsigned withdrawal transaction for Ethereum validators and forwards the request to an external withdrawal service.

Authentication: Requires a Bearer Authorization Token in the request headers.

Request Parameters (JSON-encoded string):

 • num_of_validators (number) – number of validators to be withdrawn.
 • validator_addresses (array) – Comma-separated list of validator pubkeys to be withdrawn [“pubkey”, “pubkey2”].
 • chain (string) – Ethereum network type (MainnetEth or TestnetEth).

Success Response: Unsigned raw transaction JSON

Error cases:

 • 400 Bad Request – Invalid or malformed request body.
 • 401 Unauthorized – Missing or incorrect authentication token.
 • 404 Not Found – External withdrawal service unavailable.
 • 500 Internal Server Error – Failure processing the withdrawal request.

2.7 Pooled Ethereum API Endpoints (Stakewise Wrappers)

2.7.1 Stake Ethereum in a Pooled Staking Contract

Endpoint: /ethereum/pooled_stake_eth

Method: POST

Description: Wrapper around Stakewise API to generate an unsigned staking transaction.

Request Parameters:

 • amount (number) – Amount of ETH to stake.
 • pool_address (string) – Ethereum address of the staking pool.

Success Response: Unsigned raw transaction JSON

Error cases:

 • Invalid pool address.
 • Amount is zero or negative.

Endpoint: /ethereum/pooled_withdraw_eth

Method: POST

Description: Wrapper around Stakewise API to generate an unsigned withdrawal transaction.

Request Parameters:

 • amount (number) – Amount of ETH to withdraw.
 • pool_address (string) – Ethereum address of the staking pool.

Success Response: Unsigned raw transaction JSON

Error cases:

 • Invalid pool address.
 • Insufficient balance in the staking pool.

Endpoint: /ethereum/pooled_get_user_rewards

Method: POST

Description: Wrapper around Stakewise API to fetch user staking rewards.

Request Parameters:

 • vault_address (string) – Address of the vault holding rewards.
 • user_address (string) – Ethereum address of the user.
 • date_from (number) – Unix timestamp for start of reward period.
 • date_to (optional, number) – Unix timestamp for end of reward period.
 • fill_gaps (optional, boolean) – Whether to fill missing rewards.

Success Response: Unsigned raw transaction JSON

Error cases:

 • Invalid vault_address or pool_address.
 • date_from is invalid or in the future.