How to Use the Bitcoin Core JSON-RPC API: A Complete Developer Guide

Bitcoin Core exposes a JSON-RPC server via bitcoind (or bitcoin-qt -server) that listens on port 8332 by default, accepting authenticated HTTP POST requests to query blockchain data, manage wallets, and submit transactions.

The Bitcoin Core JSON-RPC API provides programmatic access to the Bitcoin blockchain and wallet functionality through a standardized JSON-RPC 2.0 interface. According to the bitcoin/bitcoin source code, every available method is registered as an RPCHelpMan object in the central dispatch table located in src/rpc/server.cpp. Whether you are building analytics tools, automated payment processors, or wallet services, mastering this interface is essential for integrating with the Bitcoin network.

Bitcoin Core JSON-RPC Architecture

The server architecture centers on an HTTP listener that parses incoming requests and dispatches them to specific handler functions.

Endpoints and Request Handling

Two HTTP endpoints are defined in the repository's doc/JSON-RPC-interface.md:

• / – Always active; handles non-wallet operations and single-wallet configurations.
• /wallet/<walletname>/ – Active when the wallet module is compiled; required when multiple wallets are loaded.

When a client sends a POST request, the HTTP listener in src/rpc/server.cpp parses the JSON payload and constructs a JSONRPCRequest object. The request is dispatched to the matching RPCHelpMan handler, which executes core logic—often utilizing validation utilities from src/rpc/util.cpp—and returns a UniValue JSON response wrapped in a standard JSON-RPC envelope with HTTP status 200 (or 204 for notifications).

Method Registration

Each RPC method self-registers using the RPCHelpMan class, which encapsulates the handler function, argument specifications, result descriptions, and usage examples. While the central registry lives in src/rpc/server.cpp, individual implementations are distributed across specialized files such as src/rpc/blockchain.cpp for chain queries and src/rpc/rawtransaction.cpp for transaction operations.

Authentication and Configuration

Before issuing requests, you must configure authentication. Bitcoin Core supports two mechanisms: a temporary .cookie file generated on startup (default for local connections) or static credentials via rpcuser and rpcpassword configuration options. The server binds to TCP port 8332 by default, configurable via the -rpcport argument.

Practical Usage Examples

Querying Blockchain Data with curl

To retrieve the current block height, send a JSON-RPC request to the root endpoint. The getblockcount method is implemented in src/rpc/blockchain.cpp.

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

The server returns the block count as an integer within the JSON-RPC result envelope.

Managing Wallets with bitcoin-cli

The bitcoin-cli utility simplifies local interactions by automatically reading the cookie file for authentication and converting command-line arguments to JSON. Its conversion logic is defined in src/rpc/client.cpp within the vRPCConvertParams table.

bitcoin-cli -named getbalance wallet_name=myswallet

This command queries the balance for the specified wallet, with bitcoin-cli translating the named arguments into the positional params array expected by the RPC specification.

Sending Transactions with Python

For programmatic transaction broadcasting, use the sendrawtransaction method implemented in src/rpc/rawtransaction.cpp. This example demonstrates reading the .cookie file for authentication:

import requests, json, os

# Load cookie for authentication

cookie_path = os.path.expanduser('~/.bitcoin/.cookie')
with open(cookie_path) as f:
    auth = f.read().strip()

url = 'http://127.0.0.1:8332/'
payload = {
    "jsonrpc": "2.0",
    "id": "py1",
    "method": "sendrawtransaction",
    "params": ["020000000001..."]   # raw tx hex

}
headers = {'content-type': 'application/json'}

response = requests.post(url, data=json.dumps(payload),
                         headers=headers, auth=auth)
print(response.json())

Accessing Specific Wallet Endpoints

When multiple wallets are loaded, target a specific wallet using the /wallet/<name>/ endpoint. The following requests unspent outputs from the desc-wallet wallet:

curl --user alice --data-binary \
  '{"jsonrpc":"2.0","id":"2","method":"listunspent","params":[]}' \
  -H 'content-type:application/json' \
  http://127.0.0.1:8332/wallet/desc-wallet

Key Source Files for Reference

Understanding the Bitcoin Core JSON-RPC implementation requires familiarity with these core files:

• src/rpc/server.cpp – Contains the HTTP listener, request parsing logic, and central RPCHelpMan registry.
• src/rpc/client.cpp – Implements bitcoin-cli argument conversion tables (vRPCConvertParams).
• src/rpc/util.cpp – Provides helper utilities for argument validation, error handling, and JSON construction.
• src/rpc/blockchain.cpp – Implements chain query methods like getblockcount and getblock.
• src/rpc/rawtransaction.cpp – Handles raw transaction RPCs including sendrawtransaction and signrawtransactionwithkey.
• src/wallet/rpc/ – Directory containing wallet-specific RPC implementations.
• doc/JSON-RPC-interface.md – Human-readable documentation of endpoints, authentication, and versioning.

Summary

• Bitcoin Core JSON-RPC API runs on port 8332 by default and requires authentication via .cookie file or rpcuser/rpcpassword credentials.
• Two endpoints exist: / for general calls and /wallet/<name>/ for multi-wallet environments.
• The RPCHelpMan architecture in src/rpc/server.cpp registers and dispatches all RPC methods.
• bitcoin-cli automates local authentication and parameter conversion using logic from src/rpc/client.cpp.
• Direct HTTP clients like curl or Python requests can interact with the API by posting JSON-RPC 2.0 payloads to the appropriate endpoint.

Frequently Asked Questions

What is the default port for the Bitcoin Core JSON-RPC API?

The server listens on TCP port 8332 by default, configurable via the -rpcport command-line argument or the rpcport setting in bitcoin.conf.

How does authentication work for Bitcoin Core RPC?

Bitcoin Core generates a temporary .cookie file containing authentication credentials on startup, which bitcoin-cli reads automatically. Alternatively, you can define static rpcuser and rpcpassword values in bitcoin.conf for persistent credentials required by remote HTTP clients.

Can I use the JSON-RPC API with Bitcoin Core GUI?

Yes, but you must start bitcoin-qt with the -server command-line flag to enable the JSON-RPC server; the interface is active by default only in bitcoind (daemon mode).

Why do I need to use the /wallet/ endpoint?

The /wallet/<walletname>/ endpoint is required when multiple wallets are loaded simultaneously. If you only load one wallet, you may use the root / endpoint, but multi-wallet configurations require explicitly targeting the specific wallet URL to avoid ambiguity in wallet-specific calls like getbalance or listunspent.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}