NULS-SDK

Introduction
This document is the user guide for the NULS Java SDK which describes instructions regarding
the basic functional interfaces provided by the NULS service, including accounts, transactions,
blocks, etc.

Agreement
All SDK interfaces uniformly return Result (data explanation enclosed at the end of the
article)
The return object described by each interface refers to the content of the data attribute in
the result.
Except as stated otherwise indicated, Na is taken as the unit for all the NULS in this
document - 1NULS = 100000000 Na
Before running the SDK, it is compulsory to confirm that the NULS node service has
started and functioned properly
JDK 1.8 + is recommended

Version update record

Version Update Update content
date

v0.9.11 2018-06- Interface to the basic functions of the NULS service

19

v0.9.11.1 2018-06- added the interface to get the latest block height and hash(3.6, 3.7)
22 and modified 2.1

Quick start

1.Import file
Import the jar package with the build tool
 Maven mode

<dependency>
<groupId>io.nuls.sdk</groupId>
<artifactId>nuls-sdk</artifactId>
<version>0.9.11</version>
</dependency>

2.Create an SDK instance

First add the SDK namespace

//SDK start class namespace

import io.nuls.sdk.SDKBootstrap;
import io.nuls.sdk.model.Result;
//Import the named namespace of the corresponding module according to the
requirement
import io.nuls.account.sdk.service.AccountService;
import io.nuls.account.sdk.service.impl.AccountServiceImpl;

Once imported, generate an instance client using the following code

Start the SDK

When the startup method does not pass parameters, the default PRC ip and port
respectively are 127.0.0.1 , 8003 .

//Default
SDKBootstrap.sdkStart();
//Pass the IP and port into NULS service
SDKBootstrap.sdkStart("192.168.1.88", "8001");

Generate an instance and call the interface

AccountService as = new AccountServiceImpl();

Result = as.createAccount("nuls123456");

e.g. A complete example of creating an account with the password

import io.nuls.sdk.SDKBootstrap;
import io.nuls.sdk.model.Result;
//Import the named namespace of the corresponding module according to the
requirement
import io.nuls.account.sdk.service.AccountService;
import io.nuls.account.sdk.service.impl.AccountServiceImpl;
 public static void main(String[] args) {
SDKBootstrap.sdkStart();
AccountService as = new AccountServiceImpl();
Result = as.createAccount("nuls123456");
}

Account AccountService

1.1 Create Account

Interface

Result createAccount(int count, String password);

Description

When you create an account, you can create a single or multiple accounts with or without a
password based on the parameters passed in;
Successfully created account information will be persisted to the NULS service’s local database.

Return the address set of successfully created accounts

Parameter Type Required Description

count int No Number of accounts created ( default value is 1 )

password String No Set the account password, password length (8~20), must
include both letters and numbers, no spaces.

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data":{
"list": [ //Return a address set that was successfully created ac
counts
"2Cbkwxu34iCjsiHKBjqZDNjoVbLMcJv",
"2Cbkwxu34iCjsiHKBjqZDNjoVbLMcJv"
]
}
}
e.g.

//Create an account without a password

createAccount();
//Create an account with a password
createAccount("nuls123456");
//Create three accounts without a password
createAccount(3);
//Create three accounts with a password
createAccount(3, "nuls123456");

1.2 Create offline account

Interface

Result createOfflineAccount(int count, String password)

Description

The action of creating an account and returning it completely when offline will not
interact with NULS underlying and persist operation.
Create encrypted off-line accounts (Not saved to the database)

Result.data List<AccountDto>

Parameter Type Required Description

count int No Number of accounts created ( default value is 1 )

password String No Set the account password, password length (8~20), must
include both letters and numbers, no spaces.

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data":
{
"list":
[
{
"address": String, Account address
"alias": String, alias
"pubKey": String, public key
 "extend": String, extend
"createTime": Long, createTime
"encrypted": boolean, encrypt or not
"priKey": String, Private key (valid only for account cre
ated offline with no password)
（
"encryptedPriKey": String, encrypted PriKey valid only fo
r account created offline with password ）
},
{
"address": "2CiBQg72BCLmLqttRpPfp8ECRCBwbdD",
"alias": null,
"pubKey": "020159dc5cc74463f346b71c08dd934a823e9e6fe727d8
d3c577e7d462e1a364bb",
"extend": null,
"createTime": 1529314943624,
"encrypted": true,
"priKey": "",
"encryptedPriKey": "5664f746654fb111e967bb3922910b16340f1
e60ff1b281c7a333179d7b82d6220bb12d1c058d9cd06099d4f443a4cb0"
}
]
}
}

e.g.

//Create an offline account without a password

createOfflineAccount();
//Create an offline account with a password
createOfflineAccount("nuls123456");
//Create three accounts without a password
createOfflineAccount(3);
//Create three accounts with a password
createOfflineAccount(3, "nuls123456");

1.3 Get Account

Interface

Result getAccount(String address)

Description

Query account information based on the account address

Result.data AccountDto
 Parameter Type Required Description

address String Yes Account address

API Response

：
A successful call will give you a result similar to this

{
"success": true,
"data": {
"address": String, account address
"alias": String, alias
"pubKey": String, public key
"extend": String, extend
"createTime": Long, create time
"encrypted": boolean, encrypt or not
"priKey": String, Private key (value only if you create an offlin
e account with no password)
（
"encryptedPriKey": String, encrypted PriKey value only if you cre
ate an offline account with password ）
}
}

