Bitcoin Developer Reference
Find technical specifications and API documentation.
- Block Chain
- Transactions
- Wallets
- Bitcoin Core APIs
- Remote Procedure Calls (RPCs)
- addmultisigaddress
- addnode
- backupwallet
- createmultisig
- createrawtransaction
- decoderawtransaction
- decodescript
- dumpprivkey
- dumpwallet
- encryptwallet
- getaccount
- getaccountaddress
- getaddednodeinfo
- getaddressesbyaccount
- getbalance
- getbestblockhash
- getblock
- getblockchaininfo
- getblockcount
- getblockhash
- getblocktemplate
- getconnectioncount
- getdifficulty
- getgenerate
- gethashespersec
- getinfo
- getmininginfo
- getnettotals
- getnetworkhashps
- getnetworkinfo
- getnewaddress
- getpeerinfo
- getrawchangeaddress
- getrawmempool
- getrawtransaction
- getreceivedbyaccount
- getreceivedbyaddress
- gettransaction
- gettxout
- gettxoutsetinfo
- getunconfirmedbalance
- getwalletinfo
- getwork
- help
- importprivkey
- importwallet
- keypoolrefill
- listaccounts
- listaddressgroupings
- listlockunspent
- listreceivedbyaccount
- listreceivedbyaddress
- listsinceblock
- listtransactions
- listunspent
- lockunspent
- move
- ping
- sendfrom
- sendmany
- sendrawtransaction
- sendtoaddress
- setaccount
- setgenerate
- settxfee
- signmessage
- signrawtransaction
- stop
- submitblock
- validateaddress
- verifychain
- verifymessage
- walletlock
- walletpassphrase
- walletpassphrasechange
- Remote Procedure Calls (RPCs)
The Developer Reference aims to provide specifications and API information to help you start building Bitcoin-based applications. To make the best use of this documentation, you may want to install the current version of Bitcoin Core, either from source or from a pre-compiled executable.
Questions about Bitcoin development are best sent to the Bitcoin Forum and IRC channels. Errors or suggestions related to documentation on Bitcoin.org can be submitted as an issue or posted to the bitcoin-documentation mailing list.
In the following documentation, some strings have been shortened or wrapped: “[…]” indicates extra data was removed, and lines ending in a single backslash “\” are continued below. If you hover your mouse over a paragraph, cross-reference links will be shown in blue. If you hover over a cross-reference link, a brief definition of the term will be displayed in a tooltip.
Block Chain
The following subsections briefly document core block details.
Block Contents
This section describes version 2 blocks, which are any blocks with a
block height greater than 227,835. (Version 1 and version 2 blocks were
intermingled for some time before that point.) Future block versions may
break compatibility with the information in this section. You can determine
the version of any block by checking its version
field using
bitcoind RPC calls.
As of version 2 blocks, each block consists of four root elements:
-
A magic number (0xd9b4bef9).
-
A 4-byte unsigned integer indicating how many bytes follow until the end of the block. Although this field would suggest maximum block sizes of 4 GiB, max block size is currently capped at 1 MiB and the default max block size (used by most miners) is 350 KiB (although this will likely increase over time).
-
An 80-byte block header described in the section below.
-
One or more transactions.
The first transaction in a block must be a coinbase transaction which should collect and spend any transaction fees paid by transactions included in this block. All blocks with a block height less than 6,930,000 are entitled to receive a block reward of newly created bitcoin value, which also should be spent in the coinbase transaction. (The block reward started at 50 bitcoins and is being halved every 210,000 blocks—approximately once every four years. As of June 2014, it’s 25 bitcoins.) A coinbase transaction is invalid if it tries to spend more value than is available from the transaction fees and block reward.
The coinbase transaction has the same basic format as any other transaction, but it references a single non-existent UTXO and a special coinbase field replaces the field that would normally hold a scriptSig and signature. In version 2 blocks, the coinbase parameter must begin with the current block’s block height and may contain additional arbitrary data or a script up to a maximum total of 100 bytes.
Block Header
The 80-byte block header contains the following six fields:
| Field | Bytes | Format |
|---|---|---|
| 1. Version | 4 | Unsigned Int |
| 2. hashPrevBlock | 32 | Unsigned Int (SHA256 Hash) |
| 3. hashMerkleRoot | 32 | Unsigned Int (SHA256 Hash) |
| 4. Time | 4 | Unsigned Int (Epoch Time) |
| 5. Bits | 4 | Internal Bitcoin Target Format |
| 6. Nonce | 4 | (Arbitrary Data) |
-
The block version number indicates which set of block validation rules to follow so Bitcoin Core developers can add features or fix bugs. As of block height 227,836, all blocks use version number 2.
-
The hash of the previous block header puts this block on the block chain and ensures no previous block can be changed without also changing this block’s header.
-
The Merkle root is a hash derived from hashes of all the transactions included in this block. It ensures no transactions can be modified in this block without changing the block header hash.
-
The block time is the approximate time when this block was created in Unix Epoch time format (number of seconds elapsed since 1970-01-01T00:00 UTC). The time value must be greater than the median time of the previous 11 blocks. No peer will accept a block with a time currently more than two hours in the future according to the peer’s clock.
-
Bits translates into the target threshold value—the maximum allowed value for this block’s hash. The bits value must match the network difficulty at the time the block was mined.
-
The header nonce is an arbitrary input that miners can change to test different hash values for the header until they find a hash value less than or equal to the target threshold. If all values within the nonce’s four bytes are tested, the time can be updated or the coinbase transaction can be changed and the Merkle root updated.
Transactions
The following subsections briefly document core transaction details.
OP Codes
The op codes used in standard transactions are,
-
Various data pushing op codes from 0x00 to 0x4e (1–78). These aren’t typically shown in examples, but they must be used to push signatures and public keys onto the stack. See the link below this list for a description.
-
OP_1NEGATE
(0x4f),OP_TRUE
/OP_1
(0x51), andOP_2
throughOP_16
(0x52–0x60), which (respectively) push the values -1, 1, and 2–16 to the stack. -
OP_CHECKSIG
consumes a signature and a full public key, and returns true if the the transaction data specified by the SIGHASH flag was converted into the signature using the same ECDSA private key that generated the public key. Otherwise, it returns false. -
OP_HASH160
consumes the item on the stack below it and returns with a RIPEMD-160(SHA256()) hash of that item. -
OP_EQUAL
consumes the two items on the stack below it and returns true if they are the same. Otherwise, it returns false. -
OP_VERIFY
consumes one value and returns nothing, but it will terminate the script in failure if the value consumed is zero (false). -
OP_EQUALVERIFY
runsOP_EQUAL
and thenOP_VERIFY
in sequence. -
OP_CHECKMULTISIG
consumes the value (n) at the top of the stack, consumes that many of the next stack levels (public keys), consumes the value (m) now at the top of the stack, and consumes that many of the next values (signatures) plus one extra value. Then it compares each of public keys against each of the signatures looking for ECDSA matches; if n of the public keys match signatures, it returns true. Otherwise, it returns false.The “one extra value” it consumes is the result of an off-by-one error in the Bitcoin Core implementation. This value is not used, so scriptSigs prefix the signatures with a single OP_0 (0x00).
-
OP_RETURN
terminates the script in failure, rendering the output unspendable and allowing a miner to claim the satoshis sent to that OP_RETURN output as an additional transaction fee.
A complete list of OP codes can be found on the Bitcoin Wiki Script
Page, with an authoritative list in the opcodetype
enum
of the Bitcoin Core script header file
Note: non-standard transactions can add non-data-pushing op codes to
their scriptSig, but scriptSig is run separately from the script (with a
shared stack), so scriptSig can’t use arguments such as OP_RETURN
to
prevent the script from working as expected.
Address Conversion
The hashes used in P2PKH and P2SH outputs are commonly encoded as Bitcoin addresses. This is the procedure to encode those hashes and decode the addresses.
First, get your hash. For P2PKH, you RIPEMD-160(SHA256()) hash a ECDSA public key derived from your 256-bit ECDSA private key (random data). For P2SH, you RIPEMD-160(SHA256()) hash a redeemScript serialized in the format used in raw transactions (described in a following sub-section). Taking the resulting hash:
-
Add an address version byte in front of the hash. The version bytes commonly used by Bitcoin are:
-
Create a copy of the version and hash; then hash that twice with SHA256:
SHA256(SHA256(version . hash))
-
Extract the four most significant bytes from the double-hashed copy. These are used as a checksum to ensure the base hash gets transmitted correctly.
-
Append the checksum to the version and hash, and encode it as a base58 string:
BASE58(version . hash . checksum)
Bitcoin’s base58 encoding, called Base58Check may not match other implementations. Tier Nolan provided the following example encoding algorithm to the Bitcoin Wiki Base58Check encoding page:
code_string = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
x = convert_bytes_to_big_integer(hash_result)
output_string = ""
while(x > 0)
{
(x, remainder) = divide(x, 58)
output_string.append(code_string[remainder])
}
repeat(number_of_leading_zero_bytes_in_hash)
{
output_string.append(code_string[0]);
}
output_string.reverse();
Bitcoin’s own code can be traced using the base58 header file.
To convert addresses back into hashes, reverse the base58 encoding, extract the checksum, repeat the steps to create the checksum and compare it against the extracted checksum, and then remove the version byte.
Raw Transaction Format
Bitcoin transactions are broadcast between peers and stored in the block chain in a serialized byte format, called raw format. Bitcoin Core and many other tools print and accept raw transactions encoded as hex.
A sample raw transaction is the first non-coinbase transaction, made in
block 170. To get the transaction, use the getrawtransaction
RPC with
that transaction’s txid (provided below):
> getrawtransaction \
f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16
0100000001c997a5e56e104102fa209c6a852dd90660a20b2d9c352423e\
dce25857fcd3704000000004847304402204e45e16932b8af514961a1d3\
a1a25fdf3f4f7732e9d624c6c61548ab5fb8cd410220181522ec8eca07d\
e4860a4acdd12909d831cc56cbbac4622082221a8768d1d0901ffffffff\
0200ca9a3b00000000434104ae1a62fe09c5f51b13905f07f06b99a2f71\
59b2225f374cd378d71302fa28414e7aab37397f554a7df5f142c21c1b7\
303b8a0626f1baded5c72a704f7e6cd84cac00286bee000000004341041\
1db93e1dcdb8a016b49840f8c53bc1eb68a382e97b1482ecad7b148a690\
9a5cb2e0eaddfb84ccf9744464f82e160bfa9b8b64f9d4c03f999b8643f\
656b412a3ac00000000
A byte-by-byte analysis by Amir Taaki (Genjix) of this transaction is provided below. (Originally from the Bitcoin Wiki OP_CHECKSIG page; Genjix’s text has been updated to use the terms used in this document.)
01 00 00 00 version number
01 number of inputs (var_uint)
input 0:
c9 97 a5 e5 6e 10 41 02 previous tx hash (txid)
fa 20 9c 6a 85 2d d9 06
60 a2 0b 2d 9c 35 24 23
ed ce 25 85 7f cd 37 04
00 00 00 00 previous output index
48 size of script (var_uint)
47 push 71 bytes to stack
30 44 02 20 4e 45 e1 69
32 b8 af 51 49 61 a1 d3
a1 a2 5f df 3f 4f 77 32
e9 d6 24 c6 c6 15 48 ab
5f b8 cd 41 02 20 18 15
22 ec 8e ca 07 de 48 60
a4 ac dd 12 90 9d 83 1c
c5 6c bb ac 46 22 08 22
21 a8 76 8d 1d 09 01
ff ff ff ff sequence number
02 number of outputs (var_uint)
output 0:
00 ca 9a 3b 00 00 00 00 amount = 10.00000000 BTC
43 size of script (var_uint)
script for output 0:
41 push 65 bytes to stack
04 ae 1a 62 fe 09 c5 f5
1b 13 90 5f 07 f0 6b 99
a2 f7 15 9b 22 25 f3 74
cd 37 8d 71 30 2f a2 84
14 e7 aa b3 73 97 f5 54
a7 df 5f 14 2c 21 c1 b7
30 3b 8a 06 26 f1 ba de
d5 c7 2a 70 4f 7e 6c d8
4c
ac OP_CHECKSIG
output 1:
00 28 6b ee 00 00 00 00 amount = 40.00000000 BTC
43 size of script (var_uint)
script for output 1:
41 push 65 bytes to stack
04 11 db 93 e1 dc db 8a
01 6b 49 84 0f 8c 53 bc
1e b6 8a 38 2e 97 b1 48
2e ca d7 b1 48 a6 90 9a
5c b2 e0 ea dd fb 84 cc
f9 74 44 64 f8 2e 16 0b
fa 9b 8b 64 f9 d4 c0 3f
99 9b 86 43 f6 56 b4 12
a3
ac OP_CHECKSIG
00 00 00 00 locktime
Wallets
Deterministic Wallet Formats
Type 1: Single Chain Wallets
Type 1 deterministic wallets are the simpler of the two, which can create a single series of keys from a single seed. A primary weakness is that if the seed is leaked, all funds are compromised, and wallet sharing is extremely limited.
Type 2: Hierarchical Deterministic (HD) Wallets
For an overview of HD wallets, please see the developer guide section. For details, please see BIP32.
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 <IP_ADDRESS>: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<PHONE_NUMBER>268a9ad7bf\
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" :<PHONE_NUMBER>
}
],
"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<PHONE_NUMBER>00ee69171016b7dd21\
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 v<IP_ADDRESS>-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<PHONE_NUMBER>ede4c10594af8087748507fb06dcd30b8f4f48b9cc463cabc9d767),
# mined on 2014-04-29T21:15:07Z
cTtefiUaLfXuyBXJBBywSdg8soTEkBNh9yTi1KgoHxUYxt1xZ2aA 2014-02-05T15:44:03Z label=test1 # addr=mnUbTmdAFD5EAg3348Ejmonub7JcWtrMck
cQNY9v93Gyt8KmwygFR59bDhVs3aRDkuT8pKaCBpop82TZ8ND1tH 2014-02-05T16:58:41Z reserve=1 # addr=mp4MmhTp3au21HPRz5waf6YohGumuNnsqT
cNTEPzZH9mjquFFADXe5S3BweNiHLUKD6PvEKEsHApqjX4ZddeU6 2014-02-05T16:58:41Z reserve=1 # addr=n3pdvsxveMBkktjsGJixfSbxacRUwJ9jQW
cTVNtBK7mBi2yc9syEnwbiUpnpGJKohDWzXMeF4tGKAQ7wvomr95 2014-02-05T16:58:41Z change=1 # addr=moQR7i8XM4rSGoNwEsw3h4YEuduuP6mxw7
cNCD679B4xi17jb4XeLpbRbZCbYUugptD7dCtUTfSU4KPuK2DyKT 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 a dumpwallet
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 encrypted
wallet. 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" : "<IP_ADDRESS>:44549",
"connected" : true,
"addresses" : [
{
"address" : "<IP_ADDRESS>: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.
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" 1000
0.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" :<PHONE_NUMBER>,
"nonce" :<PHONE_NUMBER>,
"bits" : "1d00ffff",
"difficulty" : 1.00000000,
"chainwork" : "000000000000000000000000000000000000000000000000083ada4a4009841a",
"previousblockhash" : "00000000c7f4990e6ebf71ad7e21a47131dfeb22c759505b3998d7a814c011df",
"nextblockhash" : "00000000afe1928529ac766f1237657819a11cfcc8ca6d67f119e868ed5b6188"
}
getblockchaininfo
getblockchaininfo
Provides information about the current state of the block chain. This RPC was added in Bitcoin Core 0.9.2.
Result
A JSON object containing several key/value pairs: chain telling you whether you’re working on the main block chain or a testnet or regtest block chain, the number of blocks processed by the node, the best block hash (tip of the chain), the current network difficulty, an estimate of the verification progress (1 for 100% verified), and the total amount of chain work seen in the current chain (displayed in hexadecimal). Note: verificationprogress may exceed 1 (100%) because it’s just an estimate.
{
"chain": "<name>",
"blocks": <integer>,
"bestblockhash": "<SHA256 hash>",
"difficulty": <decimal difficulty>,
"verificationprogress": <decimal>,
"chainwork": "<hexadecimal>"
}
Example
bitcoin-cli -testnet getblockchaininfo
Result:
{
"chain" : "testnet3",
"blocks" : 272899,
"bestblockhash" : "00000000000047021429fb03107900637205c38b6\
4ebd2400bfe5be18f78da5e",
"difficulty" :<PHONE_NUMBER>3374,
"verificationprogress" : 0.99999913,
"chainwork" : "000000000000000000000000000000000000000000000\
0001dc6696de16ca6c8"
}
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" :<PHONE_NUMBER>,
"target" : "000000000001968c00000000000000000000000000000000\
0000000000000000",
"mintime" :<PHONE_NUMBER>,
"mutable" : [
"time",
"transactions",
"prevblock"
],
"noncerange" : "00000000ffffffff",
"sigoplimit" : 20000,
"sizelimit" : 1000000,
"curtime" :<PHONE_NUMBER>,
"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.
Warning: getinfo
will be removed in a later version of Bitcoin
Core. Use getblockchaininfo
, getnetworkinfo
, or getwalletinfo
instead.
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" :<PHONE_NUMBER>,
"keypoolsize" : 201,
"paytxfee" : 0.00100000,
"unlocked_until" :<PHONE_NUMBER>,
"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" :<PHONE_NUMBER>8,
"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" :<PHONE_NUMBER>758
}
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
getnetworkinfo
getnetworkinfo
Provides information about the node’s connection to the network. This RPC was added in Bitcoin Core 0.9.2.
Result
A JSON object containing several key/value pairs: the server version, the protocol version, the server’s time offset from the averaged network time, how many connections it has to other nodes, information about any proxy being used, the smallest relay fee per kilobyte this node will accept in order to relay transactions, and a JSON array of IP addresses and port numbers which the node is listening to along with a score for each (with the array with the highest score being the one returned to peers).
{
"version": <integer>,
"protocolversion": <integer>,
"timeoffset": <integer seconds>,
"connections": <integer>,
"proxy": "<host>:<port>",
"relayfee": <decimal bitcoins>,
"localaddresses": [
"address": "<address>",
"port": <port>,
"score": <integer>
]
}
Example
bitcoin-cli -testnet getnetworkinfo
Result:
{
"version" : 90200,
"protocolversion" : 70002,
"timeoffset" : 0,
"connections" : 12,
"proxy" : "",
"relayfee" : 0.00001000,
"localaddresses" : [
{
"address" : "<IP_ADDRESS>",
"port" : 18333,
"score" : 65
}
]
}
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" : "<IP_ADDRESS>:18333",
"addrlocal" : "<IP_ADDRESS>:18333",
"services" : "00000001",
"lastsend" :<PHONE_NUMBER>,
"lastrecv" :<PHONE_NUMBER>,
"bytessent" : 210597,
"bytesrecv" : 300962,
"conntime" :<PHONE_NUMBER>,
"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" :<PHONE_NUMBER>,
"height" : 227310,
"startingpriority" : 97456429.70512821,
"currentpriority" : 97456429.70512821,
"depends" : [
]
},
"2baa1f49ac9b951fa781c4c95814333a2f3eda71ed3d0245cd76c2829b3ce354" : {
"size" : 191,
"fee" : 0.00020000,
"time" :<PHONE_NUMBER>,
"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" :<PHONE_NUMBER>
}
],
"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" :<PHONE_NUMBER>,
"blocktime" :<PHONE_NUMBER>
}
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" :<PHONE_NUMBER>,
"txid" : "5a7d24cd665108c66b2d56146f244932edae4e2376b561b3d396d5ae017b9589",
"walletconflicts" : [
],
"time" :<PHONE_NUMBER>,
"timereceived" :<PHONE_NUMBER>,
"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
getwalletinfo
getwalletinfo
Provides information about the wallet. This RPC was added in Bitcoin Core 0.9.2.
Result
A JSON object containing several key/value pairs: the walletversion
number, the current wallet’s balance (the same as getbalance
), the
number of transactions made by this wallet (txcount), the oldest
pre-generated key in the keypool (keypoololdest), the number of keys
in the keypool which have not received a transaction (keypoolsize),
the time in seconds since 1 January 1970 (epoch time) when an encrypted wallet
will become locked or 0 if the wallet is currently locked
(unlocked_until)—see walletpassphrase
.
{
"walletversion" : <integer>,
"balance" : <decimal bitcoins>,
"txcount" : <integer>,
"keypoololdest" : <epoch date>,
"keypoolsize" : <integer>,
"unlocked_until" : <epoch date>
}
Example
bitcoin-cli -testnet getwalletinfo
Result:
{
"walletversion" : 60000,
"balance" : 1.45060000,
"txcount" : 17,
"keypoololdest" :<PHONE_NUMBER>,
"keypoolsize" : 196,
"unlocked_until" : 0
}
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 of bitcoind
.
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 the getbestblockhash
RPC).
Note: this argument does not affect which transactions are returned; it
only changes the lastblock
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" :<PHONE_NUMBER>,
"txid" : "ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e",
"walletconflicts" : [
],
"time" :<PHONE_NUMBER>,
"timereceived" :<PHONE_NUMBER>,
"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" :<PHONE_NUMBER>,
"txid" : "997115d0cf7b83ed332e6c1f2e8c44f803c95ea43490c84ce3e9ede4b2e1605f",
"walletconflicts" : [
],
"time" :<PHONE_NUMBER>,
"timereceived" :<PHONE_NUMBER>
}
]
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<PHONE_NUMBER>1e48dee8b82c\
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<PHONE_NUMBER>89957b01aed5\
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 by signmessage
.
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.)