Wallet API has the same structure as Node Stratum API protocol (JSON RPC 2.0 over TCP connection) and should have an online connection to the node. However it can work over HTTP if using --api_use_http=1 option, send POST requests to http://x.x.x.x:port/api/wallet in this case.

Place wallet-api binary located in the wallet folder near your wallet.db file and run with the following arguments:

Wallet API general options:
  -h [ --help ]                     list of all options
  -p [ --port ] arg (=10000)        port to start server on
  -n [ --node_addr ] arg            address of node
  --wallet_path arg (=wallet.db)    path to wallet file
  --pass arg                        password for the wallet
  --use_http arg (=0)               use JSON RPC over HTTP
  --ip_whitelist arg                IP whitelist

User authorization options:
  --use_acl arg (=0)                use Access Control List (ACL)
  --acl_path arg (=wallet_api.acl)  path to ACL file

TLS protocol options:
  --use_tls arg (=0)                use TLS protocol
  --tls_cert arg (=wallet_api.crt)  path to TLS certificate
  --tls_key arg (=wallet_api.key)   path to TLS private key
  --tls_request_cert (=false)       request client's certificate for verification for client authentication
  --tls_reject_unauthorized (=true) server will reject any connection which is not authorized with the list of supplied CAs

For example ./wallet-api --node_addr=172.104.249.212:8101 --pass=123

Here is an example NodeJS code to get all UTXOs:

var net = require('net');

var client = new net.Socket();
client.connect(10000, '127.0.0.1', function() {
	console.log('Connected');
	client.write(JSON.stringify(
		{
			jsonrpc: '2.0',
			id: 123,
			method: 'get_utxo',
			params: {}
		}) + '\n');
});

var acc = '';

client.on('data', function(data) {
	acc += data;

	// searching for \n symbol to find end of response
	if(data.indexOf('\n') != -1)
	{
		var res = JSON.parse(acc);

		console.log('Received:', res);

		client.destroy(); // kill client after server's response
	}
});

client.on('close', function() {
	console.log('Connection closed');
});

If you use JSONRPC over HTTP you can perform POST requests using CURL. Specify 'use_http=1' in wallet-api.cfg to enable HTTP mode.

Here is an example to get current wallet status.

curl -d '{"jsonrpc":"2.0","id":1,"method":"wallet_status"}' -H "Content-Type: application/json" -X POST http://x.x.x.x:port/api/wallet

v5.0 API implements confidential assets support. To ensure backward compatibility by default API does not return asset coins and asset transactions info. Asset operations (send, receive, issue, consume &c.) are disabled as well.

To enable assets you should start your API server with the --enable_assets CLI param.

In API requests you should explicitly enable assets support via corresponding request parameter ("assets": true) or by providing non-zero asset_id. In some cases enabling assets support would significantly change method's response. If you do not enable assets support your old code should be able to use new v5.0 API without any changes.

However in most responses additional asset_id field is returned by default even if assets support is not enabled in the request. It is always 0 for HDS and can be safely ignored.

API has the following methods:

• create_address
• validate_address
• addr_list
• delete_address
• edit_address
• tx_send
• tx_split
• tx_asset_issue
• tx_asset_consume
• tx_asset_info
• tx_cancel
• tx_delete
• tx_status
• tx_list
• wallet_status
• get_utxo
• get_asset_info
• generate_tx_id
• export_payment_proof
• verify_payment_proof

If you build wallet-api with HDS_ATOMIC_SWAP_SUPPORT then you can use additional methods. See here for details.

Creates new receiver address with given comment and expiration.

-->

{
    "jsonrpc" : "2.0", 
    "id" : 1,
    "method" : "create_address", 
    "params" :
    {
        "expiration" : "24h",
        "comment" : "John Smith"
    }
}

• expiration can be expired/never/24h. Optional, by default address expires in 24 hours.
• comment any string, optional.

<--

{
    "jsonrpc" : "2.0", 
    "id" : 1,
    "result" : "472e17b0419055ffee3b3813b98ae671579b0ac0dcd6f1a23b11a75ab148cc67"
}

Just a simple validations, checks if the address isn't garbage and belongs to our elliptic curve. Also returns is_mine == true if address is found in the local wallet DB.

-->

