fully compatible with the original bitcoind/bitcoin-qt. There are a few key
differences between dcrd and bitcoind as far as how RPCs are serviced:
* Unlike bitcoind that has the wallet and chain intermingled in the same process which leads to several issues, dcrd intentionally splits the wallet and chain services into independent processes. See the blog post [https://blog.conformal.com/btcd-not-your-moms-bitcoin-daemon/ here] for further details on why they were separated. This means that if you are talking directly to dcrd, only chain-related RPCs are available. However both chain-related and wallet-related RPCs are available via [https://github.com/decred/dcrwallet dcrwallet].
* dcrd is secure by default which means that the RPC connection is TLS-enabled by default
* dcrd provides access to the API through both [https://en.wikipedia.org/wiki/POST_%28HTTP%29 HTTP POST] requests and [https://en.wikipedia.org/wiki/WebSocket Websockets]
Websockets are the preferred transport for dcrd RPC and are used by applications
such as [https://github.com/decred/dcrwallet dcrwallet] for inter-process
communication with dcrd. The websocket connection endpoint for dcrd is
<code>wss://your_ip_or_domain:9109/ws</code>.
In addition to the [[#5-standard-methods|standard API]], an [[#6-websocket-methods-websocket-specific|extension API]]
has been developed that is exclusive to clients using Websockets. In its current
state, this API attempts to cover features found missing in the standard API
during the development of dcrwallet.
While the [[#5-standard-methods|standard API]] is stable, the
[[#6-websocket-methods-websocket-specific|Websocket extension API]] should be considered a work in
progress, incomplete, and susceptible to changes (both additions and removals).
==2. HTTP POST Versus Websockets==
The dcrd RPC server supports both [https://en.wikipedia.org/wiki/POST_%28HTTP%29 HTTP POST]
requests and the preferred [https://en.wikipedia.org/wiki/WebSocket Websockets].
All of the standard and extension methods described in
this documentation can be accessed through both. As the name
indicates, the [[#6-websocket-methods-websocket-specific|Websocket-specific extension]] methods can only be
accessed when connected via Websockets.
As mentioned in the [[#1-overview|overview]], the websocket connection endpoint for
dcrd is <code>wss://your_ip_or_domain:9109/ws</code>.
The most important differences between the two transports as it pertains to the
JSON-RPC API are:
{|
!
!HTTP POST Requests
!Websockets
|-
|Allows multiple requests across a single connection
|Yes
|Yes
|-
|Supports asynchronous notifications
|No
|Yes
|-
|Scales well with large numbers of requests
|No
|Yes
|}
==3. Authentication==
===3.1 Authentication Overview===
The following authentication details are needed before establishing a connection
to a dcrd RPC server:
* '''rpcuser''' is the full-access username configured for the dcrd RPC server
* '''rpcpass''' is the full-access password configured for the dcrd RPC server
* '''rpclimituser''' is the limited username configured for the dcrd RPC server
* '''rpclimitpass''' is the limited password configured for the dcrd RPC server
* '''rpccert''' is the PEM-encoded X.509 certificate (public key) that the dcrd server is configured with. It is automatically generated by dcrd and placed in the dcrd home directory (which is typically <code>%LOCALAPPDATA%\Dcrd</code> on Windows and <code>~/.dcrd</code> on POSIX-like OSes)
'''NOTE:''' As mentioned above, dcrd is secure by default which means the RPC
server is not running unless configured with a '''rpcuser''' and '''rpcpass'''
and/or a '''rpclimituser''' and '''rpclimitpass''', and uses TLS authentication for
all connections.
Depending on which connection type you are using, you can choose one of
two, mutually exclusive, methods.
* [[#32-http-basic-access-authentication|Use HTTP Authorization Header]] - HTTP POST requests and Websockets
* [[#33-json-rpc-authenticate-command-websocket-specific|Use the JSON-RPC "authenticate" command]] - Websockets only
===3.2 HTTP Basic Access Authentication===
The dcrd RPC server uses HTTP [https://en.wikipedia.org/wiki/Basic_access_authentication basic access authentication] with the '''rpcuser'''
and '''rpcpass''' detailed above. If the supplied credentials are invalid, you
will be disconnected immediately upon making the connection.
|Returns formatted hash data to work on or checks and submits solved data. NOTE: Since dcrd does not have the wallet integrated to provide payment addresses, dcrd must be configured via the <code>--miningaddr</code> option to provide which payment addresses to pay created blocks to for this RPC to function.
|-
|[[#help|help]]
|Y
|Returns a list of all commands or help for a specified command.
|Set the server to generate coins (mine) or not. NOTE: Since dcrd does not have the wallet integrated to provide payment addresses, dcrd must be configured via the <code>--miningaddr</code> option to provide which payment addresses to pay created blocks to for this RPC to function.
|-
|[[#stop|stop]]
|N
|Shutdown dcrd.
|-
|[[#submitblock|submitblock]]
|Y
|Attempts to submit a new serialized, hex-encoded block to the network.
# <code>peer</code>: <code>(string, required)</code> ip address and port of the peer to operate on.
# <code>command</code>: <code>(string, required)</code> - <code>add</code> to add a persistent peer, <code>remove</code> to remove a persistent peer, or <code>onetry</code> to try a single connection to a peer.
# <code>addresses and amounts</code>: <code>(JSON object, required)</code> - json object with addresses as keys and output amounts as values.
#: <code>address</code>: <code>(string, required)</code> the address to send the specified output amount to.
#: <code>{"address": n.nnn, ...}</code>
|-
!Description
|
: Returns a new transaction spending the provided inputs and sending to the provided addresses.The transaction inputs are not signed in the created transaction.
: The <code>signrawtransaction</code> RPC command provided by wallet must be used to sign the resulting transaction.
|-
!Returns
|<code>transaction</code>: (string) - hex-encoded bytes of the serialized transaction
# <code>levelspec</code>: <code>(string, required)</code> the debug level specification.
|-
!Description
|
: Dynamically changes the debug logging level.
: The levelspec can either be a debug level or of the form <code><subsystem>=<level>,<subsystem2>=<level2>,...</code>
: The valid debug levels are <code>trace</code>, <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, and <code>critical</code>.
: The valid subsystems are <code>AMGR</code>, <code>ADXR</code>, <code>BCDB</code>, <code>BMGR</code>, <code>DCRD</code>, <code>CHAN</code>, <code>DISC</code>, <code>PEER</code>, <code>RPCS</code>, <code>SCRP</code>, <code>SRVR</code>, and <code>TXMP</code>.
: Additionally, the special keyword <code>show</code> can be used to get a list of the available subsystems.
# <code>confirmations</code>: <code>(numeric, required)</code> Estimate the fee rate a transaction requires so that it is mined in up to this number of blocks.
# <code>mode</code>: <code>(string)</code> The only supported mode for the moment is 'conservative'.
# <code>addresses</code>: <code>(json array, required)</code> The addresses to check.
|-
!Description
|Returns the existence of the provided address.
|-
!Returns
|<code>bitset</code> Bitset of bools showing if addresses exist or not.
|-
!Example Return
|<code>07</code>
|}
----
====existsexpiredtickets====
{|
!Method
|existsexpiredtickets
|-
!Parameters
|
# <code>txhashes</code>: <code>(json array, required)</code> The array of tx hashes to check.
|-
!Description
|Returns the existence of the provided tickets in the expired ticket map.
|-
!Returns
|<code>bitset</code> Bitset of bools showing if tx hashes exist or not as expired tickets.
|-
!Example Return
|<code>00</code>
|}
----
====existsliveticket====
{|
!Method
|existsliveticket
|-
!Parameters
|
# <code>txhash</code>: <code>(string, required)</code> The ticket hash to check.
|-
!Description
|Returns the existence of the provided ticket.
|-
!Returns
|<code>boolean</code>
|-
!Example Return
|<code>true</code>
|}
----
====existslivetickets====
{|
!Method
|existslivetickets
|-
!Parameters
|
# <code>txhashes</code>: <code>(json array, required)</code> The array of tx hashes to check.
|-
!Description
|Returns the existence of the provided tickets in the live ticket map.
|-
!Returns
|<code>bitset</code> Bitset of bools showing if tx hashes exist or not as live tickets.
|-
!Example Return
|<code>00</code>
|}
----
====existsmempooltxs====
{|
!Method
|existsmempooltxs
|-
!Parameters
|
# <code>txhashes</code>: <code>(json array, required)</code> The array of tx hashes to check.
|-
!Description
|Returns the existence of the provided txs in the mempool.
|-
!Returns
|<code>bitset</code> Bitset of bools showing if tx hashes exist or not in the mempool.
|-
!Example Return
|<code>00</code>
|}
----
====existsmissedtickets====
{|
!Method
|existsmissedtickets
|-
!Parameters
|
# <code>txhashes</code>: <code>(json array, required)</code> The array of tx hashes to check.
|-
!Description
|Returns the existence of the provided tickets in the missed ticket map.
|-
!Returns
|<code>bitset</code> Bitset of bools showing if tx hashes exist or not as missed tickets.
|-
!Example Return
|<code>00</code>
|}
----
====generate====
{|
!Method
|generate
|-
!Parameters
|
# <code>numblocks</code>: <code>(int, required)</code> The number of blocks to generate.
|-
!Description
|When in simnet or regtest mode, generates <code>numblocks</code> blocks. If blocks arrive from elsewhere, they are built upon but don't count toward the number of blocks to generate. Only generated blocks are returned. This RPC call will exit with an error if the server is already CPU mining, and will prevent the server from CPU mining for another command while it runs.
|-
!Returns
|<code>(json array of strings)</code>
: <code>blockhash</code>: hash of the generated block.
<code>["blockhash", ...]</code>
|-
|}
----
====getaddednodeinfo====
{|
!Method
|getaddednodeinfo
|-
!Parameters
|
# <code>dns</code>: <code>(boolean, required)</code> specifies whether the returned data is a JSON object including DNS and connection information, or just a list of added peers.
# <code>node</code>: <code>(string, optional)</code> only return information about this specific peer instead of all added peers.
|-
!Description
|Returns information about manually added (persistent) peers.
|-
!Returns (dns=false)
|<code>["ip:port", ...]</code>
|-
!Returns (dns=true)
|<code>(json array of objects)</code>
: <code>addednode</code>: <code>(string)</code> the ip address or domain of the added peer.
: <code>connected</code>: <code>(boolean)</code> whether or not the peer is currently connected.
: <code>addresses</code>: <code>(json array or objects)</code> DNS lookup and connection information about the peer.
: <code>address</code>: <code>(string)</code> the ip address for this DNS entry.
: <code>connected</code>: <code>(string)</code> the connection 'direction' (if connected).
# <code>block hash</code>: <code>(string, required)</code> the hash of the block.
# <code>verbose</code>: <code>(boolean, optional, default=true)</code> specifies the block is returned as a JSON object instead of hex-encoded string.
# <code>verbosetx</code>: <code>(boolean, optional, default=false)</code> specifies that each transaction is returned as a JSON object and only applies if the <code>verbose</code> flag is true.
|-
!Description
|Returns information about a block given its hash.
|-
!Returns (verbose=false)
|<code>"data" (string) hex-encoded bytes of the serialized block</code>
|-
!Returns (verbose=true, verbosetx=false)
|
<code>(json object)</code>
: <code>hash</code>: <code>(string)</code> the hash of the block (same as provided).
: <code>confirmations</code>: <code>(numeric)</code> the number of confirmations.
: <code>size</code>: <code>(numeric)</code> the size of the block.
: <code>height</code>: <code>(numeric)</code> the height of the block in the block chain.
: <code>version</code>: <code>(numeric)</code> the block version.
: <code>merkleroot</code>: <code>(string)</code> root hash of the merkle tree.
: <code>stakeroot</code>: <code>(string)</code> root hash of the stake tree.
: <code>tx</code>: <code>(json array of string)</code> the transaction hashes.
: <code>stx</code>: <code>(json array of string)</code> the stake transaction hashes.
: <code>time</code>: <code>(numeric)</code> the block time in seconds since 1 Jan 1970 GMT.
: <code>nonce</code>: <code>(numeric)</code> the block nonce.
: <code>votebits</code>: <code>(numeric)</code> the block voting results.
: <code>finalstate</code>: <code>(string)</code> the final lottery state.
: <code>voters</code>: <code>(numeric)</code> the number of votes.
: <code>freshstake</code>: <code>(numeric)</code> the number of ticket purchases.
: <code>revocations</code>: <code>(numeric)</code> the number of ticket revocations.
: <code>poolsize</code>: <code>(numeric)</code> the total number of valid spendble tickets as of the block.
: <code>bits</code>: <code>(numeric)</code> the bits which represent the block difficulty.
: <code>sbits</code>: <code>(numeric)</code> the bits which represent the stake difficulty.
: <code>difficulty</code>: <code>(numeric)</code> the proof-of-work difficulty as a multiple of the minimum difficulty.
: <code>chainwork</code>: <code>(string)</code> the total number of hashes expected to produce the chain up to the block in hex.
: <code>extradata</code>: <code>(string)</code> extra data for the block including the extra nonce used by proof-of-work miners.
: <code>previousblockhash</code>: <code>(string)</code> the hash of the previous block.
: <code>nextblockhash</code>: <code>(string)</code> the hash of the next block (only if there is one).
<code>{"hash": "blockhash", "confirmations": n, "size": n, "height": n, "version": n, "merkleroot": "hash", "stakeroot": "hash", "tx": ["transactionhash", ...], "stx": ["transactionhash", ...], "time": n, "nonce": n, "votebits": n, "finalstate": "state", "voters": n, "freshstake": n, "revocations": n, "poolsize": n, "bits": n, "sbits": n.nn, "difficulty": n.nn, "chainwork": "workhex", "extradata": "data", "stakeversion": n, previousblockhash": "hash", "nextblockhash": "hash"}</code>
|-
!Example Return (verbose=false)
|
: Newlines added for display purposes. The actual return does not contain newlines.
|Returns information about the current state of the block chain.
|-
!Returns
|<code>(json object)</code>
: <code>chain</code>: <code>(string)</code> The current network name.
: <code>blocks</code>: <code>(numeric)</code> The number of blocks in the current best chain.
: <code>headers</code>: <code>(numeric)</code> The number of validated block headers that comprise the target best chain.
: <code>syncheight</code>: <code>(numeric)</code> The latest known block height being synced to.
: <code>bestblockhash</code>: <code>(string)</code> The block hash of the current best chain tip.
: <code>difficulty</code>: <code>(numeric)</code> (DEPRECATED) The current network difficulty.
: <code>difficultyratio</code>: <code>(numeric)</code> The current proof-of-work difficulty as a multiple of the minimum difficulty.
: <code>verificationprogress</code>: <code>(numeric)</code> The chain verification progress estimate.
: <code>chainwork</code>: <code>(string)</code> Hex encoded total work done for the chain.
: <code>initialblockdownload</code>: <code>(boolean)</code> Best guess of whether this node is in the initial block download mode used to catch up the chain when it is far behind.
: <code>maxblocksize</code>: <code>(numeric)</code> The maximum allowed block size.
: <code>deployments</code>: <code>(json array of objects)</code> Network consensus deployments.
: <code>status</code>: <code>(string)</code> The deployment agenda's current status.
: <code>since</code>: <code>(numeric)</code> The blockheight of the first block to which the status applies.
: <code>starttime</code>: <code>(numeric)</code> The start time of the voting period for the agenda.
: <code>expiretime</code>: <code>(numeric)</code> The expiry time of the voting period for the agenda.
<code>{ "chain": "name", "blocks": n, "headers": n, "syncheight": n, "bestblockhash": "hash", "difficulty": n, "difficultyratio": n, "verificationprogress": n, "chainwork": "n", "initialblockdownload": bool, "maxblocksize": n, "deployments": {"agenda": { "status": "status", "since": n, "starttime": n, "expiretime": n}, ...}}</code>
# <code>block hash</code>: <code>(string, required)</code> the hash of the block.
# <code>verbose</code>: <code>(boolean, optional, default=true)</code> specifies the block header is returned as a JSON object instead of a hex-encoded string.
|-
!Description
|Returns hex-encoded bytes of the serialized block header.
|-
!Returns (verbose=false)
|<code>"data" (string) hex-encoded bytes of the serialized block</code>
|-
!Returns (verbose=true)
|<code>(json object)</code>
: <code>hash</code>: <code>(string)</code> the hash of the block (same as provided).
: <code>confirmations</code>: <code>(numeric)</code> the number of confirmations.
: <code>version</code>: <code>(numeric)</code> the block version.
: <code>merkleroot</code>: <code>(string)</code> root hash of the merkle tree.
: <code>stakeroot</code>: <code>(string)</code> root hash of the stake tree.
: <code>votebits</code>: <code>(numeric)</code> the block voting results.
: <code>finalstate</code>: <code>(string)</code> the final lottery state.
: <code>voters</code>: <code>(numeric)</code> the number of votes.
: <code>freshstake</code>: <code>(numeric)</code> the number of ticket purchases.
: <code>revocations</code>: <code>(numeric)</code> the number of ticket revocations.
: <code>poolsize</code>: <code>(numeric)</code> the total number of valid spendble tickets as of the block.
: <code>bits</code>: <code>(numeric)</code> the bits which represent the block difficulty.
: <code>sbits</code>: <code>(numeric)</code> the bits which represent the stake difficulty.
: <code>height</code>: <code>(numeric)</code> the height of the block in the block chain.
: <code>size</code>: <code>(numeric)</code> the size of the block.
: <code>time</code>: <code>(numeric)</code> the block time in seconds since 1 Jan 1970 GMT.
: <code>nonce</code>: <code>(numeric)</code> the block nonce.
: <code>extradata</code>: <code>(string)</code> extra data for the block including the extra nonce used by proof-of-work miners.
: <code>difficulty</code>: <code>(numeric)</code> the proof-of-work difficulty as a multiple of the minimum difficulty.
: <code>chainwork</code>: <code>(string)</code> the total number of hashes expected to produce the chain up to the block in hex.
: <code>previousblockhash</code>: <code>(string)</code> the hash of the previous block.
: <code>nextblockhash</code>: <code>(string)</code> the hash of the next block (only if there is one).
<code>{"hash": "blockhash", "confirmations": n, "version": n, "merkleroot": "hash", "stakeroot": "hash", "votebits": n, "finalstate": "state", "voters": n, "freshstake": n, "revocations": n, "poolsize": n, "bits": n, "sbits": n.nn, "height": n, "size": n, "time": n, "nonce": n, "extradata": "data", "stakeversion": n, "difficulty": n.nn, "chainwork": "workhex", "previousblockhash": "hash", "nextblockhash": "hash"}</code>
|-
!Example Return (verbose=false)
|
: Newlines added for display purposes. The actual return does not contain newlines.
: Returns about all known chain tips the in the block tree.
: The statuses in the result have the following meanings:
* <code>active</code>: The current best chain tip.
* <code>invalid</code>: The block or one of its ancestors is invalid.
* <code>headers-only</code>: The block or one of its ancestors does not have the full block data available which also means the block can't be validated or connected.
* <code>valid-fork</code>: The block is fully validated which implies it was probably part of the main chain at one point and was reorganized.
* <code>valid-headers</code>: The full block data is available and the header is valid, but the block was never validated which implies it was probably never part of the main chain.
|-
!Returns
|
<code>(json array of objects)</code>
: <code>height</code>: <code>(numeric)</code> The height of the chain tip.
: <code>hash</code>: <code>(string)</code> The block hash of the chain tip.
: <code>branchlen</code>: <code>(numeric)</code> The length of the branch that connects the tip to the main chain (0 for the main chain tip).
: <code>status</code>: <code>(string)</code> status of the chain (active, invalid, headers-only, valid-fork, valid-headers).
<code>[{"height": n, "hash": "hash", "branchlen": n, "status": "status"}, ...]</code>
# <code>blocklocators</code>: <code>(json array, required)</code> Array of block locator hashes.
# <code>hashstop</code>: <code>(string, required)</code> Block hash to stop including block headers for, set to zero to get as many blocks as possible.
|-
!Description
|Returns block headers starting with the first known block hash from the request.
|-
!Returns
|<code>(json object)</code>
: <code>headers</code>: <code>(json array)</code> Serialized block headers of all located blocks, limited to some arbitrary maximum number of hashes (currently 2000, which matches the wire protocol headers message, but this is not guaranteed).
|Returns a JSON object containing various state info.
|-
!Notes
|NOTE: Since dcrd does NOT contain wallet functionality, wallet-related fields are not returned. See getinfo in dcrwallet for a version which includes that information.
|-
!Returns
|
<code>(json object)</code>
: <code>version</code>: <code>(numeric)</code> the version of the server.
: <code>protocolversion</code>: <code>(numeric)</code> the latest supported protocol version.
: <code>blocks</code>: <code>(numeric)</code> the number of blocks processed.
: <code>timeoffset</code>: <code>(numeric)</code> the time offset.
: <code>connections</code>: <code>(numeric)</code> the number of connected peers.
: <code>proxy</code>: <code>(string)</code> the proxy used by the server
: <code>difficulty</code>: <code>(numeric)</code> the current target difficulty.
: <code>testnet</code>: <code>(boolean)</code> whether or not server is using testnet.
: <code>relayfee</code>: <code>(numeric)</code> the minimum relay fee for non-free transactions in DCR/KB.
<code>{"version": n,"protocolversion": n, "blocks": n, "timeoffset": n, "connections": n, "proxy": "host:port", "difficulty": n.nn, "testnet": true or false, "relayfee": n.nn}</code>
|Returns a JSON object containing mempool-related information.
|-
!Returns
|<code>(json object)</code>
: <code>bytes</code>: <code>(numeric)</code> size in bytes of the mempool
: <code>size</code>: <code>(numeric)</code> number of transactions in the mempool
<code>{"bytes": n, "size": n}</code>
|-
!Example Return
|<code>{"bytes": 310768, "size": 157}</code>
|}
----
====getmininginfo====
{|
!Method
|getmininginfo
|-
!Parameters
|None
|-
!Description
|Returns a JSON object containing mining-related information.
|-
!Returns
|<code>(json object)</code>
: <code>blocks</code>: <code>(numeric)</code> latest best block.
: <code>currentblocksize</code>: <code>(numeric)</code> size of the latest best block.
: <code>currentblocktx</code>: <code>(numeric)</code> number of transactions in the latest best block.
: <code>difficulty</code>: <code>(numeric)</code> current target difficulty.
: <code>stakedifficulty</code>: <code>(numeric)</code> Stake difficulty required for the next block.
: <code>errors</code>: <code>(string)</code> any current errors.
: <code>generate</code>: <code>(boolean)</code> whether or not server is set to generate coins.
: <code>genproclimit</code>: <code>(numeric)</code> number of processors to use for coin generation (-1 when disabled).
: <code>hashespersec</code>: <code>(numeric)</code> recent hashes per second performance measurement while generating coins.
: <code>networkhashps</code>: <code>(numeric)</code> estimated network hashes per second for the most recent blocks.
: <code>pooledtx</code>: <code>(numeric)</code> number of transactions in the memory pool.
: <code>testnet</code>: <code>(boolean)</code> whether or not server is using testnet.
<code>{"blocks": n, "currentblocksize": n, "currentblocktx": n, "difficulty": n.nn, "stakedifficulty": n, "errors": "errors", "generate": true or false, "genproclimit": n, "hashespersec": n, "networkhashps": n, "pooledtx": n, "testnet": true or false }</code>
# <code>blocks</code>: <code>(numeric, optional, default=120)</code> The number of blocks, or -1 for blocks since last difficulty change.
# <code>height</code>: <code>(numeric, optional, default=-1)</code> Perform estimate ending with this height or -1 for current best chain block height.
|-
!Description
|Returns the estimated network hashes per second for the block heights provided by the parameters.
: <code>name</code>: <code>(string)</code> The name of the network interface.
: <code>limited</code>: <code>(boolean)</code> True if only connections to the network are allowed.
: <code>proxy</code>: <code>(string)</code> The proxy set for the network.
: <code>proxyrandomizecredentials</code>: <code>(boolean)</code> True if randomized credentials are set for the proxy.
: <code>reachable</code>: <code>(boolean)</code> True if connections can be made to or from the network.
: <code>version</code>: <code>(numeric)</code> The version of the node as a numeric.
: <code>subversion</code>: <code>(string)</code> The subversion of the node, as advertised to peers.
: <code>protocolversion</code>: <code>(numeric)</code> The protocol version of the node.
: <code>timeoffset</code>: <code>(numeric)</code> The node clock offset in seconds.
: <code>connections</code>: <code>(numeric)</code> The total number of open connections for the node.
: <code>networks</code>: <code>(json array)</code> An array of objects describing IPV4, IPV6 and Onion network interface states.
: <code>relayfee</code>: <code>(numeric)</code> The minimum required transaction fee for the node.
: <code>localaddresses</code>: <code>(json array)</code> An array of objects describing local addresses being listened on by the node.
: <code>localservices</code>: <code>(string)</code> The services supported by the node, as advertised in its version message.
<code>{"version": n, "subversion": "major.minor.patch", "protocolversion": n, "timeoffset": n, "connections": n, "networks": [{"name": "network", "limited": true or false, "reachable": true or false, "proxy": "host:port","proxyrandomizecredentials": true or false }, ...], "relayfee": n.nn., "localaddresses": [{ "address": "ip", "port": n, "score": n }, ...], "localservices": "services"}</code>
<code>[{"addr": "host:port", "services": "00000001", "lastrecv": n, "lastsend": n, "bytessent": n, "bytesrecv": n, "conntime": n, "pingtime": n, "pingwait": n, "version": n, "subver": "useragent", "inbound": true_or_false, "startingheight": n, "currentheight": n, "syncnode": true_or_false }, ...]</code>
:Returns an array of hashes for all of the transactions currently in the memory pool.
:The <code>verbose</code> flag specifies that each transaction is returned as a JSON object.
|-
!Notes
|Since dcrd does not perform any mining, the priority related fields <code>startingpriority</code> and <code>currentpriority</code> that are available when the <code>verbose</code> flag is set are always 0.
|-
!Returns (verbose=false)
|
<code>(json array of string)</code>
: <code>transactionhash</code>: <code>(string)</code> hash of the transaction.
<code>["transactionhash", ...]</code>
|-
!Returns (verbose=true)
|
<code>(json object)</code>
: <code>size</code>: <code>(numeric)</code> transaction size in bytes.
: <code>fee</code> : <code>(numeric)</code> transaction fee in DCR.
: <code>time</code>: <code>(numeric)</code> local time transaction entered pool in seconds since 1 Jan 1970 GMT.
: <code>height</code>: <code>(numeric)</code> block height when transaction entered the pool.
: <code>startingpriority</code>: <code>(numeric)</code> priority when transaction entered the pool.
: <code>currentpriority</code>: <code>(numeric)</code> current priority.
: <code>depends</code>: <code>(json array)</code> unconfirmed transactions used as inputs for this transaction.
: <code>transactionhash</code>: <code>(string)</code> hash of the parent transaction.
<code>{"transactionhash": {"size": n,"fee" : n, "time": n,"height": n, "startingpriority": n, "currentpriority": n, "depends": ["transactionhash", ...]}, ...}</code>
# <code>data</code>: <code>(string, optional)</code> The hex
|-
!Description
|Returns information about a transaction given its hash.
|-
!Notes
|Since dcrd does not have the wallet integrated to provide payment addresses, dcrd must be configured via the <code>--miningaddr</code> option to provide which payment addresses to pay created blocks to for this RPC to function.
|-
!Returns (data not specified)
|
<code>(json object)</code>
: <code>data</code>: <code>(string)</code> hex-encoded block data
# <code>command</code>: <code>(string, required)</code> <code>connect</code> to add a peer (defaults to temporary), <code>remove</code> to remove a persistent peer, or <code>disconnect</code> to remove all matching non-persistent peers.
# <code>peer</code>: <code>(string, required)</code> ip address and port, or ID of the peer to operate on.
# <code>connection type</code>: <code>(string)</code> <code>perm</code> indicates the peer should be added as a permanent peer, <code>temp</code> indicates a connection should only be attempted once.
# <code>verbose</code>: <code>(int, optional, default=true)</code> specifies the transaction is returned as a JSON object instead of hex-encoded string.
# <code>skip</code>: <code>(int, optional, default=0)</code> the number of leading transactions to leave out of the final response.
# <code>count</code>: <code>(int, optional, default=100)</code> the maximum number of transactions to return.
# <code>vinextra</code>: <code>(int, optional, default=0)</code> specify that extra data from previous output will be returned in vin.
|Returns raw data for transactions involving the passed address. Returned transactions are pulled from both the database, and transactions currently in the mempool. Transactions pulled from the mempool will have the <code>"confirmations"</code> field set to 0. Usage of this RPC requires the optional <code>--addrindex</code> flag to be activated, otherwise all responses will simply return with an error stating the address index has not yet been built up. Similarly, until the address index has caught up with the current best height, all requests will return an error response in order to avoid serving stale data.
|NOTE: Since dcrd does not have the wallet integrated to provide payment addresses, dcrd must be configured via the <code>--miningaddr</code> option to provide which payment addresses to pay created blocks to for this RPC to function.
: <code>feeinfomempool</code>: <code>(json object)</code> Ticket fee information for all tickets in the mempool (units: DCR/kB).
:: <code>number</code>: <code>(numeric)</code> Number of transactions in the mempool.
:: <code>min</code>: <code>(numeric)</code> Minimum transaction fee in the mempool.
:: <code>max</code>: <code>(numeric)</code> Minimum transaction fee in the mempool.
:: <code>mean</code>: <code>(numeric)</code> Mean of transaction fees in the mempool.
:: <code>median</code>: <code>(numeric)</code> Median of transaction fees in the mempool.
:: <code>stddev</code>: <code>(numeric)</code> Standard deviation of transaction fees in the mempool.
: <code>feeinfoblocks</code>: <code>(json array)</code> Ticket fee information for a given list of blocks descending from the chain tip (units: DCR/kB).
:: <code>height</code>: <code>(numeric)</code> Height of the block.
:: <code>number</code>: <code>(numeric)</code> Number of transactions in the block.
:: <code>min</code>: <code>(numeric)</code> Minimum transaction fee in the block.
:: <code>max</code>: <code>(numeric)</code> Minimum transaction fee in the block.
:: <code>mean</code>: <code>(numeric)</code> Mean of transaction fees in the block.
:: <code>median</code>: <code>(numeric)</code> Median of transaction fees in the block.
:: <code>stddev</code>: <code>(numeric)</code> Standard deviation of transaction fees in the block.
: <code>feeinfowindows</code>: <code>(json array)</code> Ticket fee information for a window period where the stake difficulty was the same (units: DCR/kB).
:: <code>startheight</code>: <code>(numeric)</code> First block in the window (inclusive).
:: <code>endheight</code>: <code>(numeric)</code> Last block in the window (exclusive).
:: <code>number</code>: <code>(numeric)</code> Number of transactions in the window.
:: <code>min</code>: <code>(numeric)</code> Minimum transaction fee in the window.
:: <code>max</code>: <code>(numeric)</code> Minimum transaction fee in the window.
:: <code>mean</code>: <code>(numeric)</code> Mean of transaction fees in the window.
:: <code>median</code>: <code>(numeric)</code> Median of transaction fees in the window.
:: <code>stddev</code>: <code>(numeric)</code> Standard deviation of transaction fees in the window.
# <code>blocks</code>: <code>(numeric)</code> The number of blocks to calculate transaction fees for, starting from the end of the tip moving backwards.
# <code>rangestart</code>: <code>(numeric)</code> The start height of the block range to calculate transaction fees for.
# <code>rangeend</code>: <code>(numeric)</code> The end height of the block range to calculate transaction fees for.
# <code>checklevel</code>: <code>(numeric, optional, default=3)</code> how in-depth the verification is (0=least amount of checks, higher levels are clamped to the highest supported level).
# <code>numblocks</code>: <code>(numeric, optional, default=288)</code> the number of blocks starting from the end of the chain to verify.
:Verifies the block chain database. The actual checks performed by the <code>checklevel</code> parameter is implementation specific.
:For dcrd this is:
:: <code>checklevel=0</code> - Look up each block and ensure it can be loaded from the database.
:: <code>checklevel=1</code> - Perform basic context-free sanity checks on each block.
|-
!Notes
|dcrd currently only supports <code>checklevel</code> 0 and 1, but the default is still 3 for compatibility. Per the information in the Parameters section above, higher levels are automatically clamped to the highest supported level, so this means the default is effectively 1 for dcrd.
The following is an overview of the RPC method requests available exclusively to Websocket clients. All of these RPC methods are available to the limited
user. Click the method name for further details such as parameter and return information.
{|
!Method
!Description
!Notifications
|-
|[[#authenticate|authenticate]]
|Authenticate the connection against the username and passphrase configured for the RPC server. NOTE: This is only required if an HTTP Authorization header is not being used.
|None
|-
|[[#notifyblocks|notifyblocks]]
|Send notifications when a block is connected or disconnected from the best chain.
|[[#blockconnected|blockconnected]] and [[#blockdisconnected|blockdisconnected]]
|-
|[[#stopnotifyblocks|stopnotifyblocks]]
|Cancel registered notifications for whenever a block is connected or disconnected from the main (best) chain.
|None
|-
|[[#notifyreceived|notifyreceived]]
|Send notifications when a txout spends to an address.
|[[#recvtx|recvtx]] and [[#redeemingtx|redeemingtx]]
|-
|[[#stopnotifyreceived|stopnotifyreceived]]
|Cancel registered notifications for when a txout spends to any of the passed addresses.
|None
|-
|[[#notifyspent|notifyspent]]
|Send notification when a txout is spent.
|[[#redeemingtx|redeemingtx]]
|-
|[[#stopnotifyspent|stopnotifyspent]]
|Cancel registered spending notifications for each passed outpoint.
|None
|-
|[[#loadtxfilter|loadtxfilter]]
|Load, add to, or reload a websocket client's transaction filter for mempool transactions, new blocks and rescanblocks.
|[[#relevanttxaccepted|relevanttxaccepted]]
|-
|[[#rescan|rescan]]
|Rescan block chain for transactions to addresses and spent transaction outpoints.
|[[#recvtx|recvtx]], [[#redeemingtx|redeemingtx]], [[#rescanprogress|rescanprogress]], and [[#rescanfinished|rescanfinished]]
|-
|[[#notifynewtransactions|notifynewtransactions]]
|Send notifications for all new transactions as they are accepted into the mempool.
|[[#txaccepted|txaccepted]] or [[#txacceptedverbose|txacceptedverbose]]
|Authenticate the connection against the username and password configured for the RPC server. Invoking any other method before authenticating with this command will close the connection.
NOTE: This is only required if an HTTP Authorization header is not being used.
|[[#blockconnected|blockconnected]] and [[#blockdisconnected|blockdisconnected]]
|-
!Parameters
|None
|-
!Description
|Request notifications for whenever a block is connected or disconnected from the main (best) chain. NOTE: If a client subscribes to both block and transaction (recvtx and redeemingtx) notifications, the blockconnected notification will be sent after all transaction notifications have been sent. This allows clients to know when all relevant transactions for a block have been received.
|-
!Returns
|Nothing
|}
----
====stopnotifyblocks====
{|
!Method
|stopnotifyblocks
|-
!Notifications
|None
|-
!Parameters
|None
|-
!Description
|Cancel sending notifications for whenever a block is connected or disconnected from the main (best) chain.
|-
!Returns
|Nothing
|}
----
====notifyreceived====
{|
!Method
|notifyreceived
|-
!Notifications
|[[#recvtx|recvtx]] and [[#redeemingtx|redeemingtx]]
: <code>decredaddress</code>: <code>(string)</code> the Decred address.
<code>["decredaddress", ...]</code>
|-
!Description
|Send a recvtx notification when a transaction added to mempool or appears in a newly-attached block contains a txout pkScript sending to any of the passed addresses. Matching outpoints are automatically registered for redeemingtx notifications.
: <code>hash</code>: <code>(string)</code> the hex-encoded bytes of the outpoint hash.
: <code>index</code>: <code>(numeric)</code> the txout index of the outpoint.
<code>[{"hash":"data", "index":n }, ...]</code>
|-
!Description
|Send a redeemingtx notification when a transaction spending an outpoint appears in mempool (if relayed to this dcrd instance) and when such a transaction first appears in a newly-attached block.
|[[#txaccepted|txaccepted]] or [[#txacceptedverbose|txacceptedverbose]]
|-
!Parameters
|
# <code>verbose</code>: <code>(boolean, optional, default=false)</code> specifies which type of notification to receive. If verbose is true, then the caller receives [[#txacceptedverbose|txacceptedverbose]], otherwise the caller receives [[#txaccepted|txaccepted]]
|-
!Description
|Send either a [[#txaccepted|txaccepted]] or a [[#txacceptedverbose|txacceptedverbose]] notification when a new transaction is accepted into the mempool.
|-
!Returns
|Nothing
|}
----
====stopnotifynewtransactions====
{|
!Method
|stopnotifynewtransactions
|-
!Notifications
|None
|-
!Parameters
|None
|-
!Description
|Stop sending either a [[#txaccepted|txaccepted]] or a [[#txacceptedverbose|txacceptedverbose]] notification when a new transaction is accepted into the mempool.
|-
!Returns
|Nothing
|}
----
====session====
{|
!Method
|session
|-
!Notifications
|None
|-
!Parameters
|None
|-
!Description
|Return a JSON object with details regarding a websocket client's current connection to the RPC server. This currently only includes the session ID, a random unsigned 64-bit integer that is created for each newly connected client. Session IDs may be used to verify that the current connection was not lost and subsequently reestablished.
|-
!Returns
|
<code>(json object)</code>
: <code>sessionid</code>: <code>(numeric)</code> the session ID.
<code>{"sessionid": n}</code>
|-
!Example Return
|<code>{"sessionid": 67089679842}</code>
|}
==7. Notifications (Websocket-specific)==
dcrd uses standard JSON-RPC notifications to notify clients of changes, rather than requiring clients to poll dcrd for updates. JSON-RPC notifications are a subset of requests, but do not contain an ID. The notification type is categorized by the <code>method</code> field and additional details are sent as a JSON array in the <code>params</code> field.
===7.1 Notification Overview===
The following is an overview of the JSON-RPC notifications used for Websocket connections. Click the method name for further details of the context(s) in which they are sent and their parameters.
{|
!Method
!Description
!Request
|-
|[[#blockconnected|blockconnected]]
|Block connected to the main chain.
|[[#notifyblocks|notifyblocks]]
|-
|[[#blockdisconnected|blockdisconnected]]
|Block disconnected from the main chain.
|[[#notifyblocks|notifyblocks]]
|-
|[[#recvtx|recvtx]]
|Processed a transaction output spending to a wallet address.
|[[#notifyreceived|notifyreceived]] and [[#rescan|rescan]]
|-
|[[#redeemingtx|redeemingtx]]
|Processed a transaction that spends a registered outpoint.
|[[#notifyspent|notifyspent]] and [[#rescan|rescan]]
|-
|[[#txaccepted|txaccepted]]
|Received a new transaction after requesting simple notifications of all new transactions accepted into the mempool.
|[[#notifynewtransactions|notifynewtransactions]]
|-
|[[#txacceptedverbose|txacceptedverbose]]
|Received a new transaction after requesting verbose notifications of all new transactions accepted into the mempool.
|[[#notifynewtransactions|notifynewtransactions]]
|-
|[[#rescanprogress|rescanprogress]]
|A rescan operation that is underway has made progress.
|[[#rescan|rescan]]
|-
|[[#rescanfinished|rescanfinished]]
|A rescan operation has completed.
|[[#rescan|rescan]]
|}
===7.2 Notification Details===
====blockconnected====
{|
!Method
|blockconnected
|-
!Request
|[[#notifyblocks|notifyblocks]]
|-
!Parameters
|
# <code>BlockHash</code>: <code>(string)</code> hex-encoded bytes of the attached block hash.
# <code>BlockHeight</code>: <code>(numeric)</code> height of the attached block.
# <code>BlockTime</code>: <code>(numeric)</code> unix time of the attached block.
|-
!Description
|Notifies when a block has been added to the main chain. Notification is sent to all connected clients.
|-
!Example
|Example blockconnected notification for mainnet block 280330:
|[[#rescan|rescan]] or [[#notifyreceived|notifyreceived]]
|-
!Parameters
|
# <code>Transaction</code>: <code>(string)</code> full transaction encoded as a hex string.
# <code>Block details</code>: <code>(object, optional)</code> details about a block and the index of the transaction within a block, if the transaction is mined.
|-
!Description
|Notifies a client when a transaction is processed that contains at least a single output with a pkScript sending to a requested address. If multiple outputs send to requested addresses, a single notification is sent. If a mempool (unmined) transaction is processed, the block details object (second parameter) is excluded.
|-
!Example
|Example recvtx notification for mainnet transaction <code>61d3696de4c888730cbe06b0ad8ecb6d72d6108e893895aa9bc067bd7eba3fad</code> when processed by mempool:
|[[#notifyspent|notifyspent]] and [[#rescan|rescan]]
|-
!Parameters
|
# <code>Transaction</code>: <code>(string)</code> full transaction encoded as a hex string.
# <code>Block details</code>: <code>(object, optional)</code> details about a block and the index of the transaction within a block, if the transaction is mined.
|Example redeemingtx notification for mainnet outpoint <code>61d3696de4c888730cbe06b0ad8ecb6d72d6108e893895aa9bc067bd7eba3fad:0</code> after being spent by transaction <code>4ad0c16ac973ff675dec1f3e5f1273f1c45be2a63554343f21b70240a1e43ece</code>:
* [[#811-using-getblockcount-to-retrieve-the-current-block-height|Using getblockcount to Retrieve the Current Block Height]]
* [[#812-using-getblock-to-retrieve-the-genesis-block|Using getblock to Retrieve the Genesis Block]]
* [[#813-using-notifyblocks-to-receive-blockconnected-and-blockdisconnected-notifications-websocket-specific|Using notifyblocks to Receive blockconnected and blockdisconnected Notifications (Websocket-specific)]]
====8.1.1 Using getblockcount to Retrieve the Current Block Height====
The following is an example Go application which uses the
[https://github.com/decred/dcrd/tree/master/rpcclient rpcclient] package to connect with
a dcrd instance via Websockets, issues [[#getblockcount|getblockcount]] to
retrieve the current block height, and displays it.
