Bitcoin RPC Guide: Working Safely with Bitcoin Core 31.0

A Bitcoin RPC guide is only useful if it teaches you how to use Bitcoin Core without mixing up transport, wallet scope, and mempool state. In Bitcoin Core 31.0, that distinction matters more than ever because the node now exposes cluster-mempool RPCs and private-broadcast controls that change how you inspect unconfirmed transactions and broadcast behavior.

What Bitcoin RPC actually is

Bitcoin RPC is the programmatic control surface for Bitcoin Core. The headless daemon bitcoind has JSON-RPC enabled by default, while bitcoin-qt keeps it off unless you start it with -server. That means this Bitcoin RPC guide is really about how to talk to a node that is already enforcing consensus rules, wallet rules, and network policy on your behalf. Bitcoin Core’s own docs also note that the server recognizes JSON-RPC 2.0 requests, while older clients without a "jsonrpc": "2.0" marker follow the legacy 1.1 path; v27.0 and earlier only supported the older mode.

For wallet work, the endpoint matters. Bitcoin Core exposes two JSON-RPC endpoints: / for general calls and /wallet/<walletname>/ for wallet-scoped calls. The wallet endpoint is the one bitcoin-cli uses when you pass -rpcwallet=, and the documentation says it is the best practice when multiple wallets are in use. A solid Bitcoin RPC guide should treat that as a structural rule, not a convenience detail.

There is also a subtle but useful parsing detail. Bitcoin Core accepts both positional and named parameters, and the docs say bitcoin rpc can substitute for bitcoin-cli -named as a newer alternative. That is the kind of operational nuance that keeps a Bitcoin RPC guide useful after the reader already knows the basics.

Why this Bitcoin RPC guide starts with security, not commands

The most important thing to understand is that RPC access is powerful enough to spend wallet funds, influence consensus verification, and read private data. Bitcoin Core’s own security notes say that anyone with valid RPC credentials should be treated as having significant control over the node and the filesystem resources the process can access. In other words, a Bitcoin RPC guide that skips security is incomplete.

The preferred authentication method is the cookie file. When no rpcpassword is specified, Bitcoin Core generates unique login credentials at startup and stores them in a .cookie file in the configuration directory; the docs describe that as the preferred RPC authentication method. If you truly need static credentials, Bitcoin Core recommends the share/rpcauth script before falling back to manually chosen rpcuser and rpcpassword values.

Remote RPC access should stay private. Bitcoin Core says rpcallowip and rpcbind are only meant for secure private networks or otherwise secured connections such as VPN, SSH, or stunnel, and it explicitly says not to expose RPC to the public Internet. The same document warns that RPC credentials are sent in clear text because the interface is authenticated but not encrypted. If you run Bitcoin Core in Docker, the docs also recommend binding the port to localhost instead of exposing it broadly.

Whitelisting helps, but it is not a hard security boundary. Bitcoin Core provides -rpcwhitelist and -rpcwhitelistdefault, yet the documentation warns that they should not be treated as robust isolation between users. For security-sensitive operations, the safer design is system-level isolation: separate user accounts, containers, or virtualization with restricted permissions.

A practical Bitcoin RPC guide workflow

The cleanest way to learn Bitcoin RPC is to separate testing from production. Bitcoin Developer docs say it is safer and cheaper to use testnet or regtest for development, and regtest wallets plus chainstate live in the regtest subdirectory so you can reset the environment without touching mainnet wallets. That makes regtest the right place to practice before you automate anything against real funds.

A minimal workflow looks like this:

bitcoin-cli -regtest getblockchaininfobitcoin-cli -regtest getnewaddress "" bech32bitcoin-cli -regtest getbalancebitcoin-cli -regtest testmempoolaccept '["signedhex"]'

The Bitcoin Developer examples show bitcoin-cli -regtest as the normal way to invoke RPCs in regression test mode, and they use getbalance as a simple confirmation that the wallet can spend funds in that local environment.

