# NULS2.0 API接口文档

# 简介

每个NULS2.0节点都可选的提供了一套API接口,用于从节点获取可视化区块链数据,使得开发区块链应用变得十分方便。接口通过 JSON-RPC 的方式提供,底层使用HTTP协议进行通讯。

要启动一个提供RPC服务的节点,需做到以下几个步骤:

  • 获取钱包

方式一:下载能提供RPC服务的全节点钱包(http://正式上线后填充 下载地址链接)

方式二:同步https://github.com/nuls-io/nuls-v2上NULS2.0项目master分支的源代码,执行如下命令,手动打包全节点钱包:

./package -a api-module
./package
  • 节点服务器需安装mongoDB数据库
  • 修改module.ncf文件,[api-module]的相关配置,如下:
[api-module]
#数据库url地址
databaseUrl=127.0.0.1
#数据库端口号
databasePort=27017

完成配置后,启动节点程序,客户端会解析已同步的区块,并存储到mongoDB中。

# 监听端口

默认端口为18003,可修改module.ncf文件,[api-module]的相关配置,如下:

[api-module]
#api-module模块对外的rpc端口号
rpcPort=18003

# 接口说明

# 字符集编码

UTF-8

# 远程调用协议

JSON-RPC

{
	"jsonrpc":"2.0",
	"method":"getChainInfo",		//接口名称
	"params":[],					//所有接口的参数,都已数组方式传递,且参数顺序不能变
	"id":1234
}

# 接口返回格式

正常返回
//example
{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
         "networkHeight": 4936,
         "localHeight": 4936
     }
}
异常返回
//example
{
     "jsonrpc": "2.0",
     "id": 1234,
     "error": {
          "code": 1000,
          "message": "Parameters is wrong!",
          "data": "Incorrect number of parameters"
     }
}

# 代币转换

涉及到有代币的接口,参数和返回里的代币数量为了避免小数精度丢失,统一转为BigInteger格式。NULS主网的小数精度为8位,因此接口层统一右移8位,即100,000,000 = 1NULS。

# 返回数据定义

# 交易类型(txType)

    int COIN_BASE = 1;						//coinBase奖励
    int TRANSFER = 2;						//转账
 	int ACCOUNT_ALIAS = 3;					//设置账户别名
   	int REGISTER_AGENT = 4;					//新建共识节点
   	int DEPOSIT = 5;						//委托参与共识
    int CANCEL_DEPOSIT = 6;					//取消委托
    int YELLOW_PUNISH = 7;					//黄牌惩罚
    int RED_PUNISH = 8;						//红牌惩罚
    int STOP_AGENT = 9;						//注销共识节点
    int CROSS_CHAIN = 10;					//跨链转账
	int REGISTER_CHAIN_AND_ASSET = 11;		//注册链
    int DESTROY_CHAIN_AND_ASSET = 12;		//销毁链
    int ADD_ASSET_TO_CHAIN = 13;			//新增资产上链
   	int REMOVE_ASSET_FROM_CHAIN = 14;		//注销资产
    int CREATE_CONTRACT = 15;				//创建智能合约
    int CALL_CONTRACT = 16;					//调用智能合约
    int DELETE_CONTRACT = 17;				//删除智能合约
    int CONTRACT_TRANSFER = 18;				//合约内部转账
    int CONTRACT_RETURN_GAS = 19;			//合约执行手续费返还
    int CONTRACT_CREATE_AGENT = 20;			//合约创建共识节点
	int CONTRACT_DEPOSIT = 21;				//合约委托参与共识
 	int CONTRACT_CANCEL_DEPOSIT = 22;		//合约取消委托
 	int CONTRACT_STOP_AGENT = 23;			//合约注销共识节点

# 资产信息(assetInfo)

assetInfo:{
    "key": "100-1",						//string	主键
    "chainId": 100,						//int		资产的链id 		
    "assetId": 1,						//int		资产id
    "symbol": "NULS",					//string	资产符号
    "decimals":8						//int		资产支持小数位
    "initCoins": 100000000000000,		//bigInt	资产初始金额
    "address": "tNULSeBaMoodYW7A……",	//string	资产创建人地址			
    "status": 1							//int		状态, 0:注销	1:启用
}


# 区块头信息(blockHeaderInfo)

