Bitcoin原始API

Bitcoin Core APIs

Remote Procedure Calls (RPCs)

Warning: the block chain and memory pool can include arbitrary data which several of the commands below will return in hex format. If you convert this data to another format in an executable context, it could be used in an exploit. For example, displaying an output script as ASCII text in a webpage could add arbitrary Javascript to that page and create a cross-site scripting (XSS) exploit. To avoid problems, please treat block chain and memory pool data as an arbitrary input from an untrusted source.

addmultisigaddress

addmultisigaddress <num required> <addresses|pubkeys> [account]

Add a P2SH multisig address to the wallet.

Related RPCs: createmultisig

Argument #1: Number Of Signatures Required

Number; required: the minimum (m) number of signatures required to spend satoshis sent to this m-of-n P2SH multisig script.

<m>

Argument #2: Full Public Keys, Or Addresses For Known Public Keys

String; required: A JSON array of hex-encoded public keys or addresses for public keys known to this Bitcoin Core instance. The multisig script can only use full (unhashed) public keys, so you generally must provide public keys for any address not known to this wallet.

[  "<address|pubkey>"  ,[...]]

Argument #3: Account Name

String; optional: The name of an account in the wallet which will store the address.

"<account>"

Result: A P2SH Address Printed And Stored In The Wallet

String: a hash of the P2SH multisig redeemScript, which is also stored in the wallet so Bitcoin Core can monitor the network and block chain for transactions sent to that address (which will be displayed in the wallet as spendable balances).

Example

Adding a 2-of-3 P2SH multisig address to the “test account” by mixing two P2PKH addresses and one full public key:

> bitcoin-cli -testnet addmultisigaddress \  2 \  '''    [       "mjbLRSidW1MY8oubvs4SMEnHNFXxCcoehQ",       "02ecd2d250a76d204011de6bc365a56033b9b3a149f679bc17205555d3c2b2854f",       "mt17cV37fBqZsnMmrHnGCm9pM28R1kQdMG"     ]  ''' \  'test account'

Result:

2MyVxxgNBk5zHRPRY2iVjGRJHYZEp1pMCSq

(New P2SH multisig address also stored in wallet.)

addnode

addnode <ip address>:<port> <add|remove|onetry>

Attempts add or remove a node from the addnode list, or try a connection to a node once.

Argument #1: IP Address And Port Of Node

String, required: the colon-delimited IP address and port of the node to add, remove, or connect to.

Argument #2: Add Or Remove The Node, Or Try Once To Connect

String, required: whether to add or remove the node to the list of known nodes. This does not necessarily mean that a connection to the node will be established. To attempt to establish a connection immediately, use onetry.

Return: Empty Or Error

Will not return any data if the node is added or if onetry is used (even if the connection attempt fails). Will return an error if you try removing an unknown node.

Example

Try connecting to the following node.

> bitcoin-cli -testnet addnode 68.39.150.9:18333 onetry

backupwallet

backupwallet <filename|directory>

Safely copies wallet.dat to destination, which can be a directory or a path with filename.

Argument #1: Destination Directory Or Filename

String, required: a directory or filename. If a directory, a file named wallet.dat will be created or overwritten. If a filename, a file of that name will be created or overwritten.

Return: Empty Or Error

Nothing will be returned on success. If the file couldn’t be created or written, an error will be returned.

Example

> bitcoin-cli -testnet backupwallet /tmp/backup.dat

createmultisig

createmultisig <num required> <addresses|pubkeys>

Creates a multi-signature address.

Related RPCs: addmultisigaddress

Argument #1: Number Of Signatures Required

Number; required: the minimum (m) number of signatures required to spend satoshis sent to this m-of-n multisig script.

<m>

Argument #2: Full Public Keys, Or Addresses For Known Public Keys

String; required: A JSON array of hex-encoded public keys or addresses for public keys known to this Bitcoin Core instance. The multisig script can only use full (unhashed) public keys, so you generally must provide public keys for any address not known to this wallet.

[  "<address|pubkey>"  ,[...]]

Result: Address And Hex-Encoded RedeemScript

String: JSON object with the P2SH address and hex-encoded redeemScript.

{  "address":"<P2SH address>",  "redeemScript":"<hex redeemScript>"}

Example

Creating a 2-of-3 P2SH multisig address by mixing two P2PKH addresses and one full public key:

> bitcoin-cli -testnet createmultisig 2 '''  [     "mjbLRSidW1MY8oubvs4SMEnHNFXxCcoehQ",     "02ecd2d250a76d204011de6bc365a56033b9b3a149f679bc17205555d3c2b2854f",     "mt17cV37fBqZsnMmrHnGCm9pM28R1kQdMG"   ]  '''

Result (redeemScript wrapped):

{  "address" : "2MyVxxgNBk5zHRPRY2iVjGRJHYZEp1pMCSq",  "redeemScript" : "522103ede722780d27b05f0b1169efc90fa15a601a32\                    fc6c3295114500c586831b6aaf2102ecd2d250a76d20\                    4011de6bc365a56033b9b3a149f679bc17205555d3c2\                    b2854f21022d609d2f0d359e5bc0e5d0ea20ff9f5d33\                    96cb5b1906aa9c56a0e7b5edc0c5d553ae"}

createrawtransaction

createrawtransaction <previous output(s)> <new output(s)>

Create an unsigned transaction in hex rawtransaction format that spends a previous output to an new output with a P2PKH or P2SH address. The transaction is not stored in the wallet or transmitted to the network.

Argument #1: References To Previous Outputs

String; required: A JSON array of JSON objects. Each object in the array references a previous output by its txid (string; required) and output index number, called vout (number; required).

[  {    "txid":"<previous output txid>",    "vout":<previous output index number>  }  ,[...]]

Argument #2: P2PKH Or P2SH Addresses For New Outputs

String; required: A JSON object with P2PKH or P2SH addresses to pay as keys and the amount to pay each address as its value (number; required) in decimal bitcoins.

{  "<address>": <bitcoins>.<decimal bitcoins>  ,[...]}

Result: Unsigned Raw Transaction (In Hex)

String: The resulting unsigned transaction in hex-encoded rawtransaction format, or a JSON error if any value provided was invalid.

Example

> bitcoin-cli -testnet createrawtransaction '''  [    {       "txid":"5a7d24cd665108c66b2d56146f244932edae4e2376b561b3d396d5ae017b9589",       "vout":0     }   ]  ''' '''  {     "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe": 0.1   }''''

Result:

010000000189957b01aed596d3b361b576234eaeed3249246f14562d6bc60851\66cd247d5a0000000000ffffffff0180969800000000001976a9140dfc8bafc8\419853b34d5e072ad37d1a5159f58488ac00000000

decoderawtransaction

decoderawtransaction <hexstring>

Decode a rawtransaction format hex string into a JSON object representing the transaction.

Argument: RawTransaction Hex

String; required: a complete transaction in rawtransaction format hex.

Result: JSON Object

A JSON object describing the the transaction is returned. The object is described in parts below.

{  "txid" : "<hash>",  "version" : <number>,  "locktime" : <epoch time|block height>,

The transaction identifier (txid), the transaction version number, and the locktime.

  "vin" : [     {       "txid": "<txid>",       "vout": <output index number>,       "scriptSig": {         "asm": "<script psuedo-code>",         "hex": "<script hex>"       },       "sequence": <sequence number>     }     ,...  ],

A JSON array of inputs, with each inputs prevout txid, prevout output index number (vout), scriptSig in script-language psuedocode (asm) and hex, and the input sequence number.

  "vout" : [     {       "value" : <decimal bitcoins>,       "n" : <index number>,       "scriptPubKey" : {         "asm" : "<script psuedo-code>",         "hex" : "<script hex>",         "reqSigs" : <number of required signatures>,         "type" : "<type>",         "addresses" : [           "<address>"           ,[...]         ]       }     }     ,[...]  ],}

A JSON array of outputs, with each output containing a value in decimal bitcoins, an output index number (n), a script (scriptPubKey) in script-language psuedocode (asm) and hex, the number of signatures required (reqSigs), the type of script (if it’s a standard transaction), and an array of addresses used in the output. (More than one address means it’s a multisig output.)

Example

Decode a signed one-input, two-output transaction:

> bitcoin-cli -testnet decoderawtransaction 0100000001268a9ad7bf\              b21d3c086f0ff28f73a064964aa069ebb69a9e437da85c7e55\              c7d7000000006b483045022100ee69171016b7dd218491faf6\              e13f53d40d64f4b40123a2de52560feb95de63b902206f23a0\              919471eaa1e45a0982ed288d374397d30dff541b2dd45a4c3d\              0041acc0012103a7c1fd1fdec50e1cf3f0cc8cb4378cd8e9a2\              cee8ca9b3118f3db16cbbcf8f326ffffffff0350ac60020000\              00001976a91456847befbd2360df0e35b4e3b77bae48585ae0\              6888ac80969800000000001976a9142b14950b8d31620c6cc9\              23c5408a701b1ec0a02088ac002d3101000000001976a9140d\              fc8bafc8419853b34d5e072ad37d1a5159f58488ac00000000

Result:

{    "txid" : "ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb0\              1c2cb8e8de481e",    "version" : 1,    "locktime" : 0,    "vin" : [        {            "txid" : "d7c7557e5ca87d439e9ab6eb69a04a9664a0738ff2\                      0f6f083c1db2bfd79a8a26",            "vout" : 0,            "scriptSig" : {                "asm" : "3045022100ee69171016b7dd218491faf6e13f5\                         3d40d64f4b40123a2de52560feb95de63b90220\                         6f23a0919471eaa1e45a0982ed288d374397d30\                         dff541b2dd45a4c3d0041acc001 03a7c1fd1fd\                         ec50e1cf3f0cc8cb4378cd8e9a2cee8ca9b3118\                         f3db16cbbcf8f326",                "hex" : "483045022100ee69171016b7dd218491faf6e13\                         f53d40d64f4b40123a2de52560feb95de63b902\                         206f23a0919471eaa1e45a0982ed288d374397d\                         30dff541b2dd45a4c3d0041acc0012103a7c1fd\                         1fdec50e1cf3f0cc8cb4378cd8e9a2cee8ca9b3\                         118f3db16cbbcf8f326"            },            "sequence" : 4294967295        }    ],    "vout" : [        {            "value" : 0.39890000,            "n" : 0,            "scriptPubKey" : {                "asm" : "OP_DUP OP_HASH160                  56847befbd2360df0e35b4e3b77bae48585ae068                  OP_EQUALVERIFY OP_CHECKSIG",                "hex" : "76a91456847befbd2360df0e35b4e3b77bae48585ae06888ac",                "reqSigs" : 1,                "type" : "pubkeyhash",                "addresses" : [                    "moQR7i8XM4rSGoNwEsw3h4YEuduuP6mxw7"                ]            }        },        {            "value" : 0.10000000,            "n" : 1,            "scriptPubKey" : {                "asm" : "OP_DUP OP_HASH160                  2b14950b8d31620c6cc923c5408a701b1ec0a020                  OP_EQUALVERIFY OP_CHECKSIG",                "hex" : "76a9142b14950b8d31620c6cc923c5408a701b1ec0a02088ac",                "reqSigs" : 1,                "type" : "pubkeyhash",                "addresses" : [                    "mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN"                ]            }        },        {            "value" : 0.20000000,            "n" : 2,            "scriptPubKey" : {                "asm" : "OP_DUP OP_HASH160                  0dfc8bafc8419853b34d5e072ad37d1a5159f584                  OP_EQUALVERIFY OP_CHECKSIG",                "hex" : "76a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac",                "reqSigs" : 1,                "type" : "pubkeyhash",                "addresses" : [                    "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe"                ]            }        }    ]}

