Walletd API

Manage multiple BLOC addresses

BLOC e-commerce solution called BLOC RPC Wallet (Walletd). BLOC RPC Wallet is a HTTP server which provides JSON 2.0 RPC interface for BLOC payment operations and address management.

BLOC JSON RPC API

BLOC E-Commerce and automated services solution

The cryptocurrency BLOC has unfolded and advanced a set of key methods to portray universal and integrated access to act as an alternative or replace the current banking system in regards to the expensive and restricted POS contactless terminals. BLOC is providing an open platform that enables companies to build their own products using the BLOC API. Enter the URL of the API where to connect to. Make sure you enter it exactly like on the exemple, then enter the RPC password. Test the implementation in your application using the form and exemple provided below.


Example: http://0.0.0.0:2093/json_rpc
this password will not be saved on server side



{API}
W A L L E T D

Accepting BLOC payments with Walletd

Introduction to walletd

BLOC integration process differes from other cryptocurrencies. Firstly, the coin has three separate binaries:


  • BLOCd — to synchronize with the block chain and mine BLOC coins.
  • simplewallet — to operate the funds and accept deposits using one address
  • Walletd — to operate the funds and accept deposits using multiple addresses

This section describes BLOC integration process into your service with BLOC e-commerce solution called BLOC RPC Wallet. BLOC RPC Wallet is a HTTP server which provides JSON 2.0 RPC interface for BLOC payment operations and address management. BLOC RPC Wallet allows you to accept incoming payments, generate an address for each user via and much more. BLOC RPC Wallet JSON RPC API contains detailed description of every method as follow:


Integration guide with Walletd

Setup and configuration of the BLOC RPC Wallet (Walletd)

To start integration process you should first download BLOC RPC Wallet, you can find it here: https://bloc.money/download

You may also build RPC Wallet from source code: https://github.com/furiousteam/BLOC


Generate a new wallet

To start using RPC wallet you must first generate a container. Container file is the only file that stores all data required to run your service. It contains user addresses and private keys required to operate them. Make sure to backup this file regularly. To generate a new container you should run the following command:


./walletd --container-file=mycontainer --container-password=mypassword --generate-container 

where: 

  • <mycontainer> is the container file name and a path to it (relative or absolute); path is optional in this argument, specifying only a container name will result in new file located in the same folder as RPC Wallet
  • <mypass> is a secret password for the new wallet file. Whichever you like;
  • --generate-container option tells RPC wallet to generate container file and exit.

Note: if <mycontainer> exists BLOC RPC Wallet (walletd) will show you the notification and will ask you to provide a different name.