{
    "jsonrpc":"2.0", 
    "id": 1,
    "method": "validate_address", 
    "params":
    {
        "address" : "472e17b0419055ffee3b3813b98ae671579b0ac0dcd6f1a23b11a75ab148cc67"
    }
}

<--

{
    "jsonrpc":"2.0", 
    "id": 1,
    "result" : 
    {
        "is_valid" : true,
        "is_mine" : false,
    }
}

Get all the addresses in the wallet. -->

{
    "jsonrpc":"2.0", 
    "id": 8,
    "method":"addr_list",
    "params":
    {
        "own" : true
    }
}

• own, optional bool. Set to true to get only own addresses. By default is false.

<--

{
    "id": 8,
    "jsonrpc": "2.0",
    "result":
    [{
        "address": "29510b33fac0cb20695fd3b836d835451e600c4224d8fb335dc1a68271deb9b6b5b",
        "category": "",
        "create_time": 1553174321,
        "duration": 1520,
        "expired": true,
        "comment": "",
        "own": true,
        "own_id": 16730903,
        "own_id_str": "16730903",
        "identity": "2d8738b0424ad50631e902fab655e7e1795fbb8d92d47c4c8df7336870fcadf5"
    }] 
}

• own_id unsigned 64 bit index used to generate given address
• own_id_str string representation of index used to generate given address (for JavaScript)
• identity identity linked to the given address.

Starting from version 4.2 we introduce an additional entity in order to make transfer more reliable. It is called identity. The main goal of identity is to proof and ensure that transaction performs between claimed participants also it could be done using untrusted 3rd parties. The main scenario is hardware wallet when host machine could be compromised, since it has ability to generate SBBS addresses, it can sign payment proof or accept transaction without need to ask hardware wallet about any secret, but if we give our identity to the other side (in addition to SBBS address), and this identity can be generated using hardware wallet only, then only hardware wallet can sign or approve transaction.

Delete specific address from the wallet.

-->

{
    "jsonrpc":"2.0", 
    "id": 8,
    "method":"delete_address",
    "params":
    {
        "address" : "29510b33fac0cb20695fd3b836d835451e600c4224d8fb335dc1a68271deb9b6b5b"
    }
}

<--

{
    "id": 8,
    "jsonrpc": "2.0",
    "result": "done"
}

Edit specific address. You can change the comment and/or expiration to expired/never/24h.

-->

{
    "jsonrpc":"2.0", 
    "id": 8,
    "method":"edit_address",
    "params":
    {
        "address" : "29510b33fac0cb20695fd3b836d835451e600c4224d8fb335dc1a68271deb9b6b5b",
        "comment" : "John Smith",
        "expiration" : "expired"
    }
}

<--

{
    "id": 8,
    "jsonrpc": "2.0",
    "result": "done"
}

Send HDS or asset to a given address.

-->

{
    "jsonrpc":"2.0", 
    "id": 2,
    "method":"tx_send", 
    "params":
    {
        "value": 12342342,
        "fee": 2,
        "from": "472e17b0419055ffee3b3813b98ae671579b0ac0dcd6f1a23b11a75ab148cc67",
        "address": "472e17b0419055ffee3b3813b98ae671579b0ac0dcd6f1a23b11a75ab148cc67",
        "comment": "thank you!",
        "asset_id": 1
    }
}

• value how much HDS or asset to send in groth or asset groth.
• fee always in HDS groth, optional. Omit for default fee.
• from own address, optional. If omitted new own address is generated and registered.
• address receiver's SBBS address or token. Token is an extension of SBBS address. It is a base58 encoded byte buffer which contains serialized parameters of a transaction. At least it contains SBBS address and identity.
• comment transaction comment, optional.
• txId optional, you can provide your own transaction ID.
• asset_id asset id to send, optional. Present starting from v5.0 and can be used only after Fork 2. Omit or set to 0 for HDS transaction.

You can preselect specific UTXOs for a transaction and fee via optional coins array parameter like "coins" : ["00057e8eca5673476e6f726d000000000000015d3ef79800", "00057e8eca1233476e6f726d000000000000015d3ef79800"]. In case of asset transaction you can specify both asset coins (to send) and non-asset coins (to pay fee).

<--

{
    "jsonrpc":"2.0", 
    "id": 2,
    "result":
    {
        "txId" : "10c4b760c842433cb58339a0fafef3db"
    }
}

Returns transaction id or error code.

