Main Menu

<< APIs

GlobalStake API Documentation

Base URL and Authentication

All GlobalStake API requests must be sent to the following base URL:

https://stakepad-api.globalstake.io

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.

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.

BNB API Endpoints

1. Delegate BNB

Endpoint: /bnb/delegate

Method: POST

Description: Generates an unsigned transaction to delegate BNB to a validator.

Request Parameters:

  • delegator (string, required) – The BNB address of the delegator.
  • amount (string, required) – The amount of BNB to delegate, formatted as a string (e.g., “1.5”).
  • chain (string, required) – “Mainnet” or “Testnet”).

Example Request:

{
   "delegator": "0x123456789abcdef123456789abcdef123456789a",
   "amount": "1.5",
   "chain": "Testnet"
}

Success Response: Unsigned raw transaction JSON

Error cases:

  • Invalid delegator address format.
  • Amount is not a valid BNB amount.

Endpoint: /bnb/claim

Method: POST

Description: Generates an unsigned transaction to claim BNB rewards for a given operator address and request number.

Request Parameters:

  • delegator (string, required) – The BNB address of the delegator.
  • operator_address (string, required) – The address of the operator for which to claim rewards.
  • request_number (string, required) – The number of unbonding requests to claim from. 0 means claiming from all unbonding requests.
  • chain (string, required) – “Mainnet” or “Testnet”

Example Request:

{
  "delegator": "0x123456789abcdef123456789abcdef123456789a",
  "operator_address": "0xabcdefabcdefabcdefabcdefabcdefabcdef",
  "request_number": "123", 
  "chain": "Mainnet"
}

Success Response: Unsigned raw transaction JSON.

Error cases:

  • Invalid delegator address format.
  • Operator address not found.
  • Invalid request number.

Endpoint: /bnb/batch-claim

Method: POST

Description: Generates an unsigned transaction to claim multiple BNB rewards in a single batch.

Request Parameters:

  • delegator (string, required) – The BNB address of the delegator.
  • operator_address (string, required) – The address of the operator for which to claim rewards.
  • request_number (string, required) – The number of unbonding requests to claim from. 0 means claiming from all unbonding requests.
  • chain (string, required) – “Mainnet” or “Testnet”

Example Request:

{
  "delegator": "0x123456789abcdef123456789abcdef123456789a",
  "operator_address": "0xabcdefabcdefabcdefabcdefabcdefabcdef",
  "request_number": "123", 
  "chain": "Mainnet"
}

Success Response: Unsigned raw transaction JSON.

Error cases:

  • Invalid delegator address format.
  • Mismatched operator_addresses and request_numbers array lengths.
  • One or more invalid request numbers.

Endpoint: /bnb/redelegate

Method: POST

Description: Generates an unsigned transaction to redelegate BNB from one validator to another.

Request Parameters:

  • delegator (string, required) – The BNB address of the delegator.
  • src_validator (string, required) – The address of the source validator.
  • dst_validator (string, required) – The address of the destination validator.
  • shares (string, required) – The amount of BNB shares to redelegate, formatted as a string.
  • delegate_vote_power (boolean, required) – Whether to delegate voting power to the destination validator.
  • chain (string, required) – “Mainnet” or “Testnet”

Example Request:

{
  "delegator": "0x123456789abcdef123456789abcdef123456789a",
  "src_validator": "0xabcdefabcdefabcdefabcdefabcdefabcdef",
  "dst_validator": "0xabcdabcdabcdabcdabcdabcdabcdabcdabcdabcd",
  "shares": "100",
  "delegate_vote_power": true, 
  "chain": "Mainnet"
}

Success Response: Unsigned raw transaction JSON.

Error cases:

  • Invalid delegator address format

  • Source or destination validator address not found.

  • Invalid share amount.

Endpoint: /bnb/undelegate

Method: POST

Description: Generates an unsigned transaction to undelegate BNB from a validator.

Request Parameters:

  • delegator (string, required) – The BNB address of the delegator.
  • operator_address (string, required) – The address of the validator from which to undelegate.
  • shares (string, required) – The amount of BNB shares to undelegate, formatted as a string.
  • chain (string, required) – “Mainnet” or “Testnet”

Example Request:

{
  "delegator": "0x123456789abcdef123456789abcdef123456789a",
  "operator_address": "0xabcdefabcdefabcdefabcdefabcdefabcdef",
  "shares": "100", 
  "chain": "Mainnet"
}

Success Response: Unsigned raw transaction JSON.

