Introduction

Boolberry command-line wallet application (simplewallet) can be run in RPC server mode. In this mode it can be controlled by RPC calls via HTTP and be used as a back-end for an arbitrary service.

Starting the wallet in RPC server mode:

  • 1. Run boolbd (the daemon application).
  • 2. Run simplewallet with the following options:

    simplewallet --wallet-file PATH_TO_WALLET_FILE --password PASSWORD --rpc-bind-ip RPC_IP --rpc-bind-port RPC_PORT --daemon-address DEAMON_ADDR:DAEMON_PORT

    where:

    PATH_TO_WALLET_FILE - path to an existing wallet file (should be created beforehand using--generate-new-walletcommand);
    PASSWORD - wallet password;
    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;
    DEAMON_ADDR:DAEMON_PORT - daemon address and port (may be omitted if the daemon is running on the same machine with the default settings);

Examples below are given with assumption that the wallet application is running in RPC server mode and listening at 127.0.0.1:12233.

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

List of RPC calls

  • getbalance

    Retrieves current wallet balance: total and unlocked.

    Inputs:
    None.

    Outputs:
    balance — unsigned integer; total amount of funds the wallet has (unlocked and locked coins).
    unlocked_balance — unsigned integer; unlocked funds, i.e. coins that are stored deep enough in the blockchain to be considered relatively safe to spend. Only this amount of coins are immediately spendable.
    unlocked_balance is always less or equal to balance.

    Examples

    $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"3","method":"getbalance"}'
    {
     "id": "3",
     "jsonrpc": "2.0",
     "result": {
       "balance": 4631800000,
       "unlocked_balance": 4431900000
     }
    }
  • getaddress

    Obtains wallet public address.

    Inputs:
    None.

    Outputs:
    address — string; standard public address of the wallet

    Examples

    $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"3","method":"getaddress"}'
    {
     "id": "3",
     "jsonrpc": "2.0",
     "result": {
       "address": "HcjASV5gT5zeABRWbWkTLj8c5vVkzDgyJfKXYQHAHvxS2qZaXke7VHP44jBsBpoDWJC2T4PSN6YEN2P3s9AVPcEWVdZZUx7"
     }
    }
  • transfer

    Creates a transaction and broadcasts it to the network.

    Inputs:
    destinations — list of transfer_destination objects (see below); list of recipients with corresponding amount of coins for each.
    fee — unsigned int; transaction fee in atomic units. Minimum 105 atomic units, recommended 106 or 107.
    mixin — unsigned int; number of foreign outputs to be mixed in with each input. Increases untraceability. Use 0 for direct and traceable transfers.
    payment_id — string; hex-encoded payment id. Can be empty if payment id is not required for this transfer.

    transfer_destinationobject fields:
    address — string; standard or integrated address of a recipient.
    amount — unsigned int; amount of coins to be sent;

    Outputs:
    tx_hash — string; hash identifier of the transaction that was successfully sent.

    Examples

    Not enough money

    $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"5","method":"transfer", "params":{"destinations":[{"address":"HcjASV5gT5zeABRWbWkTLj8c5vVkzDgyJfKXYQHAHvxS2qZaXke7VHP44jBsBpoDWJC2T4PSN6YEN2P3s9AVPcEWVdZZUx7", "amount":10000000000000}]}}'
    {
     "error": {
       "code": -4,
       "message": "NOT_ENOUGH_MONEY"
     },
     "id": "5",
     "jsonrpc": "2.0"
    }

    Fee is too small

    $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"5","method":"transfer", "params":{"destinations":[{"address":"HcjASV5gT5zeABRWbWkTLj8c5vVkzDgyJfKXYQHAHvxS2qZaXke7VHP44jBsBpoDWJC2T4PSN6YEN2P3s9AVPcEWVdZZUx7", "amount":100000000}], "fee":10}}'
    {
     "error": {
       "code": -4,
       "message": "transaction was rejected by daemon"
     },
     "id": "5",
     "jsonrpc": "2.0"
    }

    Correct request

    $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"5","method":"transfer", "params":{"destinations":[ {"address":"h9MPDxJCbEvHNSXkykzXzy7imqgsunmgn3KoHa1qn3PjEtcySfCTB6ea8YTCrXxZzS9aGBUSGTw1W5XFJGwJXjwUb7wdQ4c9dXM3Bz4ow4dD", "amount":100000000}, {"address":"HcjASV5gT5zeABRWbWkTLj8c5vVkzDgyJfKXYQHAHvxS2qZaXke7VHP44jBsBpoDWJC2T4PSN6YEN2P3s9AVPcEWVdZZUx7", "amount":200000000}], "fee":1000000, "mixin":0}}'
    {
     "id": "5",
     "jsonrpc": "2.0",
     "result": {
       "tx_hash": "<138ba717c200167634a444b25a9f30251cbfd049052cfbcc63f31367d644d1f0>"
     }
    }
  • store

    Saves wallet update progress into a wallet file. Although progress is always saved upon graceful wallet application termination, with this call a user can manually trigger saving process. Otherwise, in a case of abnormal wallet application termination the progress won’t be saved and it will take some time to synchronize on the next launch.

    Inputs:
    None.

    Outputs:
    None.

    Examples

    $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"3","method":"store"}'
    {
     "id": "3",
     "jsonrpc": "2.0",
     "result": {
     }
    }
  • get_payments

    Gets list of incoming transfers by a given payment id.

    Inputs:
    payment_id — string; hex-encoded payment id.

    Outputs:
    result — list of payments object.

    payments object fields:

    • amount — unsigned int; amount of coins in atomic units.
    • block_height — unsigned int; height of the block containing corresponding transaction.
    • block_height — unsigned int; height of the block containing corresponding transaction.
    • tx_hash — string; transaction hash.
    • unlock_time — unsigned int; if non-zero — unix timestamp after which this transfer coins can be spent. If it is less than 500000000, the value is treated as a minimum block height at which this transfer coin can be spent.

    Examples

    $ curl http://127.0.0.1:12233/json_rpc -s -H 'content-type:application/json;' --data-binary '{"jsonrpc":"2.0","id":"5","method":"get_payments", "params":{"payment_id":"6162636465"}'
    {
     "id": "5",
     "jsonrpc": "2.0",
     "result": {
       "payments": [{
         "amount": 100000000,
         "block_height": 202556,
         "tx_hash": "01220e8304d46b940a86e383d55ca5887b34f158a7365bbcdd17c5a305814a93",
         "unlock_time": 0
       }]
     }
    }