# btcd: a Go full node that validates Bitcoin but never holds your keys

> btcd is an alternative Bitcoin full node written in Go, built to follow Bitcoin Core's consensus rules exactly while deliberately leaving wallet functionality to separate projects. It suits engineers embedding a node or an RPC client into Go services, not people who want a desktop wallet.

**btcsuite/btcd** — An alternative full node bitcoin implementation written in Go (golang)

- Repository: https://github.com/btcsuite/btcd
- Website: https://github.com/btcsuite/btcd/blob/master/README.md
- Stars: 6,712 · Forks: 2,527
- Language: Go
- License: ISC
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/btcsuite-btcd

## What btcd solves, and the wallet it refuses to ship

Bitcoin Core is the reference node, but it is a C++ codebase that also carries a wallet. If your product is a Go service that needs to know whether a transaction is valid, what the current mempool looks like, or whether a block was accepted, embedding the reference node means linking against a large C++ project and inheriting a wallet you do not want to run. btcd exists for that gap. It is a full node that downloads, validates and serves the block chain, and the README states it uses the exact rules, including consensus bugs, that Bitcoin Core uses for block acceptance.

The audience is narrow and worth naming. This is for Go developers who want the node as a library or as a process behind their own RPC client, and for operators who prefer a Go binary over a C++ one. It is not for someone who wants to send and receive payments from the same program. The README is explicit that btcd does not include wallet functionality, calls that an intentional design decision, and points to btcwallet and Paymetheus (Windows-only) for it. That split is the single most consequential thing to understand before you install anything.

## Consensus fidelity is the mechanism, not a feature list

The core mechanism is validation. btcd downloads the block chain, validates it, and serves it to peers, and the README says the project includes a full block validation testing framework containing all of the official block acceptance tests plus additional ones, run on every pull request. It also states that btcd passes all of the JSON test data in the Bitcoin Core code. That is the claim that matters: the project's defence against a consensus split is a test corpus borrowed from the reference implementation, not a rewrite of the rules from the specification.

Beyond block acceptance, the node maintains a transaction pool, relays newly mined blocks, and relays individual transactions that have not yet made it into a block. It applies the rules the chain requires and adds stricter checks that filter transactions by miner requirements, which the README describes as standard transactions. The repository layout reflects the separation: blockchain/, mempool/, mining/, netsync/, peer/, connmgr/, and addrmgr/ are separate packages, with rpcserver.go and rpcwebsocket.go at the top level and a rpcclient/ package for callers. Recent releases also add a v2transport/ package, matching the transport-level work in the go.mod dependency list.

The design trade-off is visible in how btcd is packaged. Because validation, mempool policy and peer management are distinct packages, you can embed parts of the node in a Go program rather than shelling out to a binary. The cost is that you now own the wiring: chain state, database, and RPC surface are your responsibility once you go past running the daemon as-is.

## Installing btcd from source and running it for the first time

The README requires Go 1.25 or newer, and go.mod confirms the module declares go 1.25.0. Prebuilt binaries are offered through the releases page, and the README's source path assumes a GOPATH layout. Start by checking the toolchain and the two environment variables the README warns about:

```bash
go version
go env GOROOT GOPATH
```

The README notes that GOROOT and GOPATH must not be the same path, and recommends a directory under your home such as ~/goprojects to avoid write permission problems. Then fetch and install the daemon plus the utilities in cmd/:

```bash
cd $GOPATH/src/github.com/btcsuite/btcd
go install -v . ./cmd/...
```

According to the README, btcd and its utilities land in $GOPATH/bin, so add that directory to your PATH if Go's installer did not. The README says the basic operations work with zero configuration, so the first run is just the binary:

```bash
./btcd
```

If you prefer containers, the Dockerfile builds from source on an Alpine base and documents the ports in a comment: 8333 for mainnet peer-to-peer and 8334 for mainnet RPC. The image declares a volume at /root/.btcd for chain data and sets btcd as the entrypoint, so the container starts the daemon directly. The Dockerfile also accepts an ARCH build argument with amd64, arm32v7 and arm64v8 as the recognised values. The Makefile offers a parallel path: make build places the binaries in the project directory, and make install puts them in $GOPATH/bin, building btcd along with btcctl, gencerts, findcheckpoint and addblock.

## Where btcd is the wrong tool

The wallet gap is the obvious limitation, and it is not cosmetic. The README states plainly that you cannot make or receive payments directly with btcd, because that functionality lives in btcwallet and Paymetheus. If your requirement is a single process that manages keys and signs transactions, btcd is the wrong component, and pairing it with a separate wallet daemon adds an RPC hop and another process to operate.

There are softer limits too. The README describes the documentation as a work-in-progress located in the docs folder, so you should expect to read source and config files rather than a complete manual. The README also labels the project Beta while saying it has been in production use since October 2013, which is an unusual combination: the software is old and widely run, but the project does not present itself as finished. The sample-btcd.conf file in the repository root is the practical place to look for configuration keys, since the README does not enumerate them.

