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