API Integration Guide – Ethereum
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.
Operations
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.
Using the API Token
Authentication
Every request must include an API key provided by the GlobalStake team. This key is unique to your team and must be passed in the Authorization header as a Bearer token:
Authorization: Bearer YOUR_API_KEY_HERE
If the Authorization header is missing or the token is invalid, the request will be rejected with a 401 Unauthorized error.
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.
General Response Format
Each API call is expected to return an unsigned raw transaction JSON.
Any response that does not conform to this format is considered an error.
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.
Ethereum API Endpoints
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.
• amount (number) – amount of ETH to deposit per validator.
• 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.
2. Get Ethereum Validators
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.
3. Initiate Ethereum Withdrawal
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.
4. Get Ethereum Validator Status
Endpoint: /ethereum/validator_status
Method: POST
Description: Fetches validator status and activation / exit epochs for a given validator.
Request Parameters:
• index (string) – Validator index.
• chain (string) – Ethereum network type (MainnetEth or TestnetEth).
Success Response: API response including status, index, activation epoch, exit epoch, etc.
Error cases:
• Invalid validator index
5. Get Ethereum Address’s Associated Validators
Endpoint: /ethereum/get_validators_from_eth1
Method: POST
Description: Fetches validator pubkeys & indices that were created by the input address.
Request Parameters:
• address (string) – Wallet pubkey.
• chain (string) – Ethereum network type (MainnetEth or TestnetEth).
Success Response: API response including validator public keys and indices.
Error cases:
• Invalid wallet public key
• Wallet public key has no associated validators
Pooled Ethereum API Endpoints (Stakewise Wrappers)
All endpoints generate unsigned raw transaction JSONs or off-chain data via the StakeWise SDK. If a request fails due to backend overload (502), you may call the StakeWise SDK directly: https://sdk.stakewise.io/introduction
1. Stake Ethereum into a Pooled Staking Vault
Endpoint: /ethereum/pooled_stake_eth
Method: POST
Description: Generates an unsigned staking transaction using the StakeWise SDK.
Request Parameters:
• amount (number) – Amount of ETH to stake.
• vault_address (string) – Ethereum address of the staking vault.
• wallet_address (string) – User’s Ethereum address.
Success Response: Unsigned raw transaction JSON
Error cases:
• Invalid cvault address.
• Amount is zero or negative.
2. Withdraw Ethereum from a Pooled Staking Vault
Endpoint: /ethereum/pooled_withdraw_eth
Method: POST
Description: Generates an unsigned withdrawal transaction from a StakeWise vault.
Request Parameters:
• amount (number) – Amount of ETH to withdraw.
• vault_address (string) – Ethereum address of the staking vault.
• wallet_address (string) – User’s Ethereum address.
Success Response: Unsigned raw transaction JSON
Error cases:
• Invalid vault address.
• Insufficient balance or withdrawal limit reached.
3. Claim from the Exit Queue
Endpoint: /ethereum/pooled_claim_exit_queue
Method: POST
Description: Generates a transaction to claim exited ETH from the exit queue.
Request Parameters:
• positionss (object) – JSON from getExitQueuePositions.
• user_address (string) – User’s Ethereum address.
• vault_address (string) – Address of the vault.
Success Response: Unsigned raw transaction JSON
Error cases:
• No claimable positions.
• Invalid addresses or position data.
4. Get User Rewards
Endpoint: /ethereum/pooled_get_user_rewards
Method: POST
Description: Retrieves reward history for a given user and vault.
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: Array of rewards per day
Error cases:
• Invalid input timestamps or addresses.
5. Get User Balance
Endpoint: /ethereum/pooled_get_user_balance
Method: POST
Description: Returns current balance in a vault for the specified user.
Request Parameters:
• vault_address (string) – Address of the vault holding rewards.
• user_address (string) – Ethereum address of the user.
Success Response: JSON including balance, shares, and pending exits
Error cases:
• Invalid user or vault address.
6. Get Vault Metadata
Endpoint: /ethereum/pooled_get_vault_metadata
Method: POST
Description: Fetches metadata for a given StakeWise vault.
Request Parameters:
• vault_address (string)
Success Response: Vault metadata including pool parameters
Error cases:
• Invalid vault address.
7. Get Vault Statistics
Endpoint: /ethereum/pooled_get_vault_statistics
Method: POST
Description: Fetches historic statistics for a given vault.
Request Parameters:
• vault_address (string)
• days_count (number) – Number of days to fetch statistics for.
Success Response: Daily metrics including rewards and APY.
Error cases:
• Invalid vault or date range.
8. Get User APY
Endpoint: /ethereum/pooled_get_user_apy
Method: POST
Description: Calculates current APY for a user in a vault.
Request Parameters:
• vault_address (string)
• user_address (string)
Success Response: JSON with APY value.
Error cases:
• Invalid addresses.
9. Get Exit Queue Positions
Endpoint: /ethereum/pooled_get_user_exit_queue_positions
Method: POST
Description: Fetches current exit queue entries for a user.
Request Parameters:
• vault_address (string)
• user_address (string)
• is_claimed (bool) – Whether to filter for claimed/unclaimed entries.
Success Response: JSON array of queue positions.
Error cases:
• Invalid input or vault state.
10. Get Staker Actions
Endpoint: /ethereum/pooled_get_staker_actions
Method: POST
Description: Lists user staking actions for analytics or history.
Request Parameters:
• vault_address (string)
• user_address (string)
• limit (number) – Max number of entries to return.
• skip (number) – Offset for pagination.
Success Response: JSON array of actions.
Error cases:
• Invalid pagination or addresses.