Creates a specific set of outputs with given values.

NOTE: The session parameter is not IMPLEMENTED and was removed!

-->

{
    "jsonrpc":"2.0", 
    "id": 5,
    "method":"tx_split", 
    "params":
    {
        "coins" : [11, 12, 13, 50000000],
        "fee" : 100,
        "asset_id": 1
    }
}

<--

{
    "jsonrpc":"2.0", 
    "id": 5,
    "result":
    {
        "txId" : "10c4b760c842433cb58339a0fafef3db"
    }
}

• fee is always in HDS groth. Omit for default fee.
• coins amounts of coins your want to have after split.
• txId optional, provide your own transaction ID.
• asset_id asset id to split, optional. Omit or set to 0 to split HDS coins. Present starting from v5.0 and can be used only after Fork 2.

Available from v5.0, can be used after Fork2.

Mints new asset coins. You must own the asset and info about the asset should be in a local database. Use tx_asset_info to retrieve the latest asset info if necessary. Asset minting is free. You need to pay only regular transaction fee.

-->

{
    "jsonrpc": "2.0", 
    "id": 2,
    "method": "tx_asset_issue", 
    "params":
    {
        "value": 6,
        "asset_id": 1
    }
}

OR -->

{
    "jsonrpc": "2.0", 
    "id": 2,
    "method": "tx_asset_issue", 
    "params":
    {
        "value": 6,
        "asset_meta": "STD:N=Coin;SN=CN;UN=Cgro;NTHUN=Cgroth"
    }
}

• value how much asset to mint, in asset groth.
• fee transaction fee in HDS groth. Omit to use default fee.
• asset_id OR asset_meta id/meta of asset to mint.
• txId optional, provide your own transaction ID.

You can preselect specific HDS UTXOs for a transaction fee by adding coins array parameter, like "coins" : ["00057e8eca5673476e6f726d000000000000015d3ef79800", "00057e8eca1233476e6f726d000000000000015d3ef79800"]

<--

{
    "jsonrpc": "2.0", 
    "id": 2,
    "result":
    {
        "txId" : "10c4b760c842433cb58339a0fafef3db"
    }
}

Returns transaction id or error code.

Available from v5.0 and can be used after Fork2.

Burns existing asset coins. You must own the asset itself as well as asset coins to burn them. You cannot burn asset coins that belong to another wallet. Info about the asset should be in a local database. Use tx_asset_info to retrieve the latest asset info if necessary. Asset coins burning is absolutely free. You need to pay only regular transaction fee.

-->

{
    "jsonrpc":"2.0", 
    "id": 2,
    "method":"tx_asset_consume", 
    "params":
    {
        "value": 6,
        "asset_id": 1
    }
}

OR

-->

{
    "jsonrpc": "2.0", 
    "id": 2,
    "method": "tx_asset_consume", 
    "params":
    {
        "value": 6,
        "asset_meta": "STD:N=Coin;SN=CN;UN=Cgro;NTHUN=Cgroth"
    }
}

• value how much asset to burn, in asset groth.
• fee transaction fee in HDS groth, omit for a default fee.
• asset_id OR asset_meta id/meta of asset to mint.
• txId optional, provide your own transaction ID

You can preselect specific UTXOs to burn and to pay fee by adding coins array parameter, like "coins" : ["00057e8eca5673476e6f726d000000000000015d3ef79800", "00057e8eca1233476e6f726d000000000000015d3ef79800"]. Both asset coins (to burn) and HDS coins (to pay fee) can be in this array.

<--

{
    "jsonrpc":"2.0", 
    "id": 2,
    "result":
    {
        "txId" : "10c4b760c842433cb58339a0fafef3db"
    }
}

Returns transaction id or error code.

Available from v5.0 and can be used after Fork2.

Retrieve full info about any registered asset and save in a local database. If asset has been unregistered or has been never registered transaction would fail. After transaction is completed you can use get_asset_info to read/get asset info from the local database.

-->

{
    "jsonrpc":"2.0", 
    "id": 2,
    "method": "tx_asset_info",
    "params": 
    {
        "asset_id": 1
    }
}

OR

-->

{
    "jsonrpc":"2.0", 
    "id": 2,
    "method": "tx_asset_info",
    "params": 
    {
        "asset_meta": "STD:N=Coin;SN=CN;UN=Cgro;NTHUN=Cgroth"
    }
}