If the operation was successful you will get a corresponding message with your new BLOC address. At the same time BLOC RPC Wallet will save your container on the local disk (in the same folder where BLOC RPC Wallet (walletd) is located and shut down.



Configure BLOC RPC Wallet 

To configure BLOC RPC wallet you can use both command line and config file. Config file allows you to configure your settings only once and use "--config" option further. The command below launches BLOC RPC Wallet (walletd) with a specific config file:


./walletd --config=myconfig.conf --rpc-password=RPCpassword

To get help on available options run:


./walletd -h 

Please note, BLOC RPC Wallet config file may consist only of these options:


Option Description Config Example Console Example
bind-address Which address to bind BLOC RPC Wallet to. Default value is 0.0.0.0 bind-address = 127.0.0.1 --bind-address=127.0.0.1
bind-port Which port to bind BLOC RPC Wallet to. Default value is 2053 bind-port = 2093 --bind-port=2093
daemon-address BLOC daemon (BLOCd) address for remote daemon connection infrastructure daemon-address = 127.0.0.1 --daemon-address=127.0.0.1
daemon-port BLOC daemon (BLOCd) port for remote daemon connection infrastructure. Default BLOC daemon ports are 2082 and 2086 for RPC calls daemon-port = 2086 --daemon-port=2086
container-file Mandatory. Your container file name container-file = mycontainer --container-file=mycontainer
container-password Mandatory. Your container password container-password = mypassword --container-password=mypassword
log-file A name of log file that you want to use for logging. Default is walletd.log log-file = mylog.log --log-file=mylog.log
server-root Working directory that you wish to use for BLOC RPC Wallet. Default is current working directory. server-root = /home/Downloads/RPCWallet --server-root=/home/Downloads/RPCWallet
log-level Level of logging. Default is 1. log-level = 2 --log-level=2
testnet Allows you to run BLOC RPC Wallet in testnet. testnet = no --testnet=no
local Option that allows you to start BLOC RPC Wallet as an in-process node local --local


Here is an example of a config file:


container-file = mycontainer
container-password = mypassword
daemon-address = 127.0.0.1
daemon-port = 2086
bind-port = 2053
testnet = no
bind-address = 0.0.0.0
rpc-password = RPCpassword

You may specify BLOC config directly through console arguments. Here is the same example as above in console: 


./walletd --container-file=mycontainer --container-password=mypassword --daemon-address=127.0.0.1 --daemon-port=2086 --bind-address=0.0.0.0 --bind-port=2053 --rpc-password=RPCpassword 

Note: config file path is relative to current working directory, not server root.

Note: options "container-file" and "container-password" should ALWAYS be set (in either command line or config file mode).

Note: "container-file" and "log-file" options are relative to "server-root". "server-root" default is the current working directory.


Start BLOC RPC Wallet (walletd)

There are two ways to start BLOC RPC Wallet: 


Start with a remote connection to the Daemon

Remote connection allows you to bind your BLOC RPC Wallet to a remote BLOC daemon (BLOCd). Such type of connection allows you to start BLOC RPC Wallet without having to download the blockchain. Your wallet will be instantly synchronised. Always make sure that you trust the remote connection you are connecting to.


  • For local daemons use localhost or 127.0.0.1 as an IP address.
  • For remote daemons specify the remote daemon IP address.

Default BLOC daemon ports are 2082 and 2086 (for rpc calls). Use the following command to start BLOC RPC Wallet with a remote connection: 


./walletd --container-file=mycontainer --container-password=mypassword --daemon-address=IP.OF.YOUR.DAEMON --daemon-port=2086 --bind-address=0.0.0.0 --bind-port=2053 --rpc-password=RPCpassword

Note: BLOC daemon (BLOCd) should be running at the moment RPC wallet is starting in a remote connection mode.

Note: BLOC RPC Wallet will still provide some functionality even if Daemon server fails. For example, you will be able to generate addresses for your users.


Start as in-process node

You can also start BLOC RPC Wallet with an in-process node. This allows you to start RPC Wallet out-of-box with no external daemon required. You will get a fully functional node for BLOC network inside BLOC RPC Wallet. You do not have to download or install anything besides BLOC RPC Wallet. This approach will help reduce the overheads required for infrastructure maintenance.

Use the following command to start BLOC RPC Wallet with an in-process node


./walletd --container-file=mycontainer --container-password=mypassword --local --bind-address=0.0.0.0 --bind-port=2053 --rpc-password=RPCpassword

Run BLOC RPC Wallet 

BLOC RPC wallet can be started in both daemon and console modes. 


  • Daemon mode - BLOC RPC Wallet is launched in the background, while you can continue to work with a console window. 
  • Console mode - BLOC RPC Wallet is launched and prints log messages on the screen.

BLOC RPC wallet starts in console mode by default.


Start as daemon (UNIX only)

To start BLOC RPC wallet as daemon just set "--daemon" (or short "-d") option.


./walletd --container-file=mycontainer --container-password=mypassword --daemon --bind-address=0.0.0.0 --bind-port=2053 --rpc-password=RPCpassword

Note: it is a common practice for daemons to set server root directory. 

Server root is the directory where RPC Wallet stores all its files. All relative paths in RPC Wallet configuration are relative to the server root directory.


Start as service (Windows only)

To run BLOC RPC wallet as a service on Windows you have to do the following:

1. Create a config file and place it in the same directory as your RPC wallet executable resides in. 

A note for Windows Users: In case the server root in config file is not specified all paths should be ABSOLUTE. If you set server root you can use relative paths (relative to your server root);

2. Register your BLOC RPC Wallet as a service. To do so, run the following command as an ADMINISTRATOR:


walletd.exe --register-service 

3. After you see message about successful service registration you can run it in your services panel.


Uninstall service (Windows only)

If you want to delete BLOCRPC wallet you have to unregister windows service first (if you have registered it before). Run as an ADMINISTRATOR:


walletd.exe --unregister-service 


{API}
W A L L E T D

BLOC RPC Wallet API methods

Use the form below to test the integration of the BLOC RPC Wallet API (walletd) into your application. Make sure you have filled the connexion details at the top of this page.

On this page you will find description of every method in BLOC RPC Wallet API. BLOC RPC Wallet is a HTTP server which provides JSON 2.0 RPC interface for BLOC payment operations and address management. Each method has its own page that can be found by clicking on this method. To make a JSON PRC request to your BLOC RPC Wallet you should use POST request that looks like this:


http://<service address>:<service port>/json_rpc 

where:


  • <service address> is an IP of BLOC Walletd RPC server, if Walletd is located on local machine it is either 127.0.0.1 or localhost,
  • <service port> is BLOCd RPC server port, by default it is binded to 2053 port, but it can be manually binded to any port you want, scroll up on this page for more details.



Implementation Notes

createAddress() method creates an additional address into the wallet.


Input Parameters

Argument Mandatory Description Format Example
it requires no extra parameters


Implementation Notes

createDelayedTransaction() method creates a delayed transaction. Such transactions are not sent into the network automatically and should be pushed using sendDelayedTransaction() method.
Note: if container contains only 1 address, changeAddress field can be left empty and the change is going to be sent to this address
Note: if addresses field contains only 1 address, changeAddress can be left empty and the change is going to be sent to this address
Note: in the rest of the cases, changeAddress field is mandatory and must contain an address.
Note: outputs that were used for this transactions will be locked until the transaction is sent or cancelled


Input Parameters

Argument Mandatory Description Format Example
addresses no array of strings, where each string is an address array
transfers yes array that contains:
  • address - string
  • amount - int64
this is the receiver
array "amount": 10000,
"address": "abLoc7qZYJd7cWysPQRivNNMQMFgkXNPgiQXN1i2twdUWvw r2XnsMqk3c4KQ9iMJ4AV4fpBMccmjfJ4cu7uprKLNFX4qWNh"
fee yes transaction fee. Minimal fee in BLOC network is 0.0001 BLOC. This parameter should be specified in minimal available BLOC units. For example, if your fee is 0.0001 BLOC, you should pass it as 1 uint64 1
unlockTime no height of the block until which transaction is going to be locked for spending. uint64 100000
anonymity yes privacy level (a discrete number from 1 to infinity). Level 6 and higher is recommended. uint64 1
extra no string of variable length. Can contain A-Z, 0-9 characters. string
paymentId no paymentId string 64 hexadecimal characters identifier Payment ID
changeAddress no valid and existing address in this container address. string abLoc7qZYJd7cWysPQRivNNMQMFgkXNPgiQXN1i2twdUWvwr2XnsMqk3c4KQ9iMJ4AV4fpBMccmjfJ4cu7uprKLNFX4qWNh

input multiple addresses separated by comma (,)
only 1 transfer available
only 1 transfer available

Implementation Notes

deleteAddress() method delete a specified address from the container.


Input Parameters

Argument Mandatory Description Format Example
address yes a valid address found in the container to be deleted string abLoc7qZYJd7cWysPQRivNNMQMFgkXNPgiQXN1i2twdUWvwr2XnsMqk3c4KQ9iMJ4AV4fpBMccmjfJ4cu7uprKLNFX4qWNh


Implementation Notes

deleteDelayedTransaction() method deletes a specified delayed transaction.


Input Parameters

Argument Mandatory Description Format Example
transactionHash yes valid, existing delayed transaction hash sent using an address from this container string 2cf5d3d2109a133149574b10c9fbad6b2801ab2a87587c0e812c40dbe3a227dd


Implementation Notes

estimateFusion() method counts the number of unspent outputs of the specified addresses and returns how many of those outputs can be optimized.
This method is used to understand if a fusion transaction can be created. If fusionReadyCount returns a value = 0, then a fusion transaction cannot be created.


Input Parameters

Argument Mandatory Description Format Example
threshold yes value that determines which outputs will be optimized. Only the outputs, lesser than the threshold value, will be included into a fusion transaction uint64 10000
addresses no array of strings, where each string is an address to take the funds from array

input multiple addresses separated by comma (,)

Implementation Notes

getAddresses() method returns an array of your RPC Wallet's addresses stored inside the container.


Input Parameters

Argument Mandatory Description Format Example
it requires no extra parameters


Implementation Notes

getBalance() method returns a balance for a specified address inside the container.
Please note: If address is not specified, returns a cumulative balance of all RPC Wallet's addresses stored inside the container.


Input Parameters

Argument Mandatory Description Format Example
address yes a valid address found in the container string abLoc7qZYJd7cWysPQRivNNMQMFgkXNPgiQXN1i2twdUWvwr2XnsMqk3c4KQ9iMJ4AV4fpBMccmjfJ4cu7uprKLNFX4qWNh


Implementation Notes

getBlockHashes() method returns an array of block hashes for a specified block range.


Input Parameters

Argument Mandatory Description Format Example
firstBlockIndex yes starting height uint32 123123
blockCount yes number of blocks to process uint32 20


Implementation Notes

getDelayedTransactionHashes() method returns transactions hashes of delayed transactions.


Input Parameters

Argument Mandatory Description Format Example
it requires no extra parameters


Implementation Notes

getSpendKeys() method returns your spend public key and spend secret key.


Input Parameters

Argument Mandatory Description Format Example
address yes a valid address found in the container string abLoc7qZYJd7cWysPQRivNNMQMFgkXNPgiQXN1i2twdUWvwr2XnsMqk3c4KQ9iMJ4AV4fpBMccmjfJ4cu7uprKLNFX4qWNh


Implementation Notes

getStatus() method returns information about the current RPC Wallet state: block_count, known_block_count, last_block_hash and peer_count.


Input Parameters

Argument Mandatory Description Format Example
it requires no extra parameters


Implementation Notes

getTransaction() method returns information about a particular transaction.
Transaction consists of transfers. Transfer is an amount-address pair. There could be several transfers in a single transaction.
Note: the transaction Hash must belong to one of your wallet address found in the container


Input Parameters

Argument Mandatory Description Format Example
transactionHash yes hash of the requested transaction string example


Implementation Notes

getTransactionHashes() method returns an array of block and transaction hashes.
Transaction consists of transfers. Transfer is an amount-address pair. There could be several transfers in a single transaction.
Note: if paymentId parameter is set, getTransactions() method returns transactions that contain specified payment_id. (in the set block range)
Note: if addresses parameter is set, getTransactions() method returns transactions that contain transfer from at least one of specified addresses.
Note: if both above mentioned parameters are set, getTransactions() method returns transactions that contain both specified payment_id and transfer from at least one of specified addresses.


Input Parameters

Argument Mandatory Description Format Example
addresses no array of strings, where each string is an address array abLoc7qZYJd7cWysPQRivNNMQMFgkXNPgiQXN1i2twdUWvwr2XnsMqk3c4KQ9iMJ4AV4fpBMccmjfJ4cu7uprKLNFX4qWNh
blockHash only one of these parameters (blockHash or firstBlockIndex) is allowed hash of the starting block string 4297128fbe5edc25fe39cde979956e141035d2f9316ba32e97a4f9a4f06e6961
firstBlockIndex only one of these parameters (blockHash or firstBlockIndex) is allowed starting height uint32 123
blockCount yes number of blocks to return transaction hashes from uint32 20
paymentId no valid payment_id string 64 hexadecimal characters identifier Payment ID

input multiple addresses separated by comma (,)

Implementation Notes

getTransactions() method returns an array of block and transaction hashes.
Transaction consists of transfers. Transfer is an amount-address pair. There could be several transfers in a single transaction.
Note: if paymentId parameter is set, getTransactions() method returns transactions that contain specified payment_id. (in the set block range)
Note: if addresses parameter is set, getTransactions() method returns transactions that contain transfer from at least one of specified addresses.
Note: if both above mentioned parameters are set, getTransactions() method returns transactions that contain both specified payment_id and transfer from at least one of specified addresses.


Input Parameters

Argument Mandatory Description Format Example
addresses no array of strings, where each string is an address array abLoc7qZYJd7cWysPQRivNNMQMFgkXNPgiQXN1i2twdUWvwr2XnsMqk3c4KQ9iMJ4AV4fpBMccmjfJ4cu7uprKLNFX4qWNh
blockHash only one of these parameters (blockHash or firstBlockIndex) is allowed hash of the starting block string 4297128fbe5edc25fe39cde979956e141035d2f9316ba32e97a4f9a4f06e6961
firstBlockIndex only one of these parameters (blockHash or firstBlockIndex) is allowed starting height uint32 123
blockCount yes number of blocks to return transaction hashes from uint32 20
paymentId no valid payment_id string 64 hexadecimal characters identifier Payment ID

input multiple addresses separated by comma (,)

Implementation Notes

getUnconfirmedTransactionHashes() method returns information about the current unconfirmed transaction waiting to be included in a block. There could be several transfers in a single transaction.


Input Parameters

Argument Mandatory Description Format Example
addresses no array of strings, where each string is an address array abLoc7qZYJd7cWysPQRivNNMQMFgkXNPgiQXN1i2twdUWvwr2XnsMqk3c4KQ9iMJ4AV4fpBMccmjfJ4cu7uprKLNFX4qWNh

input multiple addresses separated by comma (,)

Implementation Notes

getViewKey() method returns your view key.


Input Parameters

Argument Mandatory Description Format Example
address yes a valid address found in the container to be deleted string abLoc7qZYJd7cWysPQRivNNMQMFgkXNPgiQXN1i2twdUWvwr2XnsMqk3c4KQ9iMJ4AV4fpBMccmjfJ4cu7uprKLNFX4qWNh


Implementation Notes

sendDelayedTransaction() method sends a specified delayed transaction.


Input Parameters

Argument Mandatory Description Format Example
transactionHash yes valid, existing delayed transaction hash sent using an address from this the container string 2cf5d3d2109a133149574b10c9fbad6b2801ab2a87587c0e812c40dbe3a227dd


Implementation Notes

sendFusionTransaction() method allows you to send a fusion transaction, by taking funds from selected addresses and transferring them to the destination address. If there aren't any outputs that can be optimized, sendFusionTransaction() will return an error. You can use estimateFusion to check the outputs, available for the optimization.


Input Parameters

Argument Mandatory Description Format Example
threshold yes value that determines which outputs will be optimized. Only the outputs, lesser than the threshold value, will be included into a fusion transaction uint64 10000
anonymity yes privacy level (a discrete number from 1 to infinity). Level 6 and higher is recommended uint64 6
addresses no array of strings, where each string is an address to take the funds from array
destinationAddress no an address that the optimized funds will be sent to. Valid and existing in this container address string abLoc7qZYJd7cWysPQRivNNMQMFgkXNPgiQXN1i2twdUWvwr2XnsMqk3c4KQ9iMJ4AV4fpBMccmjfJ4cu7uprKLNFX4qWNh

input multiple addresses separated by comma (,)

Implementation Notes

sendTransaction() method allows you to send transaction to one or several addresses. Also, it allows you to use a payment_id for a transaction to a single address.
Note: if container contains only 1 address, changeAddress field can be left empty and the change is going to be sent to this address
Note: if addresses field contains only 1 address, changeAddress can be left empty and the change is going to be sent to this address
Note: in the rest of the cases, changeAddress field is mandatory and must contain an address.


Input Parameters

Argument Mandatory Description Format Example
addresses no array of strings, where each string is an address to take the funds from array
transfers yes array that contains:
  • address - string
  • amount - int64
this is the receiver
array "amount": 1000,
"address": "abLoc7qZYJd7cWysPQRivNNMQMFgkXNPgiQXN1i2twdU Wvwr2XnsMqk3c4KQ9iMJ4AV4fpBMccmjfJ4cu7uprKLNFX4qWNh"
fee yes transaction fee. Minimal fee in BLOC network is 0.0001 BLOC. This parameter should be specified in minimal available BLOC units. For example, if your fee is 0.0001 BLOC, you should pass it as 1 uint64 1
unlockTime no height of the block until which transaction is going to be locked for spending. uint64 0
anonymity yes privacy level (a discrete number from 1 to infinity). Level 6 and higher is recommended. uint64 6
extra no string of variable length. Can contain A-Z, 0-9 characters. string
paymentId no paymentId string 64 hexadecimal characters identifier Payment ID
changeAddress no valid and existing in this container address. string abLoc7qZYJd7cWysPQRivNNMQMFgkXNPgiQXN1i2twdUWvwr2XnsMqk3c4KQ9iMJ4AV4fpBMccmjfJ4cu7uprKLNFX4qWNh

only 1 sender available in this example
only 1 receiver available in this example
only 1 receiver transfer available in this example

Implementation Notes

autoOptimize() method optimizes the wallet to send larger amounts.


Input Parameters

Argument Mandatory Description Format Example