Bitcoin Core JSON-RPC
Authentication
Cookie auth (recommended for local)
- File
~/.bitcoin/.cookie is auto-generated; format __cookie__:<random>.
bitcoin-cli uses cookie automatically.- HTTP:
Authorization: Basic base64(cookie_contents).
rpcauth (recommended for remote)
Generated via share/rpcauth/rpcauth.py user:
rpcauth=user:<salt>$<hmac_sha256>
Add to bitcoin.conf. Works without storing plaintext password.
rpcuser/rpcpassword (legacy, avoid)
Plaintext in conf; risk of leaking via process listings.
Wallet vs node RPCs
- Node RPCs: per-node, no wallet context (
getblockchaininfo,
getrawtransaction, scantxoutset).
- Wallet RPCs: bound to a specific wallet (
getbalance,
walletprocesspsbt, listunspent).
Multi-wallet: use rpcwallet= URL parameter or bitcoin-cli -rpcwallet=<name>:
bitcoin-cli -rpcwallet=hot getbalance
curl -u user:pass --data '{"jsonrpc":"2.0","id":1,"method":"getbalance"}' \
http://127.0.0.1:8332/wallet/hot
Common verbs (selected)
Chain & block
| RPC |
Use |
getblockchaininfo |
Sync state, network, deployments |
getbestblockhash |
Tip hash |
getblock <hash> [verbosity 0-3] |
Block data, increasing detail |
getblockstats <hash> [stats] |
Block-level stats (fees, sigops) |
gettxoutsetinfo |
UTXO set statistics |
verifychain |
Background reverification |
Transactions
| RPC |
Use |
getrawtransaction <txid> [verbose=2] |
Tx by hash (verbose=2 includes prevout values, BIP331) |
decoderawtransaction <hex> |
Parse a hex tx |
decodescript <hex> |
Parse a script |
sendrawtransaction <hex> |
Broadcast, returns txid |
testmempoolaccept '[<hex>,...]' |
Dry-run admit |
submitpackage '[<parent>,<child>]' |
Atomic package submit (BIP331) |
Wallet
| RPC |
Use |
createwallet <name> [...] |
Create wallet (default: descriptors=true since 23.0) |
loadwallet <name> / unloadwallet |
Load/unload from disk |
listunspent [minconf] [maxconf] [addrs] |
UTXOs, with desc info |
getbalances |
Mine/trusted/untrusted, immature, frozen |
walletprocesspsbt <psbt> |
Sign + finalize where possible |
walletcreatefundedpsbt |
Build PSBT, fund inputs, add change |
combinepsbt, finalizepsbt, decodepsbt, analyzepsbt |
PSBT roles |
importdescriptors '[<obj>,...]' |
Add descriptors to wallet |
listdescriptors [private] |
Inspect wallet descriptors |
bumpfee <txid>, psbtbumpfee |
RBF helpers |
Mempool
| RPC |
Use |
getmempoolinfo |
Counts, size, fee floor |
getrawmempool [verbose] |
Tx list (verbose: full info incl. ancestor counts) |
getmempoolentry <txid> |
Single tx info |
prioritisetransaction |
Mine-priority bump |
Scanning (no wallet needed)
| RPC |
Use |
scantxoutset start '[<descriptors>]' |
Scan UTXO set for descriptor matches |
scanblocks |
Scan blocks for descriptor matches (needs blockfilterindex) |
Network
| RPC |
Use |
getpeerinfo |
All peer connections + stats |
getnetworkinfo |
Local node net info |
getnodeaddresses |
Known addr database |
addnode <ip> <command> |
Manual peer mgmt |
| `disconnectnode <addr |
nodeid>` |
Curl examples
# Single call
curl -u "$(cat ~/.bitcoin/.cookie)" \
--data '{"jsonrpc":"2.0","id":"x","method":"getblockchaininfo","params":[]}' \
-H 'Content-Type: application/json' \
http://127.0.0.1:8332/
# Wallet call
curl -u "$(cat ~/.bitcoin/.cookie)" \
--data '{"jsonrpc":"2.0","id":"x","method":"getbalance","params":[]}' \
http://127.0.0.1:8332/wallet/hot
# Batch
curl -u "$(cat ~/.bitcoin/.cookie)" \
--data '[
{"jsonrpc":"2.0","id":1,"method":"getblockcount"},
{"jsonrpc":"2.0","id":2,"method":"getbestblockhash"}
]' http://127.0.0.1:8332/
Error codes
-1 Misc / internal
-3 Type mismatch
-5 Object not found (e.g., tx not in mempool/chain)
-8 Invalid parameter
-22 Invalid address / encoding
-25 Validation rejected (e.g., min relay fee not met)
-26 Tx rejected (txn-mempool-conflict, missing-inputs, etc.)
-27 Tx already in chain
RPC whitelisting
bitcoin.conf:
rpcwhitelist=ro:getblockcount,getblockhash,getrawtransaction
rpcauth=ro:...
Restricts which RPCs a given user can call.
Common bugs
- Calling wallet RPCs against a node with no wallet loaded → "Wallet
file not specified" error. Specify
-rpcwallet= or load default.
- Forgetting
verbose=2 for getrawtransaction to get spent prevout
amounts (essential for fee computation post-pruning).
- Treating
getrawtransaction for a pruned tx without txindex →
fails with -5 if tx is old.
- Race conditions: tx in mempool when you check, gone (mined or
evicted) when you act. Always handle "not found" gracefully.
See also
1---2name: bitcoin-core-rpc3description: Bitcoin Core JSON-RPC interface: authentication (cookie, rpcauth), wallet vs node RPCs, common verbs (getblockchaininfo, getrawtransaction, scantxoutset, importdescriptors, walletprocesspsbt, submitpackage, testmempoolaccept), error handling. USE WHEN: scripting bitcoind, integrating a service, debugging RPC errors.4---56# Bitcoin Core JSON-RPC78## Authentication910### Cookie auth (recommended for local)11- File `~/.bitcoin/.cookie` is auto-generated; format `__cookie__:<random>`.12- `bitcoin-cli` uses cookie automatically.13- HTTP: `Authorization: Basic base64(cookie_contents)`.1415### `rpcauth` (recommended for remote)16Generated via `share/rpcauth/rpcauth.py user`:17```18rpcauth=user:<salt>$<hmac_sha256>19```20Add to `bitcoin.conf`. Works without storing plaintext password.2122### `rpcuser`/`rpcpassword` (legacy, avoid)23Plaintext in conf; risk of leaking via process listings.2425## Wallet vs node RPCs2627- **Node RPCs**: per-node, no wallet context (`getblockchaininfo`,28 `getrawtransaction`, `scantxoutset`).29- **Wallet RPCs**: bound to a specific wallet (`getbalance`,30 `walletprocesspsbt`, `listunspent`).3132Multi-wallet: use `rpcwallet=` URL parameter or `bitcoin-cli33-rpcwallet=<name>`:34```bash35bitcoin-cli -rpcwallet=hot getbalance36curl -u user:pass --data '{"jsonrpc":"2.0","id":1,"method":"getbalance"}' \37 http://127.0.0.1:8332/wallet/hot38```3940## Common verbs (selected)4142### Chain & block43| RPC | Use |44|-----|-----|45| `getblockchaininfo` | Sync state, network, deployments |46| `getbestblockhash` | Tip hash |47| `getblock <hash> [verbosity 0-3]` | Block data, increasing detail |48| `getblockstats <hash> [stats]` | Block-level stats (fees, sigops) |49| `gettxoutsetinfo` | UTXO set statistics |50| `verifychain` | Background reverification |5152### Transactions53| RPC | Use |54|-----|-----|55| `getrawtransaction <txid> [verbose=2]` | Tx by hash (verbose=2 includes prevout values, BIP331) |56| `decoderawtransaction <hex>` | Parse a hex tx |57| `decodescript <hex>` | Parse a script |58| `sendrawtransaction <hex>` | Broadcast, returns txid |59| `testmempoolaccept '[<hex>,...]'` | Dry-run admit |60| `submitpackage '[<parent>,<child>]'` | Atomic package submit (BIP331) |6162### Wallet63| RPC | Use |64|-----|-----|65| `createwallet <name> [...]` | Create wallet (default: descriptors=true since 23.0) |66| `loadwallet <name>` / `unloadwallet` | Load/unload from disk |67| `listunspent [minconf] [maxconf] [addrs]` | UTXOs, with desc info |68| `getbalances` | Mine/trusted/untrusted, immature, frozen |69| `walletprocesspsbt <psbt>` | Sign + finalize where possible |70| `walletcreatefundedpsbt` | Build PSBT, fund inputs, add change |71| `combinepsbt`, `finalizepsbt`, `decodepsbt`, `analyzepsbt` | PSBT roles |72| `importdescriptors '[<obj>,...]'` | Add descriptors to wallet |73| `listdescriptors [private]` | Inspect wallet descriptors |74| `bumpfee <txid>`, `psbtbumpfee` | RBF helpers |7576### Mempool77| RPC | Use |78|-----|-----|79| `getmempoolinfo` | Counts, size, fee floor |80| `getrawmempool [verbose]` | Tx list (verbose: full info incl. ancestor counts) |81| `getmempoolentry <txid>` | Single tx info |82| `prioritisetransaction` | Mine-priority bump |8384### Scanning (no wallet needed)85| RPC | Use |86|-----|-----|87| `scantxoutset start '[<descriptors>]'` | Scan UTXO set for descriptor matches |88| `scanblocks` | Scan blocks for descriptor matches (needs blockfilterindex) |8990### Network91| RPC | Use |92|-----|-----|93| `getpeerinfo` | All peer connections + stats |94| `getnetworkinfo` | Local node net info |95| `getnodeaddresses` | Known addr database |96| `addnode <ip> <command>` | Manual peer mgmt |97| `disconnectnode <addr|nodeid>` | Drop a peer |9899## Curl examples100101```bash102# Single call103curl -u "$(cat ~/.bitcoin/.cookie)" \104 --data '{"jsonrpc":"2.0","id":"x","method":"getblockchaininfo","params":[]}' \105 -H 'Content-Type: application/json' \106 http://127.0.0.1:8332/107108# Wallet call109curl -u "$(cat ~/.bitcoin/.cookie)" \110 --data '{"jsonrpc":"2.0","id":"x","method":"getbalance","params":[]}' \111 http://127.0.0.1:8332/wallet/hot112113# Batch114curl -u "$(cat ~/.bitcoin/.cookie)" \115 --data '[116 {"jsonrpc":"2.0","id":1,"method":"getblockcount"},117 {"jsonrpc":"2.0","id":2,"method":"getbestblockhash"}118 ]' http://127.0.0.1:8332/119```120121## Error codes122123```124-1 Misc / internal125-3 Type mismatch126-5 Object not found (e.g., tx not in mempool/chain)127-8 Invalid parameter128-22 Invalid address / encoding129-25 Validation rejected (e.g., min relay fee not met)130-26 Tx rejected (txn-mempool-conflict, missing-inputs, etc.)131-27 Tx already in chain132```133134## RPC whitelisting135136`bitcoin.conf`:137```138rpcwhitelist=ro:getblockcount,getblockhash,getrawtransaction139rpcauth=ro:...140```141142Restricts which RPCs a given user can call.143144## Common bugs145146- Calling wallet RPCs against a node with no wallet loaded → "Wallet147 file not specified" error. Specify `-rpcwallet=` or load default.148- Forgetting `verbose=2` for `getrawtransaction` to get spent prevout149 amounts (essential for fee computation post-pruning).150- Treating `getrawtransaction` for a pruned tx without `txindex` →151 fails with -5 if tx is old.152- Race conditions: tx in mempool when you check, gone (mined or153 evicted) when you act. Always handle "not found" gracefully.154155## See also156157- [operations/SKILL.md](../operations/SKILL.md)158- [descriptors-wallet/SKILL.md](../descriptors-wallet/SKILL.md)159- [indexes/SKILL.md](../indexes/SKILL.md)160- [rest-api/SKILL.md](../rest-api/SKILL.md)
claude-dev-suite