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

> Unlock the power of Bitcoin Core with our developer guide to the JSON-RPC API. Query blockchain data, manage wallets, and submit transactions programmatically.

- Repository: [Bitcoin/bitcoin](https://github.com/bitcoin/bitcoin)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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`](https://github.com/bitcoin/bitcoin/blob/main/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`](https://github.com/bitcoin/bitcoin/blob/main/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`](https://github.com/bitcoin/bitcoin/blob/main/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`](https://github.com/bitcoin/bitcoin/blob/main/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`](https://github.com/bitcoin/bitcoin/blob/main/src/rpc/server.cpp), individual implementations are distributed across specialized files such as [`src/rpc/blockchain.cpp`](https://github.com/bitcoin/bitcoin/blob/main/src/rpc/blockchain.cpp) for chain queries and [`src/rpc/rawtransaction.cpp`](https://github.com/bitcoin/bitcoin/blob/main/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`](https://github.com/bitcoin/bitcoin/blob/main/src/rpc/blockchain.cpp).

```bash
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`](https://github.com/bitcoin/bitcoin/blob/main/src/rpc/client.cpp) within the `vRPCConvertParams` table.

```bash
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`](https://github.com/bitcoin/bitcoin/blob/main/src/rpc/rawtransaction.cpp). This example demonstrates reading the `.cookie` file for authentication:

```python
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:

```bash
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`](https://github.com/bitcoin/bitcoin/blob/main/src/rpc/server.cpp)** – Contains the HTTP listener, request parsing logic, and central `RPCHelpMan` registry.
- **[`src/rpc/client.cpp`](https://github.com/bitcoin/bitcoin/blob/main/src/rpc/client.cpp)** – Implements `bitcoin-cli` argument conversion tables (`vRPCConvertParams`).
- **[`src/rpc/util.cpp`](https://github.com/bitcoin/bitcoin/blob/main/src/rpc/util.cpp)** – Provides helper utilities for argument validation, error handling, and JSON construction.
- **[`src/rpc/blockchain.cpp`](https://github.com/bitcoin/bitcoin/blob/main/src/rpc/blockchain.cpp)** – Implements chain query methods like `getblockcount` and `getblock`.
- **[`src/rpc/rawtransaction.cpp`](https://github.com/bitcoin/bitcoin/blob/main/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`](https://github.com/bitcoin/bitcoin/blob/main/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`](https://github.com/bitcoin/bitcoin/blob/main/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`](https://github.com/bitcoin/bitcoin/blob/main/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`](https://github.com/bitcoin/bitcoin/blob/main/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`](https://github.com/bitcoin/bitcoin/blob/main/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`.