Once the node is running, the first check should be a status query rather than a send command. getblockchaininfo tells you whether the node is synced and which chain it is on; getrpcinfo helps with server-side RPC state; and logging can help when a method behaves differently than you expected. These are control-plane calls, and they are the right first stop in any Bitcoin RPC guide because they tell you whether the node itself is healthy before you touch wallet state.

After that, create a receiving address with getnewaddress. Bitcoin Core 31.0 documents the method as returning a new Bitcoin address for receiving payments, and it lets you choose address types such as legacy, p2sh-segwit, bech32, and bech32m. The label argument is not cosmetic; it links incoming payments to wallet metadata, which matters when your automation later tries to reconcile deposits.

For payment processing, listunspent and confirmation score are more useful than a simple “balance” mental model. The Bitcoin Developer payment-processing guide says Bitcoin Core provides RPCs that expose confirmation scores for wallet transactions or arbitrary transactions, and it warns that unconfirmed payments and high-value payments require explicit double-spend risk analysis. That is why a production Bitcoin RPC guide should push readers toward transaction-level inspection instead of balance-only checks.

Before broadcasting anything, test the raw transaction first. The testmempoolaccept RPC returns whether a raw transaction would be accepted by the mempool and whether it violates consensus or policy rules. In practice, that means you can catch a bad fee rate, a malformed input, or a policy rejection before you ask the network to relay the transaction.

For wallet-heavy workflows, PSBTs are often the safer bridge. Bitcoin Core’s RPC catalog includes walletcreatefundedpsbt, walletprocesspsbt, finalizepsbt, and send, which is the path many modern wallet applications use when they want the node to fund, sign, and broadcast with less raw transaction handling. That is especially relevant once you move from a toy regtest example to a multi-step production workflow.

What changed in Bitcoin Core 31.0, and why it matters for RPC users

Bitcoin Core 31.0 was published on April 19, 2026, and it is the latest major release in the official release notes. The release also says that versions 28.x and older are end of life, which is a practical reminder that a Bitcoin RPC guide should never assume old node behavior is still a safe baseline.

The biggest operator-facing change is the cluster mempool rework. Bitcoin Core 31.0 says the mempool was reimplemented with a new “cluster mempool” design, replacing ancestor/descendant size and count limits with cluster-based limits. The release notes add that clusters are limited to 64 transactions and up to 101 kB in virtual size, and that transaction ordering now reflects the feerate of the full chunk that is expected to be mined together. That is a major shift for anyone using a Bitcoin RPC guide to reason about fees, package relay, or RBF behavior.

That new design is now visible through RPC. Bitcoin Core 31.0 added getmempoolcluster, which returns the set of transactions in the same cluster as a given transaction along with ordering and chunk grouping, and getmempoolfeeratediagram, which returns the feerate diagram of the whole mempool. It also adds chunk size and chunk fee data to getmempoolentry. In practical terms, this is the first release where the RPC layer starts exposing the mempool in a way that matches the new policy model.

Private broadcast is another meaningful change. The 31.0 notes say sendrawtransaction can now be broadcast only via Tor or I2P when -privatebroadcast is enabled, and they add getprivatebroadcastinfo and abortprivatebroadcast to introspect and control that queue. The release notes also explain why this matters: the originator’s IP is not known to recipients, and unrelated transactions are less linkable because a separate connection is used for each broadcast. That is the kind of operational detail a serious Bitcoin RPC guide should surface.

The fee API changed too. -paytxfee and the settxfee RPC were deleted after being deprecated in 30.0, and Bitcoin Core now tells users to rely on fee estimation or per-transaction fee_rate arguments in RPCs such as fundrawtransaction, sendtoaddress, send, sendall, and sendmany. This is a useful line in the sand: static fee control is no longer the right mental model for modern Bitcoin Core RPC usage.

