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.
- High-level documentation is available on CashStack.info.
While developers are encouraged to run and manage their own infrastructure, cloud-based infrastructure is available via FullStack.cash. 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.
All the software above is part of the Cash Stack.
- CashStack high-level documentation.
- bch-api REST API reference
- bch-js JavaScript API reference
- bch-js example code
- Additional documentation on FullStack.cash
- Additional examples on FullStack.cash
Have questions? Need help? Join our community support:
The live servers can be used by bch-js by settings the restURL config property to one of these servers:
- BCH Mainnet REST API server: https://bchn.fullstack.cash/v5/
- eCash Mainnet REST API server: https://abc.fullstack.cash/v5/
- Check server status: https://metrics.fullstack.cash
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 CashStack.info.
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 https://github.com/Permissionless-Software-Foundation/bch-api && cd bch-api
- Install dependencies:
npm install
- Customize the start-dev-example.sh shell script to point to the required infrastructure. Start the bch-api REST API by running this script:
./start-dev-example.sh
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 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
The rate limits for api.fullstack.cash 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>
Here is an example using curl for using the JWT token when making a call to the REST API:
export BCHJSTOKEN=eyJhbGciOiJ....
curl "https://bchn.fullstack.cash/v4/electrumx/balance/bitcoincash:qr69kyzha07dcecrsvjwsj4s6slnlq4r8c30lxnur3" -X GET -H "Content-Type: application/json" -H "Authorization: Token ${BCHJSTOKEN}"
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:
bitcoincash:qqsrke9lh257tqen99dkyy2emh4uty0vky9y0z0lsr
Copies of this repository will occasionally be uploaded and hosted on the Filecoin blockchain, IPFS, and the Radicle p2p network.