Skip to content

Commit

Permalink
Merge bitcoin#27225: doc: document json rpc endpoints
Browse files Browse the repository at this point in the history
65e3abc doc: document json rpc endpoints (willcl-ark)

Pull request description:

  fixes bitcoin#20246

  This documents the two JSON-RPC endpoints available, details when they are active, specifies when they can or must be used, and outlines some known behaviour quirks.

ACKs for top commit:
  fanquake:
    ACK 65e3abc - Seems fine. Can be improved if need be.

Tree-SHA512: d557c2caf000a1bdd7b46c9da38afe63dc28446ba4a961526f1af3cec81d994a9da663e02c81ebdc4f609b794585349cfca77a582dc1e788c120de1d3b4c7db6
  • Loading branch information
fanquake committed Jun 2, 2023
2 parents 436c185 + 65e3abc commit e43fdfd
Showing 1 changed file with 35 additions and 0 deletions.
35 changes: 35 additions & 0 deletions doc/JSON-RPC-interface.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,41 @@ The headless daemon `bitcoind` has the JSON-RPC API enabled by default, the GUI
option. In the GUI it is possible to execute RPC methods in the Debug Console
Dialog.

## Endpoints

There are two JSON-RPC endpoints on the server:

1. `/`
2. `/wallet/<walletname>/`

### `/` endpoint

This endpoint is always active.
It can always service non-wallet requests and can service wallet requests when
exactly one wallet is loaded.

### `/wallet/<walletname>/` endpoint

This endpoint is only activated when the wallet component has been compiled in.
It can service both wallet and non-wallet requests.
It MUST be used for wallet requests when two or more wallets are loaded.

This is the endpoint used by bitcoin-cli when a `-rpcwallet=` parameter is passed in.

Best practice would dictate using the `/wallet/<walletname>/` endpoint for ALL
requests when multiple wallets are in use.

### Examples

```sh
# Get block count from the / endpoint when rpcuser=alice and rpcport=38332
$ curl --user alice --data-binary '{"jsonrpc": "1.0", "id": "0", "method": "getblockcount", "params": []}' -H 'content-type: text/plain;' localhost:38332/

# Get balance from the /wallet/walletname endpoint when rpcuser=alice, rpcport=38332 and rpcwallet=desc-wallet
$ curl --user alice --data-binary '{"jsonrpc": "1.0", "id": "0", "method": "getbalance", "params": []}' -H 'content-type: text/plain;' localhost:38332/wallet/desc-wallet

```

## Parameter passing

The JSON-RPC server supports both _by-position_ and _by-name_ [parameter
Expand Down

0 comments on commit e43fdfd

Please sign in to comment.