btcwallet needs btcd and offers two RPC surfaces

The architecture is a client of btcd

btcwallet is a daemon handling Bitcoin wallet functionality for a single user. It acts as both an RPC client to btcd and an RPC server for wallet clients and legacy RPC applications.

That middle position is the whole design. It is not a wallet on its own, because chain queries and notifications come from btcd over websockets.

The README is explicit that btcwallet is not an SPV client and requires connecting to a local or remote btcd instance for asynchronous blockchain queries and notifications over websockets. An alternative SPV mode compatible with btcd and Bitcoin Core is described as planned for a future release.

That planned mode is worth chasing, because it changes the deployment story completely, and the dependency list suggests work has happened in that direction: go.mod requires `lightninglabs/neutrino` along with its cache package. The README does not mention neutrino, so the documentation and the dependency graph are not currently in agreement about what the daemon can do. That gap is exactly what to check before planning an architecture around it.

The practical consequence today is operational: running btcwallet requires access to a local or remote btcd instance.

Key derivation and the public data question

Public and private keys are derived using the hierarchical deterministic format described in BIP32, and btcwallet uses the `m/44'/<coin type>'/<account>'/<branch>/<address index>` HD path for all derived addresses, as described in BIP44.

The branch component in that path is where BIP44 shows through. A single-account application does not need it, and its presence indicates multi-account support in the derivation scheme.

On storage, the position is unambiguous: unencrypted private keys are not supported and are never written to disk.

The more interesting design decision is the optional encryption of public data. Because a BIP32 wallet's public data is sensitive in its own right, btcwallet can encrypt not just the private keys but the public data as well. The stated threat model is a compromised wallet file: without this, someone who obtains the file can enumerate every current and future address the wallet manages, track all transactions involving them, and therefore know the exact balance.

The README is careful about what that does and does not buy you. Access to that information would not allow an attacker to spend or steal coins. It does allow tracking. And in a future release, public data encryption is intended to extend to transactions as well.

So the feature protects metadata, not funds, and the transaction coverage may not be present in your build. That distinction matters if you are choosing this wallet because of the privacy property specifically.

Two RPC surfaces, one of them experimental

Wallet clients can use one of two RPC servers, and the difference between them is not cosmetic.

The first is a legacy JSON-RPC server mostly compatible with Bitcoin Core. The README says it exists to ease migration of wallet applications from Core, while being clear that complete compatibility is not guaranteed: some portions of the API, and especially accounts, have to work differently due to other design decisions, mostly due to BIP44. That server is enabled by default.

The second is an experimental gRPC server using a new API built for btcwallet. It is feature gated behind a config option, `--experimentalrpclisten`. The README tells you to use it if you do not mind applications breaking due to API changes, do not want to deal with issues of the legacy API, or need notifications for wallet changes.

That framing is honest and useful. The default is the compatible one, which will have rough edges; the modern one is better engineered for new work but is not stable.

So the choice is: migrate an existing Core client with minimal change and accept accounts behaving differently, or build on gRPC and accept that your integration may break.

There is also a Makefile target worth knowing about, because it installs more than the daemon. `make install` installs btcwallet along with two utilities, `dropwtxmgr` and `sweepaccount`. And `make build` compiles the whole package tree, not just the binary.

Building and running it

The stated requirement is Go 1.25.11 or newer.

On Windows, MSIs are available, and the README links the release pages for both btcd and btcwallet, which tells you to install the node first and the wallet second.

For building from source, the instructions are GOPATH-shaped even though the build uses modules. You check `go version` and `go env GOROOT GOPATH`, and the README insists that GOROOT and GOPATH must not be the same path, recommending GOPATH somewhere under your home directory to avoid write permission issues, and adding `$GOPATH/bin` to your `PATH`.

The build itself is:

cd $GOPATH/src/github.com/btcsuite/btcwallet
GO111MODULE=on go install -v . ./cmd/...

`GO111MODULE=on` is a flag that stopped being necessary when modules became the default, and `$GOPATH/src/...` is a pre-module layout. Following this literally means placing the repository in a GOPATH tree even though `go.mod` at the root defines the module. `make build` and `make install` at the repository root are the more current path, and the Makefile still sets `GO111MODULE=on` on its build and install recipes.

Getting started is three commands: start btcd with credentials, create the wallet with `--create`, then run btcwallet with the same credentials.

btcd -u rpcuser -P rpcpass

btcwallet -u rpcuser -P rpcpass --create

The README then recommends copying the sample `btcd.conf` and `btcwallet.conf` into their per-application config directories, with separate instructions for MSI installs and source installs on Windows, and for `~/.btcd/` and `~/.btcwallet/` on POSIX systems.

Release verification and the version gap

Release tags are signed by Conformal, and the README documents how to verify them: download the public key from opensource.conformal.com, import it with `gpg --import`, and check a tag with `git tag -v TAG_NAME`.

That is a meaningful supply-chain property for a wallet, and it is the kind of thing that has become standard expectation for security-sensitive software.

The version history is the confusing part. The recent release tags are BTCWALLET_0_7_0_ALPHA from 2015-11-23, 0.6.0-alpha from 2015 and 0.5.1-alpha from March 2015. So the tags stopped in 2015, while the last push was on 2026-10-15 and the code is demonstrably current: go.mod depends on btcd v0.26.0, the btcd v2 module series, gRPC 1.73, protobuf 1.36, and a Go requirement of 1.25.11.

So this is an actively developed wallet whose release tags stopped a decade ago. The listed release tags therefore provide a much older version history than the repository's recent commit activity.

There is a related gap in go.mod, which carries a `replace` directive pointing wtxmgr at the local directory, with a comment explaining it should be removed after publishing a wtxmgr release containing release-after-spend output leases. A repository built from source depends on that local copy rather than a published module version.

The repository layout also shows how much is separated into its own module: `waddrmgr/` for address management, `wtxmgr/` for the transaction manager, `walletdb/` for the database abstraction, `snacl/` for the crypto, plus `chain/`, `rpc/`, `netparams/`, `internal/` and `build/`. There is a `.golangci.yml` and a `.protolint.yml` at the root, and a `.gemini/` directory.

Editorial conclusion

Adopt btcwallet if you run btcd already and want a wallet with hierarchical deterministic keys and a scriptable RPC surface rather than a desktop wallet. Do not adopt it as a standalone wallet for a user who cannot run a node, because it requires a btcd instance for chain queries. Verify first that your Go toolchain matches the stated requirement, that your client speaks either the legacy JSON-RPC or the gRPC API rather than assuming both, and note that the future extension of public data encryption to transactions is not yet documented as available.

Frequently asked questions

Official sources

1. btcsuite/btcwallet on GitHub
2. Issues
3. License: ISC
4. README
5. Releases