e.g

getAccount("2ChqBTvFXttQsghj8zQpcdv76TQU8G5");

1.4 Get the fee for setting up an alias

Interface

Result getAliasFee(String address, String alias)

Description

Determined by the account address and the required fee for setting alias name( not include the
fixed cost of setting the 1NULS alias ).

Result.data double , unit is NULS

NOTE: The unit of fee returned by this interface is NULS

Parameter Type Required Description

 address String Yes Account address

alias String Yes alias name to be set

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": 0.01 (NULS as unit)
}

e.g.

getAliasFee("2ChqBTvFXttQsghj8zQpcdv76TQU8G5","factory666");

1.5 Acquire Account List

Interface

Result getAccountList(int pageNumber, int pageSize)

Description

Get the list of accounts based on the paging parameters

Result.data List<AccountDto>

Parameter Type Required Description

page int Yes page, must be larger than 0

number

pageSize int Yes record the number of the return data per page, with values
ranging from 1 to 100

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": [
 {
"address": String, Account address
"alias": String, alias
"pubKey": String, public key
"extend": String, extend
"createTime": Long, time of creation
"encrypted": boolean, encrypt
（
"priKey": String, Private key value only if you create an off
line account with no password ）
（
"encryptedPriKey": String, encryptedPrivate key value only if
you create an offline account with password ）
},
{
"address": "2Cid96JrTGA2XaNG6zXrRKh18kLUbLP",
"alias": null,
"pubKey": "033da2433ef4ca111bfeefaadd9fe0f5874f3aac5186109f9d
e10a9eed6f48f184",
"extend": null,
"createTime": 1529311250627,
"encrypted": true,
"priKey": null,
"encryptedPriKey": null
}
]
}

e.g.

getAccountList(1, 10);

1.6 Acquire Account Address According to the Account Alias

Interface

Result getAddressByAlias(String alias)

Description

Get the account address string from the account alias

Result.data String

Parameter Type Required Description

alias String Yes alias

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": "2ChDcC1nvki521xXhYAUzYXt4RLNULS"
}

e.g.

getAddressByAlias("factory666");

1.7 Acquire Account Private Key

Interface

Result getPrikey(String address, String password)

Description

Get the account private key based on the account address and password, and returns the
private key string

Result.data String

Parameter Type Required Description

address String Yes Account address

password String No Account password, no need for account unencrypted

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": "1f9d3ad044e0e1201e117b041f3d2ceedacb44688e57969620f3ad7a4d6e
9d24"
}

e.g.
 //Account call with password
getPrikey("2ChqBTvFXttQsghj8zQpcdv76TQU8G5", "nuls123456");
//Account call without password
getPrikey("2ChqBTvFXttQsghj8zQpcdv76TQU8G5");

1.8 Verify the Alias Name’s Availability

Interface

Result isAliasUsable(String alias)

Description

verify the alias name’s availablity according to the alias name (whether it is reused)

Result

Parameter Type Required Description

alias String Yes Alias Name

API Response

A successful call to this command will give you a result similar to this (JSON):

{ //Indicates that the alias name can be used

"success": true,
"data": true
}

Return If alias is not available

{
"success": false,
"data" {：
"code": "ACT005",
"msg": "xxxxxx...."
}
}

Return error message

{ // error message
 "success": false,
"data" {：
"code": "ACT005",
"msg": "xxxxxx...."
}
}

e.g.

isAliasUsable("factory666");

1.9 Backup Account

Interface

Result backupAccount(String address, String path, String password)

Description

According to the account address, password, and output address backup account (export.
Keystore file), the keystore exported is encrypted by the current password if the account is
encrypted. Verify account password when importing.

Result Return the generated file address

Parameter Type Required Description

address String Yes Account Address

path String Yes The folder where the backup file will be stored. When null is
passed, it will be backed up.

password String No Account password, no need for account unencrypted

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": "/Users/lichao/Downloads/2ChDcC1nvki521xXhYAUzYXt4RLNULS.acco
untkeystore"
}

e.g.
 //Backup an account without a password to the current directory
backupAccount("2ChqBTvFXttQsghj8zQpcdv76TQU8G5", null);
//Backup an account with a password to /backup directory
backupAccount("2ChqBTvFXttQsghj8zQpcdv76TQU8G5", "/backup",
"nuls123456");

1.10 Import the Account

Interface

Result importAccountByKeystore

Description

Import account from keystore file, and if the keystore file is generated by the backup from
encrypted account, it is required to verify the password of the account for backup.

Result

Parameter Type Required Description

path/fileReader String/FileReader Yes The url of the keystore file to be imported, or

the FileReader object generated by
the.keystore file

password String No .The account password corresponding to the

.keystore file will not be filled if the
corresponding account is not encrypted
when exporting

overwrite boolean Yes true: perform an override import; False: if the

account already exists in the wallet, the
import is not performed and error messages
are returned.

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": "2ChDcC1nvki521xXhYAUzYXt4RLNULS"
}

e.g.
 //Import an account with password
importAccountByKeystore("/backup/XXXXXX.keystore", "nuls123456", true);
importAccountByKeystore(fileReader, "nuls123456", true);
//Import an account without password
importAccountByKeystore("/backup/XXXXXX.keystore", false);
importAccountByKeystore(fileReader, false);

