Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


License js-standard-style

This is a REST API server, written in node.js JavaScript, using the Express.js framework. The purpose of this code is to create a REST API server that provides a common interface for developers to build blockchain-based business applications. This software works with the Bitcoin Cash (BCH) and eCash (XEC) blockchains.

While developers are encouraged to run and manage their own infrastructure, cloud-based infrastructure is available via Free and paid tiers are available. You can use this REST API right away with the bch-js JavaScript library.

This repository is intended to be paired with bch-js, an npm JavaScript library for building Bitcoin Cash apps. Code examples for common use-cases are available, and the minimal-slp-wallet is a front end JavaScript library that incorporates bch-js and provides basic wallet functionality.

bch-api dependency diagram


All the software above is part of the Cash Stack.

Have questions? Need help? Join our community support:

Configure bch-js

The live servers can be used by bch-js by settings the restURL config property to one of these servers:


There are two installation paths, depending if you want a development or production environment. You'll also need to set up the underlying infrastructure described on

This hardware target for this software is a PC running Ubuntu 18.04 LTS Linux OS or higher.


This is a standard node.js project. The installation is as follows:

  • Clone this repository:

git clone && cd bch-api

  • Install dependencies:

npm install

  • Customize the shell script to point to the required infrastructure. Start the bch-api REST API by running this script:



For a production environment, a Docker container is provided in the docker directory. One for mainnet and one for testnet. Again, these containers target the Ubuntu 18.04 LTS Linux OS.

  • Install Docker and Docker Compose by following the commands on this Dev Ops page.

  • Customize the bash script for your installation.

  • Build the Docker container with:

docker-compose build --no-cache

  • Run the Docker container with:

docker-compose up -d

Rate Limits

Rate limiting of the REST API can be controlled in three different ways:

  • JWT tokens for individual users
  • Basic Authentication tokens for organization-wide usage.
  • Whitelisting for specific domain names

JWT Tokens

The rate limits for are controlled by a JWT token. You can increase your rate limits by purchasing a JWT token. If you're using bch-js, check the readme for instructions on increasing rate limits. For interacting with bch-api directly (without bch-js), you can then include the JWT token in the HTTP header like this:

  • Authorization: Token <JWT token>

cURL example

Here is an example using curl for using the JWT token when making a call to the REST API:

export BCHJSTOKEN=eyJhbGciOiJ....

curl "" -X GET -H "Content-Type: application/json" -H "Authorization: Token ${BCHJSTOKEN}"

Basic Authentication

For private installations, Basic Authentication can be used to give everyone in an organization access to higher rate limits, while restricting use by the public. More than one Basic Authentication password can be generated by using the colon : to separate entries in the PRO_PASS environment variable. See the bash script for an example.


Website domain names can be added to the WHITELIST_DOMAINS environment variable. Multiple domains can be separated with a comma ,. Any web app making a request from that domain will be granted top-level rate limits. See the bash script for an example.


This open source software is developed and maintained by the Permissionless Software Foundation. If this library provides value to you, please consider making a donation to support the PSF developers:


Censorship Resistance

Copies of this repository will occasionally be uploaded and hosted on the Filecoin blockchain, IPFS, and the Radicle p2p network.




The REST API powering







No packages published