Websockets are the preferred transport for btcd RPC and are used by applications
such as [btcwallet](https://github.com/btcsuite/btcwallet) for inter-process
communication with btcd. The websocket connection endpoint for btcd is
`wss://your_ip_or_domain:8334/ws`.
In addition to the [standard API](#Methods), an [extension API](#WSExtMethods)
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 btcwallet.
While the [standard API](#Methods) is stable, the
[Websocket extension API](#WSExtMethods) should be considered a work in
progress, incomplete, and susceptible to changes (both additions and removals).
The original bitcoind/bitcoin-qt JSON-RPC API documentation is available at [https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list](https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list)
<aname="HttpPostVsWebsockets"/>
### 2. HTTP POST Versus Websockets
The btcd RPC server supports both [HTTP POST](http://en.wikipedia.org/wiki/POST_%28HTTP%29)
requests and the preferred [Websockets](http://en.wikipedia.org/wiki/WebSocket).
All of the [standard](#Methods) and [extension](#ExtensionMethods) methods
described in this documentation can be accessed through both. As the name
indicates, the [Websocket-specific extension](#WSExtMethods) methods can only be
accessed when connected via Websockets.
As mentioned in the [overview](#Overview), the websocket connection endpoint for
btcd is `wss://your_ip_or_domain:8334/ws`.
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|No|Yes|
|Supports asynchronous notifications|No|Yes|
|Scales well with large numbers of requests|No|Yes|
<aname="Authentication"/>
### 3. Authentication
<aname="AuthenticationOverview"/>
**3.1 Authentication Overview**<br/>
The following authentication details are needed before establishing a connection
to a btcd RPC server:
* **rpcuser** is the username that the btcd RPC server is configured with
* **rpcpass** is the password that the btcd RPC server is configured with
* **rpccert** is the PEM-encoded X.509 certificate (public key) that the btcd
server is configured with. It is automatically generated by btcd and placed
in the btcd home directory (which is typically `%LOCALAPPDATA%\Btcd` on
Windows and `~/.btcd` on POSIX-like OSes)
**NOTE:** As mentioned above, btcd is secure by default which means the RPC
server is not running unless configured with a **rpcuser** and **rpcpass** and
uses TLS authentication for all connections.
Depending on which connection transaction you are using, you can choose one of
two, mutually exclusive, methods.
- [Use HTTP Authorization Header](#HTTPAuth) - HTTP POST requests and Websockets
- [Use the JSON-RPC "authenticate" command](#JSONAuth) - Websockets only
<aname="HTTPAuth"/>
**3.2 HTTP Basic Access Authentication**<br/>
The btcd RPC server uses HTTP [basic access authentication](http://en.wikipedia.org/wiki/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.
While the HTTP basic access authentication method is the preferred method, the
ability to set HTTP headers from websockets is not always available. In that
case, you will need to use the [authenticate](#authenticate) JSON-RPC method.
The [authenticate](#authenticate) command must be the first command sent after
connecting to the websocket. Sending any other commands before authenticating,
supplying invalid credentials, or attempting to authenticate again when already
authenticated will cause the websocket to be closed immediately.
<aname="CLIUtil"/>
### 4. Command-line Utility
btcd comes with a separate utility named `btcctl` which can be used to issue
these RPC commands via HTTP POST requests to btcd after configuring it with the
information in the [Authentication](#Authentication) section above. It can also
be used to communicate with any server/daemon/service which provides a JSON-RPC
API compatible with the original bitcoind/bitcoin-qt client.
<aname="Methods"/>
### 5. Standard Methods
<aname="MethodOverview"/>
**5.1 Method Overview**<br/>
The following is an overview of the RPC methods and their current status. Click
the method name for further details such as parameter and return information.
|#|Method|Description|
|---|------|-----------|
|1|[addnode](#addnode)|Attempts to add or remove a persistent peer.|
|2|[createrawtransaction](#createrawtransaction)|Returns a new transaction spending the provided inputs and sending to the provided addresses.|
|3|[decoderawtransaction](#decoderawtransaction)|Returns a JSON object representing the provided serialized, hex-encoded transaction.|
|4|[decodescript](#decodescript)|Returns a JSON object with information about the provided hex-encoded script.|
|5|[getaddednodeinfo](#getaddednodeinfo)|Returns information about manually added (persistent) peers.|
|6|[getbestblockhash](#getbestblockhash)|Returns the hash of the of the best (most recent) block in the longest block chain.|
|7|[getblock](#getblock)|Returns information about a block given its hash.|
|8|[getblockcount](#getblockcount)|Returns the number of blocks in the longest block chain.|
|9|[getblockhash](#getblockhash)|Returns hash of the block in best block chain at the given height.|
|10|[getconnectioncount](#getconnectioncount)|Returns the number of active connections to other peers.|
|11|[getdifficulty](#getdifficulty)|Returns the proof-of-work difficulty as a multiple of the minimum difficulty.|
|12|[getgenerate](#getgenerate)|Return if the server is set to generate coins (mine) or not.|
|13|[gethashespersec](#gethashespersec)|Returns a recent hashes per second performance measurement while generating coins (mining).|
|14|[getinfo](#getinfo)|Returns a JSON object containing various state info.|
|15|[getmininginfo](#getmininginfo)|Returns a JSON object containing mining-related information.|
|16|[getnettotals](#getnettotals)|Returns a JSON object containing network traffic statistics.|
|17|[getnetworkhashps](#getnetworkhashps)|Returns the estimated network hashes per second for the block heights provided by the parameters.|
|18|[getpeerinfo](#getpeerinfo)|Returns information about each connected network peer as an array of json objects.|
|19|[getrawmempool](#getrawmempool)|Returns an array of hashes for all of the transactions currently in the memory pool.|
|20|[getrawtransaction](#getrawtransaction)|Returns information about a transaction given its hash.|
|21|[getwork](#getwork)|Returns formatted hash data to work on or checks and submits solved data.<br/><fontcolor="orange">NOTE: Since btcd does not have the wallet integrated to provide payment addresses, btcd must be configured via the `--miningaddr` option to provide which payment addresses to pay created blocks to for this RPC to function.</font>|
|22|[help](#help)|Returns a list of all commands or help for a specified command.|
|23|[ping](#ping)|Queues a ping to be sent to each connected peer.|
|24|[sendrawtransaction](#sendrawtransaction)|Submits the serialized, hex-encoded transaction to the local peer and relays it to the network.<br/><fontcolor="orange">btcd does not yet implement the `allowhighfees` parameter, so it has no effect</font>|
|25|[setgenerate](#setgenerate) |Set the server to generate coins (mine) or not.<br/>NOTE: Since btcd does not have the wallet integrated to provide payment addresses, btcd must be configured via the `--miningaddr` option to provide which payment addresses to pay created blocks to for this RPC to function.|
|26|[stop](#stop)|Shutdown btcd.|
|27|[submitblock](#submitblock)|Attempts to submit a new serialized, hex-encoded block to the network.|
|28|[validateaddress](#validateaddress)|Verifies the given address is valid. NOTE: Since btcd does not have a wallet integrated, btcd will only return whether the address is valid or not.|
|29|[verifychain](#verifychain)|Verifies the block chain database.|
<aname="MethodDetails"/>
**5.2 Method Details**<br/>
<aname="addnode"/>
| | |
|---|---|
|Method|addnode|
|Parameters|1. peer (string, required) - ip address and port of the peer tooperate on<br/>2. command (string, required) - `add` to add a persistent peer, `remove` to remove a persistent peer, or `onetry` to try a single connection to a peer|
|Description|Attempts to add or remove a persistent peer.|
|Returns|Nothing|
[Return to Overview](#MethodOverview)<br/>
***
<aname="createrawtransaction"/>
| | |
|---|---|
|Method|createrawtransaction|
|Parameters|1. transaction inputs (JSON array, required) - json array of json objects<br/>`[`<br/> `{`<br/> `"txid": "hash", (string, required) the hash of the input transaction`<br/> `"vout": n (numeric, required) the specific output of the input transaction to redeem`<br/> `}, ...`<br/>`]`<br/>2. addresses and amounts (JSON object, required) - json object with addresses as keys and amounts as values<br/>`{`<br/> `"address": n.nnn (numeric, required) the address to send to as the key and the amount in BTC as the value`<br/> `, ...`<br/>`}`|
|Description|Returns a new transaction spending the provided inputs and sending to the provided addresses.<br/>The transaction inputs are not signed in the created transaction.<br/>The `signrawtransaction` RPC command provided by wallet must be used to sign the resulting transaction.|
|Returns|`"transaction" (string) hex-encoded bytes of the serialized transaction`|
|Example Parameters|1. transaction inputs `[{"txid":"e6da89de7a6b8508ce8f371a3d0535b04b5e108cb1a6e9284602d3bfd357c018","vout":1}]`<br/>2. addresses and amounts `{"13cgrTP7wgbZYWrY9BZ22BV6p82QXQT3nY": 0.49213337}`|
|Example Return|`010000000118c057d3bfd3024628e9a6b18c105e4bb035053d1a378fce08856b7ade89dae6010000`<br/>`0000ffffffff0199efee02000000001976a9141cb013db35ecccc156fdfd81d03a11c51998f99388`<br/>`ac00000000`<br/><fontcolor="orange">**Newlines added for display purposes. The actual return does not contain newlines.**</font>|
[Return to Overview](#MethodOverview)<br/>
***
<aname="decoderawtransaction"/>
| | |
|---|---|
|Method|decoderawtransaction|
|Parameters|1. data (string, required) - serialized, hex-encoded transaction|
|Description|Returns a JSON object representing the provided serialized, hex-encoded transaction.|
|Returns|`{ (json object)`<br/> `"txid": "hash", (string) the hash of the transaction`<br/> `"version": n, (numeric) the transaction version`<br/> `"locktime": n, (numeric) the transaction lock time`<br/> `"vin": [ (array of json objects) the transaction inputs as json objects`<br/> <fontcolor="orange">For coinbase transactions:</font><br/> `{ (json object)`<br/> `"coinbase": "data", (string) the hex-dencoded bytes of the signature script`<br/> `"sequence": n, (numeric) the script sequence number`<br/> `}`<br/> <fontcolor="orange">For non-coinbase transactions:</font><br/> `{ (json object)`<br/> `"txid": "hash", (string) the hash of the origin transaction`<br/> `"vout": n, (numeric) the index of the output being redeemed from the origin transaction`<br/> `"scriptSig": { (json object) the signature script used to redeem the origin transaction`<br/> `"asm": "asm", (string) disassembly of the script`<br/> `"hex": "data", (string) hex-encoded bytes of the script`<br/> `}`<br/> `"sequence": n, (numeric) the script sequence number`<br/> `}, ...`<br/> `]`<br/> `"vout": [ (array of json objects) the transaction outputs as json objects`<br/> `{ (json object)`<br/> `"value": n, (numeric) the value in BTC`<br/> `"n": n, (numeric) the index of this transaction output`<br/> `"scriptPubKey": { (json object) the public key script used to pay coins`<br/> `"asm": "asm", (string) disassembly of the script`<br/> `"hex": "data", (string) hex-encoded bytes of the script`<br/> `"reqSigs": n, (numeric) the number of required signatures`<br/> `"type": "scripttype" (string) the type of the script (e.g. 'pubkeyhash')`<br/> `"addresses": [ (json array of string) the bitcoin addresses associated with this output`<br/> `"bitcoinaddress", (string) the bitcoin address`<br/> `...`<br/> `]`<br/> `}`<br/> `}, ...`<br/> `]`<br/>`}`|
|Description|Returns a JSON object with information about the provided hex-encoded script.|
|Returns|`{ (json object)`<br/> `"asm": "asm", (string) disassembly of the script`<br/> `"reqSigs": n, (numeric) the number of required signatures`<br/> `"type": "scripttype", (string) the type of the script (e.g. 'pubkeyhash')`<br/> `"addresses": [ (json array of string) the bitcoin addresses associated with this script`<br/> `"bitcoinaddress", (string) the bitcoin address`<br/> `...`<br/> `]`<br/> `"p2sh": "scripthash", (string) the script hash for use in pay-to-script-hash transactions`<br/>`}`|
|Parameters|1. dns (boolean, required) - specifies whether the returned data is a JSON object including DNS and connection information, or just a list of added peers<br/>2. node (string, optional) - only return information about this specific peer instead of all added peers.|
|Description|Returns information about manually added (persistent) peers.|
|Returns (dns=false)|`["ip:port", ...]`|
|Returns (dns=true)|`[ (json array of objects)`<br/> `{ (json object)`<br/> `"addednode": "ip_or_domain", (string) the ip address or domain of the added peer`<br/> `"connected": true or false, (boolean) whether or not the peer is currently connected`<br/> `"addresses": [ (json array or objects) DNS lookup and connection information about the peer`<br/> `{ (json object)`<br/> `"address": "ip", (string) the ip address for this DNS entry`<br/> `"connected": "inbound/outbound/false" (string) the connection 'direction' (if connected)`<br/> `}, ...`<br/> `]`<br/> `}, ...`<br/>`]`|
|Parameters|1. block hash (string, required) - the hash of the block<br/>2. verbose (boolean, optional, default=true) - specifies the block is returned as a JSON object instead of hex-encoded string<br/>3. verbosetx (boolean, optional, default=false) - specifies that each transaction is returned as a JSON object and only applies if the `verbose` flag is true.<fontcolor="orange">**This parameter is a btcd extension**</font>|
|Description|Returns information about a block given its hash.|
|Returns (verbose=false)|`"data" (string) hex-encoded bytes of the serialized block`|
|Returns (verbose=true, verbosetx=false)|`{ (json object)`<br/> `"hash": "blockhash", (string) the hash of the block (same as provided)`<br/> `"confirmations": n, (numeric) the number of confirmations`<br/> `"size": n, (numeric) the size of the block`<br/> `"height": n, (numeric) the height of the block in the block chain`<br/> `"version": n, (numeric) the block version`<br/> `"merkleroot": "hash", (string) root hash of the merkle tree`<br/> `"tx": [ (json array of string) the transaction hashes`<br/> `"transactionhash", (string) hash of the parent transaction`<br/> `...`<br/> `]`<br/> `"time": n, (numeric) the block time in seconds since 1 Jan 1970 GMT`<br/> `"nonce": n, (numeric) the block nonce`<br/> `"bits", n, (numeric) the bits which represent the block difficulty`<br/> `difficulty: n.nn, (numeric) the proof-of-work difficulty as a multiple of the minimum difficulty`<br/> `"previousblockhash": "hash", (string) the hash of the previous block`<br/> `"nextblockhash": "hash", (string) the hash of the next block`<br/>`}`|
|Returns (verbose=true, verbosetx=true)|`{ (json object)`<br/> `"hash": "blockhash", (string) the hash of the block (same as provided)`<br/> `"confirmations": n, (numeric) the number of confirmations`<br/> `"size": n, (numeric) the size of the block`<br/> `"height": n, (numeric) the height of the block in the block chain`<br/> `"version": n, (numeric) the block version`<br/> `"merkleroot": "hash", (string) root hash of the merkle tree`<br/> `"rawtx": [ (array of json objects) the transactions as json objects`<br/> `(see getrawtransaction json object details)`<br/> `]`<br/> `"time": n, (numeric) the block time in seconds since 1 Jan 1970 GMT`<br/> `"nonce": n, (numeric) the block nonce`<br/> `"bits", n, (numeric) the bits which represent the block difficulty`<br/> `difficulty: n.nn, (numeric) the proof-of-work difficulty as a multiple of the minimum difficulty`<br/> `"previousblockhash": "hash", (string) the hash of the previous block`<br/> `"nextblockhash": "hash", (string) the hash of the next block`<br/>`}`|
|Example Return (verbose=false)|`"010000000000000000000000000000000000000000000000000000000000000000000000`<br/>`3ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49`<br/>`ffff001d1dac2b7c01010000000100000000000000000000000000000000000000000000`<br/>`00000000000000000000ffffffff4d04ffff001d0104455468652054696d65732030332f`<br/>`4a616e2f32303039204368616e63656c6c6f72206f6e206272696e6b206f66207365636f`<br/>`6e64206261696c6f757420666f722062616e6b73ffffffff0100f2052a01000000434104`<br/>`678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f`<br/>`4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac00000000"`<br/><fontcolor="orange">**Newlines added for display purposes. The actual return does not contain newlines.**</font>|
|Description|Returns the number of active connections to other peers|
|Returns|numeric|
|Example Return|`8`|
[Return to Overview](#MethodOverview)<br/>
***
<aname="getdifficulty"/>
| | |
|---|---|
|Method|getdifficulty|
|Parameters|None|
|Description|Returns the proof-of-work difficulty as a multiple of the minimum difficulty.|
|Returns|numeric|
|Example Return|`1180923195.260000`|
[Return to Overview](#MethodOverview)<br/>
***
<aname="getgenerate"/>
| | |
|---|---|
|Method|getgenerate|
|Parameters|None|
|Description|Return if the server is set to generate coins (mine) or not.|
|Returns|`false` (boolean)|
[Return to Overview](#MethodOverview)<br/>
***
<aname="gethashespersec"/>
| | |
|---|---|
|Method|gethashespersec|
|Parameters|None|
|Description|Returns a recent hashes per second performance measurement while generating coins (mining).|
|Returns|`0` (numeric)|
[Return to Overview](#MethodOverview)<br/>
***
<aname="getinfo"/>
| | |
|---|---|
|Method|getinfo|
|Parameters|None|
|Description|Returns a JSON object containing various state info.|
|Notes|NOTE: Since btcd does NOT contain wallet functionality, wallet-related fields are not returned. See getinfo in btcwallet for a version which includes that information.|
|Returns|`{ (json object)`<br/> `"version": n, (numeric) the version of the server`<br/> `"protocolversion": n, (numeric) the latest supported protocol version`<br/> `"blocks": n, (numeric) the number of blocks processed`<br/> `"timeoffset": n, (numeric) the time offset`<br/> `"connections": n, (numeric) the number of connected peers`<br/> `"proxy": "host:port", (string) the proxy used by the server`<br/> `"difficulty": n.nn, (numeric) the current target difficulty`<br/> `"testnet": true or false, (boolean) whether or not server is using testnet`<br/> `"relayfee": n.nn, (numeric) the minimum relay fee for non-free transactions in BTC/KB`<br/>`}`|
|Description|Returns a JSON object containing mining-related information.|
|Returns|`{ (json object)`<br/> `"blocks": n, (numeric) latest best block`<br/> `"currentblocksize": n, (numeric) size of the latest best block`<br/> `"currentblocktx": n, (numeric) number of transactions in the latest best block`<br/> `"difficulty": n.nn, (numeric) current target difficulty`<br/> `"errors": "errors", (string) any current errors`<br/> `"generate": true or false, (boolean) whether or not server is set to generate coins`<br/> `"genproclimit": n, (numeric) number of processors to use for coin generation (-1 when disabled)`<br/> `"hashespersec": n, (numeric) recent hashes per second performance measurement while generating coins`<br/> `"networkhashps": n, (numeric) estimated network hashes per second for the most recent blocks`<br/> `"pooledtx": n, (numeric) number of transactions in the memory pool`<br/> `"testnet": true or false, (boolean) whether or not server is using testnet`<br/>`}`|
|Description|Returns a JSON object containing network traffic statistics.|
|Returns|`{`<br/> `"totalbytesrecv": n, (numeric) total bytes received`<br/> `"totalbytessent": n, (numeric) total bytes sent`<br/> `"timemillis": n (numeric) number of milliseconds since 1 Jan 1970 GMT`<br/>`}`|
|Parameters|1. blocks (numeric, optional, default=120) - The number of blocks, or -1 for blocks since last difficulty change<br/>2. height (numeric, optional, default=-1) - 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.|
|Returns|numeric|
|Example Return|`6573971939`|
[Return to Overview](#MethodOverview)<br/>
***
<aname="getpeerinfo"/>
| | |
|---|---|
|Method|getpeerinfo|
|Parameters|None|
|Description|Returns data about each connected network peer as an array of json objects.|
|Returns|`[`<br/> `{`<br/> `"addr": "host:port", (string) the ip address and port of the peer`<br/> `"services": "00000001", (string) the services supported by the peer`<br/> `"lastrecv": n, (numeric) time the last message was received in seconds since 1 Jan 1970 GMT`<br/> `"lastsend": n, (numeric) time the last message was sent in seconds since 1 Jan 1970 GMT`<br/> `"bytessent": n, (numeric) total bytes sent`<br/> `"bytesrecv": n, (numeric) total bytes received`<br/> `"conntime": n, (numeric) time the connection was made in seconds since 1 Jan 1970 GMT`<br/> `"pingtime": n, (numeric) number of microseconds the last ping took`<br/> `"pingwait": n, (numeric) number of microseconds a queued ping has been waiting for a response`<br/> `"version": n, (numeric) the protocol version of the peer`<br/> `"subver": "useragent", (string) the user agent of the peer`<br/> `"inbound": true_or_false, (boolean) whether or not the peer is an inbound connection`<br/> `"startingheight": n, (numeric) the latest block height the peer knew about when the connection was established`<br/> `"syncnode": true_or_false, (boolean) whether or not the peer is the sync peer`<br/> `}, ...`<br/>`]`|
|Parameters|1. transaction hash (string, required) - the hash of the transaction<br/>2. verbose (int, optional, default=0) - specifies the transaction is returned as a JSON object instead of hex-encoded string|
|Description|Returns information about a transaction given its hash.|
|Returns (verbose=0)|`"data" (string) hex-encoded bytes of the serialized transaction`|
|Returns (verbose=1)|`{ (json object)`<br/> `"hex": "data", (string) hex-encoded transaction`<br/> `"txid": "hash", (string) the hash of the transaction`<br/> `"version": n, (numeric) the transaction version`<br/> `"locktime": n, (numeric) the transaction lock time`<br/> `"vin": [ (array of json objects) the transaction inputs as json objects`<br/> <fontcolor="orange">For coinbase transactions:</font><br/> `{ (json object)`<br/> `"coinbase": "data", (string) the hex-dencoded bytes of the signature script`<br/> `"sequence": n, (numeric) the script sequence number`<br/> `}`<br/> <fontcolor="orange">For non-coinbase transactions:</font><br/> `{ (json object)`<br/> `"txid": "hash", (string) the hash of the origin transaction`<br/> `"vout": n, (numeric) the index of the output being redeemed from the origin transaction`<br/> `"scriptSig": { (json object) the signature script used to redeem the origin transaction`<br/> `"asm": "asm", (string) disassembly of the script`<br/> `"hex": "data", (string) hex-encoded bytes of the script`<br/> `}`<br/> `"sequence": n, (numeric) the script sequence number`<br/> `}, ...`<br/> `]`<br/> `"vout": [ (array of json objects) the transaction outputs as json objects`<br/> `{ (json object)`<br/> `"value": n, (numeric) the value in BTC`<br/> `"n": n, (numeric) the index of this transaction output`<br/> `"scriptPubKey": { (json object) the public key script used to pay coins`<br/> `"asm": "asm", (string) disassembly of the script`<br/> `"hex": "data", (string) hex-encoded bytes of the script`<br/> `"reqSigs": n, (numeric) the number of required signatures`<br/> `"type": "scripttype" (string) the type of the script (e.g. 'pubkeyhash')`<br/> `"addresses": [ (json array of string) the bitcoin addresses associated with this output`<br/> `"bitcoinaddress", (string) the bitcoin address`<br/> `...`<br/> `]`<br/> `}`<br/> `}, ...`<br/> `]`<br/>`}`|
|Example Return (verbose=0)|`"010000000104be666c7053ef26c6110597dad1c1e81b5e6be53d17a8b9d0b34772054bac60000000`<br/>`008c493046022100cb42f8df44eca83dd0a727988dcde9384953e830b1f8004d57485e2ede1b9c8f`<br/>`022100fbce8d84fcf2839127605818ac6c3e7a1531ebc69277c504599289fb1e9058df0141045a33`<br/>`76eeb85e494330b03c1791619d53327441002832f4bd618fd9efa9e644d242d5e1145cb9c2f71965`<br/>`656e276633d4ff1a6db5e7153a0a9042745178ebe0f5ffffffff0280841e00000000001976a91406`<br/>`f1b6703d3f56427bfcfd372f952d50d04b64bd88ac4dd52700000000001976a9146b63f291c295ee`<br/>`abd9aee6be193ab2d019e7ea7088ac00000000`<br/><fontcolor="orange">**Newlines added for display purposes. The actual return does not contain newlines.**</font>|
|Description|Returns information about a transaction given its hash.|
|Notes|<fontcolor="orange">NOTE: Since btcd does not have the wallet integrated to provide payment addresses, btcd must be configured via the `--miningaddr` option to provide which payment addresses to pay created blocks to for this RPC to function.</font>
|Returns (data not specified)|`{ (json object)`<br/> `"data": "hex", (string) hex-encoded block data`<br/> `"hash1": "hex", (string) (DEPRECATED) hex-encoded formatted hash buffer`<br/> `"midstate": "hex", (string) (DEPRECATED) hex-encoded precomputed hash state after hashing first half of the data`<br/> `"target": "hex", (string) the hex-encoded little-endian hash target`<br/>`}`|
|Returns (data specified)|`true` or `false` (boolean)|
|Example Return (data not specified)|`{`<br/> `"data": "00000002c39b5d2b7a1e8f7356a1efce26b24bd15d7d906e85341ef9cec99b6a000000006474f...",`<br/> `"hash1": "00000000000000000000000000000000000000000000000000000000000000000000008000000...",`<br/> `"midstate": "ae4a80fc51476e452de855b4e20d5f33418c50fc7cae3b1ecd5badb819b8a584",`<br/> `"target": "0000000000000000000000000000000000000000000000008c96010000000000",`<br/>`}`|
|Example Return (data specified)|`true`|
[Return to Overview](#MethodOverview)<br/>
***
<aname="help"/>
| | |
|---|---|
|Method|help|
|Parameters|1. command (string, optional) - the command to get help for|
|Description|Returns a list of all commands or help for a specified command.<br/>When no `command` parameter is specified, a list of avaialable commands is returned<br/>When `command` is a valid method, the help text for that method is returned.|
|Returns|string|
|Example Return|getblockcount<br/>Returns a numeric for the number of blocks in the longest block chain.|
[Return to Overview](#MethodOverview)<br/>
***
<aname="ping"/>
| | |
|---|---|
|Method|ping|
|Parameters|None|
|Description|Queues a ping to be sent to each connected peer.<br/>Ping times are provided by [getpeerinfo](#getpeerinfo) via the `pingtime` and `pingwait` fields.|
|Description|Returns an array of hashes for all of the transactions currently in the memory pool.<br/>The `verbose` flag specifies that each transaction is returned as a JSON object.|
|Notes|<fontcolor="orange">Since btcd does not perform any mining, the priority related fields `startingpriority` and `currentpriority` that are available when the `verbose` flag is set are always 0.</font>|
|Returns (verbose=false)|`[ (json array of string)`<br/> `"transactionhash", (string) hash of the transaction`<br/> `...`<br/>`]`|
|Returns (verbose=true)|`{ (json object)`<br/> `"transactionhash": { (json object)`<br/> `"size": n, (numeric) transaction size in bytes`<br/> `"fee" : n, (numeric) transaction fee in bitcoins`<br/> `"time": n, (numeric) local time transaction entered pool in seconds since 1 Jan 1970 GMT`<br/> `"height": n, (numeric) block height when transaction entered the pool`<br/> `"startingpriority": n, (numeric) priority when transaction entered the pool`<br/> `"currentpriority": n, (numeric) current priority`<br/> `"depends": [ (json array) unconfirmed transactions used as inputs for this transaction`<br/> `"transactionhash", (string) hash of the parent transaction`<br/> `...`<br/> `]`<br/> `}, ...`<br/>`}`|
|Parameters|1. generate (boolean, required) - `true` to enable generation, `false` to disable it<br/>2. genproclimit (numeric, optional) - the number of processors (cores) to limit generation to or `-1` for default|
|Description|Set the server to generate coins (mine) or not.|
|Notes|NOTE: Since btcd does not have the wallet integrated to provide payment addresses, btcd must be configured via the `--miningaddr` option to provide which payment addresses to pay created blocks to for this RPC to function.|
|Returns|Nothing|
[Return to Overview](#MethodOverview)<br/>
***
<aname="sendrawtransaction"/>
| | |
|---|---|
|Method|sendrawtransaction|
|Parameters|1. signedhex (string, required) serialized, hex-encoded signed transaction<br/>2. allowhighfees (boolean, optional, default=false) whether or not to allow insanely high fees|
|Description|Submits the serialized, hex-encoded transaction to the local peer and relays it to the network.|
|Notes|<fontcolor="orange">btcd does not yet implement the `allowhighfees` parameter, so it has no effect</font>|
|Returns|`"hash" (string) the hash of the transaction`|
|Parameters|1. data (string, required) serialized, hex-encoded block<br/>2. params (json object, optional, default=nil) this parameter is currently ignored|
|Description|Attempts to submit a new serialized, hex-encoded block to the network.|
|Returns|`{ (json object)`<br/> `"isvalid": true or false, (bool) whether or not the address is valid.`<br/> `"address": "bitcoinaddress", (string) the bitcoin address validated.`<br/>}|
[Return to Overview](#MethodOverview)<br/>
***
<aname="verifychain"/>
| | |
|---|---|
|Method|verifychain|
|Parameters|1. checklevel (numeric, optional, default=3) - how in-depth the verification is (0=least amount of checks, higher levels are clamped to the highest supported level)<br/>2. numblocks (numeric, optional, default=288) - the number of blocks starting from the end of the chain to verify|
|Description|Verifies the block chain database.<br/>The actual checks performed by the `checklevel` parameter is implementation specific. For btcd this is:<br/>`checklevel=0` - Look up each block and ensure it can be loaded from the database.<br/>`checklevel=1` - Perform basic context-free sanity checks on each block.|
|Notes|<fontcolor="orange">Btcd currently only supports `checklevel` 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 btcd.</font>|
|Returns|`true` or `false` (boolean)|
|Example Return|`true`|
[Return to Overview](#MethodOverview)<br/>
<aname="ExtensionMethods"/>
### 6. Extension Methods
<aname="ExtMethodOverview"/>
**6.1 Method Overview**<br/>
The following is an overview of the RPC methods which are implemented by btcd, but not the original bitcoind client. Click the method name for further details such as parameter and return information.
|#|Method|Description|
|---|------|-----------|
|1|[debuglevel](#debuglevel)|Dynamically changes the debug logging level.|
|2|[getbestblock](#getbestblock)|Get block height and hash of best block in the main chain.|None|
|3|[getcurrentnet](#getcurrentnet)|Get bitcoin network btcd is running on.|None|
|Description|Dynamically changes the debug logging level.<br/>The levelspec can either a debug level or of the form `<subsystem>=<level>,<subsystem2>=<level2>,...`<br/>The valid debug levels are `trace`, `debug`, `info`, `warn`, `error`, and `critical`.<br/>The valid subsystems are `AMGR`, `ADXR`, `BCDB`, `BMGR`, `BTCD`, `CHAN`, `DISC`, `PEER`, `RPCS`, `SCRP`, `SRVR`, and `TXMP`.<br/>Additionally, the special keyword `show` can be used to get a list of the available subsystems.|
|Description|Get block height and hash of best block in the main chain.|
|Returns|`{ (json object)`<br/> `"hash": "data", (string) the hex-encoded bytes of the best block hash`<br/> `"height": n (numeric) the block height of the best block`<br/>`}`|
[Return to Overview](#ExtMethodOverview)<br/>
***
<aname="getcurrentnet"/>
| | |
|---|---|
|Method|getcurrentnet|
|Parameters|None|
|Description|Get bitcoin network btcd is running on.|
|Parameters|1. address (string, required) - bitcoin address <br/> 2. verbose (int, optional, default=true) - specifies the transaction is returned as a JSON object instead of hex-encoded string <br/>3. skip (int, optional, default=0) - the number of leading transactions to leave out of the final response <br/> 4. count (int, optional, default=100) - the maximum number of transactions to return|
|Description|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 `"confirmations"` field set to 0. Usage of this RPC requires the optional `--addrindex` 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.|
|Returns (verbose=0)|`"data" (string) hex-encoded bytes of the serialized transaction`|
|Returns (verbose=1)|`{ (json object)`<br/> `"hex": "data", (string) hex-encoded transaction`<br/> `"txid": "hash", (string) the hash of the transaction`<br/> `"version": n, (numeric) the transaction version`<br/> `"locktime": n, (numeric) the transaction lock time`<br/> `"vin": [ (array of json objects) the transaction inputs as json objects`<br/> <fontcolor="orange">For coinbase transactions:</font><br/> `{ (json object)`<br/> `"coinbase": "data", (string) the hex-dencoded bytes of the signature script`<br/> `"sequence": n, (numeric) the script sequence number`<br/> `}`<br/> <fontcolor="orange">For non-coinbase transactions:</font><br/> `{ (json object)`<br/> `"txid": "hash", (string) the hash of the origin transaction`<br/> `"vout": n, (numeric) the index of the output being redeemed from the origin transaction`<br/> `"scriptSig": { (json object) the signature script used to redeem the origin transaction`<br/> `"asm": "asm", (string) disassembly of the script`<br/> `"hex": "data", (string) hex-encoded bytes of the script`<br/> `}`<br/> `"sequence": n, (numeric) the script sequence number`<br/> `}, ...`<br/> `]`<br/> `"vout": [ (array of json objects) the transaction outputs as json objects`<br/> `{ (json object)`<br/> `"value": n, (numeric) the value in BTC`<br/> `"n": n, (numeric) the index of this transaction output`<br/> `"scriptPubKey": { (json object) the public key script used to pay coins`<br/> `"asm": "asm", (string) disassembly of the script`<br/> `"hex": "data", (string) hex-encoded bytes of the script`<br/> `"reqSigs": n, (numeric) the number of required signatures`<br/> `"type": "scripttype" (string) the type of the script (e.g. 'pubkeyhash')`<br/> `"addresses": [ (json array of string) the bitcoin addresses associated with this output`<br/> `"address", (string) the bitcoin address`<br/> `...`<br/> `]`<br/> `}`<br/> `}, ...`<br/> `]`<br/> `"blockhash":"hash" Hash of the block the transaction is part of.`<br/> `"confirmations":n, Number of numeric confirmations of block.`<br/> `"time":t, Transaction time in seconds since the epoch.` <br/> `"blocktime":t, Block time in seconds since the epoch.`<br/>`}`|
The following is an overview of the RPC method requests available exclusively to Websocket clients. Click the method name for further details such as parameter and return information.
|#|Method|Description|Notifications|
|---|------|-----------|-------------|
|1|[authenticate](#authenticate)|Authenticate the connection against the username and passphrase configured for the RPC server.<br/><fontcolor="orange">NOTE: This is only required if an HTTP Authorization header is not being used.</font>|None|
|2|[notifyblocks](#notifyblocks)|Send notifications when a block is connected or disconnected from the best chain.|[blockconnected](#blockconnected) and [blockdisconnected](#blockdisconnected)|
|3|[notifyreceived](#notifyreceived)|Send notifications when a txout spends to an address.|[recvtx](#recvtx) and [redeemingtx](#redeemingtx)|
|4|[notifyspent](#notifyspent)|Send notification when a txout is spent.|[redeemingtx](#redeemingtx)|
|5|[rescan](#rescan)|Rescan block chain for transactions to addresses and spent transaction outpoints.|[recvtx](#recvtx), [redeemingtx](#redeemingtx), [rescanprogress](#rescanprogress), and [rescanfinished](#rescanfinished) |
|6|[notifynewtransactions](#notifynewtransactions)|Send notifications for all new transactions as they are accepted into the mempool.|[txaccepted](#txaccepted) or [txacceptedverbose](#txacceptedverbose)|
|Description|Authenticate the connection against the username and password configured for the RPC server.<br/> Invoking any other method before authenticating with this command will close the connection.<br/><fontcolor="orange">NOTE: This is only required if an HTTP Authorization header is not being used.</font>|
[Return to Overview](#ExtensionRequestOverview)<br/>
<aname="notifyblocks"/>
| | |
|---|---|
|Method|notifyblocks|
|Notifications|[blockconnected](#blockconnected) and [blockdisconnected](#blockdisconnected)|
|Parameters|None|
|Description|Request notifications for whenever a block is connected or disconnected from the main (best) chain.|
|Returns|Nothing|
[Return to Overview](#ExtensionRequestOverview)<br/>
***
<aname="notifyreceived"/>
| | |
|---|---|
|Method|notifyreceived|
|Notifications|[recvtx](#recvtx) and [redeemingtx](#redeemingtx)|
|Parameters|1. Addresses (JSON array, required)<br/> `[ (json array of strings)`<br/> `"bitcoinaddress", (string) the bitcoin address`<br/> `...`<br/> `]`|
|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.|
|Returns|Nothing|
[Return to Overview](#ExtensionRequestOverview)<br/>
***
<aname="notifyspent"/>
| | |
|---|---|
|Method|notifyspent|
|Notifications|[redeemingtx](#redeemingtx)|
|Parameters|1. Outpoints (JSON array, required)<br/> `[ (JSON array)`<br/> `{ (JSON object)`<br/> `"hash":"data", (string) the hex-encoded bytes of the outpoint hash`<br/> `"index":n (numeric) the txout index of the outpoint`<br/> `},`<br/> `...`<br/> `]`|
|Description|Send a redeemingtx notification when a transaction spending an outpoint appears in mempool (if relayed to this btcd instance) and when such a transaction first appears in a newly-attached block.|
|Returns|Nothing|
[Return to Overview](#ExtensionRequestOverview)<br/>
***
<aname="rescan"/>
| | |
|---|---|
|Method|rescan|
|Notifications|[recvtx](#recvtx), [redeemingtx](#redeemingtx), [rescanprogress](#rescanprogress), and [rescanfinished](#rescanfinished)|
|Parameters|1. BeginBlock (string, required) block hash to begin rescanning from<br/>2. Addresses (JSON array, required)<br/> `[ (json array of strings)`<br/> `"bitcoinaddress", (string) the bitcoin address`<br/> `...` <br/> `]`<br/>3. Outpoints (JSON array, required)<br/> `[ (JSON array)`<br/> `{ (JSON object)`<br/> `"hash":"data", (string) the hex-encoded bytes of the outpoint hash`<br/> `"index":n (numeric) the txout index of the outpoint`<br/> `},`<br/> `...`<br/> `]`<br/>4. EndBlock (string, optional) hash of final block to rescan|
|Description|Rescan block chain for transactions to addresses, starting at block BeginBlock and ending at EndBlock. If EndBlock is omitted, the rescan continues through the best block in the main chain. The current known UTXO set for all passed addresses at height BeginBlock should included in the Outpoints argument. Rescan results are sent as recvtx and redeemingtx notifications. This call returns once the rescan completes.|
|Returns|Nothing|
[Return to Overview](#ExtensionRequestOverview)<br/>
***
<aname="notifynewtransactions"/>
| | |
|---|---|
|Method|notifynewtransactions|
|Notifications|[txaccepted](#txaccepted) or [txacceptedverbose](#txacceptedverbose)|
|Parameters|1. verbose (boolean, optional, default=false) - 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|
[Return to Overview](#ExtensionRequestOverview)<br/>
<aname="Notifications"/>
### 8. Notifications (Websocket-specific)
btcd uses standard JSON-RPC notifications to notify clients of changes, rather than requiring clients to poll btcd for updates. JSON-RPC notifications are a subset of requests, but do not contain an ID. The notification type is categorized by the `method` field and additional details are sent as a JSON array in the `params` field.
<aname="NotificationOverview"/>
**8.1 Notification Overview**<br/>
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|
|---|------|-----------|-------|
|1|[blockconnected](#blockconnected)|Block connected to the main chain.|[notifyblocks](#notifyblocks)|
|2|[blockdisconnected](#blockdisconnected)|Block disconnected from the main chain.|[notifyblocks](#notifyblocks)|
|3|[recvtx](#recvtx)|Processed a transaction output spending to a wallet address.|[notifyreceived](#notifyreceived) and [rescan](#rescan)|
|4|[redeemingtx](#redeemingtx)|Processed a transaction that spends a registered outpoint.|[notifyspent](#notifyspent) and [rescan](#rescan)|
|5|[txaccepted](#txaccepted)|Received a new transaction after requesting simple notifications of all new transactions accepted into the mempool.|[notifynewtransactions](#notifynewtransactions)|
|6|[txacceptedverbose](#txacceptedverbose)|Received a new transaction after requesting verbose notifications of all new transactions accepted into the mempool.|[notifynewtransactions](#notifynewtransactions)|
|7|[rescanprogress](#rescanprogress)|A rescan operation that is underway has made progress.|[rescan](#rescan)|
|8|[rescanfinished](#rescanfinished)|A rescan operation has completed.|[rescan](#rescan)|
<aname="NotificationDetails"/>
**8.2 Notification Details**<br/>
<aname="blockconnected"/>
| | |
|---|---|
|Method|blockconnected|
|Request|[notifyblocks](#notifyblocks)|
|Parameters|1. BlockHash (string) hex-encoded bytes of the attached block hash<br/>2. BlockHeight (numeric) height 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 (newlines added for readability):<br/>`{`<br/> `"jsonrpc": "1.0",`<br/> `"method": "blockconnected",`<br/> `"params":`<br/> `[`<br/> `"000000000000000004cbdfe387f4df44b914e464ca79838a8ab777b3214dbffd",`<br/> `280330`<br/> `],`<br/> `"id": null`<br/>`}`|
[Return to Overview](#NotificationOverview)<br/>
***
<aname="blockdisconnected"/>
| | |
|---|---|
|Method|blockdisconnected|
|Request|[notifyblocks](#notifyblocks)|
|Parameters|1. BlockHash (string) hex-encoded bytes of the disconnected block hash<br/>2. BlockHeight (numeric) height of the disconnected block|
|Description|Notifies when a block has been removed from the main chain. Notification is sent to all connected clients.|
|Example|Example blockdisconnected notification for mainnet block 280330 (newlines added for readability):<br/>`{`<br/> `"jsonrpc": "1.0",`<br/> `"method": "blockdisconnected",`<br/> `"params":`<br/> `[`<br/> `"000000000000000004cbdfe387f4df44b914e464ca79838a8ab777b3214dbffd",`<br/> `280330`<br/> `],`<br/> `"id": null`<br/>`}`|
[Return to Overview](#NotificationOverview)<br/>
***
<aname="recvtx"/>
| | |
|---|---|
|Method|recvtx|
|Request|[rescan](#rescan) or [notifyreceived](#notifyreceived)|
|Parameters|1. Transaction (string) full transaction encoded as a hex string<br/>2. Block details (object, optional) 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 61d3696de4c888730cbe06b0ad8ecb6d72d6108e893895aa9bc067bd7eba3fad when processed by mempool (newlines added for readability):<br/>`{`<br/> `"jsonrpc": "1.0",`<br/> `"method": "recvtx",`<br/> `"params":`<br/> `[`<br/> `"010000000114d9ff358894c486b4ae11c2a8cf7851b1df64c53d2e511278eff17c22fb737300000000..."`<br/> `],`<br/> `"id": null`<br/>`}`<br/>The recvtx notification for the same txout, after the transaction was mined into block 276425:<br/>`{`<br/> `"jsonrpc": "1.0",`<br/> `"method": "recvtx",`<br/> `"params":`<br/> `[`<br/> `"010000000114d9ff358894c486b4ae11c2a8cf7851b1df64c53d2e511278eff17c22fb737300000000...",`<br/> `{`<br/> `"height": 276425,`<br/> `"hash": "000000000000000325474bb799b9e591f965ca4461b72cb7012b808db92bb2fc",`<br/> `"index": 684,`<br/> `"time": 1387737310`<br/> `}`<br/> `],`<br/> `"id": null`<br/>`}`|
[Return to Overview](#NotificationOverview)<br/>
***
<aname="redeemingtx"/>
| | |
|---|---|
|Method|redeemingtx|
|Requests|[notifyspent](#notifyspent) and [rescan](#rescan)|
|Parameters|1. Transaction (string) full transaction encoded as a hex string<br/>2. Block details (object, optional) details about a block and the index of the transaction within a block, if the transaction is mined|
|Description|Notifies a client when an registered outpoint is spent by a transaction accepted to mempool and/or mined into a block.|
|Example|Example redeemingtx notification for mainnet outpoint 61d3696de4c888730cbe06b0ad8ecb6d72d6108e893895aa9bc067bd7eba3fad:0 after being spent by transaction 4ad0c16ac973ff675dec1f3e5f1273f1c45be2a63554343f21b70240a1e43ece (newlines added for readability):<br/>`{`<br/> `"jsonrpc": "1.0",`<br/> `"method": "redeemingtx",`<br/> `"params":`<br/> `[`<br/> `"0100000003ad3fba7ebd67c09baa9538898e10d6726dcb8eadb006be0c7388c8e46d69d3610000000..."`<br/> `],`<br/> `"id": null`<br/>`}`<br/>The redeemingtx notification for the same txout, after the spending transaction was mined into block 279143:<br/>`{`<br/> `"jsonrpc": "1.0",`<br/> `"method": "recvtx",`<br/> `"params":`<br/> `[`<br/> `"0100000003ad3fba7ebd67c09baa9538898e10d6726dcb8eadb006be0c7388c8e46d69d3610000000...",`<br/> `{`<br/> `"height": 279143,`<br/> `"hash": "00000000000000017188b968a371bab95aa43522665353b646e41865abae02a4",`<br/> `"index": 6,`<br/> `"time": 1389115004`<br/> `}`<br/> `],`<br/> `"id": null`<br/>`}`|
|Parameters|1. TxSha (string) hex-encoded bytes of the transaction hash<br/>2. Amount (numeric) sum of the value of all the transaction outpoints|
|Description|Notifies when a new transaction has been accepted and the client has requested standard transaction details.|
|Example|Example txaccepted notification for mainnet transaction id "16c54c9d02fe570b9d41b518c0daefae81cc05c69bbe842058e84c6ed5826261" (newlines added for readability):<br/>`{`<br/> `"jsonrpc": "1.0",`<br/> `"method": "txaccepted",`<br/> `"params":`<br/> `[`<br/> `"16c54c9d02fe570b9d41b518c0daefae81cc05c69bbe842058e84c6ed5826261",`<br/> `55838384`<br/> `],`<br/> `"id": null`<br/>`}`|
|Parameters|1. Hash (string) hash of the last processed block<br/>2. Height (numeric) height of the last processed block<br/>3. Time (numeric) UNIX time of the last processed block|
|Description|Notifies a client with the current progress at periodic intervals when a long-running [rescan](#rescan) is underway.|
|Parameters|1. Hash (string) hash of the last rescanned block<br/>2. Height (numeric) height of the last rescanned block<br/>3. Time (numeric) UNIX time of the last rescanned block |
|Description|Notifies a client that the [rescan](#rescan) has completed and no further notifications will be sent.|