1.11 Import Account Private key

Interface

Result importAccountByPriKey(String privateKey, String password, boolean

overwrite)

Description

Import Account based on Private key

Result

Parameter Type Required Description

privateKey String Yes Account private key

password String No Set new password, password length （8~20）, must

include both letters and numbers, no spaces

overwrite boolean Yes true: perform an override import; False: if the account
already exists in the wallet, the import is not performed
and error messages are returned.

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": "2CiU1CmB6c9jmSLDNBe6PouA7NgNULS"
}

e.g.

//Import the Account Set the password

importAccountByPriKey("1f9d3ad044e0e120......", "nuls123456", true);
 //Leave the password blank when import the account
importAccountByPriKey("1f9d3ad044e0e120......", true);

1.12 Verify the Encryption Status of the Account

Interface

Result isEncrypted(String address)

Description

Verify the Encryption Status of the Account

Result

Parameter Type Required Description

address String Yes Account address

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": true
}

e.g.

isEncrypted("2ChqBTvFXttQsghj8zQpcdv76TQU8G5");

1.13 Remove the Account

Interface

Result removeAccount(String address, String password)

Description

Remove the Account

 Result

Parameter Type Required Description

address String Yes Account address

password String No Account password, no need for account unencrypted

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": true
}

Return Error message

{ //Error message
"success": false,
"data" {：
"code": "ACT005",
"msg": "xxxxxx...."
}
}

e.g.

removeAccount("2ChqBTvFXttQsghj8zQpcdv76TQU8G5");
removeAccount("2ChqBTvFXttQsghj8zQpcdv76TQU8G5", "nuls123456");

1.14 Change Password

Interface

Result resetPassword(String address, String password, String newPassword)

Description

Set a password for an encrypted account. Unencrypted accounts cannot call this interface

Result
 Parameter Type Required Description

address String Yes Account address

password String Yes Account current password

newPassword String Yes new password length （8~20). It must include both letters
and numbers, no spaces

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true, //indicate success
"data": {
"value": true
}
}

Return Error message

{ //Error message
"success": false,
"data" {：
"code": "ACT005",
"msg": "xxxxxx...."
}
}

e.g.

resetPassword("2ChqBTvFXttQsghj8zQpcdv76TQU8G5", "nuls123456", "NULS11111

1");

1.15 Set Alias

Interface

Result setAlias(String address, String alias, String password)

Description

Set an alias for the account

 Result Return to hash trading that sets an alias

Parameter Type Required Introductions

address String Yes Account address

alias String Yes Alias name to be set

password String password Account password, no need to fill in for unencrypted

account

API Responses

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": "0020d7a69747778f6f02e2b0171640bc98aa19c53700988b7765c195ae69
1f3202c6"
}

Error Example

{
"success": false,
：
"data" {
"code": "ACT007",
"msg": "The account already set an alias"
}
}

e.g.

setAlias("2ChqBTvFXttQsghj8zQpcdv76TQU8G5", "factory666", "NULS111111");

setAlias("2ChqBTvFXttQsghj8zQpcdv76TQU8G5", "factory666");

1.16 Set the Offline Account Password

Interface

Result setPasswordOffline(String address, String priKey, String password)

Description
 Set offline account password, encrypt it independently in SDK, do not interact with NULS
service

（
Result Return encrypted private key encryptedPriKey ）

Parameter Type Required Introductions

address String Yes Account address

priKey String Yes Account private key

password String Yes New password, password length 8~20, must include both
letters and numbers, no spaces

API Responses

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": {
“value”:"a770c1886f566c973b6eb99543ef03825a89ed16e20d8dbe320aed64
a85d5863ca23df43ef16ce0475424a49e192b6f9"
}
}

e.g.

setPasswordOffline("2CacFwqMwcJiGNNBwiwV7bCL7bjwNBr","00e4bfd347351ea899b
5f0ae2c0a3e7a6951b202eaf72432d1a63a2dc85c59c82a","nuls123456");

1.17 Modify offline account password

Interface

Result resetPasswordOffline(String address, String encryptedPriKey, String

password, String newPassword)

Description

Set offline account password, encrypt it independently in sdk, do not interact with NULS service

（
Result Return the encrypted private key generated by the new password encryptedPriKey ）
 Parameter Type Required Introductions

address String Yes Account address

encryptedPriKey String Yes Encrypted private key

password String Yes original password

newPassword String Yes New password, password length 8~20, must include
both letters and numbers, no spaces

API Responses

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": {
“value”: "7ab9031c634c562c2c742b777b266796414908ad4d9e26231dd353a9d11
3cca246bdd5af25e2547df83fcbe5b386875e"
}
}

e.g.