blockHeaderInfo: {
    "hash": "c31d198b6fb5a……",					//string	区块hash
    "height": 304,								//long		区块高度
    "preHash": "d7596990d508……",				//string	前一区块hash
    "merkleHash": "85c661b36aa3fdc……",			//string	梅克尔hash
    "createTime": 1559725301,					//long		创建时间
    "agentHash": null,							//string	出块节点的hash
    "agentId": "8CPcA7kaXSHbWb3GHP7……",			//string	出块节点的id
    "packingAddress": "8CPcA7kaXSH……",			//string	出块节点的区块打包地址
    "agentAlias": null,							//string	出块节点的代理人别名
    "txCount": 1,								//int		区块打包交易数量
    "roundIndex": 155972530,					//long		出块轮次
    "totalFee": 0,								//bigInt	打包的交易手续费
    "reward": 0,								//bigInt	出块奖励
    "size": 235,								//long		区块大小
    "packingIndexOfRound": 1,					//int		本轮的出块顺序
    "scriptSign": "210e2ab7a219bca2a……",		//string	区块签名
    "txHashList": [								//[string]	区块打包的交易对应的交易hash集合
        "85c661b36aa3fdc93b9bc27bb8fdf1……"
    ],
    "roundStartTime": 1559725291,				//long		本轮出块的起始出块时间
    "agentVersion": 1,							//int		出块节点的协议版本号
    "seedPacked": true							//boolean	当前区块是否是种子节点打包
}

# 交易信息(txInfo)

txInfo: {
    "hash": "0020b15e564……",				//string	交易hash
    "type": 2,								//int 		交易类型(txType)
    "height": -1,							//long		确认交易的区块高度,-1表示还未被确认
    "size": 228,							//int		交易大小
    "createTime": 1552300674920,			//long		创建时间
    "remark": "transfer test",				//string	备注
    "txData": null,							//object	交易业务对象,根据交易类型区分,
    													具体见后面的数据定义
    "txDataHex": null,						//string	业务对象16进制序列化字符串
    "txDataList": null,						//[object]	交易业务对象集合,根据交易类型区分
    "fee": { 								//bigInt	手续费
        "chainId": 100,						//手续费链id
        "assetId": 1,						//手续费资产id
        "symbol": "ATOM",					//手续费资产符号
        "value": 100000						//手续费金额
    },
    "coinFroms": [
    {
        "address": "5MR_2CbSSboa……",			//string	转出地址
        "chainId": 12345,						//int		转出资产的链id
        "assetsId": 1,							//int		转出资产的id
        "amount": 1870000000000,				//bigInt	转出金额	
        "locked": 0,							//long		锁定时间
        "nonce": "ffffffff"						//string	转出资产最新nonce值
        "symbol":"nuls"							//string	资产符号
    }
    ],
    "coinTos": [
    {
        "address": "5MR_2CbSSboa……",			//string	接收地址
        "chainId": 12345,						//int		接收资产的链id
        "assetsId": 1,							//int		接收资产的id
        "amount": 1870000000000,				//bigInt	接收金额	
        "locked": 0,							//long		锁定时间
        "symbol":"nuls"							//string	资产符号
    }
    ],
    "value": 1860000000000						//bigInt	交易涉及到的资产变动额
}

# 账户信息(accountInfo)

accountInfo: {
    "address": "5MR_2ChNj……",					//string	账户地址
    "alias": null,								//string	账户别名
    "type": 1,									//int		账户类型 
                                                //1:普通地址	2:合约地址	3:多签地址
    "txCount": 8,								//int		交易笔数
    "totalOut": 0,								//bigInt	总支出
    "totalIn": 1000000000000000,				//bigInt	总收入
    "consensusLock": 0,							//bigInt	本链默认资产共识锁定
    "timeLock": 0,								//bigInt	本链默认资产时间锁定
    "balance": 1000000000000000,				//bigInt	本链默认资产可用余额
    "totalBalance": 1000000000000000,			//bigInt	本链默认资产总额
    "totalReward": 0,							//bigInt	共识总奖励
    "tokens": []								//[string]	拥有的nrc20资产符号列表
}

# 资产信息(accountLedgerInfo)

accountLedgerInfo: {
    "address": "tNULSeBaMrbMRiFAUeeAt……",			//string	账户地址
    "chainId": 2,									//int		资产的链id
    "assetId": 1,									//int		资产的id
    "symbol": "NULS",								//string	资产的符号
    "totalBalance": 1000000000000000,				//bigInt	资产总额
    "balance": 1000000000000000,					//bigInt	可用余额
    "timeLock": 0,									//bigInt	时间锁定
    "consensusLock": 0								//bigInt	共识锁定
}