• asset_id asset id to retrieve info about. Can be used for any asset even if you don't own it.
• asset_meta asset metadata to retrieve info about. You can query info via meta only for assets you own.
• txId optional, provide your own transaction ID

Asset info transaction is free, i.e. doesn't incur any fees.

<--

{
    "jsonrpc":"2.0", 
    "id": 2,
    "result":
    {
        "txId" : "10c4b760c842433cb58339a0fafef3db"
    }
}

Returns transaction id or error code.

Cancels running transaction

-->

{
    "jsonrpc":"2.0", 
    "id": 4,
    "method":"tx_cancel", 
    "params":
    {
        "txId" : "a13525181c0d45b0a4c5c1a697c8a7b8"
    }
}

• txId transaction id to cancel.

<--

{
    "jsonrpc":"2.0", 
    "id": 4,
    "result": true
}

Returns true if successfully canceled or error code with the reason.

Cancels running transaction

-->

{
    "jsonrpc":"2.0", 
    "id": 4,
    "method":"tx_delete", 
    "params":
    {
        "txId" : "a13525181c0d45b0a4c5c1a697c8a7b8"
    }
}

• txId transaction id to be deleted.

<--

{
    "jsonrpc":"2.0", 
    "id": 4,
    "result": true
}

Returns true if the transaction was successfully deleted or error code with the reason.

Get status & extended information about a single transaction by its transaction id. Example below is given for a simple transaction. Different transaction types have different status records. Consult tx_list method description for details.

-->

{
    "jsonrpc":"2.0", 
    "id": 4,
    "method":"tx_status", 
    "params":
    {
        "txId" : "10c4b760c842433cb58339a0fafef3db" 
    }
}

<--

{
    "jsonrpc":"2.0", 
    "id": 4,
    "result":
    { 
        "txId" : "10c4b760c842433cb58339a0fafef3db",
        "asset_id": 0,
        "comment": "",
        "fee": 100,
        "kernel": "0000000000000000000000000000000000000000000000000000000000000000",
        "receiver": "472e17b0419055ffee3b3813b98ae671579b0ac0dcd6f1a23b11a75ab148cc67",
        "sender": "f287176bdd517e9c277778e4c012bf6a3e687dd614fc552a1ed22a3fee7d94f2",
        "status": 4,
        "status_string" : "Failed",
        "tx_type": 0,
        "tx_type_string": "simple",
        "failure_reason" : "No inputs",
        "value": 12342342,
        "create_time" : 1551100217,
        "income" : false,
        "sender_identity": "a0a1ebbfeed5c312b309e32715c159e6b4548a6c6c3af25d0dbc16f37a1e9dd6",
        "receiver_identity": "2d8738b0424ad50631e902fab655e7e1795fbb8d92d47c4c8df7336870fcadf5",
        "token": "44pE7ySjZYjbLqwnTJANvr4BudMk1RdvWvaZnBvoCTwFnigfaTSza75bvw7x2GCa377Z4CSRRYZon44Ss9G9joSicNRAgts4u3pL6yV6jDQ6gAVJD9Scyr"
    } 
}

Get transactions list.

-->

{
    "jsonrpc":"2.0", 
    "id": 8,
    "method":"tx_list",
    "params":
    {
        "filter" : 
        {
            "status":4,
            "height":1055,
        },
        "skip" : 0,
        "count" : 10,
        "assets": true
    }
}

• filter.status optional, filter transactions by status
• filter.height optional, filter transactions by height. For simple, asset issue and asset consume transactions denotes height when transaction was registered in the chain. For asset asset info transaction means height at which asset confirmation was received. Works only for transactions with status Completed(3).
• count optional, number of transactions to get. By default all transactions are returned.
• skip number of transactions to skip, 0 by default.

By default method returns only simple HDS transactions. To get asset transactions use

• assets bool, false by default. If true all HDS & assets transactions (simple, asset issue, asset consume, asset info) are returned. Present starting from v5.0.
• filter.asset_id return only asset transactions with given asset id. Present starting from v5.0.

If assets is set to false and filter.asset_id is non-zero assets param overrides filter.asset_id and no transactions returned. Please note that asset_id might be 0 for failed asset_info transactions started via asset_meta parameter.

<--

