# RPC API

# 概述

RPC API 是 TOP AI Network 提供给社区使用的与链交互的接口，包括发送交易，查询交易信息、节点信息、主链信息等。

# 连接到 RPC

您可以连接到自己创建的 edge 节点，请参见成为矿工，也可以连接到 TOP AI Network edge 节点。

TOP AI Network edge 节点官方域名：

主网：mainnet.edge.topnetwork.org
测试网：testnet.edge.topnetwork.org

# 请求方法

方法名	说明
requestToken	在与链交互前需要先获取身份令牌。根据账户获取身份令牌（identity token），每个账户身份令牌不同。
sendTransaction	发送交易，包括转账、节点 staking、节点注册、节点投票、节点领取奖励、调用合约等。
getAccount	查询链上账户信息。
getTransaction	查询账户交易信息。
getBlock	查询区块信息。
getStandbys	查询节点候选池中节点信息。
getCGP	查询链上治理参数（on-chain governance parameters）。
getChainInfo	查询主链信息。
queryNodeInfo	查询节点信息。
queryNodeReward	查询节点奖励。
listVoteUsed	查询节点投票分布。
queryVoterDividend	查询投票者分红。
queryProposal	查询提案信息。

# 请求参数

参数名称	是否必选	默认值	类型	说明
target_account_addr	是	-	String	扩展字段，当前未使用，您可传入任意一个账户地址。
body	是	-	Object	body 里为具体业务参数，需将 JSON 格式转化成 Text 格式。业务参数说明请参见各接口“请求参数”。
method	是	-	String	请求方法。
sequence_id	是	-	String	客户端会话次数，递增。
identity_token	是	-	String	与链交互前首先需要获取链访问身份令牌（identity token），身份令牌因账户不同而不同。当前未对该字段进行校验。
version	是	1.0	String	RPC API 版本。

# 请求样例

请求方式：POST

以查询链上账户信息为例：

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

# 返回结构

返回体为 JSON 结构。

{
   "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"
}

返回参数说明

参数名称	类型	说明
data	Object	返回各接口具体业务数据。
errmsg	String	错误信息。
errno	Int	错误码。
sequence_id	String	客户端会话次数，递增。

# 错误码

RPC 标准错误码：

代码	错误类型	返回信息	说明
-32700	服务器解析错误。	body json parse error json parse errorrpc param error	服务器收到无效的 JSON。服务器解析 JSON 文本发生错误。
-32602	无效的方法参数	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	方法参数丢失或者无效的方法参数（参数类型错误）。

自定义错误码：

错误码	错误类型	返回信息	说明
0	交易投递状态	OK	交易被投递成功，进入共识，不代表交易最终共识状态，交易共识最终状态需要通过交易 hash 查询。
1	业务相关的参数错误	version must be 1.0 now	RPC API 版本必须是 1.0 版本。
		transaction hash error	交易 hash 错误。
		transaction sign error	交易签名错误。
		Whitelist check failed	白名单检查失败。
		Source address and destination address are the same	源地址，目的地址相同（交易检查）。
		Insufficient deposit	保证金不足。
		duration expiration check failed	交易超时。
		Transfer amount is 0	转账金额为 0。
		Transfer amount is greater than 20 billion TOP	转账金额大于 200 亿 TOP。
		Voting check failed	投票检查失败。
		transaction validation check failed (*)	交易检查失败（错误码）。括号内的详细错误码参见下方的交易检查子错误码表。
2	未知错误	unknown exception	未知错误。
3	Shard 执行错误	account not found on chain	在链上未查询到此账户信息。
		account address or transaction hash error/does not exist	在链上未查询到此交易（交易既不在交易池又不在区块，可能账户地址或者 hash 错误/不存在）。
		account address does not exist or block height does not exist	区块不存在（可能账户不存在、高度不存在）。
		unknown msg type	发送了交易和查询之外的消息类型。
		request time out	请求超时。
110	请求限流	request too often	流控开启时，同一账户、同一 IP 地址 1 秒最多发送 10 次请求。

交易检查子错误码：

错误码	说明
2949139	交易类型错，或使用了非法字段。
2949137	交易长度检查失败。
2949121	地址格式检查失败。
2949142	销毁交易检查失败。
2949141	本地合约交易检查失败。
2949134	系统合约交易检查失败。