# 共识节点信息(consensusInfo)

 {
     "txHash": "0020c734c7ec……",				//string	创建共识节点的交易hash
     "agentId": "e4ae68a2",						//string	节点id
     "agentAddress": "5MR_2CfWGwnfh……",			//string	创建节点的代理账户地址
     "packingAddress": "5MR_2CeXYdnth……",		//string	节点负责打包区块的账户地址
     "rewardAddress": "5MR_2CeXYdnt……",			//string	节点获取共识奖励的账户地址
     "agentAlias": null,						//string	节点的代理地址别名
     "deposit": 2000000000000,					//bigInt	创建节点时代理节点的保证金
     "commissionRate": 10,						//int		节点收取的佣金比例,单位%
     "createTime": 1552300674920,				//long		节点的创建时间
     "status": 0,								//int		节点状态 
     											//0:待共识, 1:共识中, 2:已注销
     "totalDeposit": 20000000000000,			//bigInt	委托参与共识总金额
     "depositCount": 0,							//int		委托次数
     "creditValue": 0,							//double	信用值 取值[-1,1]
     "totalPackingCount": 3966,					//int		节点已打包出块总数
     "lostRate": 0,								//double	丢块率
     "lastRewardHeight": 8000,					//long		最后一次出块获取奖励的区块高度
     "deleteHash": null,						//string	注销节点的交易hash
     "blockHeight": 67,							//long		创建节点时的区块高度
     "deleteHeight": 0,							//long		注销节点时的区块高度
     "totalReward": 1256976254880,				//bigInt	总共识奖励				                                                       totalReward=commissionReward+agentReward
     "commissionReward": 1256976254880,			//bigInt	委托共识奖励
     "agentReward": 0,							//bigInt	节点获取奖励
     "roundPackingTime": 0,						//long		当前轮次节点负责打包区块的时间
     "version": 1,								//int		节点的协议版本号
     "type": 1,									//int		1:普通节点,2:开发者节点,3:大使节点
 }

# 委托共识信息(depositInfo)

depositInfo:{
    "txHash": "0020dd1b606191068566c……",			//string	委托共识的交易hash
    "amount": 20000000000000,						//bigint	委托金额		
    "agentHash": "0020c734c7ecf447……",				//string	委托的共识节点的交易hash
    "address": "5MR_2CfWGwnfhPcdnho……",				//string	委托人的账户地址
    "createTime": 1552292357109,					//long		委托时间
    "blockHeight": 69,								//long		委托时的区块高度
    "deleteHeight": 0,								//long		取消委托时的区块高度
    "type": 0										//int		0:委托, 1:取消委托
    "fee": { 										//bigInt	委托交易的手续费
        "chainId": 100,								//手续费链id
        "assetId": 1,								//手续费资产id
        "symbol": "ATOM",							//手续费资产符号
        "value": 100000								//手续费金额
    },
}

# 接口列表

# 链相关接口[chain]

# 查询本链信息

请求:

{
    "jsonrpc":"2.0",
    "method":"getChainInfo",
    "params":[],
    "id":1234
}

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "chainId": 100,								//本链的id
          "chainName": "nuls",							//链名称
          "defaultAsset": {assetInfo},					//本链默认资产信息
          "assets": [									//本链所有资产信息集合
               {assetInfo}
          ],
          "seeds": [									//链的共识种子节点地址
               "8CPcA7kaXSHbWb3GHP7bd5hRLFu8RZv57rY9w"	
          ],
          "inflationCoins": 500000000000000,			//本链默认资产的通胀代币数量/年
          "status": 1									//状态:0 注销,1启用
     }
}

# 查询链运行后的通用信息

请求:

{
    "jsonrpc":"2.0",
    "method":"getInfo",
    "params":[chainId],
    "id":1234
}
//参数说明
chainId: int									//本链的id

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "networkHeight": 278,							//网络最新区块高度
          "localHeight": 278							//当前节点已同步的区块高度
          "defaultAsset": {								//本链默认资产信息
               "symbol": "NULS",						//资产符号
               "chainId": 2,							//资产链ID
               "assetId": 1,							//资产ID
               "decimals": 8							//支持小数位
          },
          "agentAsset": {								//本链参与共识所用资产信息
               "symbol": "NULS",
               "chainId": 2,
               "assetId": 1,
               "decimals": 8
          },
          "isRunCrossChain": true,						//是否支持跨链
          "isRunSmartContract": true					//是否启用智能合约
     }
}

# 查询其他已注册跨链的链信息

请求:

{
    "jsonrpc":"2.0",
    "method":"getOtherChainList",
    "params":[chainId],
    "id":1234
}
//参数说明
chainId: int									//本链的id

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": [
          {
               "chainName": "nuls2",					//链名称
               "chainId": 2								//链id
          }
     ]
}

# 区块相关接口[block]

# 查询最新区块头

请求:

{
    "jsonrpc":"2.0",
    "method":"getBestBlockHeader",
    "params":[chainId],
    "id":1234
}
//参数说明
chainId: int									//链的id

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {blockHeaderInfo}						//区块头信息
}

# 根据高度查询区块头

请求:

{
    "jsonrpc":"2.0",
    "method":"getHeaderByHeight",
    "params":[chainId, blockHeight],
    "id":1234
}
//参数说明
chainId: int									 //链的id
blockHeight:long								//区块高度

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {blockHeaderInfo}						//区块头信息
}

# 根据区块hash查询区块头

请求:

{
    "jsonrpc":"2.0",
    "method":"getHeaderByHash",
    "params":[chainId, blockHash],
    "id":1234
}
chainId: int									 //链的id
blockHash:string								//区块hash

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {blockHeaderInfo}						//区块头信息
}

# 根据高度查询完整区块

请求:

{
    "jsonrpc":"2.0",
    "method":"getBlockByHeight",
    "params":[chainId, blockHeight],
    "id":1234
}
//参数说明
chainId: int									 //链的id
blockHeight:long								//区块高度

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
     	"header":{blockHeaderInfo},						//区块头信息
     	"txList":[										//打包的交易信息
     		{txInfo}
     	]
     }						
}

# 根据区块hash查询完整区块

请求:

{
    "jsonrpc":"2.0",
    "method":"getBlockByHash",
    "params":[chainId, blockHash],
    "id":1234
}
//参数说明
chainId: int									 //链的id
blockHash:string								//区块hash

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
     	"header":{blockHeaderInfo},						//区块头信息
     	"txList":[										//打包的交易信息
     		{txInfo}
     	]
     }						
}

# 查询区块头列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getBlockHeaderList",
    "params":[chainId,pageNumber,pageSize, isHidden, packedAddress],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
isHidden:boolean								//是否隐藏只有共识奖励交易的块 
packedAddress:string							//根据区块打包地址过滤,非必填

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 7,
          "list": [
               {blockHeaderInfo}
          ]
     }
}

# 账户相关的接口[account]

# 查询账户详细信息

请求:

{
    "jsonrpc":"2.0",
    "method":"getAccount",
    "params":[chainId,address],
    "id":1234
}
//参数说明
chainId: int									//链的id
address: string									//账户地址

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {accountInfo}					//账户信息
}

# 根据别名查询账户详细信息

请求:

{
    "jsonrpc":"2.0",
    "method":"getAccountByAlias",
    "params":[chainId,alias],
    "id":1234
}
//参数说明
chainId: int									//链的id
alias: string									//账户别名

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {accountInfo}					//账户信息
}

# 查询持币账户排名

请求:

{
    "jsonrpc":"2.0",
    "method":"getCoinRanking",
    "params":[chainId,pageNumber,pageSize,sortType],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
sortType:int									//排序方式 0:总余额倒序	1:总余额正序

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
               {
                    "address": "tNULSeBaMmTNYqywL5ZSHbyAQ662uE3wibrgD1",
                    "alias": null,
                    "type": 1,
                    "totalBalance": 1000000000000000,				//余额
                    "totalOut": 0,									//总支出
                    "totalIn": 1000000000000000						//总收入
               }
               ……
          ]
     }
}

# 查询账户本链资产列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getAccountLedgerList",
    "params":[chainId,address],
    "id":1234
}
//参数说明
chainId: int									//链的id
address: string									//账户地址

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": [
          {accountLedgerInfo}
     ]
}

# 查询账户跨链资产列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getAccountCrossLedgerList",
    "params":[chainId,address],
    "id":1234
}
//参数说明
chainId: int									//链的id
address: string									//账户地址

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": [
          {accountLedgerInfo}
     ]
}

# 查询账户单个资产余额

请求:

{
    "jsonrpc":"2.0",
    "method":"getAccountBalance",
    "params":[chainId,assetChainId,assetId,address],
    "id":1234
}
//参数说明
chainId: int									//本链的id
assetChainId: int								//资产的链id
assetId: int									//资产的id
address: string									//账户地址

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "totalBalance": 1000000000000000,					//bigInt	资产总额
          "balance": 1000000000000000,						//bigInt	可用余额
          "timeLock": 0,									//bigInt	时间锁定金额
          "consensusLock": 0,								//bigInt	共识锁定金额
          "freeze": 0,										//bigInt	交易未确认金额
          "nonce": "0000000000000000",						//string	资产的nonce值
          "nonceType": 1									//int		nonce值是否已确认
          													// 0:未确认, 1:已确认
     }
}