resetPasswordOffline("2CacFwqMwcJiGNNBwiwV7bCL7bjwNBr","25368dbc0ff7eea4f
c6da22bc37e85d7976a3846f8b58d4dc0cf484e740ba1b61f96395fbe1ddf70ece9fd21fc
d95e7a","NULS111111", "nuls123456");

1.18 Get the Total Number of Accounts

Interface

Result getAccountNumber()

Description

Get the Total Number of Accounts RPC Interface

Result returned qty

API Responses

A successful call to this command will give you a result similar to this (JSON):
 {
"success": true,
"data": 66
}

e.g.

getAccountNumber();

Transaction AccountLedgerService

2.1 Creates Trades

Interface

Result createTransaction(List<InputDto> inputs, List<OutputDto> outputs, String

remark)

Description

To create a transaction based on the information of inputDto and outputDto . The sum of
the input amount = the sum of the output + transaction fee, the calculation of the handling fee
will be described in detail below.

Result.data String Hexadecimal transaction serialization string

Parameter Type Required Introductions

inputs List<InputDto> Yes the unspent output of the trade reference

outputs List<OutputDto> Yes the newly generated unspent output of the

transaction

remark String No Trade Memo

e.g.

String remark = "create transaction demo";

long fee = 100000;
List<InputDto> inputs = new ArrayList<>();
List<OutputDto> outputs = new ArrayList<>();

//inputDto Only need to pass inHash and fromIndex

 InputDto input = new InputDto();
input.setFromHash("002023c66d10cf9047dbcca12aee2235ff9dfe0f13db3c921a2ec2
2e0dd63331cb85");
input.setFromIndex(1);
inputs.add(input);

OutputDto output = new OutputDto();

output.setAddress("2CjPVMKST7h4Q5Dqa8Q9P9CwYSmN7mG");
output.setValue(1000000L);
output.setLockTime(0L);
outputs.add(output);

output = new OutputDto();

output.setAddress("2CXJEuoXZMajeTEgL6TgiSxTRRMwiMM");
output.setValue(1000000000L - 1000000 - fee);
output.setLockTime(0L);
outputs.add(output);

Result result = service.createTransaction(inputs, outputs, remark);

Transaction fee: unit price of transaction fee * the size of transaction

Unit price of transaction fee: 100000NA/1KB

The Calculation of the size of transaction:

fee = 124 + 50 * inputs.length + 38 * outputs.length + remark.length /1024
124 is the length of basic information,
50 is the length of a single input,
38 is the length of a single piece of output information.
Remark is an optional field, the length of byte is calculated according to the UTF-8 character
encoding.
The size of the transaction is calculated in KB. The maximum value of transaction is 300 KB, and
the portion less than 1 KB is recorded as 1 KB.
If the fee is less than the reasonable range, the transaction will be regarded as an illegal
transaction and will not be packaged. The difference between transaction input and output will
be taken as transaction fee with node verify while calculating the minimum amount based on the
transaction. Legal transaction packing will not happen if the transaction fee less than the
minimum amount.

2.2 Transaction Signatures

Interface

Result signTransaction(String txHex, String priKey, String address, String

password)

Description
 Sign the transaction by private key

Result.data String Signed transaction, serialized string after hexadecimal

Parameter Type Required Introductions

txHex String Yes Hexadecimal transaction serialization data

priKey String Yes Transaction private key

address String Yes the address corresponding to the private key used to verify
the validity of the private key

password String No The password for the private key is not passed if not
encrypted.

e.g.

String txHex ="020197320f96301001a78cb7fb8bb7b1710b4afa390d8341080fba7a47

e8d030000000000000000";
String priKey ="252f6d9d55b7ef539ea58df99ebaf71c9929bd9d0054338baf7a59c9b
85b4fa631f816907c8";
String address = "2CXJEuoXZMajeTEgL6TgiSxTRRMwiMM";
String password = "NULS6352s!f";
Result result = service.signTransaction(txHex, priKey, address, passwor
d);

2.3 Query Transaction Details Based on Transaction Hash

Interface

Result getTxByHash(String hash)

Description

Query transaction details based on transaction hash

Result.data TransactionDto

Parameter Type Required Introductions

hash String Yes the hash value of the transaction

API Responses
 A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": {
"hash": "00203a169b42e5e142e20b273ac925e55f773b5a38c5f5c907efdbc4
3abb7d7a67b2",
"type": 2,
"time": 1529323198461,
"blockHeight": 1884,
"fee": 100000,
"value": 99900000000,
"remark": "Transfer",
"scriptSig": "21036dd27c9fa786a1e83df204e9b31ddc24745c378f1f6b427
31d07f05347167c0000473045022100ff3372711d78eb554be331aa40cd7af246641ecd3b
c06f2fdca7faefb25f74e50220743a2f2d9d01b5a77a878349b996cbe4953af5d1a946519
a5ce4d1129cf99848",
"status": 1,
"confirmCount": 14,
"size": 255,
"inputs": [
{
"fromHash": "0020ab020707282932e6ec701f0b64e22e937fdd03ce
9b37aab498aed2e00b6fa8e7",
"fromIndex": 0,
"address": "2ChDcC1nvki521xXhYAUzYXt4RLNULS",
"value": 9999899000000
}
],
"outputs": [
{
"txHash": "00203a169b42e5e142e20b273ac925e55f773b5a38c5f5
c907efdbc43abb7d7a67b2",
"index": 0,
"address": "2CiVA3n1VoNQobAax4d7qNEBZAfehLN",
"value": 99900000000,
"lockTime": 0,
"status": 0
},
{
"txHash": "00203a169b42e5e142e20b273ac925e55f773b5a38c5f5
c907efdbc43abb7d7a67b2",
"index": 1,
"address": "2ChDcC1nvki521xXhYAUzYXt4RLNULS",
"value": 9899998900000,
"lockTime": 0,
"status": 0
}
]
}
}
e.g.

