Inside Bitcoin

1# JSON-RPC Interface
2
3The headless daemon `bitcoind` has the JSON-RPC API enabled by default, the GUI
4`bitcoin-qt` has it disabled by default. This can be changed with the `-server`
5option. In the GUI it is possible to execute RPC methods in the Debug Console
6Dialog.
7
8## Endpoints
9
10There are two JSON-RPC endpoints on the server:
11
121. `/`
132. `/wallet/<walletname>/`
14
15### `/` endpoint
16
17This endpoint is always active.
18It can always service non-wallet requests and can service wallet requests when
19exactly one wallet is loaded.
20
21### `/wallet/<walletname>/` endpoint
22
23This endpoint is only activated when the wallet component has been compiled in.
24It can service both wallet and non-wallet requests.
25It MUST be used for wallet requests when two or more wallets are loaded.
26
27This is the endpoint used by bitcoin-cli when a `-rpcwallet=` parameter is passed in.
28
29Best practice would dictate using the `/wallet/<walletname>/` endpoint for ALL
30requests when multiple wallets are in use.
31
32### Examples
33
34```sh
35# Get block count from the / endpoint when rpcuser=alice and rpcport=38332
36$ curl --user alice --data-binary '{"jsonrpc": "2.0", "id": "0", "method": "getblockcount", "params": []}' -H 'content-type: application/json' localhost:38332/
37
38# Get balance from the /wallet/walletname endpoint when rpcuser=alice, rpcport=38332 and rpcwallet=desc-wallet
39$ curl --user alice --data-binary '{"jsonrpc": "2.0", "id": "0", "method": "getbalance", "params": []}' -H 'content-type: application/json' localhost:38332/wallet/desc-wallet
40
41```
42
43## Parameter passing
44
45The JSON-RPC server supports both _by-position_ and _by-name_ [parameter
46structures](https://www.jsonrpc.org/specification#parameter_structures)
47described in the JSON-RPC specification. For extra convenience, to avoid the
48need to name every parameter value, all RPC methods accept a named parameter
49called `args`, which can be set to an array of initial positional values that
50are combined with named values.
51
52Examples:
53
54```sh
55# "params": ["mywallet", false, false, "", false, false, true]
56bitcoin-cli createwallet mywallet false false "" false false true
57
58# "params": {"wallet_name": "mywallet", "load_on_startup": true}
59bitcoin-cli -named createwallet wallet_name=mywallet load_on_startup=true
60
61# "params": {"args": ["mywallet"], "load_on_startup": true}
62bitcoin-cli -named createwallet mywallet load_on_startup=true
63```
64
65`bitcoin rpc` can also be substituted for `bitcoin-cli -named`, and is a newer alternative.
66
67## Versioning
68
69The RPC interface might change from one major version of Bitcoin Core to the
70next. This makes the RPC interface implicitly versioned on the major version.
71The version tuple can be retrieved by e.g. the `getnetworkinfo` RPC in
72`version`.
73
74Usually deprecated features can be re-enabled during the grace-period of one
75major version via the `-deprecatedrpc=` command line option. The release notes
76of a new major release come with detailed instructions on what RPC features
77were deprecated and how to re-enable them temporarily.
78
79## JSON-RPC 1.1 vs 2.0
80
81The server recognizes [JSON-RPC v2.0](https://www.jsonrpc.org/specification) requests
82and responds accordingly. A 2.0 request is identified by the presence of
83`"jsonrpc": "2.0"` in the request body. If that key + value is not present in a request,
84the legacy JSON-RPC v1.1 protocol is followed instead, which was the only available
85protocol in v27.0 and prior releases.
86
87|| 1.1 | 2.0 |
88|-|-|-|
89| Request marker | `"version": "1.1"` (or none) | `"jsonrpc": "2.0"` |
90| Response marker | (none) | `"jsonrpc": "2.0"` |
91| `"error"` and `"result"` fields in response | both present | only one is present |
92| HTTP codes in response | `200` unless there is any kind of RPC error (invalid parameters, method not found, etc) | Always `200` unless there is an actual HTTP server error (request parsing error, endpoint not found, etc) |
93| Notifications: requests that get no reply | (not supported) | Supported for requests that exclude the "id" field. Returns HTTP status `204` "No Content" |
94
95## Security
96
97The RPC interface allows other programs to control Bitcoin Core,
98including the ability to spend funds from your wallets, affect consensus
99verification, read private data, and otherwise perform operations that
100can cause loss of money, data, or privacy.  This section suggests how
101you should use and configure Bitcoin Core to reduce the risk that its
102RPC interface will be abused.
103
104- **Securing the executable:** Anyone with physical or remote access to
105  the computer, container, or virtual machine running Bitcoin Core can
106  compromise either the whole program or just the RPC interface.  This
107  includes being able to record any passphrases you enter for unlocking
108  your encrypted wallets or changing settings so that your Bitcoin Core
109  program tells you that certain transactions have multiple
110  confirmations even when they aren't part of the best block chain.  For
111  this reason, you should not use Bitcoin Core for security sensitive
112  operations on systems you do not exclusively control, such as shared
113  computers or virtual private servers.
114
115- **Securing local network access:** By default, the RPC interface can
116  only be accessed by a client running on the same computer and only
117  after the client provides a valid authentication credential (username
118  and passphrase).  Any program on your computer with access to the file
119  system and local network can obtain this level of access.
120  Additionally, other programs on your computer can attempt to provide
121  an RPC interface on the same port as used by Bitcoin Core in order to
122  trick you into revealing your authentication credentials.  For this
123  reason, it is important to only use Bitcoin Core for
124  security-sensitive operations on a computer whose other programs you
125  trust.
126
127- **RPC Credentials Security Boundary:** Any client with valid RPC credentials
128  should be treated as having significant control over both the Bitcoin Core node
129  and the filesystem resources accessible by the `bitcoind` process. RPC commands
130  can load wallet files from paths that the `bitcoind` process has permission to
131  access, specify file paths for operations, and potentially gain broader access
132  than intended. This means that someone with RPC access can potentially compromise
133  not only the Bitcoin Core node, but also the machine it is running on. Bitcoin Core
134  provides the `-rpcwhitelist` option to restrict which RPC commands specific users
135  can access, and `-rpcwhitelistdefault` to control the default behavior for users
136  without explicit whitelists. However, when using multiple wallets or sharing access
137  with different users, these should not be considered robust security boundaries, as
138  users with access to certain commands may still be able to exploit functionality in
139  unexpected ways. For security-sensitive operations, implement proper system-level
140  isolation (containers, virtualization, separate user accounts with restricted
141  permissions) rather than relying solely on RPC access controls.
142
143- **Securing remote network access:** You may optionally allow other
144  computers to remotely control Bitcoin Core by setting the `rpcallowip`
145  and `rpcbind` configuration parameters.  These settings are only meant
146  for enabling connections over secure private networks or connections
147  that have been otherwise secured (e.g. using a VPN or port forwarding
148  with SSH or stunnel).  **Do not enable RPC connections over the public
149  Internet.**  Although Bitcoin Core's RPC interface does use
150  authentication, it does not use encryption, so your login credentials
151  are sent as clear text that can be read by anyone on your network
152  path.  Additionally, the RPC interface has not been hardened to
153  withstand arbitrary Internet traffic, so changing the above settings
154  to expose it to the Internet (even using something like a Tor onion
155  service) could expose you to unconsidered vulnerabilities.  See
156  `bitcoind -help` for more information about these settings and other
157  settings described in this document.
158
159    Related, if you use Bitcoin Core inside a Docker container, you may
160    need to expose the RPC port to the host system.  The default way to
161    do this in Docker also exposes the port to the public Internet.
162    Instead, expose it only on the host system's localhost, for example:
163    `-p 127.0.0.1:8332:8332`
164
165- **Secure authentication:** By default, when no `rpcpassword` is specified, Bitcoin Core generates unique
166  login credentials each time it restarts and puts them into a file
167  readable only by the user that started Bitcoin Core, allowing any of
168  that user's RPC clients with read access to the file to login
169  automatically.  The file is `.cookie` in the Bitcoin Core
170  configuration directory, and using these credentials is the preferred
171  RPC authentication method.  If you need to generate static login
172  credentials for your programs, you can use the script in the
173  `share/rpcauth` directory in the Bitcoin Core source tree.  As a final
174  fallback, you can directly use manually-chosen `rpcuser` and
175  `rpcpassword` configuration parameters---but you must ensure that you
176  choose a strong and unique passphrase (and still don't use insecure
177  networks, as mentioned above).
178
179- **Secure string handling:** The RPC interface does not guarantee any
180  escaping of data beyond what's necessary to encode it as JSON,
181  although it does usually provide serialized data using a hex
182  representation of the bytes. If you use RPC data in your programs or
183  provide its data to other programs, you must ensure any problem strings
184  are properly escaped. For example, the `createwallet` RPC accepts
185  arguments such as `wallet_name` which is a string and could be used
186  for a path traversal attack without application level checks. Multiple
187  websites have been manipulated because they displayed decoded hex strings
188  that included HTML `<script>` tags. For this reason, and others, it is
189  recommended to display all serialized data in hex form only.
190
191## RPC consistency guarantees
192
193State that can be queried via RPCs is guaranteed to be at least up-to-date with
194the chain state immediately prior to the call's execution. However, the state
195returned by RPCs that reflect the mempool may not be up-to-date with the
196current mempool state.
197
198### Transaction Pool
199
200The mempool state returned via an RPC is consistent with itself and with the
201chain state at the time of the call. Thus, the mempool state only encompasses
202transactions that are considered mine-able by the node at the time of the RPC.
203
204The mempool state returned via an RPC reflects all effects of mempool and chain
205state related RPCs that returned prior to this call.
206
207### Wallet
208
209The wallet state returned via an RPC is consistent with itself and with the
210chain state at the time of the call.
211
212Wallet RPCs will return the latest chain state consistent with prior non-wallet
213RPCs. The effects of all blocks (and transactions in blocks) at the time of the
214call is reflected in the state of all wallet transactions. For example, if a
215block contains transactions that conflicted with mempool transactions, the
216wallet would reflect the removal of these mempool transactions in the state.
217
218However, the wallet may not be up-to-date with the current state of the mempool
219or the state of the mempool by an RPC that returned before this RPC. For
220example, a wallet transaction that was BIP-125-replaced in the mempool prior to
221this RPC may not yet be reflected as such in this RPC response.
222
223## Limitations
224
225There is a known issue in the JSON-RPC interface that can cause a node to crash if
226too many http connections are being opened at the same time because the system runs
227out of available file descriptors. To prevent this from happening you might
228want to increase the number of maximum allowed file descriptors in your system
229and try to prevent opening too many connections to your JSON-RPC interface at the
230same time if this is under your control. It is hard to give general advice
231since this depends on your system but if you make several hundred requests at
232once you are definitely at risk of encountering this issue.
233