# 查询账户锁定金额列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getAccountFreezes",
    "params":[chainId,pageNumber,pageSize,address],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
address: string									//账户地址

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "txHash":"d3ks2x9bAl38bfsl……" 		//交易hash
          "type":1								//锁定类型 
          										//1:时间锁定, 2:高度锁定, 3:共识锁定
          "time":1552300674920					//生成时间
          "lockedValue":155650000000			//锁定值
          "amount":100000000					//锁定金额
          "reason":"共识奖励"					 //锁定原因
     }
}

# 查询别名是否可用

请求:

{
    "jsonrpc":"2.0",
    "method":"isAliasUsable",
    "params":[chainId,alias],
    "id":1234
}
//参数说明
chainId: int									//链的id
alias:string									//别名

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "value": true							//boolean	true: 可用, false: 不可用
     }
}

# 交易相关接口[transaction]

# 查询交易详情

请求:

{
    "jsonrpc":"2.0",
    "method":"getTx",
    "params":[chainId,txHash],
    "id":1234
}
//参数说明
chainId: int									//链的id
txHash: string									//交易hash	

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {txInfo}
}

# 查询交易列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getAccountTxs",
    "params":[chainId,pageNumber,pageSize,address,txType,isHidden],                       
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
txType:int										//交易类型(txType),type=0时查询所有交易
isHidden:boolean								//是否隐藏共识奖励交易(txType=1的交易)

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
               {
                    "txHash": "a8611112f2b35385ee84f85……",		//交易hash
                    "address": "tNULSeBaMrbMRiFA……",			//账户地址
                    "type": 1,									//交易类型
                    "createTime": 1531152,						//交易时间,单位秒
                    "height": 0,								//交易被打包确定的区块高度
                    "chainId": 2,								//资产的链id
                    "assetId": 1,								//资产id
                    "symbol": "NULS",							//资产符号
                    "values": 1000000000000000,					//交易金额
                    "fee": { 									//bigInt	手续费
                        "chainId": 100,							//手续费链id
                        "assetId": 1,							//手续费资产id
                        "symbol": "ATOM",						//手续费资产符号
                        "value": 100000							//手续费金额
                    },
                    "balance": 1000000000000000,				//交易后账户的余额
                    "transferType": 1,							// -1:转出, 1:转入
                    "status": 1									//交易状态 0:未确认,1:已确认
               }
          ]
     }
}

# 查询区块打包的交易

请求:

{
    "jsonrpc":"2.0",
    "method":"getBlockTxList",
    "params":[chainId,pageNumber,pageSize,blockHeight,txType], 
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
blockHeight:long								//区块高度
txType:int										//交易类型(txType),type=0时查询所有交易

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
               {
                    "txHash": "a8611112f2b35385ee84f85……",		//交易hash
                    "address": "tNULSeBaMrbMRiFA……",			//账户地址
                    "type": 1,									//交易类型
                    "createTime": 1531152,						//交易时间,单位秒
                    "height": 0,								//交易被打包确定的区块高度
                    "chainId": 2,								//资产的链id
                    "assetId": 1,								//资产id
                    "symbol": "NULS",							//资产符号
                    "values": 1000000000000000,					//交易金额
                    "fee": { 									//bigInt	手续费
                        "chainId": 100,							//手续费链id
                        "assetId": 1,							//手续费资产id
                        "symbol": "ATOM",						//手续费资产符号
                        "value": 100000							//手续费金额
                    },
                    "balance": 1000000000000000,				//交易后账户的余额
                    "transferType": 1,							// -1:转出, 1:转入
                    "status": 1									//交易状态 0:未确认,1:已确认
               }
          ]
     }
}