{
    "jsonrpc":"2.0", 
    "id": 8,
    "result":
    [{ 
        "asset_id": 0,
        "txId" : "10c4b760c842433cb58339a0fafef3db",
        "comment": "",
        "fee": 0,
        "kernel": "0000000000000000000000000000000000000000000000000000000000000000",
        "receiver": "472e17b0419055ffee3b3813b98ae671579b0ac0dcd6f1a23b11a75ab148cc67",
        "sender": "f287176bdd517e9c277778e4c012bf6a3e687dd614fc552a1ed22a3fee7d94f2",
        "status": 4,
        "status_string" : "Failed",
        "failure_reason" : "No inputs",
        "value": 12342342,
        "create_time" : 1551100217,
        "income" : false,
        "token": "44pE7ySjZYjbLqwnTJANvr4BudMk1RdvWvaZnBvoCTwFnigfaTSza75bvw7x2GCa377Z4CSRRYZon44Ss9G9joSicNRAgts4u3pL6yV6jDQ6gAVJD9Scyr"
    },
    {
      "asset_id": 1,
      "asset_meta": "STD:N=Coin;SN=CN;UN=Cgro;NTHUN=Cgroth",
      "comment": "",
      "confirmations": 102,
      "create_time": 1586995332,
      "fee": 0,
      "height": 1908,
      "income": false,
      "receiver": "0",
      "sender": "0",
      "status": 3,
      "status_string": "asset confirmed",
      "txId": "d9f94306127a4ef894733f984b5512cf",
      "tx_type": 6,
      "tx_type_string": "asset info",
      "value": 0
    },
    {
        "asset_id": 1,
        "asset_meta": "STD:N=Coin;SN=CN;UN=Cgro;NTHUN=Cgroth",
        "comment": "",
        "confirmations": 1985,
        "height": 25,
        "create_time": 1586966478,
        "fee": 100,
        "income": false,
        "kernel": "1c9e4a9a61df1dda00db10ab4477f88355e13d4ed06c0db36c39b22a2a66f642",
        "receiver": "0",
        "sender": "0",
        "status": 3,
        "status_string": "asset issued",
        "txId": "77008a76aa4b4da697587040b2d21f1e",
        "tx_type": 2,
        "tx_type_string": "asset issue",
        "value": 500000000
    }]
}

• token retuned only in case if transaction was started with token.
• height and confirmations will be absent if transaction isn't in chain for simple, asset issue & asset consume transactions, or if asset confirmation is not received for asset info transaction.
• sender_identity and receiver_identity are present if both participants provided these.
• status_string is a string representation of status parameter.
• asset_meta is an asset metadata string. Present from v5.0.
• tx_type is present starting from v5.0.
• tx_type_string is a string representation of tx_type parameter. Present starting from v5.0.
• asset_id is returned starting from v5.0. For HDS transactions it is always 0, for transactions that involve assets (including send/receive) it is an asset id. Can be 0 for asset info transaction if transaction was started with asset_meta and asset has been not found.
• asset_meta is an asset metadata string. Returned starting from v5.0. Always present for asset issue & consume transactions. Can be empty for asset info transaction if it was started with asset_id and asset has been not found.
• kernel is not returned for asset info transactions. These transactions do not have any kernel and only query node for information.

• pending (0) - pending initial state, transaction is created, but not sent yet
• in progress (1) - self sending/waiting for sender/waiting for receiver. For simple transactions indicates that sender or receiver should come online to initiate the transaction. For asset issue/consume/info transactions indicates that transaction is being assembled. For asset info transaction means waiting for node response.
• canceled (2) - cancelled by sender or due to rollback
• completed (3) - transaction is completed/received/sent/asset issued/asset consumed/asset confirmed
• failed (4) - failed for some reason or expired
• registering (5) - self sending/receiving/sending transaction is taken care by the blockchain, miners needs to PoW and to add it to a block, then block should be added to the blockchain.

• simple (0) - simple transaction, send/receive HDS or asset
• reserved (1) - currently not returned
• asset issue (2) - issue new asset units
• asset consume (3) - consume asset units
• reserved (4) - currently not returned
• reserved (5) - currently not returned
• asset info (6) - asset info transaction, receive full asset information from blockchain

N.B. tx_list does not return swap, asset register & asset unregister transactions. Transactions are sorted by height in a descending order.