A third constraint is operational. A validating node is not a lightweight process. It stores chain state, maintains a mempool, and connects to peers, and the Dockerfile's own comments describe the container size rather than a minimal footprint. If you only need to query balances or broadcast a transaction, a hosted API or a light client will cost you far less than running btcd.

## How btcd differs from Bitcoin Core and from lnd

The most direct alternative is Bitcoin Core, the reference implementation. Both validate the chain and relay transactions, and btcd's stated goal is to match Core's acceptance rules rather than improve on them. The difference is language and packaging: Core is C++ and ships a wallet, while btcd is Go and does not. If your stack is Go and you want to call node functions from Go code, btcd's rpcclient package and its library layout remove a language boundary. If you want the implementation that defines the rules, and you want a wallet in the same binary, Core is the natural choice.

A second comparison is lnd, which appears in the related search terms. lnd is a Lightning Network daemon, and it depends on a Bitcoin full node for chain data rather than replacing one. The two are complementary: btcd can serve as the chain backend for software that needs validated blocks, while lnd handles off-chain channels. Choosing btcd does not mean choosing against Lightning; it means choosing which process validates the base chain.

A third point of contrast is the btcsuite split itself. btcwallet and Paymetheus are separate projects under the same organisation, and go.mod shows the node depending on versioned modules such as github.com/btcsuite/btcd/btcutil/v2, btcec/v2, chaincfg/v2, chainhash/v2, txscript/v2 and wire/v2. Those modules are usable on their own, so a Go program can consume btcd's transaction and script handling without running a node at all.

## Maintenance, upgrades and the ISC licence

btcd is not archived, and the most recent push to the repository was on 2026-09-16. Recent releases include v0.26.2 on 2026-07-24 and v0.26.0 on 2026-06-18, with a v0.26.0-beta.rc1 before it on 2026-05-20. The upgrade path documented in the README is a git pull followed by reinstalling the same package set:

```bash
cd $GOPATH/src/github.com/btcsuite/btcd
git pull
go install -v . ./cmd/...
```

That is cheap for the binary, but it is not the whole cost. go.mod carries a retract block covering a long list of older versions, explained in a comment as fixing an accidental push of the tags of a btcd fork. If you pin btcd as a module dependency, those retracted versions will not resolve, and you should expect to move to a current release rather than an old tag. The module also declares go 1.25.0, so a toolchain older than the README's stated Go 1.25 requirement will refuse to build it.

On licensing, btcd is under the ISC licence, which the README links to copyfree.org, and the repository ships a LICENSE file. ISC is a permissive licence, but the repository also vendors or depends on third-party modules under their own terms, including golang.org/x packages and github.com/syndtr/goleveldb. If you redistribute a binary, check the dependency licences rather than assuming the top-level ISC terms cover everything. That is a note about what to verify, not legal advice.

## Conclusion

Adopt btcd if you are writing Go services that need a validating node, a mempool view, or the rpcclient package, and you accept that wallet functions live in btcwallet or Paymetheus instead. Do not adopt it if you need a self-contained wallet, a GUI, or a single binary that does everything. Before committing, verify the Go toolchain version against go.mod (go 1.25.0), confirm the ISC licence terms suit your distribution model, and decide whether you will run the node on mainnet ports 8333 and 8334 or on a private network.

## FAQ

### How does btcd work?

btcd downloads, validates and serves the Bitcoin block chain, maintains a transaction pool, and relays blocks and unconfirmed transactions to peers. The README states it follows the same block acceptance rules as Bitcoin Core, including consensus bugs, and that it deliberately omits wallet functionality.

### Does btcd include a wallet?

No. The README says btcd does not include wallet functionality, calls that an intentional design decision, and states that you cannot make or receive payments directly with btcd. Wallet functions are provided by the separate btcwallet and Paymetheus projects.

### What Go version does btcd need?

The README lists Go 1.25 or newer as a requirement, and go.mod declares go 1.25.0. The README also warns that GOROOT and GOPATH must not be the same path.

### Which ports does btcd use?

The Dockerfile comments identify 8333 as the mainnet peer-to-peer port and 8334 as the mainnet RPC port, and the image exposes both. The README does not list these ports itself.

### What licence is btcd released under?

btcd is licensed under the copyfree ISC licence, and the repository includes a LICENSE file. The README links the licence badge to copyfree.org.

## Sources

- [btcsuite/btcd on GitHub](https://github.com/btcsuite/btcd)
- [License: ISC](https://github.com/btcsuite/btcd/blob/master/LICENSE)
- [Project website](https://github.com/btcsuite/btcd/blob/master/README.md)
- [README](https://github.com/btcsuite/btcd/blob/master/README.md)
- [Releases](https://github.com/btcsuite/btcd/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/btcsuite-btcd