Node JSON RPC API

Service location

By default, Bitsum Node (bitsumd) is bound only to 127.0.0.1 (localhost) interface, so can be accessed only from the same computer it runs on. This is done to reduce number of external attack vectors. Node itself (bitsumd) has access to only public information, but it sometimes runs in the same process with RPC wallet (wallet-rpc), which has access to wallet keys. To bind to all interfaces, use --daemon-rpc-bind-address=0.0.0.0:28081 command line argument (specifying port is mandatory).

To make a JSON PRC request to the Node (bitsumd) you should make an HTTP POST request to an entry point:

http://<ip>:<port>/json_rpc

where:

• <ip> is IPv4 address of the Node (bitsumd). If the service is on local machine, use 127.0.0.1 instead of localhost.
• <port> is TCP port of bitsumd. By default the service is bound to 28081.

Curl template

curl -s -u <user>:<pass> -X POST http://<ip>:<port>/json_rpc -H 'Content-Type: application/json-rpc' -d '{"jsonrpc": "2.0", "method": "<method>", "params": {<params>}}'

Methods

Method	Description
get_status	Returns status of bitsumd.

1. Get status

About

Get status about state of bitsumd.

Input (params)

Empty

Output

Field	Type	Description
top_known_block_height	uint32	Network block height.
top_block_height	uint32	Local Node height.
top_block_difficulty	uint64	Difficulty of top block.
top_block_timestamp	uint32	Timestamp of top block.
top_block_hash	string	Hash of top block.
top_block_timestamp_median	uint32	Median timestamp of top block.
recommended_fee_per_byte	uint64	Value of fee recommended.
transaction_pool_version	uint32	Adding or removing transaction from pool increments version.
incoming_peer_count	uint32	Incoming peers to bitsumd.
outgoing_peer_count	uint32	Outgoing peers from bitsumd.
lower_level_error	string	Error on lower level (bitsumd for wallet-rpc, etc).
next_block_effective_median_size	uint32	Created transaction raw size should be less this value, otherwise will not fit in block.

Example:

Let's do a regular status request.

Input:

curl -s -u user:pass -X POST http://127.0.0.1:28081/json_rpc -H 'Content-Type: application/json-rpc' -d '{
  "jsonrpc": "2.0",
  "method": "get_status",
  "params": {}
}'

Output:

{
	"jsonrpc": "2.0",
	"result": {
		"incoming_peer_count": 5,
		"lower_level_error": "",
		"next_block_effective_median_size": 100000,
		"outgoing_peer_count": 8,
		"recommended_fee_per_byte": 10000,
		"top_block_difficulty": 182766643,
		"top_block_hash": "729edc5b9e5979cb6873cddd9c39964f02957bf5bcf2e08c55c3c9861ef0850f",
		"top_block_height": 170480,
		"top_block_timestamp": 1530617196,
		"top_block_timestamp_median": 0,
		"top_known_block_height": 170480,
		"transaction_pool_version": 4
	}
}