Get current wallet status.

-->

{
	"jsonrpc":"2.0", 
	"id": 6,
	"method":"wallet_status"
}

<--

{
	"jsonrpc":"2.0", 
	"id": 6,
	"result":
	{
	    "current_height" : 1055,
	    "current_state_hash" : "f287176bdd517e9c277778e4c012bf6a3e687dd614fc552a1ed22a3fee7d94f2",
	    "prev_state_hash" : "bd39333a66a8b7cb3804b5978d42312c841dbfa03a1c31fc2f0627eeed6e43f2",
	    "available": 100500,
	    "receiving": 123,
	    "sending": 0,
	    "maturing": 50,
	    "locked": 30,
	    "difficulty": 2.93914,
	}
}

• available sum of available UTXOs you can spend
• sending/receiving sum of UTXOs currently sending/receiving
• maturing sum of UTXOs currently maturing
• locked not used at the moment, ignore
• difficulty the latest blockchain PoW difficulty

Starting from v5.0 assets support has been added. This significantly changes API response. By default even in v5.0 response has the old format described above. To get extended wallet status specify params.assets = true in the request.

-->

{
	"jsonrpc":"2.0", 
	"id": 6,
	"method":"wallet_status",
        "params": {
              "assets" : true
        }
}

<--

{
  "id": 1236,
  "jsonrpc": "2.0",
  "result": {
    "current_height": 112,
    "current_state_hash": "b9e8b868de60f28e553a1499a569f481991e4cff9fe2191d09d71a03c7708296",
    "difficulty": 378.36236572265625,
    "prev_state_hash": "3f84da0b0390deaca908603b6061867def987575a1af9311248ffb01503a0f02",
    "totals": [
      {
        "asset_id": 0,
        "available": 303000000000,
        "available_str": "303000000000",
        "maturing": 8000000000,
        "maturing_str": "8000000000",
        "receiving": 0,
        "receiving_str": "0",
        "sending": 0,
        "sending_str": "0"
      },
      {
        "asset_id": 1,
        "available": 2000000000,
        "available_str": "2000000000",
        "maturing": 0,
        "maturing_str": "0",
        "receiving": 0,
        "receiving_str": "0",
        "sending": 0,
        "sending_str": "0"
      }
    ]
  }
}

• totals is an array of totals per asset.
• asset_id denotes asset type. For HDS asset_id is always 0.
• Maximum asset emission is 2¹²⁸-1. To ensure compatibility with JavaScript raw number (available, maturing &c.) returned only if it is less than or equal to Number.MAX_SAFE_INTEGER (2⁵³-1). If total's value is greater than Number.MAX_SAFE_INTEGER only corresponding string representation (xxxx_str) is returned.

Get list of all unlocked UTXOs.

-->

{
    "jsonrpc":"2.0", 
    "id": 6,
    "method":"get_utxo",
    "params" :
    {
        "count": 10,
        "skip": 0
    }
}

• count number of UTXO to get, by default all the UTXOs are returned.
• skip number of UTXO to skip, default is 0.

<--

{
    "jsonrpc": "2.0", 
    "id": 6,
    "result":
    [{
        "id": 123,
        "asset_id": 0,
        "amount": 12345,
        "maturity": 60,
        "type": "mine",
        "createTxId": "10c4b760c842433cb58339a0fafef3db",
        "spentTxId": "",
        "status": 2,
        "status_string": "maturing"
    }]
}

• asset_id asset id if coin belongs to an asset and 0 for HDS coins.

By default method returns only HDS coins. To get asset coins use

• assets bool, false by default. If true all HDS & assets coins are returned. Present starting from v5.0.
• filter.asset_id return only asset coins with given asset id, 0 for HDS coins. Present starting from v5.0.

assets param overrides filter.asset_id. If assets is set to false and filter.asset_id is non-zero then no UTXOs are returned.

-->

{
    "jsonrpc": "2.0",
    "id": 1236,
    "method": "get_utxo",
    "params": {
        "assets": true,
        "filter": {
            "asset_id": 1
        }
    }
}

<--

{
  "id": 1236,
  "jsonrpc": "2.0",
  "result": [
    {
      "amount": 500000000,
      "asset_id": 1,
      "createTxId": "fd705ce6f8c345309c865dc93de9fec5",
      "id": "0000000183ed2de4d94e6bd56e6f726d01000000000000001dcd6500",
      "maturity": 19,
      "session": 0,
      "spentTxId": "",
      "status": 1,
      "status_string": "available",
      "type": "norm"
    }
  ]
}