There is also a smaller but practical performance change. On systems with at least 4 GiB of RAM, 31.0 increases the default -dbcache from 450 MiB to 1024 MiB. The release notes say that improves performance but also uses more memory, which matters in containerized deployments where detected RAM can exceed what is actually available.

How to read RPC output without over-interpreting it

A Bitcoin RPC guide should warn readers about state freshness. Bitcoin Core’s JSON-RPC interface notes say chain-state queries are guaranteed to be at least as up to date as the chain state immediately before the call, but mempool results may not reflect the current mempool at the exact moment you read them. That means getrawmempool, getmempoolentry, and related calls are best treated as consistent snapshots, not as real-time truth.

The same docs explain that wallet RPC responses are internally consistent with the chain state at call time, but they may lag the live mempool. That distinction matters when a payment app is trying to decide whether a transaction is “gone,” replaced, or just not yet reflected in the wallet’s view. This is where the Bitcoin RPC guide should push readers toward confirmation logic instead of UI assumptions.

getdescriptoractivity is a good example of an RPC that rewards patience. Bitcoin Core documents it as a way to get spend and receive activity for a set of descriptors across a set of blocks, and the docs note that it may take several minutes; if it times out, you can use bitcoin-cli -rpcclienttimeout=0. That is a very specific operational fact, and it is exactly the kind of detail that separates a useful Bitcoin RPC guide from a generic one.

Common mistakes that slow down Bitcoin RPC work

The first mistake is using the wrong endpoint when multiple wallets are loaded. If you query the root endpoint while your application expects a specific wallet, you may get a response that is technically valid but operationally wrong for your use case. The /wallet/<walletname>/ endpoint exists for a reason, and Bitcoin Core says it should be used for all requests when multiple wallets are in use.

The second mistake is exposing RPC as if it were a public API service. Bitcoin Core’s own documentation is blunt here: do not expose RPC to the public Internet. Authentication is not encryption, so credentials can be observed on the network path, and the interface itself is not hardened for arbitrary Internet traffic.

The third mistake is ignoring version drift. Bitcoin Core 31.0 removed settxfee, changed mempool semantics, and marks 28.x and older as EOL. A Bitcoin RPC guide that does not say “check the release notes for your major version” is silently teaching readers to depend on behavior that may already be gone.

Bitcoin RPC guide FAQ

What is the difference between bitcoin-cli and JSON-RPC?

bitcoin-cli is the command-line wrapper people usually use to talk to Bitcoin Core. JSON-RPC is the wire protocol underneath it. Bitcoin Core also accepts named and positional parameters directly over JSON-RPC, and the docs say bitcoin rpc can act as a newer alternative to bitcoin-cli -named.

Is it safe to expose Bitcoin RPC on the internet?

No. Bitcoin Core explicitly says not to expose RPC to the public Internet. The interface is authenticated but not encrypted, so credentials can be read on the network path, and the RPC service is not hardened for arbitrary Internet traffic. Use localhost, VPN, SSH, or another secure tunnel instead.

Why does Bitcoin Core prefer the .cookie file for RPC auth?

Because it avoids static passwords. When no rpcpassword is set, Bitcoin Core generates fresh credentials on startup and writes them to .cookie, which the docs describe as the preferred authentication method. For automation that needs fixed credentials, Bitcoin Core recommends rpcauth before manual passwords.

What changed in Bitcoin Core 31.0 for RPC users?

The big changes are cluster mempool visibility, private broadcast controls, and the removal of settxfee. Bitcoin Core 31.0 added getmempoolcluster and getmempoolfeeratediagram, introduced getprivatebroadcastinfo and abortprivatebroadcast, and deleted static fee-setting RPCs in favor of fee estimation and per-transaction fee rates.

Should developers use testnet or regtest for a Bitcoin RPC guide?

Yes. Bitcoin Developer documentation says development is safer and cheaper on testnet or regtest, and regtest lets you generate blocks on demand in a local environment. That makes regtest the right place to validate RPC workflows before touching real funds.