Counterparty Protocol Reference Implementation
PLpgSQL Python
Latest commit faaea5f Dec 3, 2016 @robby-dermody robby-dermody committed on GitHub Merge pull request #945 from CounterpartyXCP/sqlite-maxint-crash
fix for mainnet int overflow crash

Build Status Travis Build Status Circle Coverage Status Latest Version License Slack Status Docker Pulls


counterparty-lib is the reference implementation of the Counterparty Protocol.

Note: for the command-line interface to counterparty-lib, see counterparty-cli.


For a simple Docker-based install of the Counterparty software stack, see this guide.

Manual installation

Download the newest patched Bitcoin Core and create a bitcoin.conf file with the following options:


Then, download and install counterparty-lib:

$ git clone
$ cd counterparty-lib
$ sudo pip3 install -r requirements.txt
$ sudo python3 install

Followed by counterparty-cli:

$ git clone
$ cd counterparty-cli
$ sudo pip3 install -r requirements.txt
$ sudo python3 install

Then, launch the daemon via:

$ counterparty-server bootstrap
$ counterparty-server --backend-password=rpc start

Basic Usage

Via command-line

(Requires counterparty-cli to be installed.)

  • The first time you run the server, you may bootstrap the local database with: $ counterparty-server bootstrap

  • Start the server with: $ counterparty-server start

  • Check the status of the server with: $ counterparty-client getinfo

  • For additional command-line arguments and options: $ counterparty-server --help $ counterparty-client --help

Via Python

Bare usage from Python is also possible, without installing counterparty-cli:

$ python3
>>> from counterpartylib import server
>>> db = server.initialise(<options>)
>>> server.start_all(db)

Configuration and Operation

The paths to the configuration files, log files and database files are printed to the screen when starting the server in ‘verbose’ mode: $ counterparty-server --verbose start

By default, the configuration files are named server.conf and client.conf and located in the following directories:

  • Linux: ~/.config/counterparty/
  • Windows: %APPDATA%\Counterparty\

Client and Server log files are named counterparty.client.[testnet.]log and counterparty.server.[testnet.]log, and located in the following directories:

  • Linux: ~/.cache/counterparty/log/
  • Windows: %APPDATA%\Local\Counterparty\counterparty\Logs

Counterparty API activity is logged in server.[testnet.]api.log and client.[testnet.]api.log.

Counterparty database files are by default named counterparty.[testnet.]db and located in the following directories:

  • Linux: ~/.local/share/counterparty
  • Windows: %APPDATA%\Roaming\Counterparty\counterparty

Configuration File Format

Manual configuration is not necessary for most use cases.

A counterparty-server configuration file looks like this:

backend-name = addrindex
backend-user = <user>
backend-password = <password>
rpc-host =
rpc-user = <rpcuser>
rpc-password = <rpcpassword>

A counterparty-client configuration file looks like this:

wallet-name = bitcoincore
wallet-connect = localhost
wallet-user = <user>
wallet-password = <password>
counterparty-rpc-connect = localhost
counterparty-rpc-user = <rpcuser>
counterparty-rpc-password = <password>

Developer notes


  • Major version changes require a full (automatic) rebuild of the database.
  • Minor version changes require a(n automatic) database reparse.
  • All protocol changes are retroactive on testnet.

Continuous integration

  • TravisCI is setup to run all tests with 1 command and generate a coverage report and let python-coveralls parse and upload it. It does runs with --skiptestbook=all so it will not do the reparsing of the bootstrap files.
  • CircleCI is setup to split the tests as much as possible to make it easier to read the error reports. It also runs the integration_test.test_book tests, which reparse the bootstrap files.

Further Reading