Skip to content
sigvault Sigvault

Quickstart

The fastest path to a running walletrs is the bundled Docker Compose stack: it brings up bitcoind (regtest), electrs, and walletrs in one command. From-source instructions follow below.

Section titled “Docker Compose (recommended)”

The repository ships a docker-compose.yml that wires regtest bitcoind, electrs, and walletrs together:

Terminal window
git clone https://github.com/n1rna/walletrs
cd walletrs
docker compose up --build

walletrs exposes two surfaces:

  • gRPC on 127.0.0.1:50051
  • HTTP / JSON on 127.0.0.1:8080

Both surfaces share the same handlers and the same bearer token. The first start logs a line like:

STORE THIS — generated auth token: 7e3f...

Copy that token into your client. To pin a known token across restarts, drop a .env next to the compose file:

Terminal window
WALLETRS_AUTH_TOKEN=$(openssl rand -hex 32)
WALLETRS_KEK=$(openssl rand -base64 32)   # required if you create system-managed keys

Switch networks by editing the bitcoind / electrs flags and the BITCOIN_NETWORK env in the walletrs service.

From source

Section titled “From source”
Terminal window
cargo build --release --bin walletrs


WALLETRS_HOST=127.0.0.1 \
WALLETRS_PORT=50051 \
WALLETRS_HTTP_PORT=8080 \
BITCOIN_NETWORK=regtest \
ELECTRS_URL=tcp://127.0.0.1:60401 \
WALLETRS_STORAGE_KIND=local \
WALLETRS_STORAGE_PATH=./data \
RUST_LOG=info,walletrs=debug \
./target/release/walletrs

You can also pull a tagged release image directly:

Terminal window
docker run --rm -p 50051:50051 -p 8080:8080 \
  -v walletrs-data:/data \
  -e BITCOIN_NETWORK=signet \
  -e ELECTRS_URL=tcp://your-electrs:50001 \
  -e WALLETRS_AUTH_TOKEN=$(openssl rand -hex 32) \
  -e WALLETRS_KEK=$(openssl rand -base64 32) \
  ghcr.io/n1rna/walletrs:latest

Released images are tagged on every v* git tag (:0.1.0, :0.1, :latest) and published multi-arch (linux/amd64 + linux/arm64).

Smoke test

Section titled “Smoke test”

The Ping RPC always bypasses auth so you can use it as a liveness probe.

HTTP

Section titled “HTTP”
Terminal window
curl -sS -X POST http://127.0.0.1:8080/wallet/ping \
  -H 'content-type: application/json' \
  -d '{}'

A successful run prints {} — the empty PingResponse message.

gRPC

Section titled “gRPC”

With grpcurl and a copy of walletrpc.proto:

Terminal window
grpcurl -plaintext -proto walletrpc.proto \
  127.0.0.1:50051 walletrpc.WalletService/Ping

First authenticated call

Section titled “First authenticated call”

Once you have a token, you can hit any RPC. The HTTP form is friendly to curl:

Terminal window
TOKEN=...


curl -sS -X POST http://127.0.0.1:8080/wallet/list_managed_keys \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"user_id":"alice","key_type":""}'

For a worked end-to-end flow — system key, wallet creation, fund, sign, broadcast — see the end-to-end guide.

Next steps

Section titled “Next steps”