# 查询账户的交易列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getAccountTxs",
    "params":[chainId,pageNumber,pageSize,address,txType,isHidden],                       
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
address: string									//账户地址
txType:int										//交易类型(txType),type=0时查询所有交易
isHidden:boolean								//是否隐藏共识奖励交易(txType=1的交易)

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
               {
                    "txHash": "a8611112f2b35385ee84f85……",		//交易hash
                    "address": "tNULSeBaMrbMRiFA……",			//账户地址
                    "type": 1,									//交易类型
                    "createTime": 1531152,						//交易时间,单位秒
                    "height": 0,								//交易被打包确定的区块高度
                    "chainId": 2,								//资产的链id
                    "assetId": 1,								//资产id
                    "symbol": "NULS",							//资产符号
                    "values": 1000000000000000,					//交易金额
                    "fee": { 									//bigInt	手续费
                        "chainId": 100,							//手续费链id
                        "assetId": 1,							//手续费资产id
                        "symbol": "ATOM",						//手续费资产符号
                        "value": 100000							//手续费金额
                    },
                    "balance": 1000000000000000,				//交易后账户的余额
                    "transferType": 1,							// -1:转出, 1:转入
                    "status": 1									//交易状态 0:未确认,1:已确认
               }
          ]
     }
}

# 验证离线组装交易是否合法

请求:

{
    "jsonrpc":"2.0",
    "method":"validateTx",
    "params":[chainId, txHex], 
    "id":1234
}
//参数说明
chainId: int									//链的id
txHex: string									//组装的交易序列化后的16进制字符串

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "value": "46b90763901898c0c250bd749……"				//交易hash
     }
}

# 广播离线组装交易

请求:

{
    "jsonrpc":"2.0",
    "method":"broadcastTx",
    "params":[chainId, txHex], 
    "id":1234
}
//参数说明
chainId: int									//链的id
txHex: string									//组装的交易序列化后的16进制字符串

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "value": true							//true广播成功,false广播失败
     }
}

# 共识相关接口[consensus]

# 查询可委托共识节点列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getConsensusNodes",
    "params":[chainId,pageNumber,pageSize,type],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
type:int										//节点类型
												//0:所有节点,1:普通节点,2:开发者节点,3:大使节点

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
               {conesnsusInfo}
          ]
     }
}

# 查询所有委托共识节点列表(包括已退出、或被红牌罚下的)

请求:

{
    "jsonrpc":"2.0",
    "method":"getAllConsensusNodes",
    "params":[chainId,pageNumber,pageSize],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
               {conesnsusInfo}
          ]
     }
}

# 查询账户委托的共识节点列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getAccountConsensus",
    "params":[chainId,pageNumber,pageSize, address],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
address:string									//账户地址

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
           		{conesnsusInfo}
          ]
     }
}

# 查询共识节点详情

请求:

{
    "jsonrpc":"2.0",
    "method":"getConsensusNode",
    "params":[chainId,txHash],
    "id":1234
}
//参数说明
chainId: int									//链的id
txHash:string									//创建节点时的交易hash

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {conesnsusInfo}
}

# 查询账户创建的共识节点详情

请求:

{
    "jsonrpc":"2.0",
    "method":"getAccountConsensusNode",
    "params":[chainId,address],
    "id":1234
}
//参数说明
chainId: int									//链的id
address:string									//账户地址

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {conesnsusInfo}
}

# 查询节点委托中列表信息

请求:

{
    "jsonrpc":"2.0",
    "method":"getConsensusDeposit",
    "params":[chainId,pageNumber,pageSize,txHash],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
txHash:string									//创建节点时的交易hash

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
           		{depositInfo}
          ]
     }
}

# 查询节点历史委托列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getAllConsensusDeposit",
    "params":[chainId,pageNumber,pageSize,txHash,type],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
txHash:string									//创建节点时的交易hash
type:int										//0:加入委托,1:退出委托,2:所有  

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
           		{depositInfo}
          ]
     }
}

# 查询账户的委托列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getAccountDeposit",
    "params":[chainId,pageNumber,pageSize,address,agentHash],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
address:string									//账户地址	
txHash:string									//创建节点时的交易hash,为空时查询账户所有委托

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
           		{depositInfo}
          ]
     }
}

# 查询账户的委托总额

请求:

{
    "jsonrpc":"2.0",
    "method":"getAccountDepositValue",
    "params":[chainId,address,agentHash],
    "id":1234
}
//参数说明
chainId: int									//链的id
address:string									//账户地址	
txHash:string									//创建节点时的交易hash,为空时查询账户所有委托

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": 10000000000						//委托总额
}

# 查询共识惩罚列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getPunishList",
    "params":[chainId,pageNumber,pageSize,0,agentAddress],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
type:int							 			//惩罚类型  0:查询所有,1:黄牌,2:红牌
agentAddress:string								//共识节点的代理账户地址	

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
           		{
           			"txHash":				//string	惩罚交易hash
           			"type":					//int		惩罚类型 1:黄牌,2:红牌
           			"address":				//string	惩罚共识节点的代理账户地址
           			"time":					//long		惩罚时间
           			"blockHeight":			//long		惩罚交易的区块高度
           			"roundIndex":			//long		区块的轮次		
           			"packageIndex":			//long		打包的序列号
           			"reason":				//string	惩罚原因
           		}
          ]
     }
}

