API Integration Guide – Solana

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.

3. Solana API Routes

The following endpoints allow users to interact with Solana staking operations, including staking, adding, merging, unstaking, deactivating, and withdrawing stakes.

3.1 Stake SOL

Endpoint: POST /stake
Description: Initializes staking to a specific validator on the Solana network.

  • Request Body: JSON containing:
    • stake_account_pubkey: (string) The public key of the stake account.
    • amount: (u64) The amount to stake in Lamports.
Responses:
  • 200 – Success: Returns an unsigned transaction in JSON format if the operation was successful.
  • 400 – Bad Request: The request could not be processed due to missing or incorrect data (e.g., an invalid public key).
  • 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 stake account ID).
  • 500 – Server Error: The request could not be processed due to an internal server error, potentially due to server maintenance.

3.2 Add to Existing Stake

Endpoint: POST /add_stake
Description: Adds additional Lamports to an existing stake account.

  • Request Body: JSON containing:
    • stake_account_pubkey: (string) The public key of the stake account to which Lamports will be added.
    • amount: (u64) The amount to add in Lamports.
Responses:
  • 200 – Success: Returns an unsigned transaction in JSON format if the operation was successful.
  • 400 – Bad Request: The request could not be processed due to missing or incorrect data (e.g., an invalid public key).
  • 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 stake account ID).
  • 500 – Server Error: The request could not be processed due to an internal server error, potentially due to server maintenance.

3.3 Merge Stake Accounts

Endpoint: POST /merge_stake_accounts
Description: Merges two stake accounts on Solana, transferring the funds from the source account to the destination account.

  • Request Body: JSON containing:
    • source_stake_account_pubkey: (string) The public key of the source stake account.
    • destination_stake_account_pubkey: (string) The public key of the destination stake account.

Responses:

  • 200 – Success: Returns an unsigned transaction in JSON format if the operation was successful.
  • 400 – Bad Request: The request could not be processed due to missing or incorrect data (e.g., an invalid public key).
  • 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 stake account ID).
  • 500 – Server Error: The request could not be processed due to an internal server error, potentially due to server maintenance.

3.4 Unstake Inactive Account

Endpoint: POST /unstake_inactive_account
Description: Initiates the unstaking process for an inactive stake account.

  • Request Body: JSON containing:
    • stake_account_pubkey: (string) e public key of the inactive stake account.

Responses:

  • 200 – Success: Returns an unsigned transaction in JSON format if the operation was successful.
  • 400 – Bad Request: The request could not be processed due to missing or incorrect data (e.g., an invalid public key).
  • 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 stake account ID).
  • 500 – Server Error: The request could not be processed due to an internal server error, potentially due to server maintenance.

3.5 Deactivate Stake

Endpoint: POST /deactivate
Description: Deactivates a stake account, making it eligible for unstaking.

  • Request Body: JSON containing:
    • stake_account_pubkey: (string) The public key of the stake account to deactivate.

Responses:

  • 200 – Success: Returns an unsigned transaction in JSON format if the operation was successful.
  • 400 – Bad Request: The request could not be processed due to missing or incorrect data (e.g., an invalid public key).
  • 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 stake account ID).
  • 500 – Server Error: The request could not be processed due to an internal server error, potentially due to server maintenance.

3.6 Withdraw Stake

Endpoint: POST /withdraw
Description: Withdraws Lamports from an inactive stake account.

  • Request Body: JSON containing:
    • stake_account_pubkey: (string) The public key of the stake account from which to withdraw.
Responses:
  • 200 – Success: Returns an unsigned transaction in JSON format if the operation was successful.
  • 400 – Bad Request: The request could not be processed due to missing or incorrect data (e.g., an invalid public key).
  • 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 stake account ID).
  • 500 – Server Error: The request could not be processed due to an internal server error, potentially due to server maintenance.

3.7 Signing an Unsigned Solana Transaction via CLI

After obtaining an unsigned transaction from the GlobalStake API, you must sign it before broadcasting it to the Solana network. This section provides steps to sign an unsigned Solana transaction using the Solana CLI.

Prerequisites:

  • Ensure you have the Solana CLI installed.
  • Verify you have the necessary wallet or keypair file available to sign the transaction.

Step 1: Save the Unsigned Transaction

When you receive an unsigned transaction from the API, save it as a .json file. For example:

echo ‘<unsigned_transaction_json>’ > unsigned_tx.json

Step 2: Decode the Unsigned Transaction (Optional)

To inspect the contents of the unsigned transaction, you can decode it with the Solana CLI:

solana decode-transaction -i unsigned_tx.json

This step is optional but useful to verify transaction details before signing.

Step 3: Sign the Transaction

Use the following command to sign the transaction with your keypair:

solana decode-transactiosolana sign-transaction unsigned_tx.json –keypair <path_to_your_keypair> > signed_tx.json

  • Replace solana decode-transactio<path_to_your_keypair> with the path to your wallet’s keypair file.
  • The output will be saved as signed_tx.json, containing the signed transaction ready for submission.

Step 4: Send the Signed Transaction

Finally, send the signed transaction to the Solana network:

solana decode-transactiosolana send-transaction signed_tx.json

This command submits the transaction to the Solana blockchain, and you will receive a confirmation message once it is successfully broadcast.