API Integration Guide – Polkadot

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. Polkadot API Routes

These endpoints enable users to manage Polkadot staking operations, including adding, replacing, and bonding nominations for staking.

3.1 Add Nominees

Endpoint: POST /add_nominees
Description: Adds a list of nominated validators to an account for staking purposes.

  • Request Body: JSON containing:
    • address: (string) The address of the nominator on the Polkadot network.

Responses:

  • 200: Indicates that nominees were successfully added.
  • 400: Returned if the request body is invalid.
  • 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: Returned if an internal server error occurs.

Upon a successful call, a JSON response will contain data regarding the added nominees and the generated substrate call for nominating validators.

3.2 Replace Nominees

Endpoint: POST /replace_nominees
Description: Replaces the current list of nominees with a new list for a specified nominator.

  • Request Body: JSON string containing:
    • address: (string) The address of the nominator on the Polkadot network.

Responses:

  • 200: Indicates that nominees were successfully replaced.
  • 400: Returned if the request body is invalid.
  • 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: Returned if an internal server error occurs.

This route provides a response containing the updated list of nominees and the substrate call data necessary to execute the replacement.

3.3 Bond More

Endpoint: POST /bond_more
Description: Increases the bonded amount for a specified nominator to raise their staking position.

  • Request Body: JSON string containing:
    • address: (string) The address of the nominator on the Polkadot network.
    • amount: (string) The amount to bond additionally.

Responses:

  • 200: Indicates the bonding operation was successful.
  • 400: Returned if the request body is invalid.
  • 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: Returned if an internal server error occurs.

If successful, the response confirms the bonding increase, allowing the user to verify the new bonded amount.

Each route above requires a valid address and/or amount as per the Polkadot network standards for smooth operation and successful stake management.

3.4 Withdraw Unbonded Funds

Endpoint: POST /withdraw
Description: Initiates a withdrawal of unbonded funds from the Polkadot staking account. This operation removes funds that have completed the unbonding period and are now available for withdrawal.

  • Request Body: JSON object containing:
    • address: (string) The address of the account from which unbonded funds are to be withdrawn.

Responses:

  • 200 – Success: Returns a JSON response confirming the transaction details if the withdrawal operation is successful. The response includes:
    • call_data: (string) The encoded call data for the Polkadot extrinsic to withdraw unbonded funds.
    • human_data: (string) Additional human-readable data regarding the transaction.
    • message: (string) A message confirming successful processing (e.g., “Bonded extra”).
  • 400: Returned if the request body is invalid.
  • 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: Returned if an internal server error occurs.

3.5 Signing an Unsigned Polkadot Transaction

Once you’ve obtained an unsigned transaction from the GlobalStake API, it must be signed before broadcasting to the Polkadot network. This section explains how to sign a Polkadot transaction JSON file using the Polkadot CLI or Subkey.

Prerequisites:

  • Install Subkey or have the Polkadot-JS CLI set up.
  • Ensure access to the account keypair or private key required for signing.

Step 1: Save the Unsigned Transaction

Save the unsigned transaction JSON response as a .json file. For example:

echo ‘<unsigned_transaction_json>’ > unsigned_tx.json

Step 2: Inspect the Unsigned Transaction (Optional)

To review the transaction details before signing, you can open the JSON file in any text editor or use the CLI for inspection:

cat unsigned_tx.json

This step is optional but useful for verifying transaction details before signing.

Step 3: Sign the Transaction Using Subkey

To sign the transaction using Subkey, use the following command. Replace <path_to_keypair> with the location of your keypair file, or input the private key directly:

subkey sign-transaction –file unsigned_tx.json –suri > signed_tx.json

Step 3: Alternative Method Using Polkadot-JS CLI: If you prefer the Polkadot-JS CLI, use:

Import your keypair into Polkadot-JS CLI.

Run:
polkadot-js sign –input unsigned_tx.json –output signed_tx.json –account <your_account>

Step 4: Send the Signed Transaction

Once signed, you can submit the transaction to the Polkadot network. Using Subkey, this can be done with:

subkey submit-transaction –file signed_tx.json

Or, with the Polkadot-JS CLI:

polkadot-js send-signed –input signed_tx.json