JSON-RPC-interface.md
1 # JSON-RPC Interface 2 3 The 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` 5 option. In the GUI it is possible to execute RPC methods in the Debug Console 6 Dialog. 7 8 ## Endpoints 9 10 There are two JSON-RPC endpoints on the server: 11 12 1. `/` 13 2. `/wallet/<walletname>/` 14 15 ### `/` endpoint 16 17 This endpoint is always active. 18 It can always service non-wallet requests and can service wallet requests when 19 exactly one wallet is loaded. 20 21 ### `/wallet/<walletname>/` endpoint 22 23 This endpoint is only activated when the wallet component has been compiled in. 24 It can service both wallet and non-wallet requests. 25 It MUST be used for wallet requests when two or more wallets are loaded. 26 27 This is the endpoint used by bitcoin-cli when a `-rpcwallet=` parameter is passed in. 28 29 Best practice would dictate using the `/wallet/<walletname>/` endpoint for ALL 30 requests 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 45 The JSON-RPC server supports both _by-position_ and _by-name_ [parameter 46 structures](https://www.jsonrpc.org/specification#parameter_structures) 47 described in the JSON-RPC specification. For extra convenience, to avoid the 48 need to name every parameter value, all RPC methods accept a named parameter 49 called `args`, which can be set to an array of initial positional values that 50 are combined with named values. 51 52 Examples: 53 54 ```sh 55 # "params": ["mywallet", false, false, "", false, false, true] 56 bitcoin-cli createwallet mywallet false false "" false false true 57 58 # "params": {"wallet_name": "mywallet", "load_on_startup": true} 59 bitcoin-cli -named createwallet wallet_name=mywallet load_on_startup=true 60 61 # "params": {"args": ["mywallet"], "load_on_startup": true} 62 bitcoin-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 69 The RPC interface might change from one major version of Bitcoin Core to the 70 next. This makes the RPC interface implicitly versioned on the major version. 71 The version tuple can be retrieved by e.g. the `getnetworkinfo` RPC in 72 `version`. 73 74 Usually deprecated features can be re-enabled during the grace-period of one 75 major version via the `-deprecatedrpc=` command line option. The release notes 76 of a new major release come with detailed instructions on what RPC features 77 were deprecated and how to re-enable them temporarily. 78 79 ## JSON-RPC 1.1 vs 2.0 80 81 The server recognizes [JSON-RPC v2.0](https://www.jsonrpc.org/specification) requests 82 and 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, 84 the legacy JSON-RPC v1.1 protocol is followed instead, which was the only available 85 protocol 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 97 The RPC interface allows other programs to control Bitcoin Core, 98 including the ability to spend funds from your wallets, affect consensus 99 verification, read private data, and otherwise perform operations that 100 can cause loss of money, data, or privacy. This section suggests how 101 you should use and configure Bitcoin Core to reduce the risk that its 102 RPC 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 - **Securing remote network access:** You may optionally allow other 128 computers to remotely control Bitcoin Core by setting the `rpcallowip` 129 and `rpcbind` configuration parameters. These settings are only meant 130 for enabling connections over secure private networks or connections 131 that have been otherwise secured (e.g. using a VPN or port forwarding 132 with SSH or stunnel). **Do not enable RPC connections over the public 133 Internet.** Although Bitcoin Core's RPC interface does use 134 authentication, it does not use encryption, so your login credentials 135 are sent as clear text that can be read by anyone on your network 136 path. Additionally, the RPC interface has not been hardened to 137 withstand arbitrary Internet traffic, so changing the above settings 138 to expose it to the Internet (even using something like a Tor onion 139 service) could expose you to unconsidered vulnerabilities. See 140 `bitcoind -help` for more information about these settings and other 141 settings described in this document. 142 143 Related, if you use Bitcoin Core inside a Docker container, you may 144 need to expose the RPC port to the host system. The default way to 145 do this in Docker also exposes the port to the public Internet. 146 Instead, expose it only on the host system's localhost, for example: 147 `-p 127.0.0.1:8332:8332` 148 149 - **Secure authentication:** By default, when no `rpcpassword` is specified, Bitcoin Core generates unique 150 login credentials each time it restarts and puts them into a file 151 readable only by the user that started Bitcoin Core, allowing any of 152 that user's RPC clients with read access to the file to login 153 automatically. The file is `.cookie` in the Bitcoin Core 154 configuration directory, and using these credentials is the preferred 155 RPC authentication method. If you need to generate static login 156 credentials for your programs, you can use the script in the 157 `share/rpcauth` directory in the Bitcoin Core source tree. As a final 158 fallback, you can directly use manually-chosen `rpcuser` and 159 `rpcpassword` configuration parameters---but you must ensure that you 160 choose a strong and unique passphrase (and still don't use insecure 161 networks, as mentioned above). 162 163 - **Secure string handling:** The RPC interface does not guarantee any 164 escaping of data beyond what's necessary to encode it as JSON, 165 although it does usually provide serialized data using a hex 166 representation of the bytes. If you use RPC data in your programs or 167 provide its data to other programs, you must ensure any problem strings 168 are properly escaped. For example, the `createwallet` RPC accepts 169 arguments such as `wallet_name` which is a string and could be used 170 for a path traversal attack without application level checks. Multiple 171 websites have been manipulated because they displayed decoded hex strings 172 that included HTML `<script>` tags. For this reason, and others, it is 173 recommended to display all serialized data in hex form only. 174 175 ## RPC consistency guarantees 176 177 State that can be queried via RPCs is guaranteed to be at least up-to-date with 178 the chain state immediately prior to the call's execution. However, the state 179 returned by RPCs that reflect the mempool may not be up-to-date with the 180 current mempool state. 181 182 ### Transaction Pool 183 184 The mempool state returned via an RPC is consistent with itself and with the 185 chain state at the time of the call. Thus, the mempool state only encompasses 186 transactions that are considered mine-able by the node at the time of the RPC. 187 188 The mempool state returned via an RPC reflects all effects of mempool and chain 189 state related RPCs that returned prior to this call. 190 191 ### Wallet 192 193 The wallet state returned via an RPC is consistent with itself and with the 194 chain state at the time of the call. 195 196 Wallet RPCs will return the latest chain state consistent with prior non-wallet 197 RPCs. The effects of all blocks (and transactions in blocks) at the time of the 198 call is reflected in the state of all wallet transactions. For example, if a 199 block contains transactions that conflicted with mempool transactions, the 200 wallet would reflect the removal of these mempool transactions in the state. 201 202 However, the wallet may not be up-to-date with the current state of the mempool 203 or the state of the mempool by an RPC that returned before this RPC. For 204 example, a wallet transaction that was BIP-125-replaced in the mempool prior to 205 this RPC may not yet be reflected as such in this RPC response. 206 207 ## Limitations 208 209 There is a known issue in the JSON-RPC interface that can cause a node to crash if 210 too many http connections are being opened at the same time because the system runs 211 out of available file descriptors. To prevent this from happening you might 212 want to increase the number of maximum allowed file descriptors in your system 213 and try to prevent opening too many connections to your JSON-RPC interface at the 214 same time if this is under your control. It is hard to give general advice 215 since this depends on your system but if you make several hundred requests at 216 once you are definitely at risk of encountering this issue.