This post describes how to call Bitcoin information using simple Python scripts. The bitcoin client has a powerful API and RPC interface that can be easily called in practically any programming language one can think about.
Python is common and easy to understand scripting language that is extremely useful for automating complex tasks, especially for the bitcoin based tasks. This makes it ideal language to jump in playing with bitcoin transactions or the blockchain based applications.
Python + bitcoin
Python supports byte sequences and large integers which makes it good fit for bitcoin operations. The bitcoin client on the other hand, is highly robust.
The RPC interface in the client allows easy retrieval of information such as the network, peer connectivity, wallet related operations, signing and other low-level information such as raw transaction constructions!
RPC server
This post already assumes that user has the bitcoin client (`bitcoind`) installed and setup. First step is to run the `bitcoind` as a server using the following command:
$ bitcoind -daemon -printtoconsole
This will start `bitcoind` as a client that connects to other nodes in the bitcoin network and also as a local server that allows use of RPC calls. To make use of the RPC capabilities it is must to have RPC username and password set up in the bitcoin configuration file. The bitcoin configuration file `bitcoin.conf` is by default in ~/.bitcoin/bitcoin.conf , which if configured before running bitcoind will continue with the process of connecting to other nodes within the bitcoin network, synchronizing the blockchain along with listening to local RPC calls.
Note: It is possible to run `bitcoind` as a daemon (background process) thus reducing the workplace cluster that would otherwise spawn during the experimentation.
It is highly recommended that experimenting with RPC be conducted over either the `regtest` or the `testnet` to avoid mishaps with valid bitcoins. To run the bitcoind in either regtest or testnet mode, pass on the mode as argument for bitcoind as shown below:
$ bitcoind -[testnet=1/regtest] -daemon -printtoconsole
Making RPC calls with bitcoin-cli
In earlier versions of bitcoind it was possible to directly execute the RPC calls by passing the calls as arguments to bitcoind. In current versions, this method has been deprecated and now it is required to pass these arguments to the bitcoin-cli. For example, with bitcoin configuration set and bitcoin server running, it is possible to do the following:
https://gist.github.com/e755124b7074baaf14532675e4b11907
How it works
When the bitciond is executed in server mode, it setups a local http server that listens for requests, decodes the method name and the parameters mentioned in these requests and encodes the results as response to the http request. These encoding and decoding nothing than encapsulating as a JSON data.
From the other side, the bitcoin-cli looks up the RPC connection information from the bitcoin.conf, creates a http connection to the server, encodes the method name and parameters specified as JSON, sends a specifically formatted http request that includes the JSON. Finally, upon receipt of the http response, it decodes the JSON and outputs it for the user.
Working with Python
There are numerous libraries that can be used for connecting the bitcoin-rpc with Python. For the sake of simplicity, we use the requests library for Python. By working with python we simply pass on the arguments that would otherwise be passed via the bitcoin-cli using Python.
An example script that queries the earlier example is below:
https://gist.github.com/50226b8aca960dfb49d19aa688d5700b
If the packages are installed correctly then it should display output like the following:
https://gist.github.com/e80b24f1ea4c78f60d31997089954139
Note: Before executing the script you would need to change the rpcuser, rpcpassword and rpcport in the script to reflect the parameters defined in the bitcoin.conf file.
It is worth noting that the output data is returned in the form of Python dictionaries and lists which can be directly referred in other Python scripts without requiring any further processing.
Using Python class
It is useful to have errors and exceptions in the scripts above to make it easier for debugging. To do so, we encapsulate the our functionalities as a python class:
https://gist.github.com/6baad86e832acf0df23a70914c014d7a
This script can be easily used like following:
https://gist.github.com/6a946bd666786a8986b5118802e909ea
There are a couple of wrapper libraries in the wild that adds the actual functions for each of the RPC methods (e.g. bitcoin-python). Personally, I like the to have a simple RPCHost class as defined earlier to keep it simple and avoid dependencies on third-party libraries. This is especially helpful if you intend to have complex RPC call chains. Furthermore, creating your own RPCHost class makes it easier to implement further bitcoin based 'applications' such as the Lightning Network.
What about AltCoin RPC?
The popularity (or unpopularity) of bitcoin lead to rise of many different alternative cryptocurrencies, bunched under the term Altcoins. These altcoins in principle is the fork from the bitcoin code which includes the RPC setup which means one can use the same RPC code with almost all of the altcoins.
For example, the Litecoin's RPC capabilities can be access just by changing the port to 9332 in the same script; the Dogecoin at 22555, etc.
The possibilities of the 'shared' RPC base are near endless :D
Conclusion
Making calls to RPC bitcoind is trivial! The applications that can developed using such calls are enormous. In future post, I will be sharing more of tricks for optimizing the RPC calls using Python scripts that I have learned in my own RPC adventures, which will include RPC calls for Lightning Network.