Bitcoin

Skill based on Bitcoin Core, generated 2026-02-09. Docs: sources/bitcoin/doc/, bitcoincore.org

Bitcoin Core is the reference Bitcoin full-node implementation. It syncs and validates the chain, runs a headless daemon or GUI, and exposes JSON-RPC and REST. It supports descriptor wallets, PSBT (multisig/hardware wallets), and external signers.

Core References

Features

Wallets and Signing

APIs

External Links

• Bitcoin Core docs
• Bitcoin Core GitHub
• BIPs

Generation Info

• Source: sources/bitcoin (https://github.com/bitcoin/bitcoin)
• Git SHA: 6d625af2831b7c36d59f245a65df3f70f2110f69
• Generated: 2026-02-09
• Docs used: doc/README.md, bitcoin-conf.md, JSON-RPC-interface.md, descriptors.md, psbt.md, managing-wallets.md, external-signer.md, build-unix.md, REST-interface.md, zmq.md, multisig-tutorial.md, dependencies.md, files.md

Building Bitcoin Core

Build is CMake-based. Platform-specific notes: see doc/build-unix.md, doc/build-osx.md, doc/build-windows-msvc.md, doc/build-windows.md, and BSD variants in repo.

Unix (typical)

cmake -B build
cmake --build build    # add -j N for parallel jobs
cmake --install build  # optional

• Run cmake -B build -LH for config options.
• Dependencies: see doc/dependencies.md. Example (Ubuntu/Debian): build-essential cmake pkgconf python3, plus e.g. libevent-dev libboost-dev. For GUI add Qt dependencies.
• Memory: ≥1.5 GB RAM recommended; see doc for low-memory and clang alternatives.

Optional Features

• ZMQ: cmake -B build -DWITH_ZMQ=ON (requires libzmq). Then set ZMQ options in config or CLI to enable block/tx notifications.
• Wallet: Default build includes wallet; can be disabled for minimal node.

Binaries end up in build/src/ (e.g. bitcoind, bitcoin-cli) or install prefix.

<!-- Source references:

• https://github.com/bitcoin/bitcoin doc/build-unix.md
• https://github.com/bitcoin/bitcoin doc/dependencies.md
• https://github.com/bitcoin/bitcoin doc/zmq.md

-->

CLI and RPC Usage

bitcoin-cli / bitcoin rpc

• bitcoin-cli — Sends JSON-RPC to a running bitcoind or bitcoin-qt (with -server). Default: mainnet, localhost, default port.
• bitcoin rpc — Same as bitcoin-cli with -named style; preferred for named parameters.

Options (examples): -rpcuser, -rpcpassword, -rpcport, -rpcwallet=<name>, -testnet, -signet, -regtest, -datadir, -conf.

Common Patterns

# One wallet
bitcoin-cli -rpcwallet=mywallet getbalance

# Named params
bitcoin-cli -named createwallet wallet_name=w1 load_on_startup=true

# List RPCs
bitcoin-cli help
bitcoin-cli help getblock

When multiple wallets are loaded, always pass -rpcwallet for wallet methods so the request goes to /wallet/<name>/.

Wrapper: bitcoin

• bitcoin node — same as bitcoind
• bitcoin gui — same as bitcoin-qt
• bitcoin rpc ... — same as bitcoin-cli -named ...
• bitcoin help — list subcommands

<!-- Source references:

• https://github.com/bitcoin/bitcoin doc/README.md
• https://github.com/bitcoin/bitcoin doc/JSON-RPC-interface.md

-->

bitcoin.conf Configuration

The config file is used by bitcoind, bitcoin-qt, and bitcoin-cli. All command-line options (except -?, -help, -version, -conf) can be set in the file; command line overrides config file.

Format

• Plain text: option=value per line. No leading - for options.
• Comments: # to end of line.
• Negated options: no prefix, e.g. noconnect=1.
• Network-specific: sections [main], [test], [testnet4], [signet], [regtest] or prefix e.g. regtest.rpcport=3000. Network options override generic ones.

Precedence

1. bitcoin.conf (base) 2. settings.json (runtime/GUI and some RPCs) can augment or replace 3. Command-line overrides both

Unrecognized options in bitcoin.conf are reported in debug.log.

Location

• Default: <datadir>/bitcoin.conf. Datadir and config path can be set with -datadir and -conf.
• Use includeconf=<file> to include another config file.
• Example datadir: Windows %LOCALAPPDATA%\Bitcoin\, Linux ~/.bitcoin, macOS ~/Library/Application Support/Bitcoin.

Key Options (examples)

• Chain: testnet=1, signet=1, regtest=1
• RPC: rpcuser=, rpcpassword=, rpcport=, rpcbind=, rpcallowip=
• Server: server=1 (enable RPC in GUI)
• Pruning: prune=N (MB)
• Rest: rest=1 for REST API on same port as RPC

Users should not change options they do not understand and should be wary of config provided by others.

<!-- Source references:

• https://github.com/bitcoin/bitcoin doc/bitcoin-conf.md
• https://github.com/bitcoin/bitcoin doc/files.md

-->

Bitcoin Core Overview

Bitcoin Core is the reference Bitcoin full-node implementation. It syncs and validates the full blockchain, runs a headless daemon or GUI, and exposes JSON-RPC and REST for wallets and chain data.

Executables

Common Flows

• Run node: bitcoind or bitcoin node; data in default datadir (e.g. ~/.bitcoin on Unix). Use -testnet, -signet, or -regtest for other networks.
• Config: bitcoin.conf in datadir; options override with command-line. See core-config.
• RPC: Default port 8332 (mainnet), 18332 (testnet), 38332 (signet), 18443 (regtest). Auth via -rpcuser/-rpcpassword or cookie file.
• Wallet: No default wallet since 0.21; create with createwallet RPC or GUI. Use descriptor wallets for descriptors/PSBT.

Key Points

• Full sync requires substantial disk (hundreds of GB+). Pruning available via -prune.
• Build: see core-build. Binaries: bitcoincore.org.
• Do not expose RPC to untrusted networks without auth and understanding of security (spend, consensus, privacy).

<!-- Source references:

• https://github.com/bitcoin/bitcoin doc/README.md
• https://github.com/bitcoin/bitcoin README.md

-->

JSON-RPC Interface

The headless daemon bitcoind has JSON-RPC enabled by default; the GUI has it disabled unless -server is set.

Endpoints

• `/` — Always active. Handles non-wallet RPCs; wallet RPCs only when exactly one wallet is loaded.
• `/wallet/<walletname>/` — For wallet RPCs when multiple wallets are loaded. Use for all wallet requests when more than one wallet. bitcoin-cli -rpcwallet=<name> targets this.

Example:

curl --user alice --data-binary '{"jsonrpc":"2.0","id":"0","method":"getblockcount","params":[]}' -H 'content-type: application/json' localhost:38332/
curl --user alice --data-binary '{"jsonrpc":"2.0","id":"0","method":"getbalance","params":[]}' -H 'content-type: application/json' localhost:38332/wallet/desc-wallet

Parameters

Both by-position and by-name (JSON-RPC spec) are supported. A convenience named parameter args can be an array of initial positional values combined with other named params.

bitcoin-cli createwallet mywallet false false "" false false true
bitcoin-cli -named createwallet wallet_name=mywallet load_on_startup=true
bitcoin-cli -named createwallet args='["mywallet"]' load_on_startup=true

bitcoin rpc can be used instead of bitcoin-cli -named.

Versioning

RPC is implicitly versioned by Bitcoin Core major version. Version tuple is in getnetworkinfo → version. Deprecated features can often be re-enabled for one major version via -deprecatedrpc=...; release notes document deprecations.

JSON-RPC 2.0 vs 1.1

• Request: use "jsonrpc": "2.0" for 2.0; otherwise 1.1.
• 2.0: response has only result or error; HTTP 200 unless server error; notifications (no id) supported (HTTP 204).

Security

RPC can spend funds, affect verification, and read private data. Securing the executable and limiting who can reach RPC (auth, bind address, firewall) is critical. Do not run security-sensitive operations on shared or untrusted hosts. See doc for securing local network access and cookie/auth usage.

<!-- Source references:

• https://github.com/bitcoin/bitcoin doc/JSON-RPC-interface.md

-->

Output Descriptors

Output descriptors are a small language for describing sets of output scripts. Used by wallet import, scanning, and PSBT workflows.

Supporting RPCs

• scantxoutset — Scan UTXO set with descriptors; returns descriptors for matches.
• getdescriptorinfo — Parse and canonicalize descriptor, add checksum.
• deriveaddresses — Derive addresses from descriptor.
• listunspent — Can output descriptor for unspent (descriptor wallets).
• getaddressinfo — Output descriptor for solvable addresses.
• generatetodescriptor — Mine to descriptor (regtest only).
• utxoupdatepsbt — Add info to PSBT from descriptors.
• importdescriptors — Import into descriptor wallet.
• listdescriptors — List imported descriptors.
• scanblocks / getdescriptoractivity — Scan blocks by descriptor and get receive/spend events.

Script Types

• pk(KEY) — P2PK. pkh(KEY) — P2PKH. wpkh(KEY) — P2WPKH.
• sh(SCRIPT), wsh(SCRIPT) — P2SH, P2WSH.
• tr(KEY) or tr(KEY,TREE) — Taproot (P2TR).
• multi(k,KEY,...), sortedmulti(k,KEY,...) — k-of-n multisig (BIP67 for sorted).
• multi_a / sortedmulti_a — Multisig inside Taproot script tree.
• combo(KEY) — P2PK + P2PKH (+ wpkh/shwph if compressed).
• addr(ADDR) — From address. raw(HEX) — Raw hex script.

Keys

• Hex pubkey (66 or 130 chars), or x-only (64) for Taproot.
• BIP32: xpub/xprv with path, e.g. /0/* for all unhardened children. Optional key origin [fingerprint/path] before key.
• Hardened: use ' or h (e.g. 44'/0'/0').

Examples

• Single key: wpkh(xpub.../0/*)#checksum
• 2-of-3 multisig: wsh(sortedmulti(2,xpub1,xpub2,xpub3))
• Taproot with script tree: tr(internal_key,{pk(key1),pk(key2)})

Miniscript is supported inside wsh() and tr() (watch-only and signing in recent versions). Use getdescriptorinfo to validate and get checksum before importdescriptors.

<!-- Source references:

• https://github.com/bitcoin/bitcoin doc/descriptors.md

-->

External Signer (Hardware Wallet)

Bitcoin Core can use an external signer (e.g. hardware wallet) via -signer=<cmd>. The signer process runs alongside the node and handles signing and optional address display.

Setup

Start node with signer, e.g. HWI (experimental, use with caution):

bitcoind -signer=/path/to/hwi.py
# or: bitcoin node -signer=...

List devices:

bitcoin-cli enumeratesigners

Create wallet (imports pubkeys from device):

bitcoin-cli createwallet "hww" true true "" true true true

Usage

• Address: getnewaddress then walletdisplayaddress <address> to show on device.
• Spend: sendtoaddress etc. use PSBT under the hood; device is prompted to sign. Requires device connected.

Signer API

External signer must conform to Bitcoin Core’s Signer API (stdin/stdout JSON). Prerequisites: Output Descriptors and PSBT. Commands include:

• Device/signer enumeration
• Getting descriptors and signing PSBTs
• Displaying addresses (optional)

Details and current spec are in the repo doc; a future BIP may standardize for other wallets. When using third-party signers, prefer manufacturer-recommended software that implements the same contract.

<!-- Source references:

• https://github.com/bitcoin/bitcoin doc/external-signer.md

-->

PSBT in Bitcoin Core

PSBT (BIP 174) is an interchange format for unsigned or partially signed transactions plus metadata. Used for hardware wallets, multisig, and CoinJoin-style flows.

Roles (BIP 174)

• Creator — Builds initial PSBT (inputs/outputs, no or minimal metadata).
• Updater — Adds UTXO and script/key info.
• Signer — Adds partial signatures.
• Finalizer — Converts partial sigs into final scriptSig/scriptWitness.
• Extractor — Outputs valid raw transaction when all inputs finalized.
• Combiner — Merges metadata from multiple PSBTs for the same tx.

RPCs

Typical Flow

1. Creator: walletcreatefundedpsbt or createpsbt + updater. 2. Updater: add UTXOs/scripts (utxoupdatepsbt or wallet/descriptor RPCs). 3. Signers: sign (e.g. walletprocesspsbt or external signer); combine with combinepsbt if multiple. 4. Finalizer: finalizepsbt. 5. Extractor: same call returns raw tx; broadcast with sendrawtransaction.

Multisig example: create descriptor wallet with multisig descriptor, then use walletcreatefundedpsbt → pass PSBT to each signer → combinepsbt → finalizepsbt → sendrawtransaction.

<!-- Source references:

• https://github.com/bitcoin/bitcoin doc/psbt.md
• https://github.com/bitcoin/bitcoin doc/multisig-tutorial.md

-->

REST and ZMQ

REST Interface

Enable with -rest. Served on the same port as JSON-RPC (default 8332 mainnet, 18332 testnet, 38332 signet, 18443 regtest). Unauthenticated; do not expose to untrusted networks.

Endpoints (examples):

• Transaction: GET /rest/tx/<TXID>.<bin|hex|json> — Mempool by default; need txindex=1 for confirmed.
• Block: GET /rest/block/<HASH>.<bin|hex|json> or .../notxdetails/... (JSON without full tx details).
• Block part: GET /rest/blockpart/<HASH>.<bin|hex>?offset=&size=
• Headers: GET /rest/headers/<HASH>.<bin|hex|json>?count=5 — Up to count block headers.
• Chaininfo: GET /rest/chaininfo.json
• UTXO: GET /rest/getutxos/<CHECK>.<bin|hex|json> — UTXO set query (requires rest with specific support).

Same consistency guarantees as RPC (see doc). Limitation: many concurrent connections can exhaust file descriptors; limit concurrency or increase system limits.

ZMQ (ZeroMQ)

Publish/subscribe for blocks and transactions. Build with -DWITH_ZMQ=ON; set options in config or CLI to enable.

• zmqpubhashblock, zmqpubhashtx — Publish block/tx hashes.
• zmqpubrawblock, zmqpubrawtx — Publish raw block/tx data.

Subscribers connect to the given ZMQ endpoint; no auth, read-only. Useful for indexers and notification pipelines. See doc/zmq.md for topic names and message formats.

<!-- Source references:

• https://github.com/bitcoin/bitcoin doc/REST-interface.md
• https://github.com/bitcoin/bitcoin doc/zmq.md

-->

Managing Wallets

Since 0.21 there is no default wallet. Create with createwallet RPC or GUI (File → Create wallet).

Create and Encrypt

bitcoin-cli createwallet "wallet-01"
bitcoin-cli -rpcwallet=wallet-01 encryptwallet "passphrase"
# or create encrypted:
bitcoin-cli -named createwallet wallet_name=wallet-01 passphrase="passphrase"

Passphrase change: walletpassphrasechange "old" "new". If passphrase is lost, funds are unrecoverable.

Unlock

Encrypted wallets must be unlocked for signing/spending:

bitcoin-cli -rpcwallet=wallet-01 walletpassphrase "passphrase" 120

Timeout is seconds the decryption key stays in memory. GUI prompts on send.

Backup

Use backupwallet (or GUI File → Backup Wallet) so the copy is consistent:

bitcoin-cli -rpcwallet=wallet-01 backupwallet /path/to/backup-01.dat

After encrypting or changing passphrase, create a new backup immediately (keypool/HD seed change). Store backups offline and test restore.

Descriptor vs Legacy

Prefer descriptor wallets for new setups: they work with descriptors, PSBT, and importdescriptors. Create with createwallet (descriptor is default in recent versions). Legacy wallets can be migrated; see RPC docs.

Wallet Location

Default directory (e.g. wallets/ inside datadir): Linux ~/.bitcoin/wallets, Windows %LOCALAPPDATA%\Bitcoin\wallets, macOS ~/Library/Application Support/Bitcoin/wallets. Override with -walletdir or -datadir.

<!-- Source references:

• https://github.com/bitcoin/bitcoin doc/managing-wallets.md

-->