This step-by-step tutorial provides a hands-on walkthrough for quickly getting up and running with Bitcoin basics, from a developer's perspective. From building and installation of the headless Bitcoin daemon (bitcoind), interacting with it using the command line, and building a demo C++ application that can send RPC commands and process responses.
The tutorial is written for Ubuntu 18.04. Adjust accordingly for your own environment.
- Install Prerequisites
Install the following dependencies.
sudo apt install openssl autoconf automake libboost-dev libboost-all-dev libevent-dev
sudo add-apt-repository ppa:bitcoin/bitcoin
sudo apt-get update
sudo apt-get install libdb4.8-dev libdb4.8++-dev
- Clone the bitcoin repository and change into its directory
$ git clone https://github.com/bitcoin/bitcoin.git
$ cd bitcoin
- Configure the build
$ ./autogen.sh && ./configure
- Building and installing the project
$ make -j4 && sudo make install
- Check the installation
$ which bitcoind
Example response:
/usr/local/bin/bitcoind
$ which bitcoin-cli
Example response:
/usr/local/bin/bitcoin-cli
- Download a sample configuration file
$ wget https://raw.githubusercontent.com/bitcoin/bitcoin/master/share/examples/bitcoin.conf -O ~/.bitcoin/bitcoin.conf
- Generate a user and password
$ ./share/rpcauth/rpcauth.py user
Example response:
String to be appended to bitcoin.conf:
rpcauth=user:bf2a249c8580766a1e4fcd9f777533b0$700645074a2f4a4ffd35cf1ec7ada6d8f148053ca4be729c3f54e63ce4664a2e
Your password:
l-sHsqLHrstIh1ZuOVIDjaLcRuYn-Xoy8prVgjboRnc=
NOTE: Record your password for later use.
- Open ~/.bitcoin/bitcoin.conf, and search for the following (or similar) line:
# You can even add multiple entries of these to the server conf file, and client can use any of them:
# rpcauth=bob:b2dd077cb54591a2f3139e69a897ac$4e71f08d48b4347cf8eff3815c0e25ae2e9a4340474079f55705f40574f4ec99
- Below that line, add the rpcauth information generated by rpcauth.py.
Example:
rpcauth=user:bf2a249c8580766a1e4fcd9f777533b0$700645074a2f4a4ffd35cf1ec7ada6d8f148053ca4be729c3f54e63ce4664a2e
- Start the daemon
$ bitcoind -daemon
Example response:
Bitcoin Core starting
- Show help
$ bitcoind -?
- Test CLI commands
$ bitcoin-cli -getinfo
Example response:
{
"version": 209900,
"blocks": 156419,
"headers": 641060,
"verificationprogress": 0.003607647832804664,
"timeoffset": -1,
"connections": 10,
"proxy": "",
"difficulty": 1090715.680051267,
"chain": "main",
"keypoolsize": 1000,
"paytxfee": 0.00000000,
"balance": 0.00000000,
"relayfee": 0.00001000,
"warnings": "This is a pre-release test build - use at your own risk - do not use for mining or merchant applications"
}
- Stopping the daemon
bitcoin-cli stop
NOTE: If you may see the following error message if running commands too quickly after starting bitcoind:
error code: -28
error message:
Loading block index..
If you see this kind of error, wait another second or two and try again.
- Start the daemon (if stopped).
$ bitcoind -daemon
- Use the following curl command to test communication with the the RPC interface.
$ curl --user user --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getblockchaininfo", "params": [] }' -H 'content-type: text/plain;' http://127.0.0.1:8332
Example response:
Enter host password for user 'user':
- Enter or paste the password generated earlier (e.g. l-sHsqLHrstIh1ZuOVIDjaLcRuYn-Xoy8prVgjboRnc=)
Example response:
{"result":{"chain":"main","blocks":229810,"headers":641062,"bestblockhash":"000000000000019606fe717e1ec8832aadd0b531a9fdb3fc9b66d4396e4c0e6c","difficulty":6695826.282596251,"mediantime":1365171545,"verificationprogress":0.02829406551238997,"initialblockdownload":true,"chainwork":"0000000000000000000000000000000000000000000000340a2573e03179ff18","size_on_disk":7956125601,"pruned":false,"softforks":{"bip34":{"type":"buried","active":true,"height":227931},"bip66":{"type":"buried","active":false,"height":363725},"bip65":{"type":"buried","active":false,"height":388381},"csv":{"type":"buried","active":false,"height":419328},"segwit":{"type":"buried","active":false,"height":481824}},"warnings":"This is a pre-release test build - use at your own risk - do not use for mining or merchant applications"},"error":null,"id":"curltest"}
- Install the following:
$ sudo apt install libcurlpp-dev libcurl4-openssl-dev
- Create a file called main.cpp:
#include <curlpp/cURLpp.hpp>
#include <curlpp/Easy.hpp>
#include <curlpp/Options.hpp>
#include <string>
#include <sstream>
#include <iostream>
using namespace curlpp::options;
int main(int argc, char *argv[])
{
if(argc < 3) {
std::cerr << argv[0] << ": Wrong number of arguments" << std::endl
<< "Usage: " << argv[0] << " username password"
<< std::endl;
return EXIT_FAILURE;
}
std::string username(argv[1]);
std::string password(argv[2]);
std::string userpass = username + ":" + password;
try
{
curlpp::Cleanup btcCleanup;
curlpp::Easy btcRequest;
std::list<std::string> header;
header.push_back("Content-Type: application/json");
btcRequest.setOpt(new curlpp::options::HttpHeader(header));
// Set the daemon's URL.
curlpp::options::Url btcUrl(std::string("http://127.0.0.1:8332"));
// Set the username and password.
curlpp::options::UserPwd usrPsswd(userpass);
// Create the data payload
std::string json = R"({"jsonrpc": "1.0", "id":"curltest", "method": "getblockchaininfo", "params": [] })";
// Add options to the request
btcRequest.setOpt(btcUrl);
btcRequest.setOpt(usrPsswd);
btcRequest.setOpt(curlpp::options::PostFields(json));
btcRequest.setOpt(curlpp::options::PostFieldSize(json.size()));
// Send the request
btcRequest.perform();
}
catch(curlpp::RuntimeError & e)
{
std::cout << e.what() << std::endl;
}
catch(curlpp::LogicError & e)
{
// Result is sent to standard output.
std::cout << e.what() << std::endl;
}
return 0;
}
- Build the demo application:
$ g++ -Wall main.cpp -o btctest -Llib/x86_64-linux-gnu -lcurlpp -Wl,-Bsymbolic-functions -Wl,-z,relro -lcurl -Iinclude -I/usr/include/x86_64-linux-gnu
- Run the demo with your username and password as command line arguements. Example:
./btctest user l-sHsqLHrstIh1ZuOVIDjaLcRuYn-Xoy8prVgjboRnc=
Example response:
{"result":{"chain":"main","blocks":303520,"headers":641075,"bestblockhash":"000000000000000024450e52f5d08622114b503713243aab15f3f7f989e76267","difficulty":10455720138.48484,"mediantime":1401561878,"verificationprogress":0.07238580672791109,"initialblockdownload":true,"chainwork":"000000000000000000000000000000000000000000007829790f458ed3674540","size_on_disk":22091527638,"pruned":false,"softforks":{"bip34":{"type":"buried","active":true,"height":227931},"bip66":{"type":"buried","active":false,"height":363725},"bip65":{"type":"buried","active":false,"height":388381},"csv":{"type":"buried","active":false,"height":419328},"segwit":{"type":"buried","active":false,"height":481824}},"warnings":"This is a pre-release test build - use at your own risk - do not use for mining or merchant applications"},"error":null,"id":"curltest"}
You have successfully installed and run the Bitcoin bitcoind daemon, and created a command line application to interact with it to fetch information.
Next steps:
Use bitcoin-cli -rpcwait help
to find other RPC calls to add to the application.