Bitcoin RPC Interface

What Is the Bitcoin RPC Interface?

The Bitcoin RPC interface is a JSON-RPC server built into Bitcoin Core that allows external programs to interact with a running Bitcoin node. RPC stands for Remote Procedure Call: a protocol where a client sends a structured request to a server, which executes the corresponding function and returns the result.

When you start bitcoind (the Bitcoin Core daemon), it listens for JSON-RPC requests over HTTP on a local port. Any application that can make HTTP POST requests and parse JSON can communicate with the node: querying block data, creating transactions, checking mempool state, estimating fees, and more. This makes the RPC interface the primary way that wallets, block explorers, Lightning nodes, and other Bitcoin infrastructure interact with the base layer.

Bitcoin Core has supported JSON-RPC since 2010, when Gavin Andresen added HTTP authentication to the interface. The protocol has evolved across major releases, with Bitcoin Core v28.0 adding full JSON-RPC 2.0 compliance alongside the legacy 1.1 protocol.

How It Works

The RPC server is an HTTP server powered by libevent that listens on a configurable port. Clients send JSON-formatted requests specifying a method name and parameters. The server executes the method against the node's state and returns a JSON response.

Request and Response Format

A JSON-RPC request includes four fields: the protocol version, a method name, parameters, and a client-chosen ID for matching responses to requests.

# Request
curl --user myuser --data-binary '{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getblockcount",
  "params": []
}' -H 'content-type: application/json' http://127.0.0.1:8332/

# Response
{
  "jsonrpc": "2.0",
  "result": 847521,
  "id": "1"
}

Parameters can be passed by position (as an array) or by name (as an object). The bitcoin-cli tool supports named parameters with the -named flag, making complex commands more readable.

Default Ports

Each Bitcoin network uses a different default RPC port to prevent accidental cross-network commands:

Command Categories

Bitcoin Core exposes over 100 RPC commands organized into functional groups. Here are the most commonly used:

Blockchain commands query the state of the chain. getblockchaininfo returns sync status, chain name, and verification progress. getblock retrieves a specific block by hash, and getbestblockhash returns the tip of the longest chain.

# Get current chain height
bitcoin-cli getblockcount

# Get full block data by hash
bitcoin-cli getblock "00000000000000000002a7c4..." 2

# Check mempool state
bitcoin-cli getmempoolinfo

Wallet commands handle key management, address generation, and transaction creation. These are only available when Bitcoin Core is compiled with wallet support (the default).

# Generate a new receiving address
bitcoin-cli getnewaddress "label" "bech32m"

# Send bitcoin to an address
bitcoin-cli sendtoaddress "bc1q..." 0.001

# List unspent outputs for coin selection
bitcoin-cli listunspent

Network commands provide visibility into peer connections and network health. getpeerinfo returns detailed information about each connected peer, including latency, services, and protocol version.

Mining commands support block construction. getblocktemplate returns a candidate block template for miners, containing the selected transactions and required header fields.

Raw transaction commands provide granular control over transaction construction and signing. These work with both raw hex transactions and PSBTs (Partially Signed Bitcoin Transactions).

# Create a PSBT
bitcoin-cli createpsbt '[{"txid":"...","vout":0}]' '[{"bc1q...":0.01}]'

# Estimate fee rate (sat/vB)
bitcoin-cli estimatesmartfee 6

Authentication and Security

Because the RPC interface provides full control over a node and its wallets, proper authentication is critical. Bitcoin Core supports three authentication methods.

Cookie-Based Authentication

The default and recommended method. When no explicit credentials are configured, Bitcoin Core generates a random username and password on each startup and writes them to a .cookie file in the data directory. The file is readable only by the system user that started the daemon. Clients like bitcoin-cli read this file automatically.

# The .cookie file is auto-generated
# bitcoin-cli reads it transparently
bitcoin-cli getblockchaininfo

rpcauth (Multi-User)

For environments where multiple applications need different access levels, the rpcauth method uses HMAC-SHA256 hashed credentials. A Python script bundled with Bitcoin Core generates the hashed entry for bitcoin.conf:

# Generate hashed credentials
python3 share/rpcauth/rpcauth.py myuser

# Add to bitcoin.conf
rpcauth=myuser:<salt>$<hash>

Access Control

Beyond authentication, Bitcoin Core provides several access control mechanisms:

• rpcbind controls which network interfaces the server listens on (defaults to 127.0.0.1, localhost only)
• rpcallowip whitelists specific IP addresses or subnets
• rpcwhitelist restricts individual users to specific commands, enforcing the principle of least privilege