getTxByHash("041f3d2ceed........");

2.4 Transfer
Interface

Result transfer(String address, String toAddress, String password, long amount,

String remark)

Description

Initiate transfer transactions

Result Return Hash Trade

Parameter Type Required Introductions

address String Yes Transferee’s account address

toAddress String Yes Recipient’s account address

password String No Password of the transferee’s account. If not encrypted, do

not fill in.

amount long Yes Transfer amount (Unit: Na)

remark String Yes notes

API Responses

API Response for Result object, the format is as follows：

{
"success": true,
"data": {
“value”: "00203a169b42e5e142e20b273ac925e55f773b5a38c5f5c907efdbc43ab
b7d7a67b2"
}
}

e.g.
 //Accounts with password
transfer("2ChDcC1nvki521xXhYAUzYXt4RLNULS", "2CiU1CmB6c9jmSLDNBe6PouA7NgX
XXX", "nuls123456", 8888800000000, "Note:1NULS=10000000Na");
//Accounts without password
transfer("2ChDcC1nvki521xXhYAUzYXt4RLNULS", "2CiU1CmB6c9jmSLDNBe6PouA7NgN
ULS", 8888800000000, "Note:1NULS=10000000Na");

2.5 Check Account Balance

Interface

Result getBalance(String address)

Description

Get information of account balance

Result.data BalanceDto

Parameter Type Required Introductions

address String Yes Account address

API Responses

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": {
"balance": 1009899998900000,
"usable": 1009899998900000,
"locked": 0
}
}

e.g.

getBalance("2ChDcC1nvki521xXhYAUzYXt4RLNULS");

2.6 Broadcast Transaction

Interface

Result broadcastTransaction(String txHex);

Description

Broadcast Transaction

Result.data String Return to hash trade

Parameter Type Required Introductions

txHex String Yes Hexadecimal transaction serialization data

API Responses

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": "002023c66d10cf9047dbcca12aee2235ff9dfe0f13db3c921a2ec22e0dd6
3331cb85"
}

e.g.

String txHex = "1f9d3ad044e0e1201e117b041f3d2ceedacb44688e57969620f3ad7a4

d6e9d241f9d3ad044e0e1201e117b041f3d2ceedacb44688e57969620f3ad7a4d6e9d24";
Result result = service.broadcastTransaction(txHex);
if(result.isSuccess()) {
String txHash = (String)result.getData();
}

BlockService

3.1 Get Block Headers Based on Block Height

Interface

Result getblockHeader(int height)

Description
 Get block header information based on block height

Result.data BlockHeaderDto

Parameter Type Required Introductions

height int Yes Block height

API Responses

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": {
"hash": "002078656b6e32f4f1e9e881e7b6c4c5de036ae81ec5bf78861bde94
80f5ff3a1b33",
"preHash": "0020ee5d28fde669adb0ad16f3ed426f1ee8df40560bed0ab30bb
99cbf95df276d64",
"merkleHash": "0020cc37658e2d110c1d42f64c7fd3dcb56d9653d4edc4d3a8
406cb263a41f9f5488",
"time": 1529299160000,
"height": 4,
"txCount": 4,
"packingAddress": "2CWsZb9w8XXTE58TUhBGczxf4U6NULS",
"scriptSig": "2102e18d02154e0f68900898efea7ba72d6d14e37d7d173a621
46df2871f40996d7300473045022100d4d92a9518ffd855441c7712f4b31bd003291dc108
fa2b455fe26d51e54625f102202ae8375bd69bf1928f9967edac82619ff78f30550c17797
cc489d5effd3202bf",
"roundIndex": 419517,
"consensusMemberCount": 1,
"roundStartTime": 1529299150000,
"packingIndexOfRound": 1,
"confirmCount": 1909,
"reward": 0,
"fee": 0,
"size": 1
}
}

e.g.

getblockHeader(10);

3.2 Get the Information of Block Header by Block hash

Interface

Result getblockHeader(String hash)

Description

Get Block Header According to Block hash

Result.data BlockHeaderDto

Parameter Type Required Introductions

hash String Yes Block hash value

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": {
"hash": "002078656b6e32f4f1e9e881e7b6c4c5de036ae81ec5bf78861bde94
80f5ff3a1b33",
"preHash": "0020ee5d28fde669adb0ad16f3ed426f1ee8df40560bed0ab30bb
99cbf95df276d64",
"merkleHash": "0020cc37658e2d110c1d42f64c7fd3dcb56d9653d4edc4d3a8
406cb263a41f9f5488",
"time": 1529299160000,
"height": 4,
"txCount": 4,
"packingAddress": "2CWsZb9w8XXTE58TUhBGczxf4U6NULS",
"scriptSig": "2102e18d02154e0f68900898efea7ba72d6d14e37d7d173a621
46df2871f40996d7300473045022100d4d92a9518ffd855441c7712f4b31bd003291dc108
fa2b455fe26d51e54625f102202ae8375bd69bf1928f9967edac82619ff78f30550c17797
cc489d5effd3202bf",
"roundIndex": 419517,
"consensusMemberCount": 1,
"roundStartTime": 1529299150000,
"packingIndexOfRound": 1,
"confirmCount": 1909,
"reward": 0,
"fee": 0,
"size": 1
}
}