# 查询轮次列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getRoundList",
    "params":[chainId,pageNumber,pageSize],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 1,
          "totalCount": 4036,
          "list": [
               {
                    "index": 155233203,				//long	共识轮次
                    "startTime": 1552371670001,		//long	当前轮起始时间
                    "memberCount": 2,				//int	当前轮出块节点数
                    "endTime": 1552371690001,		//long	当前轮结束时间
                    "redCardCount": 0,				//int	本轮罚出红牌数量
                    "yellowCardCount": 0,			//int	本轮发出黄牌数量
                    "producedBlockCount": 1,		//int	本轮共计出块数量
                    "startHeight": 8000,			//long	本轮起始高度
                    "endHeight": 0,					//long	本轮结束高度	
                    "lostRate": 0					//double 丢块率
               }
          ]
     }
}

# 智能合约相关接口[contract]

# 查询合约详情

请求:

{
    "jsonrpc":"2.0",
    "method":"getContract",
    "params":[chainId, contractAddress],
    "id":1234
}
chainId: int									//链的id
contractAddress:string							//智能合约地址

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "contractAddress": "tNULSeBaNC46Z66DgU……",		//string	合约地址
          "creater": "tNULSeBaMvEtDfvZuu……",				//string	合约创建人地址
          "createTxHash": "00209d28833258b192493……",		//string	创建合约的交易hash
          "blockHeight": 15,								//long		创建合约的区块高度
          "success": true,									//boolean	是否创建成功
          "balance": 0,										//bigInt	合约的NULS余额
          "errorMsg": null,									//string	创建失败的错误信息
          "status": 0,										//int		合约状态
          									-1:执行失败,0:未认证,1:正在审核,2:通过验证,3:已删除
          "certificationTime": 0,							//long		认证时间
          "createTime": 1553336525059,						//long		合约创建时间
          "remark": "create contract test",					//string	备注
          "txCount": 2,										//int		合约相关的交易
          "deleteHash": null,								//string	删除合约的交易hash
          "methods": [										//[object]	合约包含的函数
               {
                    "name": "name",							//string	接口名称
                    "returnType": "String",					//string	返回值类型
                    "params": []							//[object]	接口参数
               }
          ],
          "nrc20": true,									//boolean	是否是nrc20合约
          "tokenName": "KQB",								//string	token名称		
          "symbol": "KQB",									//string	token符号
          "decimals": 2,									//string	小数位
          "totalSupply": "1000000000000",					//bigInt	总量
          "transferCount": 2,								//int		token转账次数
          "owners": [										//[string]	token持有者
               "tNULSeBaMvEtDfvZuukDf2mVyfGo3DdiN8KLRG",
               "tNULSeBaMnrs6JKrCy6TQdzYJZkMZJDng7QAsD"
          ]
     }
}

# 查询合约列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getContractList",
    "params":[chainId,pageNumber,pageSize,onlyNrc20,isHidden],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
onlyNrc20:boolean 								//只查询nrc20合约
isHidden: boolean 								//是否隐藏nrc20合约,这个参数只有在			                                                   onlyNrc20=false时有效

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
           		{
           			"contractAddress":				//string	合约地址
           			"remark":						//string	备注
           			"txCount":						//int		智能合约相关交易数量
           			"status":						//int		合约状态
           									-1:执行失败,0:未认证,1:正在审核,2:通过验证,3:已删除
           			"createTime":					//long		创建时间
           			"balance":						//bigInt	合约剩余NULS余额
           			"tokenName":					//string	token名称
           		    "symbol": "KQB",				//string	token符号
                    "decimals": 2,					//string	小数位
        			"totalSupply": "1000000000000", //bigInt	总量
           		}
          ]
     }
}

# 查询合约相关交易列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getContractTxList",
    "params":[chainId,pageNumber,pageSize,txType,contractAddress],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
txType:int										//交易类型 默认为0,查询所有交易
contractAddress:string							//合约地址

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 3,
          "list": [
               {
                    "contractAddress": "tNULSeBaN32a2h……",		//string 合约地址
                    "txHash": "0020658e3edc61196e73be0……		//string 交易hash
                    "blockHeight": 12,							//long	 交易确认区块高度
                    "time": 1553336503846,						//long 	 交易生成时间
                    "type": 20									//int    交易类型
                    "fee": "5100000"							//bigint 交易手续费
               }
          ]
     }
}

