Skip to main content

Counterparty Protocol Reference Implementation

Project description

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:


Note: you can and should replace the RPC credentials. Remember to use the changed RPC credentials throughout this document.

Then, download and install counterparty-lib:

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

Followed by counterparty-cli:

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

Note on sudo: both counterparty-lib and counterparty-server can be installed by non-sudoers. Please refer to external documentation for instructions on using pip without root access and other information related to custom install locations.

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. “back-end” and “wallet” are used to access Bitcoin server RPC.

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>

The force argument can be used either in the server configuration file or passed at runtime to make the server keep running in the case it loses connectivity with the Internet and falls behind the back-end database. This may be useful for non-production Counterparty servers that need to maintain RPC service availability even when the backend or counterparty server has no Internet connectivity.

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for counterparty-lib, version 9.55.4
Filename, size File type Python version Upload date Hashes
Filename, size counterparty-lib-9.55.4.tar.gz (379.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page