e.g.
 getblockHeader("041f3d2ceed........");

3.3 Get Block by Block height

Interface

Result getBlock(int height)

Description

Get Block According to Block height

Result.data BlockDto

Parameter Type Required Description

height int Yes Block Height

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": {
"hash": "00209bbcd98110b57f1ecd66c9d94d1a2381e6c03c3b9aa77db25b6e
b5955bb658d3",
"preHash": "00201c0fa53c98595c7f9ba817fca6367aa2da1c1e480f801766b
7a4a16b39c54b67",
"merkleHash": "00200c2dfa0560229ef728cd6bdc858334ef4072d8e25c3b08
31c8366f4d4cb0c168",
"time": 1529323210000,
"height": 1884,
"txCount": 1884,
"packingAddress": "2CWsZb9w8XXTE58TUhBGczxf4U6NULS",
"scriptSig": "2102e18d02154e0f68900898efea7ba72d6d14e37d7d173a621
46df2871f40996d73004730450221009d1015b7cab19ac8099245390ae41ca14da9f47d5c
28b3b7780a53bd8adcccd802202bf74bb764f9de248dfb892d98e9ff91bad25daa107cfdf
4effd3fb1c266e5ae",
"roundIndex": 420416,
"consensusMemberCount": 5,
"roundStartTime": 1529323170000,
"packingIndexOfRound": 4,
"confirmCount": 33,
"reward": 100000,
"fee": 100000,
 "size": 5,
"txList": [
{
"hash": "00202b9737b15bf7e4ebc74a58554e461fbed6fedf3e289c
6ef41afa80d83f67babc",
"type": 1,
"time": 1529323210000,
"blockHeight": 1884,
"fee": 0,
"value": 0,
"remark": null,
"scriptSig": null,
"status": 0,
"confirmCount": 33,
"size": 54,
"inputs": [],
"outputs": [
{
"address": "2CWsZb9w8XXTE58TUhBGczxf4U6NULS",
"value": 100000,
"lockTime": 2884
}
]
},
{
"hash": "00203a169b42e5e142e20b273ac925e55f773b5a38c5f5c9
07efdbc43abb7d7a67b2",
"type": 2,
"time": 1529323198461,
"blockHeight": 1884,
"fee": 100000,
"value": 0,
"remark": "Transfer",
"scriptSig": "21036dd27c9fa786a1e83df204e9b31ddc24745c378
f1f6b42731d07f05347167c0000473045022100ff3372711d78eb554be331aa40cd7af246
641ecd3bc06f2fdca7faefb25f74e50220743a2f2d9d01b5a77a878349b996cbe4953af5d
1a946519a5ce4d1129cf99848",
"status": 0,
"confirmCount": 33,
"size": 255,
"inputs": [
{
"fromHash": "0020ab020707282932e6ec701f0b64e22e93
7fdd03ce9b37aab498aed2e00b6fa8e7",
"fromIndex": 0,
"address": null,
"value": 9999899000000
}
],
"outputs": [
{
"address": "2CiVA3n1VoNQobAax4d7qNEBZAfehLN",
 "value": 99900000000,
"lockTime": 0
},
{
"address": "2ChDcC1nvki521xXhYAUzYXt4RLNULS",
"value": 9899998900000,
"lockTime": 0
}
]
},
{
"hash": "002040370fcb2ad080abdcd2d91f952826c8f6e55bda7231
c1c15f25d9d74dc8ad7f",
"type": 7,
"time": 1529323210000,
"blockHeight": 1884,
"fee": 0,
"value": 0,
"remark": null,
"scriptSig": null,
"status": 0,
"confirmCount": 33,
"size": 38,
"inputs": [],
"outputs": []
}
]
}
}

e.g.

getBlock(10);

3.4 Get Block information by Block hash

Interface

Result getBlock(String hash)

Description

Get Block According to Block hash

Result.data BlockDto
 Parameter Type Required Description