Error cases:

  • Invalid delegator address format
  • Operator address not found.
  • Invalid share amount.

Endpoint: /bnb/unbond-period

Method: POST

Description: Retrieves the unbonding period for the BNB staking contract.

Request Parameters:

  • chain (string, required) – “Mainnet” or “Testnet”

Example Request:

{
  curl -X GET http://localhost:8080/bnb/unbond-period
}

Success Response: JSON containing the unbonding period in seconds.

Error cases:

  • Contract error or unbonding period not available.

Endpoint: /bnb/decode

Method: POST

Description: Decodes raw transaction data for a BNB staking contract.

Request Parameters:

  • data (string, required) – The raw transaction data to decode, formatted as a hex string.

Example Request:

{
   "data": "0xabcdef1234567890abcdef1234567890"
}

Success Response: Decoded transaction details as JSON.

Error cases:

  • Invalid data format.
  • Failed to decode the transaction.

Endpoint: /bnb/validator-basic-info

Method: POST

Description: Retrieves basic information about a specific validator.

Request Parameters:

  • operator_address (string, required) – The address of the validator.
  • chain (string, required) – “Mainnet” or “Testnet”

Example Request:

{
   "operator_address": "0xabcdefabcdefabcdefabcdefabcdefabcdef", 
   "chain": "Mainnet"
}

Success Response: JSON containing the validator’s basic information.

Error cases:

  • Invalid operator address.
  • Validator not found.

Endpoint: /bnb/staking-logs-all

Method: POST

Description: Retrieves the entire staking history per wallet.

Request Parameters:

  • delegator (string, required) – The address of the wallet to fetch staking history.
  • from_block (number, optional) – The starting block to fetch history from.
  • to_block (number, optional) – The ending block to fetch history to.
  • chain (string, required) – “Mainnet” or “Testnet”

Example Request:

{
   "delegator": "0xabcdefabcdefabcdefabcdefabcdefabcdef",
   "from_block": 0, 
   "to_block": 9999999, 
   "chain": "Mainnet"
}

Success Response: JSON containing the staking transaction history for the wallet.

Error cases:

  • Invalid address.
  • Address has no staking history.
  • Address has no staking transactions within given block range

Endpoint: /bnb/staking-logs-gs

Method: POST

Description: Retrieves the staking history per wallet ONLY when they interacted with the GlobalStake validator.

Request Parameters:

  • delegator (string, required) – The address of the wallet to fetch staking history.
  • from_block (number, optional) – The starting block to fetch history from.
  • to_block (number, optional) – The ending block to fetch history to.
  • chain (string, required) – “Mainnet” or “Testnet”

Example Request:

{
   "delegator": "0xabcdefabcdefabcdefabcdefabcdefabcdef",
   "from_block": 0, 
   "to_block": 9999999, 
   "chain": "Mainnet"
}

Success Response: JSON containing the staking transaction history for the wallet.

Error cases:

  • Invalid address.
  • Address has no staking history with GlobalStake.
  • Address has no staking transactions within given block range

Endpoint: /bnb/staking-balance

Method: POST

Description: Fetches the amount of BNB staked per the input address.

Request Parameters:

  • delegator (string, required) – The address of the wallet.
  • from_block (number, optional)
  • to_block (number, optional)
  • chain (string, required) – “Mainnet” or “Testnet”

Example Request:

{
   "delegator": "0xabcdefabcdefabcdefabcdefabcdefabcdef", 
   "chain": "Mainnet", 
   "from_block": 10000, 
   "to_block": 45000
}

Success Response: JSON containing the wallet’s staked BNB balance.

Error cases:

  • Wallet does not contain any staked BNB.
  • Wallet not found.

Endpoint: /bnb/staking-rewards

Method: POST

Description: Fetches estimated staking rewards for a given wallet.

Request Parameters:

  • delegator (string, required) – The address of the wallet.
  • from_block (number, optional)
  • to_block (number, optional)
  • chain (string, required) – “Mainnet” or “Testnet”

Example Request:

{
   "delegator": "0xabcdefabcdefabcdefabcdefabcdefabcdef", 
   "chain": "Mainnet", 
   "from_block": 10000, 
   "to_block": 45000
}

Success Response: JSON containing the estimated staking reward for an address.

Error cases:

  • Wallet does not contain any staked BNB.
  • Wallet not found.

BNB Staking Flow Summary

