How to start wallet server

Overview

The easiest and most common way of managing your funds on the Cardano blockchain is through a wallet. This guide is to show how to start cardano-wallet together with cardano-node.

Full node mode

Here we are going to start cardano-wallet in full node mode, meaning that we need to have also cardano-node running on the same machine. We can get binaries of cardano-wallet and compatible version of cardano-node from cardano wallet release page. Cardano-wallet archives published for each release, besides cardano-wallet itself, include all the relevant tools like cardano-node, cardano-cli, cardano-addresses or bech32.

ℹ️ Alternatively one can use handy docker-compose to start wallet and the node. $ NETWORK=testnet docker-compose up

Pre-requisites

Start cardano-wallet in full node mode

We are going to use testnet configuration in this example.

  • Start node:
$ cardano-node run \
  --config testnet-config.json \
  --topology testnet-topology.json \
  --database-path ./db \
  --socket-path /path/to/node.socket
  • Start wallet:
$ cardano-wallet serve --port 8090 \
  --node-socket /path/to/node.socket \
  --testnet testnet-byron-genesis.json \
  --database ./wallet-db \
  --token-metadata-server https://metadata.cardano-testnet.iohkdev.io/

That’s it! We can basically start managing our wallets from this point onwards. See How to create a wallet and How to manage wallets.

However, in order to be able to make transactions, we still need to wait until cardano-node is synced fully with the Cardano blockchain. In case of mainnet it may take several hours, in case of testnet a bit less.

We can monitor this process using cardano-wallet's GET /network/information endpoint. Once the endpoint returns sync_progress status ready we’ll know we are good to go:

$ curl -X GET http://localhost:8090/v2/network/information | jq .sync_progress
{
  "status": "ready"
}

Light mode

⚠️ This mode is currently under development. Please note that some parts may be available only in master branch.

You can start your cardano-wallet server also in light mode. As opposed to full-node mode, in light-mode your wallet is not connected to a locally running instance of cardano-node. Instead it relays on external source of blockchain data. This significantly improves synchronization speed of the wallet and also removes the need to spend time synchronizing the node itself. The downside is that external source of data is obviously less trusted than the local one provided by your own cardano-node instance.

ℹ️ Cardano-wallet currently supports only one external data provider - Blockfrost. Before using the light mode one needs to generate API key on Blockfrost page and save it into the file on the filesystem.

Pre-requisites

Start cardano-wallet in light mode

Let’s suppose we have our API keys generated and saved in files as follows:

  • blockfrost-testnet.key - API key for testnet
  • blockfrost-mainnet.key - API key for mainnet

Now we can start cardano-wallet server for testnet or mainnet:

Testnet
$ cardano-wallet serve \
	--port 8091 \
	--light \
	--blockfrost-token-file blockfrost-testnet.key \
	--testnet testnet-byron-genesis.json \
	--database ./wallet-testnet-db-light \
Mainnet
$ cardano-wallet serve \
	--port 8092 \
	--light \
	--blockfrost-token-file blockfrost-mainnet.key \
	--mainnet \
	--database ./wallet-db-light \