hash String Yes Block hash value

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": {
"hash": "00209bbcd98110b57f1ecd66c9d94d1a2381e6c03c3b9aa77db25b6e
b5955bb658d3",
"preHash": "00201c0fa53c98595c7f9ba817fca6367aa2da1c1e480f801766b
7a4a16b39c54b67",
"merkleHash": "00200c2dfa0560229ef728cd6bdc858334ef4072d8e25c3b08
31c8366f4d4cb0c168",
"time": 1529323210000,
"height": 1884,
"txCount": 1884,
"packingAddress": "2CWsZb9w8XXTE58TUhBGczxf4U6NULS",
"scriptSig": "2102e18d02154e0f68900898efea7ba72d6d14e37d7d173a621
46df2871f40996d73004730450221009d1015b7cab19ac8099245390ae41ca14da9f47d5c
28b3b7780a53bd8adcccd802202bf74bb764f9de248dfb892d98e9ff91bad25daa107cfdf
4effd3fb1c266e5ae",
"roundIndex": 420416,
"consensusMemberCount": 5,
"roundStartTime": 1529323170000,
"packingIndexOfRound": 4,
"confirmCount": 33,
"reward": 100000,
"fee": 100000,
"size": 5,
"txList": [
{
"hash": "00202b9737b15bf7e4ebc74a58554e461fbed6fedf3e289c
6ef41afa80d83f67babc",
"type": 1,
"time": 1529323210000,
"blockHeight": 1884,
"fee": 0,
"value": 0,
"remark": null,
"scriptSig": null,
"status": 0,
"confirmCount": 33,
"size": 54,
"inputs": [],
"outputs": [
{
 "address": "2CWsZb9w8XXTE58TUhBGczxf4U6NULS",
"value": 100000,
"lockTime": 2884
}
]
},
{
"hash": "00203a169b42e5e142e20b273ac925e55f773b5a38c5f5c9
07efdbc43abb7d7a67b2",
"type": 2,
"time": 1529323198461,
"blockHeight": 1884,
"fee": 100000,
"value": 0,
"remark": "Transfer",
"scriptSig": "21036dd27c9fa786a1e83df204e9b31ddc24745c378
f1f6b42731d07f05347167c0000473045022100ff3372711d78eb554be331aa40cd7af246
641ecd3bc06f2fdca7faefb25f74e50220743a2f2d9d01b5a77a878349b996cbe4953af5d
1a946519a5ce4d1129cf99848",
"status": 0,
"confirmCount": 33,
"size": 255,
"inputs": [
{
"fromHash": "0020ab020707282932e6ec701f0b64e22e93
7fdd03ce9b37aab498aed2e00b6fa8e7",
"fromIndex": 0,
"address": null,
"value": 9999899000000
}
],
"outputs": [
{
"address": "2CiVA3n1VoNQobAax4d7qNEBZAfehLN",
"value": 99900000000,
"lockTime": 0
},
{
"address": "2ChDcC1nvki521xXhYAUzYXt4RLNULS",
"value": 9899998900000,
"lockTime": 0
}
]
},
{
"hash": "002040370fcb2ad080abdcd2d91f952826c8f6e55bda7231
c1c15f25d9d74dc8ad7f",
"type": 7,
"time": 1529323210000,
"blockHeight": 1884,
"fee": 0,
"value": 0,
 "remark": null,
"scriptSig": null,
"status": 0,
"confirmCount": 33,
"size": 38,
"inputs": [],
"outputs": []
}
]
}
}

e.g.

getBlock("041f3d2ceed........");

3.5 Get Newest Block Hash

Interface

Result get Newest Block Hash()

Description

Get Newest Block Hash

Result.data BlockHeaderDto

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": {
"hash": "002078656b6e32f4f1e9e881e7b6c4c5de036ae81ec5bf78861bde94
80f5ff3a1b33",
"preHash": "0020ee5d28fde669adb0ad16f3ed426f1ee8df40560bed0ab30bb
99cbf95df276d64",
"merkleHash": "0020cc37658e2d110c1d42f64c7fd3dcb56d9653d4edc4d3a8
406cb263a41f9f5488",
"time": 1529299160000,
"height": 4,
"txCount": 4,
"packingAddress": "2CWsZb9w8XXTE58TUhBGczxf4U6NULS",
 "scriptSig": "2102e18d02154e0f68900898efea7ba72d6d14e37d7d173a621
46df2871f40996d7300473045022100d4d92a9518ffd855441c7712f4b31bd003291dc108
fa2b455fe26d51e54625f102202ae8375bd69bf1928f9967edac82619ff78f30550c17797
cc489d5effd3202bf",
"roundIndex": 419517,
"consensusMemberCount": 1,
"roundStartTime": 1529299150000,
"packingIndexOfRound": 1,
"confirmCount": 1909,
"reward": 0,
"fee": 0,
"size": 1
}
}

e.g.

getNewestBlockHash();

3.6 query the latest block height

Interface

Result getNewestBlockHight()

Description

get the latest block height

Result.data height(Long)

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": {
"value": 5210
}
}}

e.g.
 getNewestBlockHight();

3.7 query the latest block Hash

interface

Result getNewestBlockHash()

Desription

get the latest block Hash

Result.data Hash.value(String)

API Response

A successful call to this command will give you a result similar to this (JSON):

{
"success": true,
"data": {
"value": "0020a2e1c99951184700927472c431a5a65847c7974cac0bbb97b24
2c7adf56ad27b"
}
}}

e.g.

getNewestBlockHash();

Appendix

API Response

Result
This is a successful call and return the special date

{
 "success": true, //validity of interface execution
"data": Object
}

This is a successful call and returns ture by the functions processing the business
operations

{
"success": true,
"data": {
"value":true
}
}

This is a successful call and returns false by the functions processing the business
operations

{
"success": true,
"data" { ：
"value": false
}
}

Error example

{
"success": false,
"data" { ：
"code": "ACT005",
"msg": "XXXXXXXX......"
}
}

This is the complete result of creating an offline account with a password.

{
"success": true,
//data List<account>
"data": [
{
"address": "2CacFwqMwcJiGNNBwiwV7bCL7bjwNBr",
"alias": null,
"pubKey": "030d4e752b5aa5d784f19a1fcc73b02afb6f756752fd00ebc2
fcaabc8d0979c4f0",
"extend": null,
"createTime": 1529041525794,
 "encrypted": false,
"priKey": "00e4bfd347351ea899b5f0ae2c0a3e7a6951b202eaf72432d1
a63a2dc85c59c82a",
"encryptedPriKey": ""
}
]
}

AccountDto