decodescript

decodescript <redeemScript>

Decode a hex-encoded P2SH redeemScript.

Argument: A Hex-Encoded RedeemScript

String; required: an complete (not hashed) redeemScript in hex.

Result

A JSON object describing the redeemScript, with asm being the script in script-language psuedocode, hex being the a P2PKH public key (if applicable), type being the output type (typically public key, multisig, or nonstandard), reqSigs being the required signatures, and the addresses array listing the addresses belonging to the public keys.

{  "asm":"<script psuedo-code>",  "hex":"<script hex>",  "type":"<type>",  "reqSigs": <number of required signatures>,  "addresses": [     "<address>"     ,[...]  ],  "p2sh","<address>"}

Example

A 2-of-3 P2SH multisig script:

> bitcoin-cli -testnet decodescript 483045022100ee69171016b7dd21\              8491faf6e13f53d40d64f4b40123a2de52560feb95de63b902\              206f23a0919471eaa1e45a0982ed288d374397d30dff541b2d\              d45a4c3d0041acc0012103a7c1fd1fdec50e1cf3f0cc8cb437\              8cd8e9a2cee8ca9b3118f3db16cbbcf8f326

Result:

{    "asm" : "2 03ede722780d27b05f0b1169efc90fa15a601a32fc6c32951\               14500c586831b6aaf 02ecd2d250a76d204011de6bc365a56\               033b9b3a149f679bc17205555d3c2b2854f 022d609d2f0d3\               59e5bc0e5d0ea20ff9f5d3396cb5b1906aa9c56a0e7b5edc0\               c5d5 3 OP_CHECKMULTISIG",    "reqSigs" : 2,    "type" : "multisig",    "addresses" : [        "mjbLRSidW1MY8oubvs4SMEnHNFXxCcoehQ",        "mo1vzGwCzWqteip29vGWWW6MsEBREuzW94",        "mt17cV37fBqZsnMmrHnGCm9pM28R1kQdMG"    ],    "p2sh" : "2MyVxxgNBk5zHRPRY2iVjGRJHYZEp1pMCSq"}

dumpprivkey

dumpprivkey <address>

Returns the hex-encoded private key corresponding to the address. (But does not remove it from the wallet.)

See also: importprivkey

Argument: Address Corresponding To The Private Key

String; required: the Bitcoin address of the private key you want.

Return:

A hex-encoded private key.

Example

> bitcoin-cli -testnet dumpprivkey moQR7i8XM4rSGoNwEsw3h4YEuduuP6mxw7

Result:

cTVNtBK7mBi2yc9syEnwbiUpnpGJKohDWzXMeF4tGKAQ7wvomr95

dumpwallet

dumpwallet <filename>

Creates or overwrites a file with all wallet keys in a human-readable format.

Argument: Filename

A filename.

Result

The files is created (if necessary) and written. No output is returned to the RPC.

Example

Create a wallet dump and then print its first 10 lines.

> bitcoin-cli -testnet dumpwallet /tmp/dump.txt> head /tmp/dump.txt

Space-delimited output (lines not wrapped).

# Wallet dump created by Bitcoin v0.9.1.0-g026a939-beta (Tue, 8 Apr 2014 12:04:06 +0200)# * Created on 2014-04-29T20:46:09Z# * Best block at time of backup was 227221 (0000000026ede4c10594af8087748507fb06dcd30b8f4f48b9cc463cabc9d767),#   mined on 2014-04-29T21:15:07ZcTtefiUaLfXuyBXJBBywSdg8soTEkBNh9yTi1KgoHxUYxt1xZ2aA 2014-02-05T15:44:03Z label=test1 # addr=mnUbTmdAFD5EAg3348Ejmonub7JcWtrMckcQNY9v93Gyt8KmwygFR59bDhVs3aRDkuT8pKaCBpop82TZ8ND1tH 2014-02-05T16:58:41Z reserve=1 # addr=mp4MmhTp3au21HPRz5waf6YohGumuNnsqTcNTEPzZH9mjquFFADXe5S3BweNiHLUKD6PvEKEsHApqjX4ZddeU6 2014-02-05T16:58:41Z reserve=1 # addr=n3pdvsxveMBkktjsGJixfSbxacRUwJ9jQWcTVNtBK7mBi2yc9syEnwbiUpnpGJKohDWzXMeF4tGKAQ7wvomr95 2014-02-05T16:58:41Z change=1 # addr=moQR7i8XM4rSGoNwEsw3h4YEuduuP6mxw7cNCD679B4xi17jb4XeLpbRbZCbYUugptD7dCtUTfSU4KPuK2DyKT 2014-02-05T16:58:41Z reserve=1 # addr=mq8fzjxxVbAKxUGPwaSSo3C4WaUxdzfw3C

encryptwallet

encryptwallet <passphrase>

Encrypts the wallet with ‘passphrase’. This is only to enable encryption for the first time.  After encryption is enabled, you will need to enter the passphrase to use private keys (which includes generating additional new addresses once the keypool is exhausted—see keypoolrefill).

Warning: there is no RPC to completely disable encryption. If you want to return to an unencrypted wallet, you must create a new wallet and restore your data from adumpwallet backup.

See also: walletpassphrase and walletlock

Argument: A Passphrase

String; required: a passphrase of at least one character. Longer passphrases will, in general, be more secure.

Result: A Notice (With Program Shutdown)

The wallet will be encrypted by the passphrase and the node will shutdown. A notice may be printed.

Example

> bitcoin-cli -testnet encryptwallet "test"

Result:

wallet encrypted; Bitcoin server stopping, restart to run with encryptedwallet. The keypool has been flushed, you need to make a new backup.

getaccount

getaccount <address>

Returns the name of the account associated with the given address.

Argument: A Bitcoin Address

String; required: a bitcoin address.

Result: An Account Name

String: the name of the account the address belongs to. The default account is “”.

Example

> bitcoin-cli -testnet getaccount mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN

Result:

doc test

getaccountaddress

getaccountaddress "account"

Returns the current Bitcoin address for receiving payments to this account. If the account doesn’t exist, it creates both the account and a new address for receiving payment.

Argument: An Account Name

String; required: the name of the account from which to get the current receiving address. The same address will be returned for each call until the node marks it as used (because, for example, it received a payment).

If the account doesn’t exist, it is created. For the default account, use an empty string (“”).

Result: A Bitcoin Address

An address which has not yet received any known payments.

Example

Get an address for the default account:

> bitcoin-cli -testnet getaccountaddress ""

Result:

msQyFNYHkFUo4PG3puJBbpesvRCyRQax7r

getaddednodeinfo

getaddednodeinfo <true|false> [node]

Returns information about the given added node, or all added nodes (except onetry nodes). Only nodes which have been manually added using addnode <node> add will have their information displayed.

Argument #1: Whether To Display Connection Information

Boolean; required: to display detailed information about each node, use true. To display a simple list, use false.

Argument #2: What Node To Display Information About

String; optional: the IP address of a particular node to display information about.

Result: A Detailed Or Simple List Of Nodes

The detailed list contains the addednode’s IP address, whether it’s currently connected, an array of its full addresses using IP address and port, and whether it is connected inbound or outbound.

[  {    "addednode" : "<ip address>",    "connected" : <true|false>,    "addresses" : [       {         "address" : "<ip address>:<port>",         "connected" : "<inbound|outbound>"       }       ,[...]     ]  }  ,[...]]

Example

> bitcoin-cli -testnet getaddednodeinfo true

Result:

[    {        "addednode" : "46.4.99.45:44549",        "connected" : true,        "addresses" : [            {                "address" : "46.4.99.45:44549",                "connected" : "inbound"            }        ]    }]

getaddressesbyaccount

getaddressesbyaccount <account>

Returns a list of every address assigned to a particular account.

Argument: Account Name

String; required: the name of the account.

Result: A List Of Addresses

String: A JSON array of strings, with each string being a single Bitcoin address.

[  "<address>"  ,[...]]

Example

Get the addresses assigned to the account “doc test”:

> bitcoin-cli -testnet getaddressesbyaccount "doc test"

Result:

[    "mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN"]

getbalance 查询余额

getbalance [account] [confirmations]

Get the balance in decimal bitcoins across all accounts or for a particular account. Specify the number of confirmations to only show satoshis which have been confirmed at least that many times.

返回指定账户的所有account的bitcoin数量(decimal).

Argument #1: Account Name

String; optional: the name of the account to get a balance for or “*” to get the balance for all accounts (the default). The default (primary) account can be specified using “”, which is not the same as specifying “*” for all accounts.

Argument #2: Minimum Number Of Confirmations

Number; optional: the minimum number of confirmations an incoming transaction must have before it is counted towards the balance. (Outgoing transactions are subtracted from the balance immediately.)

The default is one confirmation, so transactions are not counted towards the balance until they confirm.

Result: The Balance In Decimal Bitcoins

The balance for the account indicated (or all accounts) in decimal satoshis. May be negative if the account has spent more satoshis than it received.

Examples

Four balances: one for the current balance of the “doc test” account and one for that account with more than 1,000 confirmations. Then a balance for the default account and a balance for all accounts.

> bitcoin-cli -testnet getbalance "doc test"0.30000000

> bitcoin-cli -testnet getbalance "doc test" 10000.20000000

> bitcoin-cli -testnet getbalance ""-1.30050000

> bitcoin-cli -testnet getbalance "*"0.89850000

getbestblockhash

getbestblockhash

Returns the header hash of the most recent block on the longest block chain.

Result

The block hash in hex.

Example

> bitcoin-cli -testnet getbestblockhash

Result:

0000000000075c58ed39c3e50f99b32183d090aefa0cf8c324a82eea9b01a887

getblock

getblock <hash> [true|false]

Get a block with a particular header hash from the block chain either as a JSON object (if true) or a raw hex string (if false)

Argument: Header Hash

String; required: the SHA256(SHA256()) hash of the block header to get.

Argument: JSON Or Hex Output

Boolean; optional: by default, true to return a JSON object describing the block. False for just the hex-encoded block.

Result

A hex-encoded block or the following JSON object described in segments.

