dash-docs/_includes/ref/bitcoin-core/rpcs/intro.md

{% comment %} This file is licensed under the MIT License (MIT) available on http://opensource.org/licenses/MIT. {% endcomment %} {% assign filename="_includes/ref/bitcoin-core/rpcs/intro.md" %}

Remote Procedure Calls (RPCs)

{% include helpers/subhead-links.md %}

{% autocrossref %}

Bitcoin Core provides a large number of Remote Procedure Calls (RPCs) using a [HTTP JSON-RPC version 1.0][] interface. Any program can access the RPCs using JSON-RPC, but Bitcoin Core also provides the bitcoin-cli command to wrap the JSON-RPC access for Command Line Interface (CLI) users. Most of the RPC examples in this documentation use bitcoin-cli for simplicity, so this subsection describes raw JSON-RPC interface and how the command-line interface translates it.

In order to start bitcoind, you will need to set a password for JSON-RPC in the bitcoin.conf file. See the [Examples Page][devexamples] for details. JSON-RPC starts on port 8332 for mainnet and 18332 for testnet and regtest. By default, bitcoind doesn't use a JSON-RPC user, but you can set one (see bitcoind --help).

The interface is not intended for public access and is only accessible from localhost by default.

RPCs are made using the standard JSON-RPC 1.0 syntax, which sends several standard arguments:

Name	Type	Presence	Description
RPC	object	Required (exactly 1)	An object containing the standard RPC arguments
→ jsonrpc	number (real)	Optional (0 or 1)	The version of JSON-RPC used. Bitcoin Core currently ignores this, as it only supports version 1.0. Default is 1.0
→ id	string	Required (exactly 1)	An arbitrary string that will be returned when the response is sent. May be set to an empty string ("")
→ method	string	Required (exactly 1)	The RPC, such as getbestblockhash. See the RPC section for a list of available commands
→ params	array	Required (exactly 1)	An array containing parameters for the RPC. May be an empty array if allowed by the particular RPC
→ → Parameter	any	Optional (0 or more)	A parameter. May be any JSON type allowed by the particular RPC
{:.ntpd}

In table above and in other tables describing JSON-RPC input and output, we use the following formatting

• "→" to indicate an argument that is the child of a JSON array or JSON object. For example, "→ → Parameter" above means Parameter is the child of the params array which itself is a child of the RPC array.

• "Plain Text" names (like "RPC" above) are unnamed in the actual JSON-RPC

• literal names (like id above) are the strings that appear in the actual JSON-RPC

• Type (specifics) are the general JSON-RPC type and the specific Bitcoin Core type

• Required/Optional describe whether a field must be returned within its containing array or object. (So an optional object may still have required children.)

For example, here is the JSON-RPC requesting the hash of the latest block on the local best block chain:

{% highlight json %} { "jsonrpc": "1.0", "id": "bitcoin.org developer documentation", "method": "getbestblockhash", "params": [] } {% endhighlight %}

We can send that to a local Bitcoin Core running on testnet using cURL with the following command:

{% highlight bash %} curl --user ':your_password' --data-binary ''' { "jsonrpc": "1.0", "id":"bitcoin.org developer documentation", "method": "getbestblockhash", "params": [] }'''
-H 'content-type: text/plain;' http://127.0.0.1:18332/ {% endhighlight %}

The output will be sent using the standard JSON-RPC 1.0 format. For example (whitespace added):

{% highlight json %} { "result": "00000000bd68bfdf381efd5fff17c723d2bb645bcbb215a6e333d4204888e951", "error": null, "id": "bitcoin.org developer documentation" } {% endhighlight %}

The standard JSON-RPC 1.0 result format is described below:

Name	Type	Presence	Description
Result	object	Required (exactly 1)	An object describing the results
→ result	any	Required (exactly 1)	The results as any JSON data type. If an error occured, set to null
→ error	null/object	Required (exactly 1)	If no error occurred, set to null. If an error occured, an object describing the error
→ → code	number (int)	Required (exactly 1)	The error code as set by the returning function and defined in Bitcoin Core's [rpcprotocol.h][]
→ → message	string	Required (exactly 1)	An attempt to describe the problem in human-readable text. May be an empty string (""). Bitcoin Core often returns help text with embedded newline strings ("\n"); bitcoin-cli can expand these to actual newlines
→ id	string	Required (exactly 1)	The arbitrary string passed in when the RPC was called
{:.ntpd}

For an example of the error output, here's the result after passing an invalid address to the sendtoaddress RPC (whitespace added):

{% highlight json %} { "result": null, "error": { "code": -5, "message": "Invalid Bitcoin address" }, "id": "bitcoin.org developer documentation" } {% endhighlight %}

The bitcoin-cli command can save command line users a lot of typing compared to using cURL or another HTTP-sending command. For example, to get the block hash we got before, we would use the following command:

{% highlight bash %} bitcoin-cli getbestblockhash {% endhighlight %}

For non-error output, bitcoin-cli will only display the value of the result field, and if it's a string, bitcoin-cli will remove its JSON quotation marks. For example, the result for the command above:

{% highlight text %} 00000000bd68bfdf381efd5fff17c723d2bb645bcbb215a6e333d4204888e951 {% endhighlight %}

For errors, bitcoin-cli will display only the error object. For example, the result of the invalid address command above as formatted by bitcoin-cli:

{% highlight json %} error: {"code":-5,"message":"Invalid Bitcoin address"} {% endhighlight %}

Because bitcoin-cli abstracts away the parts of JSON-RPC we would need to repeatedly describe in each RPC description below, we describe the Bitcoin Core RPCs using bitcoin-cli. However, using an actual programming interface to the full JSON-RPC will serve you much better for automated tasks.

[{{WARNING}}][proper money handling]{:#term-proper-money-handling}{:.term} if you write programs using the JSON-RPC interface, you must ensure they handle high-precision real numbers correctly. See the [Proper Money Handling][wiki proper money handling] Bitcoin Wiki article for details and example code.

{% endautocrossref %}