Skip to main content

Daemon RPC Mode

Nirmata command-line daemon application (nirmatad) can be controlled by remote procedure calls (RPC). This makes it possible to use it as a back end for user-defined services.

The daemon starts in RPC server mode by default. To specify the RPC port or bind address the user will need to run nirmatad with the following options:

nirmatad --rpc-bind-ip RPC_IP --rpc-bind-port RPC_PORT

where:

RPC_IP — IP address to bind RPC server to (127.0.0.1 will be used if not specified);
RPC_PORT — TCP port for RPC server (11232 is default);

All examples below are based on the assumption that the daemon is listening for RPC at 127.0.0.1:11232.

All amounts and balances are represented as unsigned integers and measured in atomic units — the smallest fraction of a coin.

One coin is equal to 10^12 atomic units.

JSON RPC BUSY response​

All JSON RPC calls are served via http\://RPC_IP:RPC_PORT/json_rpc URI.

Any request may receive a BUSY response if the daemon is synchronizing with the network. In such cases the user should repeat the request later.

{
  "id": "0",
  "jsonrpc": "2.0",
  "result": {
    "status": "BUSY"
  }
}

Alternative blocks are not stored between subsequent runs of the daemon application. For a recently started daemon the list of known alternative blocks is always empty.

Connect Legacy JSON API​

This API is legacy and not compliant with the JSON RPC specification. Methods in this section are accessed directly by http://RPC_IP:RPC_PORT/METHOD_NAME URI — plain JSON in and out, with no jsonrpc/method/id envelope and no /json_rpc path.

Connect Binary RPC API​

Binary API uses binary protocol for communication, which is more compact and faster than JSON-API, especially when transferring large amounts of data. It was designed to communicate with a wallet application.
You may want to use epee serialization, in particular
epee::serialization::store_t_to_binary and epee::serialization::load_t_from_binary methods, to serialize your data before passing to API, and to deserialize upon retrieving from API. Alternatively, you may use epee::net_utils::invoke_http_bin_remote_command2

All methods in this section are accessible by http://RPC_IP:RPC_PORT/METHOD_NAME URI. Because they use epee's binary portable-storage format rather than JSON, they can't be called with a plain JSON body or exercised from a generic HTTP client — a wallet or tool needs to link epee (or reimplement its serialization) to call them. They exist mainly for wallet-to-daemon sync traffic:

  • getblocks.bin — fetch a batch of blocks for sync (COMMAND_RPC_GET_BLOCKS_FAST)
  • get_o_indexes.bin — global output indexes for a set of transactions (COMMAND_RPC_GET_TX_GLOBAL_OUTPUTS_INDEXES)
  • getrandom_outs.bin — random decoy outputs for ring signatures (COMMAND_RPC_GET_RANDOM_OUTPUTS_FOR_AMOUNTS)
  • set_maintainers_info.bin — publish maintainer/service-node info (COMMAND_RPC_SET_MAINTAINERS_INFO)
  • get_tx_pool.bin — fetch the current mempool (COMMAND_RPC_GET_TX_POOL)
  • check_keyimages.bin — check whether key images are already spent (COMMAND_RPC_CHECK_KEYIMAGES)
  • scan_pos.bin — PoS staking scan helper (COMMAND_RPC_SCAN_POS)
  • get_pos_details.bin — PoS mining details (COMMAND_RPC_GET_POS_MINING_DETAILS)