# RPC API
# Overview
RPC API is provided by TOP AI 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 AI Network edge node.
The official domain name of the TOP AI Network edge node:
Mainnet：
mainnet.edge.topnetwork.orgTestnet：
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={"params":{"account_addr":"T8000066ab344963eaa071f9636faac26b0d1a39900325"}}&method=getAccount&sequence_id=5&identity_token=&version=1.0");curl
curl -X POST --data 'target_account_addr=T800002276a7d58218ac4978733e5cca927a7d86cb7c87&body={"params":{"account_addr":"T8000066ab344963eaa071f9636faac26b0d1a39900325"}}&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. |