{  "hash" : "<hash>",  "confirmations" : <number>,  "size" : <bytes>,  "height" : <number>,  "version" : <number>,  "merkleroot" : "<hash>",

The block header hash (same as you provided); the number of confirmations (subsequent blocks), the size of the block in bytes, the block height, the block version, and the Merkle root hash.

  "tx" : [     "<txid>"     ,[...]  ],

A JSON array of transaction identifiers (txids).

  "time" : <epoch time>,  "nonce" : <number>,  "bits" : "<hex>",  "difficulty" : <number>,  "previousblockhash" : "<hash>",  "nextblockhash" : "<hash>"}

The block time in Unix epoch time, the block nonce, the target threshold in compressed bits format, the target threshold in difficulty format, the previous block (header) hash, and the next block (header) hash.

Example

A block in raw hex:

> bitcoin-cli -testnet getblock \            000000000fe549a89848c76070d4132872cfb6efe5315d01d7ef77e4900f2d39 \            false

Result:

02000000df11c014a8d798395b5059c722ebdf3171a4217ead71bf6e0e99f4c7\000000004a6f6a2db225c81e77773f6f0457bcb05865a94900ed11356d0b7522\8efb38c7785d6053ffff001d005d437001010000000100000000000000000000\00000000000000000000000000000000000000000000ffffffff0d03b4770301\64062f503253482fffffffff0100f9029500000000232103adb7d8ef6b63de74\313e0cd4e07670d09a169b13e4eda2d650f529332c47646dac00000000

Get the same block in JSON:

> bitcoin-cli -testnet getblock \            000000000fe549a89848c76070d4132872cfb6efe5315d01d7ef77e4900f2d39 \            true

Result:

{    "hash" : "000000000fe549a89848c76070d4132872cfb6efe5315d01d7ef77e4900f2d39",    "confirmations" : 2,    "size" : 189,    "height" : 227252,    "version" : 2,    "merkleroot" : "c738fb8e22750b6d3511ed0049a96558b0bc57046f3f77771ec825b22d6a6f4a",    "tx" : [        "c738fb8e22750b6d3511ed0049a96558b0bc57046f3f77771ec825b22d6a6f4a"    ],    "time" : 1398824312,    "nonce" : 1883462912,    "bits" : "1d00ffff",    "difficulty" : 1.00000000,    "chainwork" : "000000000000000000000000000000000000000000000000083ada4a4009841a",    "previousblockhash" : "00000000c7f4990e6ebf71ad7e21a47131dfeb22c759505b3998d7a814c011df",    "nextblockhash" : "00000000afe1928529ac766f1237657819a11cfcc8ca6d67f119e868ed5b6188"}

getblockcount

getblockcount

Returns the number of blocks in the longest block chain.

Result

The current block count.

Example

> bitcoin-cli -testnet getblockcount 

Result:

239402

getblockhash

getblockhash <height>

Returns hash of block in best-block-chain at block height provided.

Argument: Block Height

Number; required: the block height of the block hash to get.

Result: A Hash

The hash of a block header.

Example

> bitcoin-cli -testnet getblockhash 240886

Return:

00000000a0faf83ab5799354ae9c11da2a2bd6db44058e03c528851dee0a3fff

getblocktemplate

getblocktemplate [client capabilities]

Get a block template or proposal which mining software can use to construct a block and hash its header, as defined by BIP22.

Argument: Client Capabilities

String; optional: a JSON object containing an optional mode (of which template is both the default and only currently-allowed option) and an optional capabilities JSON array of elements describing capabilities supported by the client. Known capabilities include (but are not limited to): longpoll, coinbasetxn, coinbasevalue, proposal, serverlist, and workid.

{  "mode":"template"  "capabilities":[      "<supported capability>"      ,[...]    ]}

Result: Information Necessary To Construct The Next Block

A JSON object containing all the information necessary to construct a block which can be added to the block chain. This is a considerable amount of information, so the JSON object is described below in parts.

