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.
Each return response consists of a root JSON format of:
{
//Some information based on the transaction, e.g., funds were successfully bonded or, if there is an error, “unable to bond funds due to xyz issue”
“message”:”abc”,
//Return of data in a format that needs to be deserialized, e.g., [1,2,3] or {“x”:1}
“structured_data”:”abc”,
//Data in this field just needs to be executed and might be a raw, unsigned transaction, e.g., 0x123
“Raw-data”:”abc”,
//Whether the transaction was successful or not
“status”:”boolean”,
}
Specific to Substrate, the structured-data field would contain another serialized object:
{
//This is an encoded hexadecimal string that represents the tx to be executed on the chain. This is primary to consuming the API’s responses.
“Call_data”:””
//NOT USED RIGHT NOW
“Unsigned_call”:””
//A non-essential field which represents some information on the tx
“human_data”:””,
}
Call-data can be converted to a signable transaction using PAPI using the following:
const tx = api.txFromCallData(Binary.fromHex(callData));
const result = await tx.signAndSubmit(signer)
3.1 Bond More
Endpoint: /polkadot/bond_more
Method: POST
Description: Bonds more tokens, either to a pool or solo staking.
Request Parameters:
• address (string) – The address of the user staking.
• amount (int) – The amount you’d like to bond in planks.
Example:
{ “address”: ”0x00”, “amount”:123 }
Success Response:
{
“message”:”abc”, “structured_data”:”
{
“call_data”:””,
“unsigned_call”:””,
“human_data”:””
}
”,
”raw_data”:””,
“status”:bool
}
3.2 Unbond
Endpoint: /polkadot/unbond
Method: POST
Description: Unbonds tokens either from a pool or solo staking.
Request Parameters:
• address (string) – The address of the user staking.
• amount (int) – The amount you’d like to unbond in planks.
Example:
{ “address”: ”0x00”, “amount”:123 }
Success Response:
{
“message”:”abc”, “structured_data”:”
{
“call_data”:””,
“unsigned_call”:””,
“human_data”:””
}
”,
”raw_data”:””,
“status”:bool
}
3.3 Withdraw
Endpoint: /polkadot/withdraw
Method: POST
Description: Makes unbonded tokens transferable after the unbonding period.
Request Parameters:
• address (string) – The address of the user staking.
Example:
{ “address”: ”0x00” }
Success Response:
{
“message”:”abc”, “structured_data”:”
{
“call_data”:””,
“unsigned_call”:””,
“human_data”:””
}
”,
”raw_data”:””,
“status”:bool
}
3.4 Set Staking Proxy
Endpoint: /polkadot/set_staking_proxy
Method: POST
Description: Establishes a staking proxy.
Request Parameters:
• address (string) – The address of the user staking.
Example:
{ “address”: ”0x00” }
Success Response:
{
“message”:”abc”, “structured_data”:”
{
“call_data”:””,
“unsigned_call”:””,
“human_data”:””
}
”,
”raw_data”:””,
“status”:bool
}
3.5 Set Governance Proxy
Endpoint: /polkadot/set_governance_proxy
Method: POST
Description: Establishes a governance proxy.
Request Parameters:
• address (string) – The address of the user staking.
Example:
{ “address”: ”0x00” }
Success Response:
{
“message”:”abc”, “structured_data”:”
{
“call_data”:””,
“unsigned_call”:””,
“human_data”:””
}
”,
”raw_data”:””,
“status”:bool
}
3.6 Remove Governance Proxy
Endpoint: /polkadot/remove_staking_proxy
Method: POST
Description: Removes a staking proxy.
Request Parameters:
• address (string) – The address of the user staking.
Example:
{ “address”: ”0x00” }
Success Response:
{
“message”:”abc”, “structured_data”:”
{
“call_data”:””,
“unsigned_call”:””,
“human_data”:””
}
”,
”raw_data”:””,
“status”:bool
}
3.7 Remove Staking Proxy
Endpoint: /polkadot/remove_governance_proxy
Method: POST
Description: Removes a governance proxy.
Request Parameters:
• address (string) – The address of the user staking.
Example:
{ “address”: ”0x00” }
Success Response:
{
“message”:”abc”, “structured_data”:”
{
“call_data”:””,
“unsigned_call”:””,
“human_data”:””
}
”,
”raw_data”:””,
“status”:bool
}
3.8 Join Pool
Endpoint: /polkadot/join_pool
Method: POST
Description: Join a pool with transferable tokens.
Request Parameters:
• address (string) – The address of the user staking.
• amount (int) – The amount you’d like to bond in planks.
Example:
{ “address”: ”0x00”, “amount”:123 }
Success Response:
{
“message”:”abc”, “structured_data”:”
{
“call_data”:””,
“unsigned_call”:””,
“human_data”:””
}
”,
”raw_data”:””,
“status”:bool
}
3.9 Add Nominees
Endpoint: /polkadot/add_nominees
Method: POST
Description: Adds GlobalStake’s validators to your nominations.
Request Parameters:
• address (string) – The address of the user staking.
Example:
{ “address”: ”0x00” }
Success Response:
{
“message”:”abc”, “structured_data”:”
{
“call_data”:””,
“unsigned_call”:””,
“human_data”:””
}
”,
”raw_data”:””,
“status”:bool
}
3.10 Replace Nominees
Endpoint: /polkadot/replace_nominees
Method: POST
Description: Replaces your validator nominations with GlobalStake’s validators.
Request Parameters:
• address (string) – The address of the user staking.
Example:
{ “address”: ”0x00” }
Success Response:
{
“message”:”abc”, “structured_data”:”
{
“call_data”:””,
“unsigned_call”:””,
“human_data”:””
}
”,
”raw_data”:””,
“status”:bool
}
3.11 Get Account Info
Endpoint: /polkadot/get_account_info
Method: POST
Description:
This is a wrapper for a subscan API call, the structured data in this case would be serialized JSON meeting the format found at https://support.subscan.io/api-5471201
You can use this to find information related to balances, whether the user is in a pool or not, is solo staking, or has proxies.
Request Parameters:
• address (string) – The address of the user staking.
Example:
{ “address”: ”0x00” }
Success Response:
{
“message”:”abc”, “structured_data”:”
See note in description
”,
”raw_data”:””,
“status”:bool
}
3.12 Create Bond
Endpoint: /polkadot/create_bond
Method: POST
Description: Bonds more tokens, either to a pool or solo staking.
Request Parameters:
• payee (optional string) – The address you’d like to have rewards directed to in a transferable manner. The client’s own address is a valid input for no-compounding; if the parameter is left out, rewards will be staked.
• amount (int) – The amount you’d like to bond in planks.
Example:
{ “amount”:123, “payee”: ”xyz” }
Success Response:
{
“message”:”abc”, “structured_data”:”
{
“call_data”:””,
“unsigned_call”:””,
“human_data”:””
}
”,
”raw_data”:””,
“status”:bool
}