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## Versioning
9
10The RPC interface might change from one major version of Bitcoin Core to the
11next. This makes the RPC interface implicitly versioned on the major version.
12The version tuple can be retrieved by e.g. the `getnetworkinfo` RPC in
13`version`.
14
15Usually deprecated features can be re-enabled during the grace-period of one
16major version via the `-deprecatedrpc=` command line option. The release notes
17of a new major release come with detailed instructions on what RPC features
18were deprecated and how to re-enable them temporarily.
19
20## Security
21
22The RPC interface allows other programs to control Bitcoin Core,
23including the ability to spend funds from your wallets, affect consensus
24verification, read private data, and otherwise perform operations that
25can cause loss of money, data, or privacy.  This section suggests how
26you should use and configure Bitcoin Core to reduce the risk that its
27RPC interface will be abused.
28
29- **Securing the executable:** Anyone with physical or remote access to
30  the computer, container, or virtual machine running Bitcoin Core can
31  compromise either the whole program or just the RPC interface.  This
32  includes being able to record any passphrases you enter for unlocking
33  your encrypted wallets or changing settings so that your Bitcoin Core
34  program tells you that certain transactions have multiple
35  confirmations even when they aren't part of the best block chain.  For
36  this reason, you should not use Bitcoin Core for security sensitive
37  operations on systems you do not exclusively control, such as shared
38  computers or virtual private servers.
39
40- **Securing local network access:** By default, the RPC interface can
41  only be accessed by a client running on the same computer and only
42  after the client provides a valid authentication credential (username
43  and passphrase).  Any program on your computer with access to the file
44  system and local network can obtain this level of access.
45  Additionally, other programs on your computer can attempt to provide
46  an RPC interface on the same port as used by Bitcoin Core in order to
47  trick you into revealing your authentication credentials.  For this
48  reason, it is important to only use Bitcoin Core for
49  security-sensitive operations on a computer whose other programs you
50  trust.
51
52- **Securing remote network access:** You may optionally allow other
53  computers to remotely control Bitcoin Core by setting the `rpcallowip`
54  and `rpcbind` configuration parameters.  These settings are only meant
55  for enabling connections over secure private networks or connections
56  that have been otherwise secured (e.g. using a VPN or port forwarding
57  with SSH or stunnel).  **Do not enable RPC connections over the public
58  Internet.**  Although Bitcoin Core's RPC interface does use
59  authentication, it does not use encryption, so your login credentials
60  are sent as clear text that can be read by anyone on your network
61  path.  Additionally, the RPC interface has not been hardened to
62  withstand arbitrary Internet traffic, so changing the above settings
63  to expose it to the Internet (even using something like a Tor onion
64  service) could expose you to unconsidered vulnerabilities.  See
65  `bitcoind -help` for more information about these settings and other
66  settings described in this document.
67
68    Related, if you use Bitcoin Core inside a Docker container, you may
69    need to expose the RPC port to the host system.  The default way to
70    do this in Docker also exposes the port to the public Internet.
71    Instead, expose it only on the host system's localhost, for example:
72    `-p 127.0.0.1:8332:8332`
73
74- **Secure authentication:** By default, Bitcoin Core generates unique
75  login credentials each time it restarts and puts them into a file
76  readable only by the user that started Bitcoin Core, allowing any of
77  that user's RPC clients with read access to the file to login
78  automatically.  The file is `.cookie` in the Bitcoin Core
79  configuration directory, and using these credentials is the preferred
80  RPC authentication method.  If you need to generate static login
81  credentials for your programs, you can use the script in the
82  `share/rpcauth` directory in the Bitcoin Core source tree.  As a final
83  fallback, you can directly use manually-chosen `rpcuser` and
84  `rpcpassword` configuration parameters---but you must ensure that you
85  choose a strong and unique passphrase (and still don't use insecure
86  networks, as mentioned above).
87
88- **Secure string handling:** The RPC interface does not guarantee any
89  escaping of data beyond what's necessary to encode it as JSON,
90  although it does usually provide serialized data using a hex
91  representation of the bytes. If you use RPC data in your programs or
92  provide its data to other programs, you must ensure any problem strings
93  are properly escaped. For example, the `createwallet` RPC accepts
94  arguments such as `wallet_name` which is a string and could be used
95  for a path traversal attack without application level checks. Multiple
96  websites have been manipulated because they displayed decoded hex strings
97  that included HTML `<script>` tags. For this reason, and others, it is
98  recommended to display all serialized data in hex form only.
99
100## RPC consistency guarantees
101
102State that can be queried via RPCs is guaranteed to be at least up-to-date with
103the chain state immediately prior to the call's execution. However, the state
104returned by RPCs that reflect the mempool may not be up-to-date with the
105current mempool state.
106
107### Transaction Pool
108
109The mempool state returned via an RPC is consistent with itself and with the
110chain state at the time of the call. Thus, the mempool state only encompasses
111transactions that are considered mine-able by the node at the time of the RPC.
112
113The mempool state returned via an RPC reflects all effects of mempool and chain
114state related RPCs that returned prior to this call.
115
116### Wallet
117
118The wallet state returned via an RPC is consistent with itself and with the
119chain state at the time of the call.
120
121Wallet RPCs will return the latest chain state consistent with prior non-wallet
122RPCs. The effects of all blocks (and transactions in blocks) at the time of the
123call is reflected in the state of all wallet transactions. For example, if a
124block contains transactions that conflicted with mempool transactions, the
125wallet would reflect the removal of these mempool transactions in the state.
126
127However, the wallet may not be up-to-date with the current state of the mempool
128or the state of the mempool by an RPC that returned before this RPC. For
129example, a wallet transaction that was BIP-125-replaced in the mempool prior to
130this RPC may not yet be reflected as such in this RPC response.
131
132## Limitations
133
134There is a known issue in the JSON-RPC interface that can cause a node to crash if
135too many http connections are being opened at the same time because the system runs
136out of available file descriptors. To prevent this from happening you might
137want to increase the number of maximum allowed file descriptors in your system
138and try to prevent opening too many connections to your JSON-RPC interface at the
139same time if this is under your control. It is hard to give general advice
140since this depends on your system but if you make several hundred requests at
141once you are definitely at risk of encountering this issue.
142