Bcoin is an alternative implementation of the bitcoin protocol, written in node.js. It is a full node which can be used for full blockchain validation and is aware of all known consensus rules.
- Linux, OSX, or Windows (*) (**)
- node.js >=v10.0.0
- npm >=v6.4.1
- python2 (for node-gyp)
- gcc/g++ (for leveldb and secp256k1)
- git (optional, see below)
(*): Note that bcoin works best with unix-like OSes, and has not yet been thoroughly tested on windows.
(**): The BSDs and Solaris have also not been tested yet, but should work in theory.
Build & install
Bcoin is meant to be installed via git for security purposes, as there
are security issues when installing via npm. All tagged commits for
release should be signed by @chjj's PGP key
B4B1F62DBAC084E333F3A04A8962AB9DE6666BBD). Signed copies of node.js
are available from nodejs.org, or from your respective OS's
Installing via Git
$ curl https://keybase.io/chjj/pgp_keys.asc | gpg --import $ git clone git://github.com/bcoin-org/bcoin.git $ cd bcoin
For a specific release:
$ git tag $ git tag -v <version> # verify signature $ git checkout <version>
$ npm install $ npm install -g # link globally
Note: Dependencies are checked for integrity using
npm will not make these checks with
npm install -g and it
will link your installation globally so that
bcoin is in your
path (e.g. $ bcoin).
Installing on Debian/Ubuntu
Install the necessary dependencies in addition to Node.js:
apt-get install build-essential python
Installing via Docker
Installing on Windows
Install OpenSSL v1.0.2L 64-Bit:
As Administrator, open
cmd.exe and run:
C:\Users\bcoin\bcoin>npm install --global --production windows-build-tools
Python 2.7.x both required by
for building native modules.
Then continue Installing via Git
Note that you need a shell that supports bash scripts, like Git Bash to launch bcoin.
If the build fails compilation for
validation will be slow (a block verification which should take 1 second
on consumer grade hardware may take up to 15 seconds). Bcoin will throw a
warning on boot if it detects a build failure. If you run into this issue,
please post an issue on the repo.
Starting up your first bcoin node
If bcoin is installed globally,
$ bcoin should be in your PATH. If not,
the bcoin bootstrap script resides in
Will run a bcoin node as the foreground process, displaying all debug logs.
To run as a daemon:
$ bcoin --daemon
This will start up a full node, complete with: a blockchain, mempool, miner, p2p server, wallet server, and an HTTP REST+RPC server.
All logs will be written to
~/.bcoin/debug.log by default.
By default, the http server will only listen on
127.0.0.1:8332. No auth
will be required if an API key was not passed in. If you listen on any other
host, auth will be required and an API key will be auto-generated if one was
not passed in.
To listen publicly on the HTTP server,
--http-host=0.0.0.0 (ipv4) or
--http-host=:: (ipv4 and ipv6) can be passed. Additionally this:
--http-port=1337 can set the port.
To advertise your node on the P2P network
--public-port=[your-public-port] may be passed.
Using an API Key
If listening publicly on the HTTP server, an API key is required. One will
be randomly generated if no key was chosen, but not explicitly reported to
the user. An API key can be chosen with the
$ bcoin --http-host=0.0.0.0 --api-key hunter2 --daemon
API keys are used with HTTP Basic Auth:
$ curl http://x:hunter2@localhost:8332/
If bcoin is installed globally, both
bwallet-cli should be
on your path.
$ bcoin-cli info --api-key hunter2 $ bcoin-cli rpc getblockchaininfo --api-key hunter2 $ bwallet-cli balance
Bcoin has native support for SOCKS proxies, and will accept a
in the format of
--onion option tells bcoin that the SOCKS proxy is a Tor socks
proxy, and will enable Tor resolution for DNS lookups, as well as try to
.onion addresses found on the P2P network.
$ bcoin --proxy joe:email@example.com:9050 --onion
Running bcoin as a tor hidden service
Your hidden service must first be configured with
tor. Once you have the
.onion address, it can be passed into
--public-host in the form
It's often desirable to run behind several trusted bitcoin nodes. To select
permanent nodes to connect to, the
--nodes option is available:
$ bcoin --nodes foo.example.com:8333,220.127.116.11:8333,18.104.22.168:8333
If chosen, bcoin will always try to connect to these nodes as outbound peers. They are top priority and whitelisted (not susceptible to permanent bans, only disconnections).
To only connect to these nodes, use
$ bcoin --only foo.example.com,22.214.171.124,126.96.36.199
To avoid accepting connections on the P2P network altogether,
--listen=false can be passed to bcoin.
Bcoin also supports a "selfish" mode. In this mode, bcoin still has full blockchain and mempool validation, but network services are disabled: it will not relay transactions or serve blocks to anyone.
$ bcoin --selfish --listen=false
Note: Selfish mode is not recommended. We encourage you to help the network by relaying transactions and blocks. At the same time, selfish mode does have its uses if you do not have the bandwidth to spare, or if you're absolutely worried about potential DoS attacks.