• type can be fees, mine, norm, chng
• status can be unavailable (0), available (1), maturing (2), outgoing (3), incoming (4), spent (6), consumed (7). consumed status is returned only for asset coins starting from v5.0. It means that the coin has been burned (consumed).

Read asset info from local database. Asset info can be refreshed using tx_asset_info. It is also automatically refreshed during asset transactions (but not always) to ensure that asset operations are safe.

-->

{
    "jsonrpc":"2.0", 
    "id": 6,
    "method": "get_asset_info",
    "params" :
    {
        "asset_id": 1
    }
}

OR

-->

{
    "jsonrpc":"2.0", 
    "id": 6,
    "method": "get_asset_info",
    "params" :
    {
        "asset_meta": "STD:N=Coin;SN=CN;UN=Cgro;NTHUN=Cgroth"
    }
}

• asset_id asset id to retrieve info about. Can be used for any asset even if you don't own it.
• asset_meta asset metadata to retrieve info about. You can query info via meta only for assets you own.

<--

{
    "id": 1236,
    "jsonrpc": "2.0",
    "result": 
    {
        "asset_id": 1,
        "emission": 2000000000,
        "emission_str": "2000000000",
        "isOwned": 1,
        "lockHeight": 39,
        "metadata": "STD:N=NAME;SN=SNM;UN=UNIT;NTHUN=NTHUNIT",
        "ownerId": "0ae08a49e018e98177774294107dc033790b87538e54a20e99c6b98f1dbd39ce",
        "refreshHeight": 927
    }
}

Returns full asset info or error code.

• asset_id asset id
• metadata asset metadata
• emission & emission_str total asset emission. Maximum asset emission is 2¹²⁸-1. To ensure compatibility with JavaScript raw number returned only if it is less than or equal to Number.MAX_SAFE_INTEGER (2⁵³-1). If asset emission is greater than Number.MAX_SAFE_INTEGER only corresponding string representation is returned.
• isOwned is 1 if you own this asset
• lockHeight last block when asset emission turned to/from 0.
• refreshHeight block at which asset information has been received. Please note, that all returned fields are valid only for this and previous blocks. In next blocks emission might change, asset become unregistered &c. Use tx_asset_info to retrieve the most recent info.

Generates ID for a transaction.

-->

{
    "jsonrpc":"2.0", 
    "id": 2,
    "method":"generate_tx_id"
}

<--

{
    "jsonrpc":"2.0", 
    "id": 2,
    "result":"10c4b760c842433cb58339a0fafef3db"
}

Exports payment proof for given txId.

-->

{
    "jsonrpc":"2.0", 
    "id": 4,
    "method": "export_payment_proof", 
    "params":
    {
        "txId" : "a13525181c0d45b0a4c5c1a697c8a7b8"
    }
}

<--

{
    "jsonrpc":"2.0", 
    "id": 4,
    "result": 
    {
        "payment_proof": "8009f28991ef543253c8b6a2caf15cf99e23fb9c2b4ca30dc463c8ceb354d7979e80ef7d4255dd5e885200648abe5826d8e0ba0157d3e8cf9c42dcc8258b036986e50400371789ee82afc25ee29c9c57bcb1018b725a3a94c0ceb1fa7984ea13de4982553e0d78d925a362982182a971e654857b8e407e7ad2e9cb72b2b8228812f8ec50435351000c94e2c85996e9527d9b0c90a1843205a7ec8f99fa534083e5f1d055d9f53894"
    }
}

• payment_proof is a hex-encoded byte buffer which contains information about sender, receiver, amount and kernel, signed with receiver's private key. This info could be unpacked and verified using verify_payment_proof method by the third party. Receiver creates a payment proof in order give receiver an ability to proof that actual payment was made. Sender does not sign transaction if receiver does not provide him this evidence.

N.B. Payment proofs for asset transaction are supported starting from v5.0. These proofs cannot be verified by earlier clients/APIs versions. Regular HDS payment proofs generated by the latest clients/APIs still would be accepted by earlier versions of clients/APIs.

Verifies payment_proof.

-->

