mirrors/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2025-01-18 21:35:13 +01:00
Code Issues Projects Releases Wiki Activity

doc: document json rpc endpoints

Browse Source 
fixes #20246

Document both JSON-RPC endpoints, when they are active and which types
of requests they are able to service.

Adds two example curl requests, one for each endpoint.
This commit is contained in:
willcl-ark 2023-03-07 22:53:23 +00:00
parent d4ebdceaef
commit 65e3abcbf2
No known key found for this signature in database
GPG Key ID: CE6EC49945C17EA6
1 changed files with 35 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
doc/JSON-RPC-interface.md
View File

@ -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