Dash Core

Dash Core Developer Documentation

Welcome to the Dash Core developer documentation. You'll find guides and documentation to help you start working with Dash Core as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Guides

Remote Procedure Calls

Overview

Dash Core provides a remote procedure call (RPC) interface for various administrative tasks, walletwallet - Software that stores private keys and monitors the block chain (sometimes as a client of a server that does the processing) to allow users to spend and receive duffs. operations, and queries about networknetwork - The Dash P2P network which broadcasts transactions and blocks. and block chainblock chain - A chain of blocks with each block referencing the block that preceded it. The most-difficult-to-recreate chain is the best block chain. data.

If you start Dash Core using dash-qt, the RPC interface is disabled by default. To enable it, set server=1 in dash.conf or supply the -server argument when invoking the program. If you start Dash Core using dashd, the RPC interface is enabled by default.

The interface requires the user to provide a password for authenticating RPC requests. This password can be set either using the rpcpassword property in dash.conf or by supplying the -rpcpassword program argument. Optionally a username can be set using the rpcuser configuration value. See the Examples Page for more information about setting Dash Core configuration values.

Open-source client libraries for the RPC interface are readily available in most modern programming languages, so you probably don't need to write your own from scratch. Dash Core also ships with its own compiled C++ RPC client, dash-cli, located in the bin directory alongside dashd and dash-qt. The dash-cli program can be used as a command-line interface (CLI) to Dash Core or for making RPC calls from applications written in languages lacking a suitable native client. The remainder of this section describes the Dash Core RPC protocol in detail.

The Dash Core RPC service listens for HTTP POST requests on port 9998 in mainnetmainnet - The original and main network for Dash transactions, where duffs have real economic value. mode, 19998 in testnettestnet - A global testing environment in which developers can obtain and spend duffs that have no real-world value on a network that is very similar to the Dash mainnet., or 19898 in regression test moderegression test mode - A local testing environment in which developers can almost instantly generate blocks on demand for testing events, and can create private duffs with no real-world value.. The port number can be changed by setting rpcport in dash.conf. By default the RPC service binds to your server's localhost loopback network interface so it's not accessible from other servers. Authentication is implemented using HTTP basic authentication. RPC HTTP requests must include a Content-Type header set to text/plain and a Content-Length header set to the size of the request body.

The format of the request body and response data is based on version 1.0 of the JSON-RPC specification. Specifically, the HTTP POST data of a request must be a JSON object with the following format:

NameTypePresenceDescription
RequestobjectRequired
(exactly 1)
The JSON-RPC request object

jsonrpc
number (real)Optional
(0 or 1)
Version indicator for the JSON-RPC request. Currently ignored by Dash Core.

id
stringOptional
(0 or 1)
An arbitrary string that will be returned with the response. May be omitted or set to an empty string ("")

method
stringRequired
(exactly 1)
The RPC method name (e.g. getblock). See the RPC section for a list of available methods.

params
arrayOptional
(0 or 1)
An array containing positional parameter values for the RPC. May be an empty array or omitted for RPC calls that don't have any required parameters.

params
objectOptional
(0 or 1)
Starting from Dash Core 0.12.3 / Bitcoin Core 0.14.0 (replaces the params array above) An object containing named parameter values for the RPC. May be an empty object or omitted for RPC calls that don’t have any required parameters.
→ →
Parameter
anyOptional
(0 or more)
A parameter. May be any JSON type allowed by the particular RPC method

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

  • "→" indicates 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 Request object.

  • Plain-text names like "Request" are unnamed in the actual JSON object

  • Code-style names like params are literal strings that appear in the JSON object.

  • "Type" is the JSON data type and the specific Dash Core type.

  • "Presence" indicates whether or not a field must be present within its containing array or object. Note that an optional object may still have required children.

The HTTP response data for a RPC request is a JSON object with the following format:

NameTypePresenceDescription
ResponseobjectRequired
(exactly 1)
The JSON-RPC response object.

result
anyRequired
(exactly 1)
The RPC output whose type varies by call. Has value null if an error occurred.

