# RPC API

# Overview

RPC API is provided by TOP Network to the community to interact with the chain, including sending transactions and retrieving information on the chain: transaction information, node information, mainchain information, etc.

# Connect to RPC API

You can connect to your own edge node, or you can connect to the TOP Network edge node.

The official domain name of the TOP Network edge node:

  • Mainnet:mainnet.edge.topnetwork.org

  • Testnet:testnet.edge.topnetwork.org

# Methods

Method Description
requestToken Please get the identity token before interacting with the chain.
The identity token is different for each account.
sendTransaction Transfer, staking, node registration, voting,claiming rewards, etc.
getAccount Get account information on the chain.
getTransaction Get transaction details.
getBlock Get block by account address.
getStandbys Get candidate nodes.
getCGP Get on-chain governance parameters.
getChainInfo Get the mainchain information.
queryNodeInfo Get node information by account address.
queryNodeReward Get node reward.
listVoteUsed Get the distribution of node used votes.
queryVoterDividend Get voter dividend.
queryProposal Get proposal details.

# Request Parameters

Parameter Name Required Default Value Parameter Type Description
target_account_addr Yes - String Extension field, not currently in use, you can fill in any account address.
body Yes - Object The body defines business parameters, the JSON format needs to be serialized into String format.
method Yes - String Request method.
sequence_id Yes - String Number of client sessions, increasing.
identity_token Yes - String Please get the identity token before interacting with the chain.
The identity token is different for each account.
This field is not validated.
version Yes 1.0 String RPC API version.

# Request Sample

Request Approach: POST.

Take getting account information on chain as an example:

  • C++

    auto account_info_response = client.request("POST", "/", "target_account_addr=T800002276a7d58218ac4978733e5cca927a7d86cb7c87&body=%7b%22params%22%3a%7b%22account_addr%22%3a%22T8000066ab344963eaa071f9636faac26b0d1a39900325%22%7d%7d&method=getAccount&sequence_id=5&identity_token=&version=1.0");
    
  • curl

    curl -X POST --data 'target_account_addr=T800002276a7d58218ac4978733e5cca927a7d86cb7c87&body=%7b%22params%22%3a%7b%22account_addr%22%3a%22T8000066ab344963eaa071f9636faac26b0d1a39900325%22%7d%7d&method=getAccount&sequence_id=5&identity_token=&version=1.0'  http://localhost:19081
    

# Response Sample

The return body is a JSON structure.

{
   "data" : {
      "account_addr" : "T800002276a7d58218ac4978733e5cca927a7d86cb7c87",
      "available_gas" : 25000,
      "balance" : 100000000000000,
      "burned_token" : 0,
      "cluster_id" : 1,
      "contract_address" : [T30000MaSkcvg2iyqMRDRMFnTQ8o5237Xs1dT9TR],
      "created_time" : 1596520429,
      "disk_staked_token" : 0,
      "group_id" : 64,
      "gas_staked_token" : 0,
      "latest_tx_hash" : "0xfcd8843c36b1c8fee81bcac7e7cf2b38682deef723e9a237918b70b3a6dfc4c9",
      "latest_tx_hash_xxhash64" : "0xdb73d04d0f5daa84",
      "latest_unit_height" : 1,
      "lock_balance" : 0,
      "lock_deposit_balance" : 0,
      "lock_gas" : 0,
      "nonce" : 1,
      "total_free_gas" : 25000,
      "total_gas" : 25000,
      "total_stake_gas" : 0,
      "unlock_disk_staked" : 0, 
      "unlock_gas_staked" : 0,
      "unused_free_gas" : 25000,
      "unused_stake_gas" : 0,
      "unused_vote_amount" : 0,
      "vote_staked_token" : 0,
      "zone_id" : 0
   },
   "errmsg" : "ok",
   "errno" : 0,
   "sequence_id" : "5"
}

Return parameter description

Parameter Name Parameter Type Description
data Object Return the specific business data of each interface.
errmsg String Error message.
errno Int Error number.
sequence_id String Number of client sessions, increasing.

# Error Code

RPC Standard Errors:

Error Code Error Type Return Message Description
-32700 Parse error. body json parse error json parse errorrpc param error Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
-32602 Miss params or invalid params. miss param params account_addr or account_addr is not valid
miss param params amount or amount is not valid
miss param params last_hash or last_hash is not valid
miss param params nonce or nonce is not valid
miss param params data or data is not valid
miss param params tx_deposit or tx_deposit is not valid
miss param params to_ledger_id or to_ledger_id is not valid
miss param params from_ledger_id or from_ledger_id is not valid
miss param params tx_type or tx_type is not valid
miss param params tx_len or tx_len is not valid
miss param params send_timestamp or send_timestamp is not valid
miss param params tx_random_nonce or tx_random_nonce is not valid
miss param params last_tx_nonce or last_tx_nonce is not valid
miss param params challenge_proof or challenge_proof is not valid
miss param params tx_hash
miss param sender_action
miss param receiver_action
miss param sender_action action_hash
miss param sender_action action_type
miss param sender_action action_size
miss param sender_action account_addr
miss param sender_action action_name
miss param sender_action action_param
miss param sender_action action_authorization
miss param receiver_action action_hash
miss param receiver_action action_type
miss param receiver_action action_size
miss param receiver_action account_addr
miss param receiver_action action_name
miss param receiver_action action_param
miss param receiver_action action_authorization
miss param method or method is not valid
miss param version or version is not valid
miss param sequence_id or version is not valid
msg list is empty
Miss method parameter(s) or invalid method parameter(s) (parameter type error).

Custom Errors:

Error Code Error Type Return Message Description
0 Transaction delivery status. OK When the transaction is delivered successfully, it enters into consensus, which does not represent the final consensus status of the transaction. The final status of the transaction consensus needs to be inquired through the transaction hash.
1 Business related parameter error. version must be 1.0 now RPC API version must be 1.0.
transaction hash error -
transaction sign error -
Whitelist check failed -
Source address and destination address are the same In transaction check, source address and destination address are the same.
Insufficient deposit -
duration expiration check failed -
Transfer amount is 0 -
Transfer amount is greater than 20 billion TOP -
Voting check failed -
transaction validation check failed (*) Transaction check failed (error code). For detailed error codes in brackets, see the Sub Error Code for Transaction Check table below.
2 Unknown error unknown exception -
3 Shard execution error. account not found on chain -
account address or transaction hash error/does not exist This transaction was not found on the chain (the transaction is neither in the transaction pool nor in the block, possibly the account address or hash error/does not exist).
account address does not exist or block height does not exist Block does not exist (possibly account address or block height does not exist).
unknown msg type Messages other than transactions and queries were sent.
request time out -
110 request limit When flow control is enabled, the same account and the same IP address can send up to 10 requests per second.

Sub Error Code for Transaction Check:

Error Code Description
2949139 Incorrect transaction type, or an illegal field is used.
2949137 Transaction length check failed.
2949121 Address format check failed.
2949142 Destruction transaction check failed.
2949141 Local contract transaction check failed.
2949134 System contract transaction check failed.