Running a Wallet Service

The purpose of this tutorial is to show how to setup the Wallet Service. The Wallet Service is the backend for wallets such as BitPay's Copay Multisignature Wallet. The wallet service is very much like the backend for traditional SPV (Simplified Payment Verification) wallets except that the wallet service is much more feature-full. It's recommended to be familiar with running a Bitcore node running before starting this tutorial, please see the Run a Full Node guide for details.

Installing MongoDB

MongoDB is the database for the Bitcore Wallet Service and is the main dependency outside of the Node.js modules. Follow the installation instructions detailed at the MongoDB website, and/or follow details below.

Mac OS X

The easiest way to install MongoDB is to use brew:

brew install update
brew install mongodb
mkdir -p /data/db
sudo chown -R `whoami` /data/db #this assumes that the next step will be run by the current user

Please refer to these complete instructions at the MongoDB website.


MongoDB is included in stardard repositories and can be installed via the package manager:

sudo apt-get install mongodb

This should automatically start the mongod process.

Kerberos packages will also need be available for the Node.js MongoDB driver depends:

apt-get install libkrb5-dev

Add the Wallet Service to Our Node

Note: If you do not already have a Bitcore node setup, please see the Run a Full Node guide.

cd <your node>
bitcore install bitcore-wallet-service
bitcore install insight-api

Now we should be ready to launch Bitcore and test the Wallet Service:


Test the Wallet Service using Copay

The wallet service should be running as a service within Bitcore. You may point wallets on the same network to:

Don't forget to include the "http://"

Copay Screenshot


Once the wallet service is running on your computer, configure your Copay wallet as such:

Test the Wallet Service using the Bitcore Wallet Client

Install the wallet client:

npm install -g bitcore-wallet

Create a new wallet on your server:

wallet-create -h http://your-bitcore-node-ip:3232/bws/api --testnet 'myWallet' 1-1
   [info] Generating new keys
   * Testnet Wallet Created.
   * Saving file /Users/myUsername/.wallet.dat

Add a new address:

wallet -h http://your-bitcore-node-ip:3232/bws/api address
   * New Address mjfmEtkaVbZPGPLBYvznPDer2dDdcruirB

Then send funds to this address from a faucet or other wallet. After you have funds, you can see them by checking your wallet status.

wallet -h http://your-bitcore-node-ip:3232/bws/api status
   * Wallet myWallet [testnet]: 1-of-1 complete
   * Copayers: myUsername
   * Balance 1,000 bit (Locked: 0 bit)

Pro-tip: If you would rather not enter the host address of your wallet server every time you run a command, try aliasing it in your bash profile by adding a line like this to your .bashrc file:

alias mywallet='wallet -h http://your-bitcore-node-ip:3232/bws/api'

You can then send your bits by using your new alias:

mywallet send mxo2iZ9e1c4piKMZGyeujk2MwgBU31W7cw 100bit
   * Tx created: ID 36f4 [pending] RequiredSignatures: 1
mywallet sign 36f4
   Transaction signed by you.
mywallet broadcast 36f4
   Transaction Broadcasted: TXID: fa7b45b63562c265c3a79904f1ec9c547bad5dee1508ce63628047a9097bfd0e
mywallet balance
   * Wallet balance 900 bit (Locked 0 bit)

Adding SSL/TLS Support

Create a self-signed certificate

These directions assume that you have openssl installed. If so, please run:


You should see an "OpenSSL>" prompt, then press Ctrl+D to exit. If you don't have OpenSSL, then install it here

Next, you can run the following commands to generate a self-signed certificate:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem

For ease of use, just type in a password that you can remember to encrypt the key (you have the option to remove it later), then fill out the form or just hit "enter" for every question. If you would like to remove the password from the key.pem that you just created, then follow the next step – otherwise skip it. If you leave the password encryption on your key, then you will need to type it in each time the Wallet Service starts up:

openssl rsa -in key.pem -out key.nopass.pem

Now, key.pem has the password you typed in upon certificate creation and key.nopass.pem does not have any password. It would be a good idea to store key.pem and cert.pem somewhere safe on your computer.

Edit Your Config.

vi bitcore-node.json

Added https options. Example:

  "network": "livenet",
  "port": 3001,
  "https": true,
  "httpsOptions": {
    "key": "some-place-safe/key.nopass.pem",
    "cert": "some-place-safe/cert.pem"
  "servicesConfig": {
    "bitcore-wallet-service": {
      "bwsPort": 3232
    "bitcoind": {
      "datadir": "/home/user/.bitcore/data",
      "exec": "/home/user/bitcoin/src/bitcoind"
  "services": [

Notice that you can also specify which port your Wallet Service will run on (default is 3232).


You should now be able to run your own Wallet Service for your users. Now you can have ultimate control over your wallets without trusting random SPV nodes on the Internet.