BNB staking through the StakeHub contract allows BNB holders to earn rewards by locking their tokens with validators. The staking process involves several key operations: delegation, redelegation, undelegation, and claiming rewards.

1. Delegation

When a user stakes their BNB, they send a Delegate transaction to the StakeHub contract. This transaction requires:

  • Operator Address: The address of the validator to receive the BNB.
  • Delegate Voting Power: A boolean flag indicating whether the delegator wants to delegate their voting power to the validator for governance purposes.

Upon delegation, the contract deducts the specified amount of BNB from the delegator’s balance and mints a corresponding amount of staking credits (shares) to the validator. The number of shares a delegator receives is proportional to their stake relative to the validator’s total pooled BNB, which includes both staked BNB and unclaimed rewards. This share system ensures that delegators earn a portion of the validator’s rewards based on their relative contribution to the total pool.

 

Credit Calculation:

Shares=(Delegation Amount×Total Credit SupplyTotal Pooled BNB)\text{Shares} = \left(\frac{\text{Delegation Amount} \times \text{Total Credit Supply}}{\text{Total Pooled BNB}}\right)Shares=(Total Pooled BNBDelegation Amount×Total Credit Supply​)

A delegator can redelegate their staked BNB from one validator to another without incurring an unbonding period. This operation is useful for switching to more profitable or secure validators and involves the following:

  • Source Operator Address: The address of the current validator.
  • Destination Operator Address: The address of the new validator.
  • Amount: The amount of BNB to redelegate.
  • Delegate Voting Power: A boolean flag indicating whether to transfer voting power to the new validator.

The redelegation process burns the staking credits from the source validator and mints new credits for the destination validator, adjusting the delegator’s position without forcing them to wait through the unbonding period. However, a 0.002% redelegation fee applies to discourage frequent validator switching.

To unstake BNB, a delegator sends an Undelegate transaction to the StakeHub contract. This transaction requires:

  • Operator Address: The address of the validator from which to unstake.
  • Amount: The amount of BNB to be unstaked.

Upon undelegation, the corresponding staking credits are burned, and the BNB is moved into a withdrawal queue. This BNB remains locked for a 7-day unbonding period before it can be claimed, providing a security buffer to prevent rapid exits during network stress or validator misbehavior.

Once the unbonding period is over, a delegator can claim their unstaked BNB and accumulated rewards. This process requires:

  • Delegator Address: The BEP20 address of the user.
  • Queued Unbond Number: The specific unbond request to claim, or 0 to claim all available requests.

The claim transaction releases the BNB and any rewards back to the user’s account, completing the staking lifecycle.

Step-by-Step Guide to Fetching Delegator Rewards on BNB Chain

To accurately track and fetch delegator rewards on the BNB chain, you will need to interact with multiple smart contract methods to calculate the correct reward distribution. This guide will walk you through the required steps:

Step 1: Fetch the Total Pooled BNB for a Validator

The first step is to retrieve the total pooled BNB for a given validator. This value is critical because it represents the total amount of BNB, including both the delegations and unclaimed rewards, that the validator is managing.

API Endpoint: /bnb/validator-pooled-bnb

Method: POST

Request Body:

{
   "operator_address": "0x123456789abcdef123456789abcdef123456789a",
   "index": "0"
}

Expected Response:

{
   "operator_address": "0x123456789abcdef123456789abcdef123456789a",
   "index": 0,
   "pooled_bnb": "1000000000000000000"
}

Notes:

  • The operator_address is the address of the validator you are interested in.

  • The index is the record number you want to query. Generally, you should start with index 0 and iterate upwards until you receive an error or empty result, indicating the end of available records.

Next, you need to fetch the delegator’s current share balance. This is not directly exposed via the same contract but can be inferred from the delegation transactions and the credits issued. You can maintain this balance by tracking all delegation and undelegation transactions or by using a historical record if available.

Once you have the total pooled BNB and the delegator’s share, you can calculate the rewards as follows:

Rewards=Total Pooled BNB−Delegator’s Initial Stake\text{Rewards} = \text{Total Pooled BNB} – \text{Delegator’s Initial Stake}Rewards=Total Pooled BNB−Delegator’s Initial Stake

You will need to keep track of the initial staked amount to accurately calculate the rewards, as the pooled BNB includes both the initial stake and accumulated rewards.

Since rewards are distributed periodically, it’s essential to periodically poll the validator’s total pooled BNB and recalculate the delegator’s share to reflect ongoing rewards. This can be automated using cron jobs, background workers, or real-time data streams.