{  "version" : <version number>,  "previousblockhash" : "<hex block header hash>",

The block version number and the hash of the previous block header, both of which must be added to this block’s header.

  "transactions" : [

An array of transactions in transaction object format.

      {         "data" : "<hex transaction data> ",         "hash" : "<hex txid>",

Each object in the array contains the rawtransaction data in hex and the hash of the data in little-endian hex.

         "depends" : [             <index number>             ,[...]         ],

If the transaction depends on one or more transaction in the array, the dependent transactions are listed in the depends array by their index number in the transactions array (starting from 1).

         "fee": <number in satoshis>,         "sigops" : <sigops number>         "required" : <true|false>      }

The fee paid by the transaction and the number of signature operations (sigops) it uses which count towards the 20,000 maximum in blocks. Also whether or not the transaction is required to be in the block produced in order for that block to be accepted by Bitcoin Core (this is mainly used by mining pools). Note: if required is omitted, it is false.

      ,[...]  ],

(More transactions.)

  "coinbaseaux" : {      "<flag>" : "<data>"  },

Hex-encoded data identified by flag which should be included in the coinbase field of the coinbase transaction. The flag is for the benefit of mining software—only the data is included.

  "coinbasevalue" : <number in satoshis>

The coinbasevalue, the maximum number of satoshis which the coinbase transaction can spend (including the block reward) if all the transactions provided in the transaction array are included in the block.

  "coinbasetxn" : { <coinbase transaction> },

The coinbasetxn is a JSON object in transaction object format which describes the coinbase transaction.

  "target" : "<target hash>",

The target threshold for the block. In solo mining, this may be the network target (difficulty). In pooled mining, this is the target to generate a share.

  "mintime" : <epoch time>,

The minimum time the for the block header time in Unix epoch time format (number of seconds elapsed since 1970-01-01T00:00 UTC.

  "mutable" : [     "<value>"     ,[...]  ],

An array of values which describe how the client can modify the block template. For example, “time” to change the block header time or “transactions” to add or remove transactions.

  "noncerange" : "<min nonce hex><max nonce hex>",

Two 32-bit integers, concatenated in big-endian hexadecimal, which represent the valid ranges of block header nonces the miner may scan.

  "sigoplimit" : <number of sigops>,  "sizelimit" : <number of bytes>,

The limitations of block signature operations (sigoplimit) in number and block size (sizelimit) in bytes.

  "curtime" : <epoch time>,  "bits" : "<compressed target>",  "height" : <number of previous blocks>}

The current time in Unix epoch format (curtime), the compressed network target (difficulty) of the block being worked on (bits), and the height of the block being worked on.

Example

Getting the block template from a default Bitcoin Core 0.9.1 with the optional parameters “longpoll” and “workid” (which have no effect on default Bitcoin Core).

> bitcoin-cli -testnet getblocktemplate '{"capabilities":["longpoll", "workid"]}'

Result (long lines have been wrapped (\) and some data has been omitted ([…]):

{    "version" : 2,    "previousblockhash" : "000000005767babc38ebd1807def40cb47dfe\                           f29ef712de9d85c77ad8e039b9d",    "transactions" : [        {            "data" : "0100000001438a4d7a2333c3579b81d59f562d2af8\                      69c142f697546465339c67028f44aa65000000006b\                      483045022100eb31779b1e162e27825c5f52a1378f\                      8d90994999df58706cf29bd78c80f6920a022063c0\                      4eb627166eab60d36caacaa68a0fd805923442a3cd\                      db6babacb6b4706cc90121031a2761284af7f291e8\                      0f061f6eace13e3ea9b2aa3b0ac5407b7a21a5d43f\                      3174ffffffff0200e1f505000000001976a914a11b\                      66a67b3ff69671c8f82254099faf374b800e88ace0\                      5c9041000000001976a91406e1c288b96002df7442\                      bb1ec6c43419a1f1e74988ac00000000",            "hash" : "d471fda51e1d7284add729e44b5d8d8a462e5d4151\                      6f0a1efda712cfa76e310e",            "depends" : [            ],            "fee" : 20000,            "sigops" : 2        },        {            "data" : "[...]",            "hash" : "5c1e046ec13bd1fad71153aa28811ecad241233960\                      efca32f5554d233ff29f7f",            "depends" : [            ],            "fee" : 0,            "sigops" : 2        },        [...]    ],    "coinbaseaux" : {        "flags" : "062f503253482f"    },    "coinbasevalue" : 2500320000,    "target" : "000000000001968c00000000000000000000000000000000\                0000000000000000",    "mintime" : 1398693714,    "mutable" : [        "time",        "transactions",        "prevblock"    ],    "noncerange" : "00000000ffffffff",    "sigoplimit" : 20000,    "sizelimit" : 1000000,    "curtime" : 1398698437,    "bits" : "1b01968c",    "height" : 227051}

getconnectioncount

getconnectioncount

Returns the number of connections to other nodes.

Result

The number of connections.

Example

> bitcoin-cli -testnet getconnectioncount

Result:

14

getdifficulty

getdifficulty

Returns the proof-of-work difficulty as a decimal multiple of the minimum difficulty.

Result

The difficulty number.

Example

> bitcoin-cli -testnet getdifficulty 

Result:

1.00000000

getgenerate

getgenerate

Return true if the server is set to generate blocks.

Result

True if the server is set to generate blocks; false if not.

Example

> bitcoin-cli -testnet getgenerate

Result:

false

gethashespersec

gethashespersec

Returns a recent hashes per second performance measurement while generating blocks.

Result

A number of hashes per second.

Example

> bitcoin-cli -testnet gethashespersec                               

Result:

1995356

getinfo

getinfo

Prints various information about the node and the network.

Result

A JSON object containing several key/value pairs, most of them self-explanatory. Exceptions are version for the node’s version, keypoololdest for the oldest pre-generated key in the key pool, and unlocked_until for the epoch time until the wallet becomes locked again (0 for locked now).

{  "version": <number>,  "protocolversion": <number>,  "walletversion": <number>,  "balance": <decimal bitcoins>,  "blocks": <block height>,  "timeoffset": <seconds>,  "connections": <number of connections>,  "proxy": "<host>:<port>",  "difficulty": <difficulty number>,  "testnet": <true|false>,  "keypoololdest": <epoch time>,  "keypoolsize": <number of unused pre-generated keys>,  "paytxfee": <decimal bitcoins>,  "unlocked_until": <epoch time>,  "errors": [error list, if any]}

Example

> bitcoin-cli -testnet getinfo

Result:

{    "version" : 90100,    "protocolversion" : 70002,    "walletversion" : 60000,    "balance" : 0.59960000,    "blocks" : 240465,    "timeoffset" : 0,    "connections" : 22,    "proxy" : "",    "difficulty" : 1.00000000,    "testnet" : true,    "keypoololdest" : 1398809500,    "keypoolsize" : 201,    "paytxfee" : 0.00100000,    "unlocked_until" : 2399308877,    "errors" : ""}

getmininginfo

getmininginfo

Get mining-related information.

Result

A JSON object with key/value pairs describing the current block’s height, currentblocksize in bytes, currentblocktx count, network difficulty, any errors, whether or not the node is attempting to generate blocks, the number of processors being used for generation (genproclimit), the number of hashespersec, the size of the memory pool (pooledtx), and whether or not the node is on testnet.

{  "blocks": <block height>,  "currentblocksize": <number of bytes>,  "currentblocktx": <number of transactions>,  "difficulty": <difficulty number>,  "errors": [error descriptions],  "generate": <true|false>,  "genproclimit": <number of processors used>,  "hashespersec": <hash rate number>,  "pooledtx": <number of transactions>,  "testnet": <true|false>}

Example

> bitcoin-cli -testnet getmininginfo

Result:

{    "blocks" : 240470,    "currentblocksize" : 4447,    "currentblocktx" : 14,    "difficulty" : 1.00000000,    "errors" : "",    "genproclimit" : -1,    "networkhashps" : 79921644298,    "pooledtx" : 19,    "testnet" : true,    "generate" : false,    "hashespersec" : 0}

getnettotals

getnettotals

Returns information about network traffic, including bytes in, bytes out, and current time.

Result

A JSON object describing the totalbytesrecv, totalbytessent, and total number of milliseconds elapsed since 1970-01-01T00:00 UTC.

{  "totalbytesrecv": <number of bytes>,  "totalbytessent": <number of bytes>,  "timemillis": <number of milliseconds since the Unix epoch>}

Example

> bitcoin-cli -testnet getnettotals

Result:

{    "totalbytesrecv" : 15445246,    "totalbytessent" : 59104882,    "timemillis" : 1399419870758}

getnetworkhashps

getnetworkhashps [blocks] [height]

Returns the estimated current or historical network hashes per second based on the last n blocks

Argument #1: Number Of Blocks To Average

Number; optional: the number of blocks to average together for calculating the estimated hashes per second. Defaults to 120. Use -1 to average all blocks produced since the last difficulty change.

Argument #2: Block Height

Number; optional: the block height of the last block to use for calculating the average. Defaults to -1 (the most recent block).

Result: Estimated Hashes Per Second

Number: the estimated hashes per second.

Example

Get the average hashes per second for all the blocks since the last difficult change before block 227255.

> bitcoin-cli -testnet getnetworkhashps -1 227255

Result:

79510076167

getnewaddress

getnewaddress [account]

Returns a new Bitcoin address for receiving payments. If account is specified, payments received with the address will be credited to that account.

Argument: An Account Name

String; optional: the name of an account with which to associate the new account. If the account doesn’t exist, it will be created. If account isn’t specified, the default account (“”) will be used.

Result: A New Bitcoin Address

A new Bitcoin address is returned.

Example

Create a new address in the “doc test” account:

> /bitcoin-cli -testnet getnewaddress "doc test"

Result:

mft61jjkmiEJwJ7Zw3r1h344D6aL1xwhma

getpeerinfo

getpeerinfo

Returns data about each connected network node.

Result

A JSON array of JSON objects, with each object describing a connected network node.  Addr is the node’s address and port; addrlocal is your IP address and port as seen by the node; services is the services provided by the node.

Lastsend and lastrecv describe when you last communicated with the node; bytessent and bytesrecv describe the bandwidth used; conntime is when you connected to the node in epoch time; pingwait and pingtime describe the ping settings.

Version is the node’s numeric client version; subver is its text version; inbound is whether or not the node connected to you first; startingheight is the node’s earliest block.

Banscore is the misbehavior number for the node.

[  {    "addr":"<host>:<port>",    "addrlocal":"<ip>:<port>",    "services":"<services>",    "lastsend": <epoch time>,    "lastrecv": <epoch time>,    "bytessent": <number of bytes>,    "bytesrecv": <number of bytes>,    "conntime": <epoch time>,    "pingtime": <seconds>,    "pingwait": <seconds>,    "version": <version number>,    "subver": "/<string>/",    "inbound": <true|false>,    "startingheight": <block height>,    "banscore": <decimal ban score>,    "syncnode" : <true|false>  }  ,[...]]

Example

> bitcoin-cli -testnet getpeerinfo | head -n20

Result (only first object shown):

[    {        "addr" : "162.216.6.146:18333",        "addrlocal" : "68.39.150.9:18333",        "services" : "00000001",        "lastsend" : 1399423346,        "lastrecv" : 1399423329,        "bytessent" : 210597,        "bytesrecv" : 300962,        "conntime" : 1399383781,        "pingtime" : 0.00000000,        "version" : 70001,        "subver" : "/Satoshi:0.8.5/",        "inbound" : false,        "startingheight" : 240213,        "banscore" : 0    },

getrawchangeaddress

getrawchangeaddress

Returns a new Bitcoin address, for receiving change. This is for use with raw transactions, not normal use.

Result

The address.

Example

> bitcoin-cli -testnet getrawchangeaddress

Result:

mnycUc8FRjJodfKhaj9QBZs2PwxxYoWqaK

getrawmempool

getrawmempool [true|false]

Returns all transaction identifiers (txids) in the memory pool as a JSON array or detailed information each transaction in the memory pool as a JSON object.

Argument: Detailed JSON Object Or JSON Array Of Txids

Boolean; optional: for a detailed JSON object describing each transaction in the memory pool, true. For a JSON array with each txid as a string, false (the default).

Result For False: An Array Of Txids

A JSON array of txids:

[  "<txid>"  ,[...]]

Result For True: A JSON Object Describing Each Transaction

A JSON object containing a list of JSON objects, with each object’s key being a txid and its value being a JSON object containing the following information: the transaction size in bytes, the fee paid, the time the transaction entered the pool (in Unix epoch time), the block height when the transaction entered the pool, the starting priority when the transaction entered the pool and its current priority, plus an array of unconfirmed txid’s this transaction depends on.

{  "transactionid" : {    "size" : <size in bytes>    "fee" : <fee in decimal bitcoins>    "time" : <epoch time>    "height" : <block height>    "startingpriority" : <priority number when first seen>    "currentpriority" : <current priority number>    "depends" : [        "<txid>",       [...] ]  }, [...]]

Examples

The default (false):

> bitcoin-cli -testnet getrawmempool

[    "2b1f41d6f1837e164d6d6811d3d8dad2e66effbd1058cd9ed7bdbe1cab20ae03",    "2baa1f49ac9b951fa781c4c95814333a2f3eda71ed3d0245cd76c2829b3ce354"]

Verbose output (true):

> bitcoin-cli -testnet getrawmempool

{    "2b1f41d6f1837e164d6d6811d3d8dad2e66effbd1058cd9ed7bdbe1cab20ae03" : {        "size" : 3176,        "fee" : 0.00040000,        "time" : 1398867801,        "height" : 227310,        "startingpriority" : 97456429.70512821,        "currentpriority" : 97456429.70512821,        "depends" : [        ]    },    "2baa1f49ac9b951fa781c4c95814333a2f3eda71ed3d0245cd76c2829b3ce354" : {        "size" : 191,        "fee" : 0.00020000,        "time" : 1398867772,        "height" : 227310,        "startingpriority" : 54545454.54545455,        "currentpriority" : 54545454.54545455,        "depends" : [        ]    }}

getrawtransaction

getrawtransaction <txid> [true|false]

Get the rawtransaction-format data for a transaction or a JSON object describing the transaction. By default, bitcoind only stores complete transaction data for UTXOs and your own transactions, so the RPC may fail on historic transactions unless you use the non-default txindex=1 in your bitcoind startup settings.

See also: decoderawtransaction

Argument #1: The Transaction Txid

String; required: the txid (hash) of the transaction to get.

Argument #2: Get Hex Or JSON Object

Number; optional: either 0 (the default) to get the transaction in rawtransaction format (hex), or 1 to get a JSON object describing the transaction.

Result: Rawtransaction Hex Or Description In JSON

If 0, a hex string with the complete (signed) transaction as it appears in the block chain or memory pool.

If 1, a JSON object describing the transaction. See decoderawtransaction for a format description.

Examples:

A transaction in rawtransaction format:

> bitcoin-cli -testnet getrawtransaction \              ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e

Result:

0100000001268a9ad7bfb21d3c086f0ff28f73a064964aa069ebb69a9e437da8\5c7e55c7d7000000006b483045022100ee69171016b7dd218491faf6e13f53d4\0d64f4b40123a2de52560feb95de63b902206f23a0919471eaa1e45a0982ed28\8d374397d30dff541b2dd45a4c3d0041acc0012103a7c1fd1fdec50e1cf3f0cc\8cb4378cd8e9a2cee8ca9b3118f3db16cbbcf8f326ffffffff0350ac60020000\00001976a91456847befbd2360df0e35b4e3b77bae48585ae06888ac80969800\000000001976a9142b14950b8d31620c6cc923c5408a701b1ec0a02088ac002d\3101000000001976a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac\00000000

Get the same transaction in JSON:

> bitcoin-cli -testnet getrawtransaction            ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e \            1

Result:

{    "hex" : "0100000001268a9ad7bfb21d3c086f0ff28f73a064964aa069e\             bb69a9e437da85c7e55c7d7000000006b483045022100ee6917\             1016b7dd218491faf6e13f53d40d64f4b40123a2de52560feb9\             5de63b902206f23a0919471eaa1e45a0982ed288d374397d30d\             ff541b2dd45a4c3d0041acc0012103a7c1fd1fdec50e1cf3f0c\             c8cb4378cd8e9a2cee8ca9b3118f3db16cbbcf8f326ffffffff\             0350ac6002000000001976a91456847befbd2360df0e35b4e3b\             77bae48585ae06888ac80969800000000001976a9142b14950b\             8d31620c6cc923c5408a701b1ec0a02088ac002d31010000000\             01976a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488\             ac00000000",    "txid" : "ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e",    "version" : 1,    "locktime" : 0,    "vin" : [        {            "txid" : "d7c7557e5ca87d439e9ab6eb69a04a9664a0738ff20f6f083c1db2bfd79a8a26",            "vout" : 0,            "scriptSig" : {                "asm" : "3045022100ee69171016b7dd218491faf6e13f5\                3d40d64f4b40123a2de52560feb95de63b902206f23a0919\                471eaa1e45a0982ed288d374397d30dff541b2dd45a4c3d0\                041acc001 03a7c1fd1fdec50e1cf3f0cc8cb4378cd8e9a2\                cee8ca9b3118f3db16cbbcf8f326",                "hex" : "483045022100ee69171016b7dd218491faf6e13\                f53d40d64f4b40123a2de52560feb95de63b902206f23a09\                19471eaa1e45a0982ed288d374397d30dff541b2dd45a4c3\                d0041acc0012103a7c1fd1fdec50e1cf3f0cc8cb4378cd8e\                9a2cee8ca9b3118f3db16cbbcf8f326"            },            "sequence" : 4294967295        }    ],    "vout" : [        {            "value" : 0.39890000,            "n" : 0,            "scriptPubKey" : {                "asm" : "OP_DUP OP_HASH160 56847befbd2360df0e35b\                4e3b77bae48585ae068 OP_EQUALVERIFY OP_CHECKSIG",                "hex" : "76a91456847befbd2360df0e35b4e3b77bae48585ae06888ac",                "reqSigs" : 1,                "type" : "pubkeyhash",                "addresses" : [                    "moQR7i8XM4rSGoNwEsw3h4YEuduuP6mxw7"                ]            }        },        {            "value" : 0.10000000,            "n" : 1,            "scriptPubKey" : {                "asm" : "OP_DUP OP_HASH160 2b14950b8d31620c6cc92\                3c5408a701b1ec0a020 OP_EQUALVERIFY OP_CHECKSIG",                "hex" : "76a9142b14950b8d31620c6cc923c5408a701b1ec0a02088ac",                "reqSigs" : 1,                "type" : "pubkeyhash",                "addresses" : [                    "mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN"                ]            }        },        {            "value" : 0.20000000,            "n" : 2,            "scriptPubKey" : {                "asm" : "OP_DUP OP_HASH160 0dfc8bafc8419853b34d5\                e072ad37d1a5159f584 OP_EQUALVERIFY OP_CHECKSIG",                "hex" : "76a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac",                "reqSigs" : 1,                "type" : "pubkeyhash",                "addresses" : [                    "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe"                ]            }        }    ],    "blockhash" : "00000000103e0091b7d27e5dc744a305108f0c752be249893c749e19c1c82317",    "confirmations" : 216,    "time" : 1398734825,    "blocktime" : 1398734825}

getreceivedbyaccount

getreceivedbyaccount <account> <confirmations>

Returns the total amount received by addresses in a particular account from transactions with the specified number of confirmations.

Argument #1: The Account Name

String; required: the name of the account. Use “” for the default account.

Argument #2: The Minimum Number Of Confirmations

Number; optional: the Minimum number of confirmations a transaction must have before it is counted.

Result: Decimal Bitcoins

Number: the number of satoshis received in decimal bitcoins.

Example

Get the satoshis received by the “doc test” account with six or more confirmations:

> bitcoin-cli -testnet getreceivedbyaccount "doc test" 6

Result:

0.30000000

getreceivedbyaddress

getreceivedbyaddress <address> [confirmations]

Returns the total amount received by the specified address in transactions with at least the indicated number of confirmations.

Argument #1: A Bitcoin Address

String; required: a Bitcoin address to check. Must be an address belonging to the wallet.

Argument #2: The Minimum Number Of Confirmations

Number; optional: the minimum number of confirmations a transaction must have before it is counted towards the total. 1 is the default; use 0 to also count unconfirmed transactions.

Result: The Number Of Decimal Bitcoins Received

The number of decimal bitcoins received by the address.

Example

Get the amount of satoshis received by the following address with at least six confirmations.

> bitcoin-cli -testnet getreceivedbyaddress mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN 6

Result:

0.30000000

gettransaction

gettransaction <txid>

Get detailed information about an in-wallet transaction.

Argument: A Transaction Identifier (txid)

String; required: a transaction identifier (txid) for the transaction to get information about.

Result: A Description Of The Transaction

String: a JSON object describing the transaction: the amount of the transaction in decimal bitcoins, the number of confirmations the transaction has, the blockhash (if any) the transaction appeared in and also that block’s height (blockindex) and blocktime, the txid (same as you provided), and an array of details about each input and output in the transaction.

The details array includes the account the transaction belongs to (“” for the default account), the address used in the input or output, the category (input or output), and the amount of the particular input or output.

Last is the rawtransaction format hex of the transaction.

{  "amount" : <decimal bitcoins>,  "confirmations" : <number>,  "blockhash" : "<hash>",  "blockindex" : <block height>,  "blocktime" : <epoch time>,  "txid" : "<txid>",  "time" : <epoch time>,  "timereceived" : <epoch time>,  "details" : [    {      "account" : "<account>",      "address" : "<address>",      "category" : "<send|receive>",      "amount" : <decimal bitcoins>    }    ,[...]  ],  "hex" : "<raw transaction hex>"}

Example

> bitcoin-cli -testnet gettransaction \            5a7d24cd665108c66b2d56146f244932edae4e2376b561b3d396d5ae017b9589

Result:

{    "amount" : 0.00000000,    "fee" : 0.00000000,    "confirmations" : 18707,    "blockhash" : "000000008b630b3aae99b6fe215548168bed92167c47a2f7ad4df41e571bcb51",    "blockindex" : 1,    "blocktime" : 1396321351,    "txid" : "5a7d24cd665108c66b2d56146f244932edae4e2376b561b3d396d5ae017b9589",    "walletconflicts" : [    ],    "time" : 1396318587,    "timereceived" : 1396318587,    "details" : [        {            "account" : "",            "address" : "mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN",            "category" : "send",            "amount" : -0.10000000,            "fee" : 0.00000000        },        {            "account" : "doc test",            "address" : "mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN",            "category" : "receive",            "amount" : 0.10000000        }    ],    "hex" : "0100000001cde58f2e37d000eabbb60d9cf0b79ddf67cede6db\             a58732539983fa341dd5e6c010000006a47304402201feaf129\             08260f666ab369bb8753cdc12f78d0c8bdfdef997da17acff50\             2d321022049ba0b80945a7192e631c03bafd5c6dc3c7cb35ac5\             c1c0ffb9e22fec86dd311c01210321eeeb46fd878ce8e62d5e0\             f408a0eab41d7c3a7872dc836ce360439536e423dffffffff01\             80969800000000001976a9142b14950b8d31620c6cc923c5408\             a701b1ec0a02088ac00000000"}

gettxout

gettxout <txid> <output index number> [true|false]

Returns details about an unspent transaction output (UTXO).

Argument #1: A Transaction Identifier (txid)

String; required: the txid of the transaction the UTXO belongs to.

Argument #2: An Output Index Number

Number; required: the output index number (vout) of the UTXO.

Argument #3: Whether To Display Outputs From The Memory Pool

Boolean; optional: display UTXOs from the memory pool with true, or only to display UTXOs on the block chain with false (the default).

Result: A Description Of The Output

String: A JSON object describing the output, with bestblock providing the header hash of the block which includes the UTXO (if any), the number of confirmations the UTXO has, the value of the output in decimal bitcoins, and a JSON object describing the output script, including the script in script psuedocode (asm), the script in hex, the number of required signatures, the type of output script, and the addresses it references (if known). Also provided are the UTXO’s transaction version number and whether or not it’s a coinbase transaction.

{  "bestblock" : "<hash>",  "confirmations" : <number>,  "value" : <decimal bitcoins>,  "scriptPubKey" : {     "asm" : "<psuedo code>",     "hex" : "<rawtransaction hex>",     "reqSigs" : <number>,     "type" : "<type>",     "addresses" : [        "<address>"        ,[...]     ]  },  "version" : <number>,  "coinbase" : <true|false>}

Example

Get the UTXO from the following transaction from the third output index (“2”), searching the memory pool if necessary.

> bitcoin-cli -testnet gettxout \              ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e \              2 true

Result:

{    "bestblock" : "0000000020183137a80225af8ee2a523220af75c96e06b63f9dcd7eb7b059688",    "confirmations" : 240,    "value" : 0.20000000,    "scriptPubKey" : {        "asm" : "OP_DUP OP_HASH160 \        0dfc8bafc8419853b34d5e072ad37d1a5159f584 OP_EQUALVERIFY OP_CHECKSIG",        "hex" : "76a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac",        "reqSigs" : 1,        "type" : "pubkeyhash",        "addresses" : [            "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe"        ]    },    "version" : 1,    "coinbase" : false}

gettxoutsetinfo

gettxoutsetinfo

Returns statistics about the unspent transaction output set. Note this call may take some time.

Result

A JSON object with key/value pairs describing the UTXO set: height is the current block height; bestblock is the hash of the most recent block; transactions is the number of transactions with UTXOs; txouts is the number of UTXOs; bytes_serialized in the size of the UTXO set in bytes; hash_serialized is the hash of the complete UTXO set; total_amount is the total amount of decimal bitcoins in the UTXO set.

{  "height":<block height>,  "bestblock": <block header hash>,  "transactions": <number>,  "txouts": <number>,  "bytes_serialized": <number of bytes>,  "hash_serialized": <hash>,  "total_amount": <decimal bitcoins>}

Example

> bitcoin-cli -testnet gettxoutsetinfo

Result:

{    "height" : 240479,    "bestblock" : "0000000000e8801ce010028a8a614e8f593db9b156ac54369b478c74f8005ee4",    "transactions" : 371826,    "txouts" : 2273512,    "bytes_serialized" : 75018402,    "hash_serialized" : "9aa9969c8d87c9c25aff0ac3b09a2fcdba25408d87444adce7ed30497276014b",    "total_amount" : 11261448.49446353}

getunconfirmedbalance

getunconfirmedbalance

Returns the wallet’s total unconfirmed balance

Result

The unconfirmed balance in decimal bitcoins.

Example

> bitcoin-cli -testnet getunconfirmedbalance                         

Result (no satoshis unconfirmed):

0.00000000

getwork

getwork [data]

Provides a block header which can be hashed to attempt to find the next block, and lets a miner return a successful header.

Argument: A Header Hash

String; optional: if header data is provided, it will be checked to see if it meets the target threshold (difficulty) and then affixed to a block of transactions (which produces a matching Merkle root). Then the complete block will be broadcast to the network. Data is in the same format as provided by the data output parameter (see below).

Result #1: Hashing Data

String: A JSON object with four key/value pairs is returned. data is the block data used by mining software and target is the hash target either for the network or for the mining pool. The other two parameters, midstate and hash1, are deprecated.

{  "midstate" : "<hash>",  "data" : "<hex data>",  "hash1" : "<hex data>",  "target" : "<target hex>"}

Result #2: Whether The Block Was Accepted

Boolean: either true or false depending on whether or not the data was accepted.

Examples

Get work:

> bitcoin-cli -testnet getwork

Result:

{    "midstate" : "c9c4c5ce837b181be3c8f1de27657eeadba9d4860be9b8f82db0b6c061e2d9da",    "data" : "000000026d49c668f433f5ed3e0c8357466f0416818f7aa29b\              c8d8d8d158d63b000000007cf7260312d8d5bfc098d066d600\              62c09776c9595521aeb6eb2c552f7174df0a536158061b0196\              8c000000000000008000000000000000000000000000000000\              00000000000000000000000000000000000000000000000080\              020000",    "hash1" : "0000000000000000000000000000000000000000000000000\               0000000000000000000008000000000000000000000000000\               000000000000000000000000010000",    "target" : "000000000000000000000000000000000000000000000000\                8c96010000000000"}

Submit data: (we’ll submit the data we just received, which is highly unlikely to hash to a value below the target threshold)

> bitcoin-cli -testnet getwork 000000026d49c668f433f5ed3e0c8357466\            f0416818f7aa29bc8d8d8d158d63b000000007cf7260312d8d5b\            fc098d066d60062c09776c9595521aeb6eb2c552f7174df0a536\            158061b01968c000000000000008000000000000000000000000\            0000000000000000000000000000000000000000000000000000\            0000080020000

Result:

false

help

help [RPC]

List all commands, or get help for the specified RPC.

Argument: An RPC

String, optional: get detailed help for the specified RPC.

Result: A List Of RPCs Or Detailed Help

If an RPC was specified, detailed help for that RPC. If nothing specified, a list of available RPCs.

Example

Command to get a description similar to this subsection:

> bitcoin-cli -testnet help help

importprivkey

importprivkey <private key> [label] [rescan]

Adds a private key (in the format created by dumpprivkey to your wallet.

Argument #1: Private Key

String; required: a private key in the hexadecimal format created by dumpprivkey.

Argument #2: Label

String; optional: the name to associate with the address corresponding to the private key. Defaults to no label.

Argument #3: Whether To Rescan The Block Chain

Boolean; optional: whether or not to rescan the saved block chain data for transactions related to this private key. If true, scans the block chain (which may take a while); if false, only show transactions related to this key from the UTXO set. The default is true.

Result: None On Success

No result generated if key imported successfully.

Example

Import the private key for the address mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe, giving it a label and scanning the entire block chain:

> bitcoin-cli -testnet importprivkey \              cU8Q2jGeX3GNKNa5etiC8mgEgFSeVUTRQfWE2ZCzszyqYNK4Mepy \              "test label" \              true

(Success: no result generated.)

importwallet

importwallet <filename>

Imports private keys from a file in wallet dump file format (see dumpwallet). These keys will be added to the keys currently in the wallet.

Argument: The Filename

String; required: the filename of the wallet file relative to the working directory ofbitcoind.

Result: None On Success

No result generate on successful import.

Example

Import the file shown in the example subsection of dumpwallet.

> bitcoin-cli -testnet importwallet /tmp/dump.txt

(Success: no result generated.)

keypoolrefill

keypoolrefill [size]

Fills the cache of unused pre-generated keys, the keypool. Requires the wallet be unlocked if encryption is used.

Argument: New Keypool Size

Number; optional: the number of keys which should be in the keypool after generating new cache keys. Defaults to 100.

Result: None On Success

No result generated on success.

Example

Generate one extra key than the default:

> bitcoin-cli -testnet keypoolrefill 101

listaccounts

listaccounts [minconf]

Provides a JSON object which lists accounts and their balances.

Argument: Minimum Number Of Confirmations

Number; optional: the minimum number of confirmations an incoming transaction must have before it is counted towards the balance. Outgoing transactions are counted regardless of the number of confirmations. Default is 1; use 0 to count unconfirmed transactions.

Result: A JSON Object With Paired Account/Balance Values

A JSON object is produced which lists every account name and its corresponding value in decimal bitcoins. “” is the default account. Balance can be negative if transaction fees paid by this account exceed satoshis received.

~~~{  "<account>": <balance in decimal bitcoins>,  [...]}~~~

Example

> bitcoin-cli -testnet listaccounts

Result:

{    "" : -1.40010000,    "Refund from example.com" : 0.00000000,    "doc test" : 0.30000000,    "test" : 0.00000000,    "test account" : 0.00000000,    "test label" : 0.29960000,    "test1" : 1.69900000}

listaddressgroupings

listaddressgroupings

Lists groups of addresses which have had their common ownership made public by common use as inputs or as the resulting change in past transactions.

Result

A JSON array of JSON arrays of JSON arrays, with the inner array listing address, amount, and account tuples. The middle array shows which of the tuples are associated with each other. The outer array simply stores the results.

[  [    [      "<address>",      <amount in decimal bitcoins>,      "<account>"    ]    ,...  ]  ,...]

Example

> bitcoin-cli -testnet listaddressgroupings

Result (truncated):

[    [        [            "mgKgzJ7HR64CrB3zm1B4FUUCLtaSqUKfDb",            0.00000000        ],        [            "mnUbTmdAFD5EAg3348Ejmonub7JcWtrMck",            0.00000000,            "test1"        ],        [            "myNrzM1Dda4t1q4UEqwuRosapCbBA8z61o",            0.00000000        ],        [            "moQR7i8XM4rSGoNwEsw3h4YEuduuP6mxw7",            0.00000000        ],        [            "mpHeUC7RGRaypfcLNGNrGgfkT872WnKasb",            0.00000000        ]    ],

listlockunspent

listlockunspent

Returns list of temporarily unspendable outputs.

See also: lockunspent

Result

A JSON array of JSON objects, with each object listing a locked txid and output index number (vout).

[  {    "txid" : "<txid>",    "vout" : <output index number>  }  ,[...]]

Example

> bitcoin-cli -testnet listlockunspent

Result:

[    {        "txid" : "ca7cb6a5ffcc2f21036879493db4530c0ce9b5bff9648f9a3be46e2dfc8e0166",        "vout" : 0    }]

listreceivedbyaccount

listreceivedbyaccount [confirmations] [true|false]

List the total number of bitcoins received by each account.

Argument #1: Minimum Number Of Confirmations

Number; optional: the minimum number of confirmations an incoming transaction must have before it is counted towards the balance. Outgoing transactions are counted regardless of the number of confirmations. Default is 1; use 0 to count unconfirmed transactions.

Argument #2: Whether To Include Empty Accounts

Boolean; optional: whether or not accounts which have not received a payment should be included in the results. Defaults to true to display all accounts.

Result: Account Names, Balances, And Minimum Confirmations

A JSON array of JSON objects, with each object containing an account name, an amount in decimal bitcoins, and the confirmation score of the transaction most recently received by that account.

[  {    "account" : "<account>",    "amount" : <decimal bitcoins>,    "confirmations" : <number of confirmations>  }  ,[...]]

Example

Get the balances for all non-empty accounts, including only transactions which have been confirmed at least six times:

> bitcoin-cli -testnet listreceivedbyaccount 6 false

Result:

[    {        "account" : "",        "amount" : 0.19960000,        "confirmations" : 53601    },    {        "account" : "doc test",        "amount" : 0.30000000,        "confirmations" : 8991    }]

listreceivedbyaddress

listreceivedbyaddress [confirmations] [true|false]

List the total number of bitcoins received by each account.

Argument #1: Minimum Number Of Confirmations

Number; optional: the minimum number of confirmations an incoming transaction must have before it is counted towards the balance. Outgoing transactions are counted regardless of the number of confirmations. Default is 1; use 0 to count unconfirmed transactions.

Argument #2: Whether To Include Empty Accounts

Boolean; optional: whether or not addresses which have not received a payment should be included in the results. Defaults to false to display only addresses which have received payment.

Result: Addresses, Account Names, Balances, And Minimum Confirmations

A JSON array of JSON objects, with each object containing an address, the account that address belongs to, an amount in decimal bitcoins, and the confirmation score of the transaction most recently received by that address. Also provided is a txids JSON array of txids affecting that address.

[  {    "address" : "<address>",    "account" : "<account>",    "amount" : <amount in decimal bitcoins>,    "confirmations" : <number of confirmations>    [        "txids" : [            "<txid>",            [...]    ]  }  ,[...]]

Example

List addresses with balances confirmed by at least six blocks:

> bitcoin-cli -testnet listreceivedbyaddress 6

Result (truncated after first entry):

[    {        "address" : "mnUbTmdAFD5EAg3348Ejmonub7JcWtrMck",        "account" : "test1",        "amount" : 1.99900000,        "confirmations" : 55680,        "txids" : [            "4d71a6127796766c39270881c779b6e05183f2bf35589261e9572436356f287f",            "997115d0cf7b83ed332e6c1f2e8c44f803c95ea43490c84ce3e9ede4b2e1605f"        ]    },[...]

listsinceblock

listsinceblock [block hash] [block depth]

Get all transactions affecting addresses in the wallet which have occurred since a particular block, plus the header hash of a block at a particular depth.

Argument #1: Block Hash

String; optional: the hash of a block header from which all subsequent transactions should be listed. If omitted, all transactions affecting addresses in this wallet which have occurred since the genesis block will be listed.

Argument #2: Block Depth For Header Hash

Number; optional: return the hash of a block header at a particular depth. The default is 1, which will return the most recent block header hash (the same result as thegetbestblockhash RPC).

Note: this argument does not affect which transactions are returned; it only changes thelastblock value in the returned data.

Result

A JSON object containing a transactions JSON array, with each JSON object in the array describing a single transaction: the name of the account the transaction affects (with “” for the default account), the Bitcoin address (not present for transactions between address in this wallet), the category of transaction (either send or receive), the amount of the transaction in decimal bitcoins (negative for sends), the fee, the number of confirmations, the blockhash and blocktime of the block the transaction appears in, the blockindex number indicating what number it was in the block (counting from one), the txid, the time and timereceived of the transaction, plus a comment and to (label) for the transaction, if set.

Outside of the array, the lastblock value stores the header hash of a block at the depth indicated by the second argument, the most recent block by default.

{  "transactions": [    "account":"<account>",    "address":"<address>",    "category":"<send|receive>",    "amount": <amount in decimal bitcoins>,    "fee": <amount in decimal bitcoins>,    "confirmations": <confirmations>,    "blockhash": "<hash>",    "blockindex": <block index number>,    "blocktime": <epoch time>,    "txid": "<txid>",    "time": <epoch time>,    "timereceived": <epoch time>,    "comment": "<comment>",    "to": "<label>",  ],  "lastblock": "<hash>"}

Example

Get all transactions since a particular block and the header hash of the sixth most recent block.

> bitcoin-cli -testnet listsinceblock \              00000000688633a503f69818a70eac281302e9189b1bb57a76a05c329fcda718 \              6

Result (some array objects removed):

{    "transactions" : [        {            "account" : "test1",            "address" : "mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN",            "category" : "send",            "amount" : -0.10000000,            "fee" : 0.00000000,            "confirmations" : 9213,            "blockhash" : "00000000103e0091b7d27e5dc744a305108f0c752be249893c749e19c1c82317",            "blockindex" : 2,            "blocktime" : 1398734825,            "txid" : "ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e",            "walletconflicts" : [            ],            "time" : 1398730842,            "timereceived" : 1398730842,            "comment" : "Example Transaction"        }    ],    "lastblock" : "00000000008e6ace6bf932022929da3dcdcdfcdad23503cb3007a041c7c89eb6"}

listtransactions

listtransactions [account] [count] [from]

Returns the most recent transactions.

Argument #1: An Account

String; optional: get transactions only for this account. Use “” for the default account. By default, gets all transactions for all accounts.

Argument #2: The Number Of Transactions To Get

Number; optional: get only this number of the most recent transactions. Defaults to 10.

Argument #3: The Number Of Transactions To Skip

Number; optional: skip the earliest number of transactions. Defaults to zero (don’t skip any transactions).

Result: Transaction Details

Returns a JSON array with JSON objects in the same format as listsinceblock.

Example

List the most recent nine transactions for the default account, skipping the first eight:

> bitcoin-cli -testnet listtransactions "" 9 8

Result:

[    {        "account" : "",        "address" : "mnUbTmdAFD5EAg3348Ejmonub7JcWtrMck",        "category" : "send",        "amount" : -0.99900000,        "fee" : -0.00100000,        "confirmations" : 55935,        "blockhash" : "000000000036f608beb8e7c8250098f18c66e2a8dbe14e1232d36452430ad97f",        "blockindex" : 1,        "blocktime" : 1391826572,        "txid" : "997115d0cf7b83ed332e6c1f2e8c44f803c95ea43490c84ce3e9ede4b2e1605f",        "walletconflicts" : [        ],        "time" : 1391740136,        "timereceived" : 1391740136    }]

listunspent

listunspent [minconf] [maxconf] [addresses]

Returns an array of unspent transaction outputs.

Argument #1: Minimum Number Of Confirmations

Number; optional: the minimum number of confirmations an incoming transaction must have before it is counted towards the balance. Spent UTXOs are not included regardless of the number of confirmations. Default is 1; use 0 to count unconfirmed transactions.

Argument #2: Maximum Number Of Confirmations

Number; optional: the maximum number of confirmations an incoming transaction may have to be included in the results. Default is 9,999,999; use 0 to count unconfirmed transactions.

Argument #3: An Array Of Addresses To Check

String; optional: A JSON array of addresses to check. Only UTXOs affecting these addresses will returned.

[  "<address>"  ,[...]]

Result: An Array Describing Each UTXO

A JSON array with a list of JSON objects, each object describing a single transaction: its txid, output index number (vout), address, the account that address belongs to, the unsigned scriptSig (scriptPubKey) to spend it, the amount in decimal bitcoins, and the number of confirmations the transactions has.

[  {    "txid" : "<txid>",    "vout" : <output index number>,    "address" : "<address>",    "account" : "<account>",    "scriptPubKey" : "<key>",    "amount" : <amount in decimal bitcoins>,    "confirmations" : <number>  }  ,[...]]

Example

Get all transactions confirmed at least 6 times for a particular address:

> bitcoin-cli -testnet listunspent 6 99999999 '''  [    "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe"  ]'''

Result:

[    {        "txid" : "6c5edd41a33f9839257358ba6ddece67df9db7f09c0db6bbea00d0372e8fe5cd",        "vout" : 0,        "address" : "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe",        "account" : "test label",        "scriptPubKey" : "76a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac",        "amount" : 0.09960000,        "confirmations" : 28332    },    {        "txid" : "ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e",        "vout" : 2,        "address" : "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe",        "account" : "test label",        "scriptPubKey" : "76a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac",        "amount" : 0.20000000,        "confirmations" : 9524    }]

lockunspent

lockunspent <true|false> <outputs>

Updates list of temporarily unspendable outputs.

Temporarily lock or unlock specified transaction outputs. A locked transaction output will not be chosen by automatic coin selection when spending bitcoins. Locks are stored in memory only, so nodes start with zero locked outputs and the locked output list is always cleared when a node stops or fails.

Argument #1: Lock (True) Or Unlock (False)

Boolean; required: whether to lock (true) or unlock (false) the outputs.

Argument #2: The Outputs To Lock Or Unlock

String; required: A JSON array of JSON objects. Each object has a transaction identifier (txid) and output index number (vout) for the output to lock or unlock.

[  {    "txid":"<transaction identifier (hash)>",    "vout": <output index number>  }  ,...]

Result

Boolean: true if the command was successful; false if it was not.

Example

Lock two outputs:

> bitcoin-cli -testnet lockunspent true '''  [     {       "txid": "5a7d24cd665108c66b2d56146f244932edae4e2376b561b3d396d5ae017b9589",      "vout": 0     },     {       "txid": "6c5edd41a33f9839257358ba6ddece67df9db7f09c0db6bbea00d0372e8fe5cd",       "vout": 0     }   ]'''

Result:

true

Unlock one of the above outputs:

> bitcoin-cli -testnet lockunspent false '''[   {     "txid": "5a7d24cd665108c66b2d56146f244932edae4e2376b561b3d396d5ae017b9589",    "vout": 0  } ]'''

Result:

true

move

move <account> <account> <amount> [minconf] [comment]

Move a specified amount from one account in your wallet to another.

Argument #1: From Account

String, required: the name of the account from which to move the funds. Use “” for the default account.

Argument #2: To Account

String, required: the name of the account to which the funds should be moved. Use “” for the default account.

Argument #3: Amount To Move

Number; required: the amount to move in decimal bitcoins.

Argument #4: Minimum Confirmations

Number; optional: the minimum number of confirmations an incoming transaction must have before it will be spent. Previously spent UTXOs are not included regardless of the number of confirmations. Default is 1; use 0 to spend unconfirmed transactions.

Argument #5: A Comment

String; optional: a comment to associate with this transaction.

Result: True Or False

True if the transaction is successfully broadcast.

Example

Move 0.1 bitcoins from “doc test” to “test1” using only transactions with a confirmation of 6 or higher, and giving the transaction the comment “Example move”:

> bitcoin-cli -testnet move "doc test" "test1" 0.1 6 "Example move"

Result:

true

ping

ping

Requests that a ping be sent to all other nodes, to measure ping time. Results provided in getpeerinfo pingtime and pingwait fields as decimal seconds. Ping command is handled in queue with all other commands, so it measures processing backlog, not just network ping.

Example

bitcoin-cli -testnet ping

(Success: no result printed.)

sendfrom

sendfrom <account> <address> <amount> [confirmations] [comment] [label]

Spend an amount from an account to a bitcoin address.

Argument #1: From Account

String, required: the name of the account from which to spend the funds. Use “” for the default account.

Argument #2: To Address

String, required: the address to which the funds should be spent. Use “” for the default account.

Argument #3: Amount To Spend

Number; required: the amount to spend in decimal bitcoins.

Argument #4: Minimum Confirmations

Number; optional: the minimum number of confirmations an incoming transaction must have before it will be spent. Previously spent UTXOs are not included regardless of the number of confirmations. Default is 1; use 0 to spend unconfirmed transactions.

Argument #5: A Comment

String; optional: a comment to associate with this transaction.

Argument #6: A Label

String; optional: the label (name) to give the recipient.

Result: TXID

A txid for the transaction created.

Example

Spend 0.1 bitcoins from the account “doc test” to the address indicated below using only UTXOs with at least six confirmations, giving the transaction the comment “Example spend” and labeling the spender “Example.com”:

bitcoin-cli -testnet sendfrom "doc test" \            mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe \            0.1 \            6 \            "Example spend" \            "Example.com"

Result:

ca7cb6a5ffcc2f21036879493db4530c0ce9b5bff9648f9a3be46e2dfc8e0166

sendmany

sendmany <account> <addresses & amounts> [confirmations] [memo]

Create and broadcast a transaction which spends outputs to multiple addresses.

Argument #1: Account From Which The Satoshis Should Be Sent

String; required: the wallet account from which the funds should be withdrawn. Can be “” for the default account.

Argument #2: The Output Address/Amount Pairs

String; required: a JSON object with addresses as keys and amounts as values.

{  "<address>":<amount in decimal bitcoins>  ,[...]}

Argument #3: The Minimum Number Of Confirmations For Inputs

Number; optional: the minimum number of confirmations an previously-received output must have before it will be spent. The default is 1 confirmation.

Argument #4: A Memo

String, optional: a memo to be recorded with this transaction for record-keeping purposes. The memo is not included in the transaction.

Result: A Transaction Identifier

String: a transaction identifier (txid) for the transaction created and broadcast to the peer-to-peer network.

Example

From the account test1, send 0.1 bitcoins to the first address and 0.2 bitcoins to the second address, with a memo of “Example Transaction”.

> bitcoin-cli -testnet sendmany \  "test1" \  '''    {       "mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN": 0.1,      "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe": 0.2    } ''' \  6       \  "Example Transaction"

Result:

ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e

sendrawtransaction

sendrawtransaction <hex> [true|false]

Broadcasts transaction in rawtransaction format to the peer-to-peer network.

See also: createrawtransaction and signrawtransaction

Argument #1: Raw Transaction

String; required: a fully-signed transaction in rawtransaction format (hex).

Argument #2: Whether To Allow High Fees

Boolean; optional: whether or not to allow the transaction to have a high transaction fee. Transaction fees are the difference between the sum of the inputs and the sum of the outputs, so a raw transaction which accidentally leaves off a change output, for example, can have a transaction fee dozens or hundreds of times larger than the network norm. If true is specified, that will be allowed. If false (the default), the transaction will be rejected with an informative error message.

Result: A TXID Or Error Message

If successful, the transaction’s txid (hash) will be returned. If unsuccessful, an error message will be returned.

Examples

Create and sign a transaction spending over 0.2 bitcoins as fees:

> bitcoin-cli -testnet signrawtransaction $(     bitcoin-cli -testnet createrawtransaction '''      [         {           "txid": "ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e",          "vout": 0         }       ]''' '''      {         "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe": 0.1       }'''   )

Result:

{    "hex" : "01000000011e48dee8b82c1cb03ba63998660b7bff269b70ba9\             b23ead268afa56bbf0c7cef000000006b4830450221009c711c\             e4df4cd8e22a10016ff6098e799f081e3a1706a9c0df14eeeb8\             6c31bb302206323d29ab4f3138371df7b7bb794bb7c6a5e7e40\             161e98b5c873f892d319d5230121027ce4f9db9f237fc75e420\             742320c7df3b4ca95c44b6bc715400930f24870b2b1ffffffff\             0180969800000000001976a9140dfc8bafc8419853b34d5e072\             ad37d1a5159f58488ac00000000",    "complete" : true}

Now attempt to broadcast it:

> bitcoin-cli -testnet sendrawtransaction 01000000011e48dee8b82c\    1cb03ba63998660b7bff269b70ba9b23ead268afa56bbf0c7cef00000000\    6b4830450221009c711ce4df4cd8e22a10016ff6098e799f081e3a1706a9\    c0df14eeeb86c31bb302206323d29ab4f3138371df7b7bb794bb7c6a5e7e\    40161e98b5c873f892d319d5230121027ce4f9db9f237fc75e420742320c\    7df3b4ca95c44b6bc715400930f24870b2b1ffffffff0180969800000000\    001976a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac00000000

Result:

error: {"code":-22,"message":"TX rejected"}

Allow high fees to force it to spend:

> bitcoin-cli -testnet sendrawtransaction 01000000[...]00000000 true

Result (success):

6d62d3f74be5ca614e32a2fb662deabe87ff95c7d90228cd8615da39cc824e34

sendtoaddress

sendtoaddress <address> <amount> <memo> <label>

Spend an amount to a given address. Encrypted wallets must be unlocked first.

Argument #1: Address

String; required: A bitcoin address which will received payment.

Argument #2: Amount

Number; required: the amount in decimal bitcoins.

Argument #3: Memo

String; optional: the memo to give the transaction. This is not broadcast to the peer-to-peer network; it is stored in your wallet only.

Argument #4: Label

String; optional: the label to give the transaction. This is not broadcast to the peer-to-peer network; it is stored in your wallet only.

Result: TXID

If the spend is successful, the txid is returned.

Example

Spend 0.1 bitcoins to the address below with the memo “sendtoadress example” and the label “Nemo From Example.com”:

> bitcoin-cli -testnet sendtoaddress mmXgiR6KAhZCyQ8ndr2BCfEq1wNG2UnyG6 \    0.1 "sendtoaddress example" "Nemo From Example.com"

85a98fdf1529f7d5156483ad020a51b7f3340e47448cf932f470b72ff01a6821

setaccount

setaccount <address> <account>

Puts the given address in the given account.

Argument #1: A Bitcoin Address

String; required: the address to put in the account.

Argument #2: An Account

String; required: the account in which to put the address.

Result: None On Success

No result generated on success.

Example

Put the address indicated below in the “doc test” account.

> bitcoin-cli -testnet setaccount \    mmXgiR6KAhZCyQ8ndr2BCfEq1wNG2UnyG6 "doc test"

(Success: no result displayed.)

setgenerate

setgenerate <true|false> [processors]

Enable or disable hashing to attempt to find the next block.

See also: getgenerate

Argument #1: Whether To Enable Or Disable Generation

Boolean; required: to enable generation, true; to disable, false.

Argument #2: The Number Of Processors To Use

Number; optional: the number of logical processors to use. Defaults to 1; use -1 to use all available processors.

Note: in regtest mode, this argument will automatically create that number of blocks. See example below.

Result: None On Success

No result on success.

Examples

Enable generation using two logical processors (on this machine, two cores of one physical processor):

> bitcoin-cli -testnet setgenerate true 2

(Success: no result displayed. Process manager shows 200% CPU usage.)

Using regtest mode, generate 101 blocks (enough to be able to spend the coinbase transaction of the first block generated):

> bitcoin-cli -regtest setgenerate true 101

(Success: no result displayed. Wallet balance shows 50 bitcoins available.)

settxfee

settxfee amount

Set the transaction fee per kilobyte.

Argument: Amount

Number; required: the transaction fee in decimal bitcoins per kilobyte. Will be rounded up to the nearest satoshi (0.00000001).

Result: True Or False

True if successful.

Example

Set the transaction fee per kilobyte to 100,000 satoshis (1 millibit).

> bitcoin-cli -testnet settxfee 0.00100000

Result:

true

signmessage

signmessage <address> <message>

Sign a message with the private key of an address. Encrypted wallets must be unlocked first.

Argument #1: Address

String; required: the Bitcoin address corresponding to the private key which should be used to sign the message.

Argument #2: Message

String; required: The message to sign.

Result: Message Signature

The signature of the message encoded in base64.

Example

Sign a the message “Hello, World!” using the following address:

> bitcoin-cli -testnet signmessage mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe \    'Hello, World!'

Result:

IOGreqb/7UgD1ifcojESd32ZJgH5RGzUXitmbl6ZbdenSmitipWoLSi73TskmLY7zhcD662bTw3RHoYQl/dOAhE=

signrawtransaction

signrawtransaction <raw transaction hex> [previous transactions] [private keys] [sighashtype]

Sign inputs of a transaction in rawtransaction format using private keys stored in the wallet or provided in the call.

Argument #1: The Transaction To Sign

String; required: the transaction to sign in rawtransaction format (hex).

Argument #2: P2SH Transaction Dependencies

String; optional: A JSON array of JSON objects. Each object contains details about an unknown-to-this-node P2SH transaction that this transaction depends upon.

Each previous P2SH transaction must include its txid in hex, output index number (vout), public key (scriptPubKey) in hex, and redeemScript in hex.

[  {    "txid":"<txid>",    "vout":<output index number>,    "scriptPubKey": "<scriptPubKey in hex>",    "redeemScript": "<redeemScript in hex>"  }  ,[...]]

Argument #3: Private Keys For Signing

String; optional: A JSON array of base58check-encoded private keys to use for signing. If this argument is used, only the keys provided will be used to sign even if the wallet has other matching keys. If this argument is omitted, keys from the wallet will be used.

[  "<private key in base58check hex>"  ,[...]]

Argument #4: Sighash Type

String, optional: The type of signature hash to use for all of the signatures performed. (You must use separate calls to signrawtransaction if you want to use different sighash types for different signatures.)

The allowed values are ALL, NONE, SINGLE, ALL|ANYONECANPAY, NONE|ANYONECANPAY, and SINGLE|ANYONECANPAY.

Result: Signed Transaction

String: a JSON object containing the transaction in hex with as many signatures as could be applied and a complete key indicating whether or not the the transaction is fully signed (0 indicates it is not complete).

{  "hex": "<signed raw transaction hex>",  "complete": <0|1>}

Example

Sign the hex generated in the example section for the rawtransaction RPC:

> bitcoin-cli -testnet signrawtransaction 010000000189957b01aed5\              96d3b361b576234eaeed3249246f14562d6bc6085166cd247d\              5a0000000000ffffffff0180969800000000001976a9140dfc\              8bafc8419853b34d5e072ad37d1a5159f58488ac00000000

Result:

{  "hex" : "010000000189957b01aed596d3b361b576234eaeed3249246f145\           62d6bc6085166cd247d5a000000006b483045022100c7a034fd7d\           990b8a2bfba45fde44cae40b5ffbe42c5cf7d8143bfe317bdef3f\           10220584e52f59b6a46d688322d65178efe83972a8517c9479630\           6d40083af5b807c901210321eeeb46fd878ce8e62d5e0f408a0ea\           b41d7c3a7872dc836ce360439536e423dffffffff018096980000\           0000001976a9140dfc8bafc8419853b34d5e072ad37d1a5159f58\           488ac00000000",  "complete" : true}

stop

stop

Stop the Bitcoin Core server.

Example

bitcoin-cli -testnet stop

(Success: no result printed but bitcoind shutdown.)

submitblock

submitblock <new block>  [extra parameters]

Attempts to broadcast a new block to network. Extra parameters are ignored by Bitcoin Core but may be used by mining pools or other programs.

Argument #1: The New Block In Hex

String; required: the hex-encoded block data to broadcast to the peer-to-peer network.

Argument #2: Extra Parameters

String; optional: A JSON object containing extra parameters for mining pools and other software, such as a work identifier (workid). The extra parameters will not be broadcast to the network.

{  "<key>" : "<value>"}

Result: None

No result printed if successful. An error message if failed.

Example

Submit the following block with the workid, “test”.

> bitcoin-cli -testnet submitblock 02000000df11c014a8d798395b505\              9c722ebdf3171a4217ead71bf6e0e99f4c7000000004a6f6a2\              db225c81e77773f6f0457bcb05865a94900ed11356d0b75228\              efb38c7785d6053ffff001d005d43700101000000010000000\              00000000000000000000000000000000000000000000000000\              0000000ffffffff0d03b477030164062f503253482ffffffff\              f0100f9029500000000232103adb7d8ef6b63de74313e0cd4e\              07670d09a169b13e4eda2d650f529332c47646dac00000000\              '{ "workid": "test" }'

validateaddress

validateaddress <address>

Return information about the given Bitcoin address.

Argument: An Address

String; required: A Bitcoin address.

Result: Information About The Address

A JSON object containing one or more values (the exact number depending on the information). The result of isvalid is always returned to indicated whether or not the address is valid. If it is valid, the validated address is returned plus ismine to indicate whether or not it belongs to this wallet and account to indicate which account it belongs to. If it’s a P2SH address, isscript will be true. If it’s a P2PKH address, pubkey will contain the public key and compressed will indicate whether or not the pubkey/address is compressed.

{  "isvalid" : <true|false>,  "address" : "<address>",  "ismine" : <true|false>,  "isscript" : <true|false>,  "pubkey" : "<public key hex>",  "iscompressed" : <true|false>,  "account" : "<account>"}

Example

Validate the following address from the wallet:

> bitcoin-cli -testnet validateaddress mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe

Result:

{    "isvalid" : true,    "address" : "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe",    "ismine" : true,    "isscript" : false,    "pubkey" : "03bacb84c6464a58b3e0a53cc0ba4cb3b82848cd7bed25a7724b3cc75d76c9c1ba",    "iscompressed" : true,    "account" : "test label"}

verifychain

verifychain [throughness] [blocks]

Verify the local blockchain database.

Argument #1: Throughness

Number; optional: how thoroughly to check the database, from 0 to 4 with 4 being the most through. Defaults to 3.

Argument #2: Number Of Blocks To Check

Number; optional: check this number of the most recent blocks.

Result: Verified Or Not

True if verified.

Example

Verify the most recent 10,000 blocks in the most through way:

> bitcoin-cli -testnet verifychain 4 10000

Result (took 25 seconds on a generic PC laptop):

true

verifymessage

verifymessage <address> <signature> <message>

Verify a signed message.

Argument #1: The Address

String; required: the address corresponding to the private key used to create the signature.

Argument #2: The Signature

String; required: the signature provided in the same base64 format generated bysignmessage.

Argument #3: The Message

String; required: the exact message which was signed.

Result: True Or False

True if the message provided was signed by the private key corresponding to the address provided.

Example

Check the signature on the message created in the example for signmessage:

> bitcoin-cli -testnet verifymessage \    mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe \    IOGreqb/7UgD1ifcojESd32ZJgH5RGzUXitmbl6ZbdenSmitipWoLSi73TskmLY7zhcD662bTw3RHoYQl/dOAhE= \    'Hello, World!'

Result:

true

walletlock

walletlock

Removes the wallet encryption key from memory, locking the wallet. After calling this method, you will need to call walletpassphrase again before being able to call any methods which require the wallet to be unlocked.

Return

No return printed on success.

Example

> bitcoin-cli -testnet walletlock

(Success: nothing printed.)

walletpassphrase

walletpassphrase

Stores the wallet decryption key in memory for the indicated number of seconds. Issuing the walletpassphrase command while the wallet is already unlocked will set a new unlock time that overrides the old one.

Argument #1: The Passphrase

String; required: the passphrase to unlock the encrypted wallet.

Argument #2: The Number Of Seconds To Leave The Wallet Unlocked

Number; required: The number of seconds after which the decryption key will be automatically deleted from memory.

Result

No result printed on success.

Example

Unlock the wallet for 10 minutes (the passphrase is “test”):

> bitcoin-cli -testnet walletpassphrase test 600

(Success: no result printed.)

walletpassphrasechange

walletpassphrasechange <old passphrase> <new passphrase>

Changes the wallet passphrase from ‘old passphrase’ to ‘new passphrase’.

Argument #1: The Old Passphrase

String; required: the current passphrase.

Argument #2: The New Passphrase

String; required: the new passphrase.

Result

No result printed on success.

Example

Change the wallet passphrase from “test” to “example”:

> bitcoin-cli -testnet walletpassphrasechange test example

(Success: no result printed.)