diff options
| author | fanquake <fanquake@gmail.com> | 2023-06-02 16:24:31 +0100 |
|---|---|---|
| committer | fanquake <fanquake@gmail.com> | 2023-06-02 16:27:27 +0100 |
| commit | e43fdfd9adf253d94d1d428d3d177101fd56eb19 (patch) | |
| tree | 986f1114e872c740d6ebd93251ab16b9a8942f61 /doc | |
| parent | 436c185b05200e28696ef6ff64e679c3148f72bb (diff) | |
| parent | 65e3abcbf2b9e818f3b9f1ba35f3cfe7df5e3811 (diff) | |
| download | bitcoin-e43fdfd9adf253d94d1d428d3d177101fd56eb19.tar.xz | |
Merge bitcoin/bitcoin#27225: doc: document json rpc endpoints
65e3abcbf2b9e818f3b9f1ba35f3cfe7df5e3811 doc: document json rpc endpoints (willcl-ark)
Pull request description:
fixes #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 65e3abcbf2b9e818f3b9f1ba35f3cfe7df5e3811 - Seems fine. Can be improved if need be.
Tree-SHA512: d557c2caf000a1bdd7b46c9da38afe63dc28446ba4a961526f1af3cec81d994a9da663e02c81ebdc4f609b794585349cfca77a582dc1e788c120de1d3b4c7db6
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/JSON-RPC-interface.md | 35 |
1 files changed, 35 insertions, 0 deletions
diff --git a/doc/JSON-RPC-interface.md b/doc/JSON-RPC-interface.md index ab5db58cdd..6cbb6ebd72 100644 --- a/doc/JSON-RPC-interface.md +++ b/doc/JSON-RPC-interface.md @@ -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 |