Beam wallet protocol API

Starting from v6.0 BEAM wallet supports API versioning. Please choose the corresponding API version in the list below to get available methods description.

• version 6.0
• version 6.1

Sections below apply to the all API versions above 6.0.

General

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 using --use_http=1 option. Send POST requests to http://x.x.x.x:port/api/wallet in this case.

Running Wallet API

Place wallet-api binary located in the wallet folder near your wallet.db and run it. You can specify options in CLI or using wallet-api.cfg file. Minimal options required are your wallet.db password (--pass) and the node to connect to ( - n=)

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
  --log_cleanup_days arg (=5)           old logfiles cleanup period(days)
  --node_poll_period arg (=0)           Node poll period in milliseconds. Set
                                        to 0 to keep connection. Anyway poll
                                        period would be no less than the
                                        expected rate of blocks if it is less
                                        then it will be rounded up to block
                                        rate value.
  --enable_assets                       enable confidential assets transactions
  --enable_lelantus                     enable Lelantus MW transactions
  --api_version                         specify API version. Available since v6.0. Acceptable values: current, 6.0, 6.1 &c.

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

wallet-api.cfg file

Running API Server in TCP mode

By default API launches in TCP mode. For example:

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

Accessing API Server via TCP

Here is an example NodeJS code to get all UTXOs from the Wallet API server that is running in TCP mode

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');
});

Running API Server in HTTP mode

Run via cli with '--use_http=1':

./wallet-api --node_addr=172.104.249.212:8101 --pass=123 --use_http=1

Or add 'use_http=1' to the wallet-api.cfg to enable HTTP mode.

Accessing API Server via HTTP

You can perform POST requests using CURL. Here is an example to get the 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