error
null/objectRequired
(exactly 1)
An object describing the error if one occurred, otherwise null.
→ →
code
number (int)Required
(exactly 1)
The error code returned by the RPC function call. See rpcprotocol.h for a full list of error codes and their meanings.
→ →
message
stringRequired
(exactly 1)
A text description of the error. May be an empty string ("").

id
stringRequired
(exactly 1)
The value of id provided with the request. Has value null if the id field was omitted in the request.

Example

As an example, here is the JSON-RPC request object for the hash of the genesis blockgenesis block - The first block in the Dash block chain.:

{
    "method": "getblockhash",
    "params": [0],
    "id": "foo"
}

The command to send this request using dash-cli is:

dash-cli getblockhash 0

The command to send this request using dash-cli with named parameters is:

dash-cli -named getblockhash height=0

Alternatively, we could POST this request using the cURL command-line program as follows:

curl --user 'my_username:my_secret_password' --data-binary '''
  {
      "method": "getblockhash",
      "params": [0],
      "id": "foo"
  }''' \
  --header 'Content-Type: text/plain;' localhost:9998

The HTTP response data for this request would be:

{
    "result": "00000bafbc94add76cb75e2ec92894837288a481e5c005f6563d91623bf8bc2c",
    "error": null,
    "id": "foo"
}

📘

Note: In order to minimize its size, the raw JSON response from Dash Core doesn't include any extraneous whitespace characters.

Here whitespace has been added to make the object more readable. dash-cli also transforms the raw response to make it more human-readable. It:

  • Adds whitespace indentation to JSON objects
  • Expands escaped newline characters ("\n") into actual newlines
  • Returns only the value of the result field if there's no error
  • Strips the outer double-quotes around results of type string
  • Returns only the error field if there's an error

Continuing with the example above, the output from the dash-cli command would be simply:

00000bafbc94add76cb75e2ec92894837288a481e5c005f6563d91623bf8bc2c

RPCs with sub-commands

Dash Core has a number of RPC requests that use sub-commands to group access to related data under one RPC method name. Examples of this include the gobject, masternode, protx, and quorum RPCs. If using cURL, the sub-commands should be included in the requests params field as shown here:

curl --user 'my_username:my_secret_password' --data-binary '''
  {
      "method": "gobject",
      "params": ["list", "valid", "proposals"],
      "id": "foo"
  }''' \
  --header 'Content-Type: text/plain;' localhost:9998

Error Handling

If there's an error processing a request, Dash Core sets the result field to null and provides information about the error in the error field. For example, a request for the block hash at block height -1 would be met with the following response (again, whitespace added for clarity):

{
    "result": null,
    "error": {
        "code": -8,
        "message": "Block height out of range"
    },
    "id": "foo"
}

If dash-cli encounters an error, it exits with a non-zero status code and outputs the error field as text to the process's standard error stream:

error code: -8
error message:
Block height out of range

Batch Requests

The RPC interface supports request batching as described in version 2.0 of the JSON-RPC specification. To initiate multiple RPC requests within a single HTTP request, a client can POST a JSON array filled with Request objects. The HTTP response data is then a JSON array filled with the corresponding Response objects. Depending on your usage pattern, request batching may provide significant performance gains. The dash-cli RPC client does not support batch requests.

curl --user 'my_username:my_secret_password' --data-binary '''
  [
    {
      "method": "getblockhash",
      "params": [0],
      "id": "foo"
    },
    {
      "method": "getblockhash",
      "params": [1],
      "id": "foo2"
    }
  ]''' \
  --header 'Content-Type: text/plain;' localhost:9998

To keep this documentation compact and readable, the examples for each of the available RPC calls will be given as dash-cli commands:

dash-cli [options] <method name> <param1> <param2> ...

This translates into an JSON-RPC Request object of the form:

{
    "method": "<method name>",
    "params": [ "<param1>", "<param2>", "..." ],
    "id": "foo"
}

🚧

High-precision real numbers

Warning: if you write programs using the JSON-RPC interface, you must ensure they handle high-precision real numbers correctly. See the Proper Money Handling Bitcoin Wiki article for details and example code.

Updated 5 months ago


What's Next

Quick Reference

Remote Procedure Calls


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.