{
"address": String, Account address
"alias": String, alias
"pubKey": String, public key
"extend": String, extend
"createTime": Long, time of creation
"encrypted": boolean, encrypt
（
"priKey": String, Private key value only if you create an offline acc
ount with no password ）
（
"encryptedPriKey": String, encryptedPrivate key value only if you cre
ate an offline account with password ）
}

InputDto

{
"fromHash": String, txHash of output source
"fromIndex": Integer, outIndex of output source
"address": String, The address of rolling in
"value": Long The amount of rolling in
}

OutputDto

{
"txHash": String, dealing hash
"index": Integer, Index
"address": String, Address
"value": Long, Amount
"lockTime": Long, The time of locking
"status": Integer 0:usable, 1:timeLock, 2:consensusLock, 3:spent
}
TransactionDto

{
"hash": String, dealing amount of hash
"type": Integer, the types of dealing
"time": Long, the beginning time of dealing
"blockHeight": Long, Block Height
"fee": Long, the cost of dealing
"value": Long, dealing amount
"remark": String, notes
"scriptSig": String, Signature
"status": Integer, States 0:unConfirm, 1:confirm
"confirmCount": Long, confirmation times
"size": int, size
"inputs": [
{
"fromHash": String, txHash of output source
"fromIndex": Integer, outIndex of output source
"address": String, The address of rolling in
"value": Long The amount of rolling in
}
],
"outputs": [
{
"txHash": String, dealing hash
"index": Integer, Index
"address": String, Address
"value": Long, Amount
"lockTime": Long, The time of locking
"status": Integer 0:usable, 1:timeLock, 2:consensusLock, 3:s
pent
}
]
}

BalanceDto

{
"balance": long, Balance
"usable": long, Available BalanceAvailable remainder
locked": long Locked Balance
}
BlockHeaderDto

{
"hash": String, the Hash value of the block
"preHash": String, the preHash value of the block
"merkleHash": String, Merkel hash
"time": Long, The form time of block
"height": Long, Block Height
"txCount": Long, The deal amount of block pack
"packingAddress": String, the address of block pack
"scriptSig": String, Signature
"roundIndex": Long, Common round
"consensusMemberCount": Integer, The amount of member
"roundStartTime": Long, Common round starting time
"packingIndexOfRound": Integer, Packing index of round
"confirmCount": Long, confirmation times
"reward": Long, Rewards
"fee": Long, The handling charge of acquire pack
"size": int, size
}

BlockDto

{
"hash": String, the hash value of the block
"preHash": String, 上一个the hash value of the block
"merkleHash": String, Merkel hash
"time": Long, The form time of block
"height": Long, Block Height
"txCount": Long, The deal amount of block pack
"packingAddress": String, the address of block pack
"scriptSig": String, Signature
"roundIndex": Long, Common round
"consensusMemberCount": Integer, The amount of member
"roundStartTime": Long, Common round starting time
"packingIndexOfRound": Integer, Packing index of round
"confirmCount": Long, confirmation times
"reward": Long, Rewards
"fee": Long, The handling charge of acquire pack
"size": int, size
"txList": [
{
"hash": String, dealing amount of hash
"type": Integer, the types of dealing
"time": Long, the beginning time of dealing
"blockHeight": Long, Block Height
"fee": Long, the cost of dealing
"value": Long, dealing amount
 "remark": String, notes
"scriptSig": String, Signature
"status": Integer, States 0:unConfirm, 1:confirm
"confirmCount": Long, confirmation times
"size": int, size
"inputs": [ input
{
"fromHash": String, txHash of output source
"fromIndex": Integer, outIndex of output source
"address": String, The address of rolling in
"value": Long The amount of rolling in
}
],
"outputs": [
{
"address": String, address
"value": Long, Amount
"lockTime": Long, lockTime
}
]
}
]
}

ERROR CODE
("SYS000", "10000") SUCCESS
("SYS001", "10001") FAILED
("SYS006", "10006") DATA_ERROR
("SYS018", "10018") PARAMETER_ERROR
("SYS021", "20021") SIGNATURE_ERROR
("DATA004", "11000") VERIFICATION_FAILD
("DATA001", "11001") DATA_PARSE_ERROR
("ACT000", "50000") PASSWORD_IS_WRONG
("ACT001", "50001") ACCOUNT_NOT_EXIST
("ACT002", "50002")ACCOUNT_IS_ALREADY_ENCRYPTED
("ACT003", "50003")ACCOUNT_EXIST
("ACT004", "50004")ADDRESS_ERROR
("ACT005", "50005") ALIAS_EXIST
("ACT006", "50006")ALIAS_NOT_EXIST
("ACT007", "50007") ACCOUNT_ALREADY_SET_ALIAS
("ACT008", "50008")PARAMETER_ERROR
("ACT009", "50009") DATA_PARSE_ERROR
("ACT010", "50010")SUCCESS
("ACT011", "50011") FAILED
("ACT012", "50012")INSUFFICIENT_BALANCE
("ACT013", "50013") ALIAS_ROLLBACK_ERROR
("ACT014", "50014") ACCOUNTKEYSTORE_FILE_NOT_EXIST
("ACT015", "50015") ACCOUNTKEYSTORE_FILE_DAMAGED
("ACT016", "50016") ALIAS_FORMAT_WRONG
("ACT017", "50017")PASSWORD_FORMAT_WRONG