Important: The RPC interface is designed for trusted environments only. Never expose it to the public internet. For remote access, use SSH tunnels or a VPN. Bitcoin Core does not natively support HTTPS for RPC: use a reverse proxy with TLS if encryption over the network is required.

bitcoin-cli: The Command-Line Client

bitcoin-cli is the standard command-line tool for interacting with a running bitcoind instance. It reads connection settings from bitcoin.conf, handles authentication (including automatic cookie file reading), and formats requests as JSON-RPC calls.

# Basic usage
bitcoin-cli help                    # List all commands
bitcoin-cli help getblock           # Help for a specific command

# Named parameters for readability
bitcoin-cli -named sendtoaddress \
  address="bc1q..." \
  amount=0.01 \
  fee_rate=5

# Target a specific wallet in multi-wallet mode
bitcoin-cli -rpcwallet=savings getbalance

# Connect to a remote node
bitcoin-cli -rpcconnect=192.168.1.100 -rpcport=8332 getblockcount

For developers building applications, bitcoin-cli is useful for prototyping and debugging before integrating RPC calls into application code. Any language with HTTP and JSON support can call the RPC interface directly, and client libraries exist for Python, JavaScript, Go, Rust, and most other popular languages.

Use Cases

Lightning Network Infrastructure

Lightning implementations depend heavily on the Bitcoin RPC interface. LND requires JSON-RPC access to a fully synchronized bitcoind for on-chain operations: opening channels, force-closing, sweeping outputs, and monitoring confirmation depth. It also uses Bitcoin Core's ZMQ notification interface (a complementary push-based system) to receive real-time block and transaction events. Core Lightning similarly requires a synced bitcoind with RPC access.

Block Explorers and Analytics

Self-hosted block explorers connect directly to a node via RPC to query blocks, transactions, and address histories. Enabling the txindex flag allows fast transaction lookups by hash, which is essential for explorer functionality. Chain analysis tools also use RPC to scan the UTXO set and trace transaction flows.

Wallet Applications and Custody

Enterprise custody solutions, hardware wallet coordinators, and desktop wallets use RPC to manage keys, construct transactions, and broadcast them to the network. Multi-wallet support allows a single Bitcoin Core instance to serve multiple wallets through the /wallet/<name>/ endpoint. For more on building Bitcoin payment infrastructure, see the guide to building Bitcoin payment apps.

Development and Testing

The RPC interface is central to Bitcoin development workflows. Developers use regtest mode to spin up private networks where blocks can be generated on demand via generatetoaddress. This enables rapid testing of transaction logic, Script execution, and fee estimation without spending real bitcoin. The signet and testnet networks provide more realistic testing environments while still using the same RPC commands.

Complementary Interfaces

Bitcoin Core provides two additional interfaces alongside the JSON-RPC server:

• REST interface: a read-only, unauthenticated HTTP API for public blockchain data (enabled with the -rest flag). It runs on the same port as RPC and supports JSON, binary, and hex output formats. Useful for lightweight queries that do not require authentication.
• ZMQ (ZeroMQ) notifications: a push-based system for real-time events. Instead of polling via RPC, applications subscribe to block and transaction notifications. This is essential for latency-sensitive use cases like Lightning Network nodes and fee estimation services.

Risks and Considerations

Security Exposure

The RPC interface provides full control over the node and any loaded wallets. Compromised credentials can lead to stolen funds, network disruption, or filesystem access. Always use cookie-based authentication or rpcauth, restrict access with rpcallowip, and never store plaintext credentials in configuration files.

Resource Consumption

Some RPC commands are computationally expensive. gettxoutsetinfo scans the entire UTXO set and can take several minutes. Batch requests with no size limit can cause out-of-memory conditions. Production deployments should implement rate limiting and use rpcwhitelist to prevent abuse.

Deprecation and Breaking Changes

The RPC interface evolves with each Bitcoin Core release. Commands are deprecated with a one-version grace period (re-enabled via -deprecatedrpc), and some are removed entirely. Bitcoin Core v30.0, for example, removed 11 legacy wallet RPCs including dumpprivkey and importprivkey as part of the migration to descriptor-based wallets. Applications must track release notes and adapt accordingly.

Consistency Guarantees

Blockchain queries reflect chain state at execution time, and mempool queries return self-consistent snapshots. However, wallet state may lag behind the mempool. Applications that require strong consistency across multiple queries should account for the fact that state can change between calls.

For a broader comparison of Bitcoin node implementations and their RPC capabilities, see the Bitcoin node implementation comparison.

This glossary entry is for informational purposes only and does not constitute financial or investment advice. Always do your own research before using any protocol or technology.