{
    "jsonrpc":"2.0", 
    "id": 4,
    "method":"verify_payment_proof", 
    "params":
    {
        "payment_proof" : "8009f28991ef543253c8b6a2caf15cf99e23fb9c2b4ca30dc463c8ceb354d7979e80ef7d4255dd5e885200648abe5826d8e0ba0157d3e8cf9c42dcc8258b036986e50400371789ee82afc25ee29c9c57bcb1018b725a3a94c0ceb1fa7984ea13de4982553e0d78d925a362982182a971e654857b8e407e7ad2e9cb72b2b8228812f8ec50435351000c94e2c85996e9527d9b0c90a1843205a7ec8f99fa534083e5f1d055d9f53894"
    }
}

<--

{
    "jsonrpc":"2.0", 
    "id": 4,
    "result": 
    {
        "is_valid": true,
        "asset_id": 0,
        "sender":   "9f28991ef543253c8b6a2caf15cf99e23fb9c2b4ca30dc463c8ceb354d7979e",
        "receiver": "ef7d4255dd5e885200648abe5826d8e0ba0157d3e8cf9c42dcc8258b036986e5",
        "amount":   2300000000,
        "kernel":   "ee82afc25ee29c9c57bcb1018b725a3a94c0ceb1fa7984ea13de4982553e0d78"
    }
}

• is_valid true if signature is valid,
• sender sender's SBBS address
• receiver is a receiver's SBBS address, is it is used to verify the signature
• amount amount sent by the transaction in groth
• asset_id asset id of the transaction, 0 for HDS. Returned starting from v5.0
• kernel id of the kernel of this transaction

N.B. v5.0+ APIs accept proofs generated by older versions.

Errors are returned as:

  error: {
    code: -32003,
    data: "It's not your own address.",
    message: 'Invalid address.'
  }

where

• code is a unique identifier of the error
• message textual description of the error
• data is the context data of the error

Here is the list of the possible error codes(with messages):

• -32600 ("Invalid JSON-RPC.")
• -32601 ("Procedure not found.")
• -32602 ("Invalid parameters.")
• -32603 ("Internal JSON-RPC error.")
• -32001 ("Invalid TX status.")
• -32002 ("Unknown API key.")
• -32003 ("Invalid address.")
• -32004 ("Invalid transaction ID.")
• -32005 ("Feature is not supported")
• -32006 ("Invalid payment proof provided")
• -32007 ("Cannot export payment proof")
• -32008 ("Invalid swap token.")
• -32009 ("Can't accept own swap offer.")
• -32010 ("Not enought hdss.")
• -32011 ("Doesn't have active connection.")
• -32012 ("Database error")
• -32013 ("Database not found")
• -32014 ("Requests limit exceeded")

Add --ip_whitelist=192.168.0.1,192.168.0.2 parameter to enable access to the API by IP address.

The API methods can have access rights if you enable Access Control List (ACL) in the command line using --use_acl=1 parameter)

create_address      - write access
validate_address    - read access
addr_list           - read access
delete_address      - write access
edit_address        - write access
tx_send             - write access
tx_status           - read access
tx_split            - write access
tx_asset_issue      - write access
tx_asset_consume    - write access
tx_asset_info       - write access
tx_cancel           - write access
get_utxo            - read access
tx_list             - read access
wallet_status       - read access
get_asset_info      - read access
generate_tx_id      - read access
export_payment_proof- read access
verify_payment_proof- read access

ACL file should look like a list with the access keys and read/write rights:

472e17b0419055ffee3b3813b98ae671579b0ac0dcd6f1a23b11a75ab148cc67 : write
bd39333a66a8b7cb3804b5978d42312c841dbfa03a1c31fc2f0627eeed6e43f2 : read
f287176bdd517e9c277778e4c012bf6a3e687dd614fc552a1ed22a3fee7d94f2 : read

Also, don't forget to send a user key in every JSONRPC request to the API:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "wallet_status",
    "key": "bd39333a66a8b7cb3804b5978d42312c841dbfa03a1c31fc2f0627eeed6e43f2"
}

Add --use_tls=1 to enable TLS encryption. Also, you have to buy certificates or create self signed certificates on your local machine and pass them using --tls_cert and --tls_key parameters.

If you are only testing you can download the sample certificate and key files from here:
Certificate File
Certificate Private Key File