# 查询nrc20合约转账记录列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getContractTokens",
    "params":[chainId,pageNumber,pageSize,contractAddress],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
contractAddress:string							//合约地址

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 3,
          "list": [
              {
                 "address": "tNULSeBaMvEt……",				//string	账户地址
                 "tokenName": "KQB",						//string	转账token名称
                 "tokenSymbol": "KQB",						//string	转账token符号
                 "contractAddress": "tNULSeBaNC46Z……",		//string	合约地址
                 "balance": 999900000000,					//bigint	转账后余额
                 "decimals": 2								//int		精确小数位数
              }
          ]
     }
}

# 查询账户nrc20转账记录列表

请求:

{
    "jsonrpc":"2.0",
    "method":"getTokenTransfers",
    "params":[chainId,pageNumber,pageSize,address,contractAddress],
    "id":1234
}
//参数说明
chainId: int									//链的id
pageNumber:int									//页码
pageSize:int									//每页显示条数,取值[1-1000]
address:string									//账户地址
contractAddress:string							//合约地址

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": {
          "pageNumber": 1,
          "pageSize": 10,
          "totalCount": 1,
          "list": [
               {
                    "txHash": "002016f5a811b939535……",		//string	交易hash
                    "height": 19,							//long		交易打包确认区块高度
                    "contractAddress": "tNULSeBaNC……",		//string	合约地址
                    "name": "KQB",							//string	token名称
                    "symbol": "KQB",						//string	token符号
                    "decimals": 2,							//int		精确小数位数
                    "fromAddress": "tNULSeBaMvE……",			//string	转账地址
                    "toAddress": "tNULSeBaMnrs6……",			//string	接收地址
                    "value": "100000000",					//bigInt	转账金额
                    "time": 1553336574791,					//long		交易时间
                    "fromBalance": "999900000000",			//bigInt	转账人余额
                    "toBalance": "100000000"				//bigInt	接收人余额
               }
          ]
     }
}

# 统计相关接口[statistical]

# 交易数量统计

请求:

{
"jsonrpc":"2.0",
"method":"getTxStatistical",
"params":[chainId,type],
"id":1234
}
//参数说明
chainId: int								//链的id
type: int							 		//0:最近14天, 1:最近一周, 2:最近一月, 3:最近一年

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": [
          {
               "key": "2018-6",						//string	统计周期
               "value": 265234						//long		统计数量
          },
          {
               "key": "2018-7",
               "value": 425327
          }
     ]
}

# 统计共识节点数量

请求:

{
    "jsonrpc":"2.0",
    "method":"getConsensusNodeCount",
    "params":[chainId],
    "id":1234
}
//参数说明
chainId: int								//链的id

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result":{
          "consensusCount":78,						//int	共识节点数量
          "seedsCount":5,							//int	种子节点数量
          "totalCount":83							//int	总数量
     }
}

# 共识奖励统计

请求:

{
    "jsonrpc":"2.0",
    "method":"getConsensusStatistical",
    "params":[chainId,type],
    "id":1234
}
//参数说明
chainId: int								//链的id
type: int							 		//0:14天,1:周,2:月,3:年,4:全部

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": [
          {
               "key": "6/5",							//string	统计周期
               "value": 556572872229264					//bigInt	共识奖励总额
          },
          {
               "key": "6/6",
               "value": 608939272229264
          },
          {
               "key": "6/7",
               "value": 628717072229264
          },
          {
               "key": "6/8",
               "value": 632738172229264
          },
          {
               "key": "6/9",
               "value": 629865972229264
          },
          {
               "key": "6/10",
               "value": 671865972229264
          }
     ]
}

# 年化奖励率统计

请求:

{
    "jsonrpc":"2.0",
    "method":"getAnnulizedRewardStatistical",
    "params":[chainId,type],
    "id":1234
}
//参数说明
chainId: int								//链的id
type: int							 		//0:14天,1:周,2:月,3:年,4:全部

返回:

{
     "jsonrpc": "2.0",
     "id": 1234,
     "result": [
          {
               "key": "5/29",						//string	统计周期
               "value": 116.17						//dobule	年化收益%
          },
          {
               "key": "5/30",
               "value": 121.61
          },
          {
               "key": "5/31",
               "value": 106.16
          },
          {
               "key": "6/1",
               "value": 112.27
          },
          {
               "key": "6/2",
               "value": 112.27
          }
     ]
}     
Last Updated: 2024/2/1 上午9:21:51