Bitkoin Programeri Reference

Pronađi tehničke detalje i API dokumentaciju.

BETA: Ova dokumentacija nije obimno proveravana od stane Bitkoin eksperata i verovatno sadrži brojne greške. Molimo koristite Problem i Izmena linkove u donjem levom uglu menija kako bi nam pomogli da je poboljšamo. Da zatvorite upozorenje kliknite ovde

BETA: Ova verzija dokumentacije može sadržati Englesku verziju pojedinih delova. Ako želite da pomognete prevodom ovog dokumenta na svoj maternji jezik, molimo koristite linkove ispod svakog naslova ili posetite ovaj link

The Developer Reference aims to provide technical details and API information to help you start building Bitcoin-based applications, but it is not a specification. 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 asked in one of the Bitcoin development communities. 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.

Not A Specification

The Bitcoin.org Developer Documentation describes how Bitcoin works to help educate new Bitcoin developers, but it is not a specification—and it never will be.

Bitcoin security depends on consensus. Should your program diverge from consensus, its security is weakened or destroyed. The cause of the divergence doesn’t matter: it could be a bug in your program, it could be an error in this documentation which you implemented as described, or it could be you do everything right but other software on the network behaves unexpectedly. The specific cause will not matter to the users of your software whose wealth is lost.

The only correct specification of consensus behavior is the actual behavior of programs on the network which maintain consensus. As that behavior is subject to arbitrary inputs in a large variety of unique environments, it cannot ever be fully documented here or anywhere else.

However, the Bitcoin Core developers are working on making their consensus code portable so other implementations can use it. Bitcoin Core 0.10.0 provided libbitcoinconsensus, as the first attempt at exporting some consensus code. Future versions of Bitcoin Core also provided consensus code that is more complete, more portable, and more consistent in diverse environments.

In addition, we also warn you that this documentation has not been extensively reviewed by Bitcoin experts and so likely contains numerous errors. At the bottom of the menu on the left, you will find links that allow you to report an issue or to edit the documentation on GitHub. Please use those links if you find any errors or important missing information.

Block Chain

The following subsections briefly document core block details.

Block Headers

Block headers are serialized in the 80-byte format described below and then hashed as part of Bitcoin’s proof-of-work algorithm, making the serialized header format part of the consensus rules.

Bytes Name Data Type Description
4 version int32_t The block version number indicates which set of block validation rules to follow. See the list of block versions below.
32 previous block header hash char[32] A SHA256(SHA256()) hash in internal byte order of the previous block’s header. This ensures no previous block can be changed without also changing this block’s header.
32 merkle root hash char[32] A SHA256(SHA256()) hash in internal byte order. The merkle root is derived from the hashes of all transactions included in this block, ensuring that none of those transactions can be modified without modifying the header. See the merkle trees section below.
4 time uint32_t The block time is a Unix epoch time when the miner started hashing the header (according to the miner). Must be strictly greater than the median time of the previous 11 blocks. Full nodes will not accept blocks with headers more than two hours in the future according to their clock.
4 nBits uint32_t An encoded version of the target threshold this block’s header hash must be less than or equal to. See the nBits format described below.
4 nonce uint32_t An arbitrary number miners change to modify the header hash in order to produce a hash less than or equal to the target threshold. If all 32-bit values are tested, the time can be updated or the coinbase transaction can be changed and the merkle root updated.

The hashes are in internal byte order; the other values are all in little-endian order.

An example header in hex:

02000000 ........................... Block version: 2

b6ff0b1b1680a2862a30ca44d346d9e8
910d334beb48ca0c0000000000000000 ... Hash of previous block's header
9d10aa52ee949386ca9385695f04ede2
70dda20810decd12bc9b048aaab31471 ... Merkle root

24d95a54 ........................... Unix time: 1415239972
30c31b18 ........................... Target: 0x1bc330 * 256**(0x18-3)
fe9f0864 ........................... Nonce

Block Versions

The mechanism used for the version 2, 3, and 4 upgrades is commonly called IsSuperMajority() after the function added to Bitcoin Core to manage those soft forking changes. See BIP34 for a full description of this method.

As of this writing, a newer method called version bits is being designed to manage future soft forking changes, although it’s not known whether version 4 will be the last soft fork to use the IsSuperMajority() function. Draft BIP9 describes the version bits design as of this writing, although it is still being actively edited and may substantially change while in the draft state.

Merkle Trees

The merkle root is constructed using all the TXIDs of transactions in this block, but first the TXIDs are placed in order as required by the consensus rules:

If a block only has a coinbase transaction, the coinbase TXID is used as the merkle root hash.

If a block only has a coinbase transaction and one other transaction, the TXIDs of those two transactions are placed in order, concatenated as 64 raw bytes, and then SHA256(SHA256()) hashed together to form the merkle root.

If a block has three or more transactions, intermediate merkle tree rows are formed. The TXIDs are placed in order and paired, starting with the coinbase transaction’s TXID. Each pair is concatenated together as 64 raw bytes and SHA256(SHA256()) hashed to form a second row of hashes. If there are an odd (non-even) number of TXIDs, the last TXID is concatenated with a copy of itself and hashed. If there are more than two hashes in the second row, the process is repeated to create a third row (and, if necessary, repeated further to create additional rows). Once a row is obtained with only two hashes, those hashes are concatenated and hashed to produce the merkle root.

Example Merkle Tree Construction

TXIDs and intermediate hashes are always in internal byte order when they’re concatenated, and the resulting merkle root is also in internal byte order when it’s placed in the block header.

Target nBits

The target threshold is a 256-bit unsigned integer which a header hash must be equal to or below in order for that header to be a valid part of the block chain. However, the header field nBits provides only 32 bits of space, so the target number uses a less precise format called “compact” which works like a base-256 version of scientific notation:

Converting nBits Into A Target Threshold

As a base-256 number, nBits can be quickly parsed as bytes the same way you might parse a decimal number in base-10 scientific notation:

Quickly Converting nBits

Although the target threshold should be an unsigned integer, the original nBits implementation inherits properties from a signed data class, allowing the target threshold to be negative if the high bit of the significand is set. This is useless—the header hash is treated as an unsigned number, so it can never be equal to or lower than a negative target threshold. Bitcoin Core deals with this in two ways:

  • When parsing nBits, Bitcoin Core converts a negative target threshold into a target of zero, which the header hash can equal (in theory, at least).

  • When creating a value for nBits, Bitcoin Core checks to see if it will produce an nBits which will be interpreted as negative; if so, it divides the significand by 256 and increases the exponent by 1 to produce the same number with a different encoding.

Some examples taken from the Bitcoin Core test cases:

nBits Target Notes
0x01003456  0x00  
0x01123456  0x12  
0x02008000  0x80  
0x05009234  0x92340000  
0x04923456 -0x12345600 High bit set (0x80 in 0x92).
0x04123456  0x12345600 Inverse of above; no high bit.

Difficulty 1, the minimum allowed difficulty, is represented on mainnet and the current testnet by the nBits value 0x1d00ffff. Regtest mode uses a different difficulty 1 value—0x207fffff, the highest possible value below uint32_max which can be encoded; this allows near-instant building of blocks in regtest mode.

Serialized Blocks

Under current consensus rules, a block is not valid unless its serialized size is less than or equal to 1 MB. All fields described below are counted towards the serialized size.

Bytes Name Data Type Description
80 block header block_header The block header in the format described in the block header section.
Varies txn_count compactSize uint The total number of transactions in this block, including the coinbase transaction.
Varies txns raw transaction Every transaction in this block, one after another, in raw transaction format. Transactions must appear in the data stream in the same order their TXIDs appeared in the first row of the merkle tree. See the merkle tree section for details.

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 subsidy of newly created bitcoin value, which also should be spent in the coinbase transaction. (The block subsidy started at 50 bitcoins and is being halved every 210,000 blocks—approximately once every four years. As of November 2017, it’s 12.5 bitcoins.)

Together, the transaction fees and block subsidy are called the block reward. A coinbase transaction is invalid if it tries to spend more value than is available from the block reward.

Transactions

The following subsections briefly document core transaction details.

OpCodes

The opcodes used in the pubkey scripts of standard transactions are:

  • Various data pushing opcodes 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_TRUE/OP_1 (0x51) and OP_2 through OP_16 (0x52–0x60), which push the values 1 through 16 to the stack.

  • OP_CHECKSIG consumes a signature and a full public key, and pushes true onto the stack if 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 pushes false onto the stack.

  • OP_DUP pushes a copy of the topmost stack item on to the stack.

  • OP_HASH160 consumes the topmost item on the stack, computes the RIPEMD160(SHA256()) hash of that item, and pushes that hash onto the stack.

  • OP_EQUAL consumes the top two items on the stack, compares them, and pushes true onto the stack if they are the same, false if not.

  • OP_VERIFY consumes the topmost item on the stack. If that item is zero (false) it terminates the script in failure.

  • OP_EQUALVERIFY runs OP_EQUAL and then OP_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.

    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 signature scripts prefix the list of secp256k1 signatures with a single OP_0 (0x00).

    OP_CHECKMULTISIG compares the first signature against each public key until it finds an ECDSA match. Starting with the subsequent public key, it compares the second signature against each remaining public key until it finds an ECDSA match. The process is repeated until all signatures have been checked or not enough public keys remain to produce a successful result.

    Because public keys are not checked again if they fail any signature comparison, signatures must be placed in the signature script using the same order as their corresponding public keys were placed in the pubkey script or redeem script. See the OP_CHECKMULTISIG warning below for more details.

  • OP_RETURN terminates the script in failure when executed.

A complete list of opcodes can be found on the Bitcoin Wiki Script Page, with an authoritative list in the opcodetype enum of the Bitcoin Core script header file

Warning icon Signature script modification warning: Signature scripts are not signed, so anyone can modify them. This means signature scripts should only contain data and data-pushing opcodes which can’t be modified without causing the pubkey script to fail. Placing non-data-pushing opcodes in the signature script currently makes a transaction non-standard, and future consensus rules may forbid such transactions altogether. (Non-data-pushing opcodes are already forbidden in signature scripts when spending a P2SH pubkey script.)

Warning icon OP_CHECKMULTISIG warning: The multisig verification process described above requires that signatures in the signature script be provided in the same order as their corresponding public keys in the pubkey script or redeem script. For example, the following combined signature and pubkey script will produce the stack and comparisons shown:

OP_0 <A sig> <B sig> OP_2 <A pubkey> <B pubkey> <C pubkey> OP_3

Sig Stack       Pubkey Stack  (Actually a single stack)
---------       ------------
B sig           C pubkey
A sig           B pubkey
OP_0            A pubkey

1. B sig compared to C pubkey (no match)
2. B sig compared to B pubkey (match #1)
3. A sig compared to A pubkey (match #2)

Success: two matches found

But reversing the order of the signatures with everything else the same will fail, as shown below:

OP_0 <B sig> <A sig> OP_2 <A pubkey> <B pubkey> <C pubkey> OP_3

Sig Stack       Pubkey Stack  (Actually a single stack)
---------       ------------
A sig           C pubkey
B sig           B pubkey
OP_0            A pubkey

1. A sig compared to C pubkey (no match)
2. A sig compared to B pubkey (no match)

Failure, aborted: two signature matches required but none found so far, and there's only one pubkey remaining

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 redeem script serialized in the format used in raw transactions (described in a following sub-section). Taking the resulting hash:

  1. Add an address version byte in front of the hash. The version bytes commonly used by Bitcoin are:

  2. Create a copy of the version and hash; then hash that twice with SHA256: SHA256(SHA256(version . hash))

  3. Extract the first four bytes from the double-hashed copy. These are used as a checksum to ensure the base hash gets transmitted correctly.

  4. 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 under the Creative Commons Attribution 3.0 license:

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 in a serialized byte format, called raw format. It is this form of a transaction which is SHA256(SHA256()) hashed to create the TXID and, ultimately, the merkle root of a block containing the transaction—making the transaction format part of the consensus rules.

Bitcoin Core and many other tools print and accept raw transactions encoded as hex.

As of Bitcoin Core 0.9.3 (October 2014), all transactions use the version 1 format described below. (Note: transactions in the block chain are allowed to list a higher version number to permit soft forks, but they are treated as version 1 transactions by current software.)

A raw transaction has the following top-level format:

Bytes Name Data Type Description
4 version int32_t Transaction version number (note, this is signed); currently version 1 or 2. Programs creating transactions using newer consensus rules may use higher version numbers. Version 2 means that BIP 68 applies.
Varies tx_in count compactSize uint Number of inputs in this transaction.
Varies tx_in txIn Transaction inputs. See description of txIn below.
Varies tx_out count compactSize uint Number of outputs in this transaction.
Varies tx_out txOut Transaction outputs. See description of txOut below.
4 lock_time uint32_t A time (Unix epoch time) or block number. See the locktime parsing rules.

A transaction may have multiple inputs and outputs, so the txIn and txOut structures may recur within a transaction. CompactSize unsigned integers are a form of variable-length integers; they are described in the CompactSize section.

TxIn: A Transaction Input (Non-Coinbase)

Each non-coinbase input spends an outpoint from a previous transaction. (Coinbase inputs are described separately after the example section below.)

Bytes Name Data Type Description
36 previous_output outpoint The previous outpoint being spent. See description of outpoint below.
Varies script bytes compactSize uint The number of bytes in the signature script. Maximum is 10,000 bytes.
Varies signature script char[] A script-language script which satisfies the conditions placed in the outpoint’s pubkey script. Should only contain data pushes; see the signature script modification warning.
4 sequence uint32_t Sequence number. Default for Bitcoin Core and almost all other programs is 0xffffffff.
Outpoint: The Specific Part Of A Specific Output

Because a single transaction can include multiple outputs, the outpoint structure includes both a TXID and an output index number to refer to specific output.

Bytes Name Data Type Description
32 hash char[32] The TXID of the transaction holding the output to spend. The TXID is a hash provided here in internal byte order.
4 index uint32_t The output index number of the specific output to spend from the transaction. The first output is 0x00000000.
TxOut: A Transaction Output

Each output spends a certain number of satoshis, placing them under control of anyone who can satisfy the provided pubkey script.

Bytes Name Data Type Description
8 value int64_t Number of satoshis to spend. May be zero; the sum of all outputs may not exceed the sum of satoshis previously spent to the outpoints provided in the input section. (Exception: coinbase transactions spend the block subsidy and collected transaction fees.)
1+ pk_script bytes compactSize uint Number of bytes in the pubkey script. Maximum is 10,000 bytes.
Varies pk_script char[] Defines the conditions which must be satisfied to spend this output.

Example

The sample raw transaction itemized below is the one created in the Simple Raw Transaction section of the Developer Examples. It spends a previous pay-to-pubkey output by paying to a new pay-to-pubkey-hash (P2PKH) output.

01000000 ................................... Version

01 ......................................... Number of inputs
|
| 7b1eabe0209b1fe794124575ef807057
| c77ada2138ae4fa8d6c4de0398a14f3f ......... Outpoint TXID
| 00000000 ................................. Outpoint index number
|
| 49 ....................................... Bytes in sig. script: 73
| | 48 ..................................... Push 72 bytes as data
| | | 30450221008949f0cb400094ad2b5eb3
| | | 99d59d01c14d73d8fe6e96df1a7150de
| | | b388ab8935022079656090d7f6bac4c9
| | | a94e0aad311a4268e082a725f8aeae05
| | | 73fb12ff866a5f01 ..................... Secp256k1 signature
|
| ffffffff ................................. Sequence number: UINT32_MAX

01 ......................................... Number of outputs
| f0ca052a01000000 ......................... Satoshis (49.99990000 BTC)
|
| 19 ....................................... Bytes in pubkey script: 25
| | 76 ..................................... OP_DUP
| | a9 ..................................... OP_HASH160
| | 14 ..................................... Push 20 bytes as data
| | | cbc20a7664f2f69e5355aa427045bc15
| | | e7c6c772 ............................. PubKey hash
| | 88 ..................................... OP_EQUALVERIFY
| | ac ..................................... OP_CHECKSIG

00000000 ................................... locktime: 0 (a block height)
Coinbase Input: The Input Of The First Transaction In A Block

The first transaction in a block, called the coinbase transaction, must have exactly one input, called a coinbase. The coinbase input currently has the following format.

Bytes Name Data Type Description
32 hash (null) char[32] A 32-byte null, as a coinbase has no previous outpoint.
4 index (UINT32_MAX) uint32_t 0xffffffff, as a coinbase has no previous outpoint.
Varies script bytes compactSize uint The number of bytes in the coinbase script, up to a maximum of 100 bytes.
Varies (4) height script The block height of this block as required by BIP34. Uses script language: starts with a data-pushing opcode that indicates how many bytes to push to the stack followed by the block height as a little-endian unsigned integer. This script must be as short as possible, otherwise it may be rejected.

The data-pushing opcode will be 0x03 and the total size four bytes until block 16,777,216 about 300 years from now.
Varies coinbase script None The coinbase field: Arbitrary data not exceeding 100 bytes minus the (4) height bytes. Miners commonly place an extra nonce in this field to update the block header merkle root during hashing.
4 sequence uint32_t Sequence number.

Most (but not all) blocks prior to block height 227,836 used block version 1 which did not require the height parameter to be prefixed to the coinbase script. The block height parameter is now required.

Although the coinbase script is arbitrary data, if it includes the bytes used by any signature-checking operations such as OP_CHECKSIG, those signature checks will be counted as signature operations (sigops) towards the block’s sigop limit. To avoid this, you can prefix all data with the appropriate push operation.

An itemized coinbase transaction:

01000000 .............................. Version

01 .................................... Number of inputs
| 00000000000000000000000000000000
| 00000000000000000000000000000000 ...  Previous outpoint TXID
| ffffffff ............................ Previous outpoint index
|
| 29 .................................. Bytes in coinbase
| |
| | 03 ................................ Bytes in height
| | | 4e0105 .......................... Height: 328014
| |
| | 062f503253482f0472d35454085fffed
| | f2400000f90f54696d65202620486561
| | 6c74682021 ........................ Arbitrary data
| 00000000 ............................ Sequence

01 .................................... Output count
| 2c37449500000000 .................... Satoshis (25.04275756 BTC)
| 1976a914a09be8040cbf399926aeb1f4
| 70c37d1341f3b46588ac ................ P2PKH script
| 00000000 ............................ Locktime

CompactSize Unsigned Integers

The raw transaction format and several peer-to-peer network messages use a type of variable-length integer to indicate the number of bytes in a following piece of data.

Bitcoin Core code and this document refers to these variable length integers as compactSize. Many other documents refer to them as var_int or varInt, but this risks conflation with other variable-length integer encodings—such as the CVarInt class used in Bitcoin Core for serializing data to disk. Because it’s used in the transaction format, the format of compactSize unsigned integers is part of the consensus rules.

For numbers from 0 to 252, compactSize unsigned integers look like regular unsigned integers. For other numbers up to 0xffffffffffffffff, a byte is prefixed to the number to indicate its length—but otherwise the numbers look like regular unsigned integers in little-endian order.

Value Bytes Used Format
>= 0 && <= 252 1 uint8_t
>= 253 && <= 0xffff 3 0xfd followed by the number as uint16_t
>= 0x10000 && <= 0xffffffff 5 0xfe followed by the number as uint32_t
>= 0x100000000 && <= 0xffffffffffffffff 9 0xff followed by the number as uint64_t

For example, the number 515 is encoded as 0xfd0302.

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

Overview Of Hierarchical Deterministic Key Derivation

For an overview of HD wallets, please see the developer guide section. For details, please see BIP32.

P2P Network

This section describes the Bitcoin P2P network protocol (but it is not a specification). It does not describe the discontinued direct IP-to-IP payment protocol, the deprecated BIP70 payment protocol, the GetBlockTemplate mining protocol, or any network protocol never implemented in an official version of Bitcoin Core.

All peer-to-peer communication occurs entirely over TCP.

Note: unless their description says otherwise, all multi-byte integers mentioned in this section are transmitted in little-endian order.

Constants And Defaults

The following constants and defaults are taken from Bitcoin Core’s chainparams.cpp source code file.

Network Default Port Start String Max nBits
Mainnet 8333 0xf9beb4d9 0x1d00ffff
Testnet 18333 0x0b110907 0x1d00ffff
Regtest 18444 0xfabfb5da 0x207fffff

Note: the testnet start string and nBits above are for testnet3; the original testnet used a different string and higher (less difficult) nBits.

Command line parameters can change what port a node listens on (see -help). Start strings are hardcoded constants that appear at the start of all messages sent on the Bitcoin network; they may also appear in data files such as Bitcoin Core’s block database. The nBits displayed above are in big-endian order; they’re sent over the network in little-endian order.

Bitcoin Core’s chainparams.cpp also includes other constants useful to programs, such as the hash of the genesis blocks for the different networks.

Protocol Versions

The table below lists some notable versions of the P2P network protocol, with the most recent versions listed first. (If you know of a protocol version that implemented a major change but which is not listed here, please open an issue.)

As of Bitcoin Core 0.18.0, the most recent protocol version is 70015.

Version Initial Release Major Changes
70015 Bitcoin Core 0.13.2
(Jan 2017)
• New banning behavior for invalid compact blocks #9026 in v0.14.0, Backported to v0.13.2 in #9048.
70014 Bitcoin Core 0.13.0
(Aug 2016)
BIP152:
• Added sendcmpct, cmpctblock, getblocktxn, blocktxn messages
• Added MSG_CMPCT_BLOCK inventory type to getdata message.
70013 Bitcoin Core 0.13.0
(Aug 2016)
BIP133:
• Added feefilter message.
• Removed alert message system. See Alert System Retirement
70012 Bitcoin Core 0.12.0
(Feb 2016)
BIP130:
• Added sendheaders message.
70011 Bitcoin Core 0.12.0
(Feb 2016)
BIP111:
filter* messages are disabled without NODE_BLOOM after and including this version.
70002 Bitcoin Core 0.9.0
(Mar 2014)
• Send multiple inv messages in response to a mempool message if necessary

BIP61:
• Added reject message
70001 Bitcoin Core 0.8.0
(Feb 2013)
• Added notfound message.

BIP37:
• Added filterload message.
• Added filteradd message.
• Added filterclear message.
• Added merkleblock message.
• Added relay field to version message
• Added MSG_FILTERED_BLOCK inventory type to getdata message.
60002 Bitcoin Core 0.7.0
(Sep 2012)
BIP35:
• Added mempool message.
• Extended getdata message to allow download of memory pool transactions
60001 Bitcoin Core 0.6.1
(May 2012)
BIP31:
• Added nonce field to ping message
• Added pong message
60000 Bitcoin Core 0.6.0
(Mar 2012)
BIP14:
• Separated protocol version from Bitcoin Core version
31800 Bitcoin Core 0.3.18
(Dec 2010)
• Added getheaders message and headers message.
31402 Bitcoin Core 0.3.15
(Oct 2010)
• Added time field to addr message.
311 Bitcoin Core 0.3.11
(Aug 2010)
• Added alert message.
209 Bitcoin Core 0.2.9
(May 2010)
• Added checksum field to message headers, added verack message, and added starting height field to version message.
106 Bitcoin Core 0.1.6
(Oct 2009)
• Added transmitter IP address fields, nonce, and User Agent (subVer) to version message.

Message Headers

All messages in the network protocol use the same container format, which provides a required multi-field message header and an optional payload. The message header format is:

Bytes Name Data Type Description
4 start string char[4] Magic bytes indicating the originating network; used to seek to next message when stream state is unknown.
12 command name char[12] ASCII string which identifies what message type is contained in the payload. Followed by nulls (0x00) to pad out byte count; for example: version\0\0\0\0\0.
4 payload size uint32_t Number of bytes in payload. The current maximum number of bytes (MAX_SIZE) allowed in the payload by Bitcoin Core is 32 MiB—messages with a payload size larger than this will be dropped or rejected.
4 checksum char[4] Added in protocol version 209.

First 4 bytes of SHA256(SHA256(payload)) in internal byte order.

If payload is empty, as in verack and getaddr messages, the checksum is always 0x5df6e0e2 (SHA256(SHA256(<empty string>))).

The following example is an annotated hex dump of a mainnet message header from a verack message which has no payload.

f9beb4d9 ................... Start string: Mainnet
76657261636b000000000000 ... Command name: verack + null padding
00000000 ................... Byte count: 0
5df6e0e2 ................... Checksum: SHA256(SHA256(<empty>))

Data Messages

The following network messages all request or provide data related to transactions and blocks.

Overview Of P2P Protocol Data Request And Reply Messages

Many of the data messages use inventories as unique identifiers for transactions and blocks. Inventories have a simple 36-byte structure:

Bytes Name Data Type Description
4 type identifier uint32_t The type of object which was hashed. See list of type identifiers below.
32 hash char[32] SHA256(SHA256()) hash of the object in internal byte order.

The currently-available type identifiers are:

Type Identifier Name Description
1 MSG_TX The hash is a TXID.
2 MSG_BLOCK The hash is of a block header.
3 MSG_FILTERED_BLOCK The hash is of a block header; identical to MSG_BLOCK. When used in a getdata message, this indicates the response should be a merkleblock message rather than a block message (but this only works if a bloom filter was previously configured). Only for use in getdata messages.
4 MSG_CMPCT_BLOCK The hash is of a block header; identical to MSG_BLOCK. When used in a getdata message, this indicates the response should be a cmpctblock message. Only for use in getdata messages.
1† MSG_WITNESS_TX The hash is a TXID. When used in a getdata message, this indicates the response should be a transaction message, if the witness structure is nonempty, the witness serialization will be used. Only for use in getdata messages.
2† MSG_WITNESS_BLOCK The hash is of a block header; identical to MSG_BLOCK. When used in a getdata message, this indicates the response should be a block message with transactions that have a witness using witness serialization. Only for use in getdata messages.
3† MSG_FILTERED_WITNESS_BLOCK Reserved for future use, not used as of Protocol Version 70015.

† These are the same as their respective type identifier but with their 30th bit set to indicate witness. For example MSG_WITNESS_TX = 0x01000040.

Type identifier zero and type identifiers greater than seven are reserved for future implementations. Bitcoin Core ignores all inventories with one of these unknown types.

Block

The block message transmits a single serialized block in the format described in the serialized blocks section. See that section for an example hexdump. It can be sent for two different reasons:

  1. GetData Response: Nodes will always send it in response to a getdata message that requests the block with an inventory type of MSG_BLOCK (provided the node has that block available for relay).

  2. Unsolicited: Some miners will send unsolicited block messages broadcasting their newly-mined blocks to all of their peers. Many mining pools do the same thing, although some may be misconfigured to send the block from multiple nodes, possibly sending the same block to some peers more than once.

GetBlocks

The getblocks message requests an inv message that provides block header hashes starting from a particular point in the block chain. It allows a peer which has been disconnected or started for the first time to get the data it needs to request the blocks it hasn’t seen.

Peers which have been disconnected may have stale blocks in their locally-stored block chain, so the getblocks message allows the requesting peer to provide the receiving peer with multiple header hashes at various heights on their local chain. This allows the receiving peer to find, within that list, the last header hash they had in common and reply with all subsequent header hashes.

Note: the receiving peer itself may respond with an inv message containing header hashes of stale blocks. It is up to the requesting peer to poll all of its peers to find the best block chain.

If the receiving peer does not find a common header hash within the list, it will assume the last common block was the genesis block (block zero), so it will reply with in inv message containing header hashes starting with block one (the first block after the genesis block).

Bytes Name Data Type Description
4 version uint32_t The protocol version number; the same as sent in the version message.
Varies hash count compactSize uint The number of header hashes provided not including the stop hash. There is no limit except that the byte size of the entire message must be below the MAX_SIZE limit; typically from 1 to 200 hashes are sent.
Varies block header hashes char[32] One or more block header hashes (32 bytes each) in internal byte order. Hashes should be provided in reverse order of block height, so highest-height hashes are listed first and lowest-height hashes are listed last.
32 stop hash char[32] The header hash of the last header hash being requested; set to all zeroes to request an inv message with all subsequent header hashes (a maximum of 500 will be sent as a reply to this message; if you need more than 500, you will need to send another getblocks message with a higher-height header hash as the first entry in block header hash field).

The following annotated hexdump shows a getblocks message. (The message header has been omitted.)

71110100 ........................... Protocol version: 70001
02 ................................. Hash count: 2

d39f608a7775b537729884d4e6633bb2
105e55a16a14d31b0000000000000000 ... Hash #1

5c3e6403d40837110a2e8afb602b1c01
714bda7ce23bea0a0000000000000000 ... Hash #2

00000000000000000000000000000000
00000000000000000000000000000000 ... Stop hash

GetData

The getdata message requests one or more data objects from another node. The objects are requested by an inventory, which the requesting node typically received previously by way of an inv message.

The response to a getdata message can be a tx message, block message, merkleblock message, cmpctblock message, or notfound message.

This message cannot be used to request arbitrary data, such as historic transactions no longer in the memory pool or relay set. Full nodes may not even be able to provide older blocks if they’ve pruned old transactions from their block database. For this reason, the getdata message should usually only be used to request data from a node which previously advertised it had that data by sending an inv message.

The format and maximum size limitations of the getdata message are identical to the inv message; only the message header differs.

GetHeaders

Added in protocol version 31800.

The getheaders message requests a headers message that provides block headers starting from a particular point in the block chain. It allows a peer which has been disconnected or started for the first time to get the headers it hasn’t seen yet.

The getheaders message is nearly identical to the getblocks message, with one minor difference: the inv reply to the getblocks message will include no more than 500 block header hashes; the headers reply to the getheaders message will include as many as 2,000 block headers.

Headers

Added in protocol version 31800.

The headers message sends block headers to a node which previously requested certain headers with a getheaders message. A headers message can be empty.

Bytes Name Data Type Description
Varies count compactSize uint Number of block headers up to a maximum of 2,000. Note: headers-first sync assumes the sending node will send the maximum number of headers whenever possible.
Varies headers block_header Block headers: each 80-byte block header is in the format described in the block headers section with an additional 0x00 suffixed. This 0x00 is called the transaction count, but because the headers message doesn’t include any transactions, the transaction count is always zero.

The following annotated hexdump shows a headers message. (The message header has been omitted.)

01 ................................. Header count: 1

02000000 ........................... Block version: 2
b6ff0b1b1680a2862a30ca44d346d9e8
910d334beb48ca0c0000000000000000 ... Hash of previous block's header
9d10aa52ee949386ca9385695f04ede2
70dda20810decd12bc9b048aaab31471 ... Merkle root
24d95a54 ........................... Unix time: 1415239972
30c31b18 ........................... Target (bits)
fe9f0864 ........................... Nonce

00 ................................. Transaction count (0x00)

Inv

The inv message (inventory message) transmits one or more inventories of objects known to the transmitting peer. It can be sent unsolicited to announce new transactions or blocks, or it can be sent in reply to a getblocks message or mempool message.

The receiving peer can compare the inventories from an inv message against the inventories it has already seen, and then use a follow-up message to request unseen objects.

Bytes Name Data Type Description
Varies count compactSize uint The number of inventory entries.
Varies inventory inventory One or more inventory entries up to a maximum of 50,000 entries.

The following annotated hexdump shows an inv message with two inventory entries. (The message header has been omitted.)

02 ................................. Count: 2

01000000 ........................... Type: MSG_TX
de55ffd709ac1f5dc509a0925d0b1fc4
42ca034f224732e429081da1b621f55a ... Hash (TXID)

01000000 ........................... Type: MSG_TX
91d36d997037e08018262978766f24b8
a055aaf1d872e94ae85e9817b2c68dc7 ... Hash (TXID)

MemPool

Added in protocol version 60002.

The mempool message requests the TXIDs of transactions that the receiving node has verified as valid but which have not yet appeared in a block. That is, transactions which are in the receiving node’s memory pool. The response to the mempool message is one or more inv messages containing the TXIDs in the usual inventory format.

Sending the mempool message is mostly useful when a program first connects to the network. Full nodes can use it to quickly gather most or all of the unconfirmed transactions available on the network; this is especially useful for miners trying to gather transactions for their transaction fees. SPV clients can set a filter before sending a mempool to only receive transactions that match that filter; this allows a recently-started client to get most or all unconfirmed transactions related to its wallet.

The inv response to the mempool message is, at best, one node’s view of the network—not a complete list of unconfirmed transactions on the network. Here are some additional reasons the list might not be complete:

  • Before Bitcoin Core 0.9.0, the response to the mempool message was only one inv message. An inv message is limited to 50,000 inventories, so a node with a memory pool larger than 50,000 entries would not send everything. Later versions of Bitcoin Core send as many inv messages as needed to reference its complete memory pool.

  • The mempool message is not currently fully compatible with the filterload message’s BLOOM_UPDATE_ALL and BLOOM_UPDATE_P2PUBKEY_ONLY flags. Mempool transactions are not sorted like in-block transactions, so a transaction (tx2) spending an output can appear before the transaction (tx1) containing that output, which means the automatic filter update mechanism won’t operate until the second-appearing transaction (tx1) is seen—missing the first-appearing transaction (tx2). It has been proposed in Bitcoin Core issue #2381 that the transactions should be sorted before being processed by the filter.

There is no payload in a mempool message. See the message header section for an example of a message without a payload.

MerkleBlock

Added in protocol version 70001 as described by BIP37.

The merkleblock message is a reply to a getdata message which requested a block using the inventory type MSG_MERKLEBLOCK. It is only part of the reply: if any matching transactions are found, they will be sent separately as tx messages.

If a filter has been previously set with the filterload message, the merkleblock message will contain the TXIDs of any transactions in the requested block that matched the filter, as well as any parts of the block’s merkle tree necessary to connect those transactions to the block header’s merkle root. The message also contains a complete copy of the block header to allow the client to hash it and confirm its proof of work.

Bytes Name Data Type Description
80 block header block_header The block header in the format described in the block header section.
4 transaction count uint32_t The number of transactions in the block (including ones that don’t match the filter).
Varies hash count compactSize uint The number of hashes in the following field.
Varies hashes char[32] One or more hashes of both transactions and merkle nodes in internal byte order. Each hash is 32 bytes.
Varies flag byte count compactSize uint The number of flag bytes in the following field.
Varies flags byte[] A sequence of bits packed eight in a byte with the least significant bit first. May be padded to the nearest byte boundary but must not contain any more bits than that. Used to assign the hashes to particular nodes in the merkle tree as described below.

The annotated hexdump below shows a merkleblock message which corresponds to the examples below. (The message header has been omitted.)

01000000 ........................... Block version: 1
82bb869cf3a793432a66e826e05a6fc3
7469f8efb7421dc88067010000000000 ... Hash of previous block's header
7f16c5962e8bd963659c793ce370d95f
093bc7e367117b3c30c1f8fdd0d97287 ... Merkle root
76381b4d ........................... Time: 1293629558
4c86041b ........................... nBits: 0x04864c * 256**(0x1b-3)
554b8529 ........................... Nonce

07000000 ........................... Transaction count: 7
04 ................................. Hash count: 4

3612262624047ee87660be1a707519a4
43b1c1ce3d248cbfc6c15870f6c5daa2 ... Hash #1
019f5b01d4195ecbc9398fbf3c3b1fa9
bb3183301d7a1fb3bd174fcfa40a2b65 ... Hash #2
41ed70551dd7e841883ab8f0b16bf041
76b7d1480e4f0af9f3d4c3595768d068 ... Hash #3
20d2a7bc994987302e5b1ac80fc425fe
25f8b63169ea78e68fbaaefa59379bbf ... Hash #4

01 ................................. Flag bytes: 1
1d ................................. Flags: 1 0 1 1 1 0 0 0

Note: when fully decoded, the above merkleblock message provided the TXID for a single transaction that matched the filter. In the network traffic dump this output was taken from, the full transaction belonging to that TXID was sent immediately after the merkleblock message as a tx message.

Parsing A MerkleBlock Message

As seen in the annotated hexdump above, the merkleblock message provides three special data types: a transaction count, a list of hashes, and a list of one-bit flags.

You can use the transaction count to construct an empty merkle tree. We’ll call each entry in the tree a node; on the bottom are TXID nodes—the hashes for these nodes are TXIDs; the remaining nodes (including the merkle root) are non-TXID nodes—they may actually have the same hash as a TXID, but we treat them differently.

Example Of Parsing A MerkleBlock Message

Keep the hashes and flags in the order they appear in the merkleblock message. When we say “next flag” or “next hash”, we mean the next flag or hash on the list, even if it’s the first one we’ve used so far.

Start with the merkle root node and the first flag. The table below describes how to evaluate a flag based on whether the node being processed is a TXID node or a non-TXID node. Once you apply a flag to a node, never apply another flag to that same node or reuse that same flag again.

Flag TXID Node Non-TXID Node
0 Use the next hash as this node’s TXID, but this transaction didn’t match the filter. Use the next hash as this node’s hash. Don’t process any descendant nodes.
1 Use the next hash as this node’s TXID, and mark this transaction as matching the filter. The hash needs to be computed. Process the left child node to get its hash; process the right child node to get its hash; then concatenate the two hashes as 64 raw bytes and hash them to get this node’s hash.

Any time you begin processing a node for the first time, evaluate the next flag. Never use a flag at any other time.

When processing a child node, you may need to process its children (the grandchildren of the original node) or further-descended nodes before returning to the parent node. This is expected—keep processing depth first until you reach a TXID node or a non-TXID node with a flag of 0.

After you process a TXID node or a non-TXID node with a flag of 0, stop processing flags and begin to ascend the tree. As you ascend, compute the hash of any nodes for which you now have both child hashes or for which you now have the sole child hash. See the merkle tree section for hashing instructions. If you reach a node where only the left hash is known, descend into its right child (if present) and further descendants as necessary.

However, if you find a node whose left and right children both have the same hash, fail. This is related to CVE-2012-2459.

Continue descending and ascending until you have enough information to obtain the hash of the merkle root node. If you run out of flags or hashes before that condition is reached, fail. Then perform the following checks (order doesn’t matter):

For a detailed example of parsing a merkleblock message, please see the corresponding merkle block examples section.

Creating A MerkleBlock Message

It’s easier to understand how to create a merkleblock message after you understand how to parse an already-created message, so we recommend you read the parsing section above first.

Create a complete merkle tree with TXIDs on the bottom row and all the other hashes calculated up to the merkle root on the top row. For each transaction that matches the filter, track its TXID node and all of its ancestor nodes.

Example Of Creating A MerkleBlock Message

Start processing the tree with the merkle root node. The table below describes how to process both TXID nodes and non-TXID nodes based on whether the node is a match, a match ancestor, or neither a match nor a match ancestor.

  TXID Node Non-TXID Node
Neither Match Nor Match Ancestor Append a 0 to the flag list; append this node’s TXID to the hash list. Append a 0 to the flag list; append this node’s hash to the hash list. Do not descend into its child nodes.
Match Or Match Ancestor Append a 1 to the flag list; append this node’s TXID to the hash list. Append a 1 to the flag list; process the left child node. Then, if the node has a right child, process the right child. Do not append a hash to the hash list for this node.

Any time you begin processing a node for the first time, a flag should be appended to the flag list. Never put a flag on the list at any other time, except when processing is complete to pad out the flag list to a byte boundary.

When processing a child node, you may need to process its children (the grandchildren of the original node) or further-descended nodes before returning to the parent node. This is expected—keep processing depth first until you reach a TXID node or a node which is neither a TXID nor a match ancestor.

After you process a TXID node or a node which is neither a TXID nor a match ancestor, stop processing and begin to ascend the tree until you find a node with a right child you haven’t processed yet. Descend into that right child and process it.

After you fully process the merkle root node according to the instructions in the table above, processing is complete. Pad your flag list to a byte boundary and construct the merkleblock message using the template near the beginning of this subsection.

CmpctBlock

Added in protocol version 70014 as described by BIP152.

Version 1 compact blocks are pre-segwit (txids) Version 2 compact blocks are post-segwit (wtxids)

The cmpctblock message is a reply to a getdata message which requested a block using the inventory type MSG_CMPCT_BLOCK. If the requested block was recently announced and is close to the tip of the best chain of the receiver and after having sent the requesting peer a sendcmpct message, nodes respond with a cmpctblock message containing data for the block.

If the requested block is too old, the node responds with a full non-compact block

Upon receipt of a cmpctblock message, after sending a sendcmpct message, nodes should calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message. After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block should request the missing transactions using a getblocktxn message.

A node must not send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block. A node must not send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing, fully-validated chain with a valid proof-of-work either as a part of the current most-work valid chain, or building directly on top of it. A node may send a cmpctblock message before validating that each transaction in the block validly spends existing UTXO set entries.

The cmpctblock message contains a vector of PrefilledTransaction whose structure is defined below.

Bytes Name Data Type Description
Varies index compactSize uint The index into the block at which this transaction is located.
Varies tx Transaction The transaction which is in the block at the index.

The cmpctblock message is compromised of a serialized HeaderAndShortIDs structure which is defined below. A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.

Bytes Name Data Type Description
80 block header block_header The block header in the format described in the block header section.
8 nonce uint64_t A nonce for use in short transaction ID calculations.
Varies shortids length compactSize uint The number of short transaction IDs in the following field.
Varies shortids byte[] The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn. Vector of 6-byte integers in the spec, padded with two null-bytes so it can be read as an 8-byte integer. In version 2 of compact blocks, shortids should use the wtxid instead of txid as defined by BIP141
Varies prefilled txn length compactSize uint The number of prefilled transactions in the following field.
Varies prefilled txn PrefilledTransaction[] Used to provide the coinbase transaction and a select few which we expect a peer may be missing. Vector of PrefilledTransaction structures defined above.

Important protocol version 70015 notes regarding Compact Blocks

New banning behavior was added to the compact block logic in protocol version 70015 to prevent node abuse, the new changes are outlined below as defined in BIP152.

Any undefined behavior in this spec may cause failure to transfer block to, peer disconnection by, or self-destruction by the receiving node. A node receiving non-minimally-encoded CompactSize encodings should make a best-effort to eat the sender’s cat.

As high-bandwidth mode permits relaying of cmpctblock messages prior to full validation (requiring only that the block header is valid before relay), nodes SHOULD NOT ban a peer for announcing a new block with a cmpctblock message that is invalid, but has a valid header.

For avoidance of doubt, nodes SHOULD bump their peer-to-peer protocol version to 70015 or higher to signal that they will not ban or punish a peer for announcing compact blocks prior to full validation, and nodes SHOULD NOT announce a cmpctblock message to a peer with a version number below 70015 before fully validating the block.

Version 2 compact blocks notes

Transactions inside cmpctblock messages (both those used as direct announcement and those in response to getdata) and in blocktxn messages should include witness data, using the same format as responses to getdata MSG_WITNESS_TX, specified in BIP144.

Upon receipt of a getdata message containing a request for a MSG_CMPCT_BLOCK object for which a cmpctblock message is not sent in response, the block message containing the requested block in non-compact form MUST be encoded with witnesses (as is sent in reply to a MSG_WITNESS_BLOCK) if the protocol version used to encode the cmpctblock message would have been 2, and encoded without witnesses (as is sent in response to a MSG_BLOCK) if the protocol version used to encode the cmpctblock message would have been 1.

Short Transaction ID calculation

Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated as follows,

  • A single-SHA256 hashing the block header with the nonce appended (in little-endian)
  • Running SipHash-2-4 with the input being the transaction ID (wtxid in version 2 of compact blocks) and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.
  • Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.
  • Two null-bytes appended so it can be read as an 8-byte integer.

SendCmpct

Added in protocol version 70014 as described by BIP152.

The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer. The first integer is interpreted as a boolean and should have a value of either 1 or 0. The second integer is be interpreted as a little-endian version number.

Upon receipt of a sendcmpct message with the first and second integers set to 1, the node should announce new blocks by sending a cmpctblock message.

Upon receipt of a sendcmpct message with the first integer set to 0, the node shouldn’t announce new blocks by sending a cmpctblock message, but instead announce new blocks by sending invs or headers, as defined by BIP130.

Upon receipt of a sendcmpct message with the second integer set to something other than 1, nodes should treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in cmpctblock messages, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.

Nodes should check for a protocol version of >= 70014 before sending sendcmpct messages. Nodes shouldn’t send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer. Nodes shouldn’t request a MSG_CMPCT_BLOCK object before having sent all sendcmpct messages to that peer which they intend to send, as the peer cannot know what version protocol to use in the response.

The structure of a sendcmpct message is defined below.

Bytes Name Data Type Description
1 announce bool An integer representing a boolean value, must be 0x01 (true) or 0x00 (false).
8 version uint64_t A little-endian representation of a version number. Version 2 compact blocks should be specified by setting version to 2

GetBlockTxn

Added in protocol version 70014 as described by BIP152.

The getblocktxn message is defined as a message containing a serialized BlockTransactionsRequest message. Upon receipt of a properly-formatted getblocktxn message, nodes which recently provided the sender of such a message a cmpctblock message for the block hash identified in this message must respond with either an appropriate blocktxn message, or a full block message.

A blocktxn message response must contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn message indexes list, in the order requested.

The structure of BlockTransactionsRequest is defined below.

Bytes Name Data Type Description
32 block hash binary blob The blockhash of the block which the transactions being requested are in.
Varies indexes length compactSize uint The number of transactions being requested.
Varies indexes compactSize uint[] Vector of compactSize containing the indexes of the transactions being requested in the block. In version 2 of compact blocks, the wtxid should be used instead of the txid as defined by BIP141

BlockTxn

Added in protocol version 70014 as described by BIP152.

The blocktxn message is defined as a message containing a serialized BlockTransactions message. Upon receipt of a properly-formatted requested blocktxn message, nodes should attempt to reconstruct the full block by taking the prefilledtxn transactions from the original cmpctblock message and placing them in the marked positions, then for each short transaction ID from the original cmpctblock message, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block then once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes must not be penalized for such collisions, wherever they appear.

The structure of BlockTransactions is defined below.

Bytes Name Data Type Description
32 block hash binary blob The blockhash of the block which the transactions being provided are in.
Varies transactions length compactSize uint The number of transactions being provided.
Varies transactions Transactions[] Vector of transactions, for an example hexdump of the raw transaction format, see the raw transaction section.

NotFound

Added in protocol version 70001.

The notfound message is a reply to a getdata message which requested an object the receiving node does not have available for relay. (Nodes are not expected to relay historic transactions which are no longer in the memory pool or relay set. Nodes may also have pruned spent transactions from older blocks, making them unable to send those blocks.)

The format and maximum size limitations of the notfound message are identical to the inv message; only the message header differs.

Tx

The tx message transmits a single transaction in the raw transaction format. It can be sent in a variety of situations;

For an example hexdump of the raw transaction format, see the raw transaction section.

Control Messages

The following network messages all help control the connection between two peers or allow them to advise each other about the rest of the network.

Overview Of P2P Protocol Control And Advisory Messages

Note that almost none of the control messages are authenticated in any way, meaning they can contain incorrect or intentionally harmful information. In addition, this section does not yet cover P2P protocol operation over the Tor network; if you would like to contribute information about Tor, please open an issue.

Addr

The addr (IP address) message relays connection information for peers on the network. Each peer which wants to accept incoming connections creates an addr message providing its connection information and then sends that message to its peers unsolicited. Some of its peers send that information to their peers (also unsolicited), some of which further distribute it, allowing decentralized peer discovery for any program already on the network.

An addr message may also be sent in response to a getaddr message.

Bytes Name Data Type Description
Varies IP address count compactSize uint The number of IP address entries up to a maximum of 1,000.
Varies IP addresses network IP address IP address entries. See the table below for the format of a Bitcoin network IP address.

Each encapsulated network IP address currently uses the following structure:

Bytes Name Data Type Description
4 time uint32 Added in protocol version 31402.

A time in Unix epoch time format. Nodes advertising their own IP address set this to the current time. Nodes advertising IP addresses they’ve connected to set this to the last time they connected to that node. Other nodes just relaying the IP address should not change the time. Nodes can use the time field to avoid relaying old addr messages.

Malicious nodes may change times or even set them in the future.
8 services uint64_t The services the node advertised in its version message.
16 IP address char[16] IPv6 address in big endian byte order. IPv4 addresses can be provided as IPv4-mapped IPv6 addresses
2 port uint16_t Port number in big endian byte order. Note that Bitcoin Core will only connect to nodes with non-standard port numbers as a last resort for finding peers. This is to prevent anyone from trying to use the network to disrupt non-Bitcoin services that run on other ports.

The following annotated hexdump shows part of an addr message. (The message header has been omitted and the actual IP address has been replaced with a RFC5737 reserved IP address.)

fde803 ............................. Address count: 1000

d91f4854 ........................... Epoch time: 1414012889
0100000000000000 ................... Service bits: 01 (network node)
00000000000000000000ffffc0000233 ... IP Address: ::ffff:192.0.2.51
208d ............................... Port: 8333

[...] .............................. (999 more addresses omitted)

Alert

Added in protocol version 311. Removed in protocol version 70013 and released in Bitcoin Core 0.13.0

The legacy p2p network alert messaging system has been retired; however, internal alerts, partition detection warnings and the -alertnotify option features remain. See Alert System Retirement for details.

FeeFilter

Added in protocol version 70013 as described by BIP133.

The feefilter message is a request to the receiving peer to not relay any transaction inv messages to the sending peer where the fee rate for the transaction is below the fee rate specified in the feefilter message.

feefilter was introduced in Bitcoin Core 0.13.0 following the introduction of mempool limiting in Bitcoin Core 0.12.0. Mempool limiting provides protection against attacks and spam transactions that have low fee rates and are unlikely to be included in mined blocks. The feefilter messages allows a node to inform its peers that it will not accept transactions below a specified fee rate into its mempool, and therefore that the peers can skip relaying inv messages for transactions below that fee rate to that node.

Bytes Name Data Type Description
8 feerate uint64_t The fee rate (in satoshis per kilobyte) below which transactions should not be relayed to this peer.

The receiving peer may choose to ignore the message and not filter transaction inv messages.

The fee filter is additive with bloom filters. If an SPV client loads a bloom filter and sends a feefilter message, transactions should only be relayed if they pass both filters.

Note however that feefilter has no effect on block propagation or responses to getdata messages. For example, if a node requests a merkleblock from its peer by sending a getdata message with inv type MSG_FILTERED_BLOCK and it has previously sent a feefilter to that peer, the peer should respond with a merkleblock containing all the transactions matching the bloom filter, even if they are below the feefilter fee rate.

inv messages generated from a mempool message are subject to a fee filter if it exists.

The annotated hexdump below shows a feefilter message. (The message header has been omitted.)

7cbd000000000000 ... satoshis per kilobyte: 48,508

FilterAdd

Added in protocol version 70001 as described by BIP37.

The filteradd message tells the receiving peer to add a single element to a previously-set bloom filter, such as a new public key. The element is sent directly to the receiving peer; the peer then uses the parameters set in the filterload message to add the element to the bloom filter.

Because the element is sent directly to the receiving peer, there is no obfuscation of the element and none of the plausible-deniability privacy provided by the bloom filter. Clients that want to maintain greater privacy should recalculate the bloom filter themselves and send a new filterload message with the recalculated bloom filter.

Bytes Name Data Type Description
Varies element bytes compactSize uint The number of bytes in the following element field.
Varies element uint8_t[] The element to add to the current filter. Maximum of 520 bytes, which is the maximum size of an element which can be pushed onto the stack in a pubkey or signature script. Elements must be sent in the byte order they would use when appearing in a raw transaction; for example, hashes should be sent in internal byte order.

Note: a filteradd message will not be accepted unless a filter was previously set with the filterload message.

The annotated hexdump below shows a filteradd message adding a TXID. (The message header has been omitted.) This TXID appears in the same block used for the example hexdump in the merkleblock message; if that merkleblock message is re-sent after sending this filteradd message, six hashes are returned instead of four.

20 ................................. Element bytes: 32
fdacf9b3eb077412e7a968d2e4f11b9a
9dee312d666187ed77ee7d26af16cb0b ... Element (A TXID)

FilterClear

Added in protocol version 70001 as described by BIP37.

The filterclear message tells the receiving peer to remove a previously-set bloom filter. This also undoes the effect of setting the relay field in the version message to 0, allowing unfiltered access to inv messages announcing new transactions.

Bitcoin Core does not require a filterclear message before a replacement filter is loaded with filterload. It also doesn’t require a filterload message before a filterclear message.

There is no payload in a filterclear message. See the message header section for an example of a message without a payload.

FilterLoad

Added in protocol version 70001 as described by BIP37.

The filterload message tells the receiving peer to filter all relayed transactions and requested merkle blocks through the provided filter. This allows clients to receive transactions relevant to their wallet plus a configurable rate of false positive transactions which can provide plausible-deniability privacy.

Bytes Name Data Type Description
Varies nFilterBytes compactSize uint Number of bytes in the following filter bit field.
Varies filter uint8_t[] A bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.
4 nHashFuncs uint32_t The number of hash functions to use in this filter. The maximum value allowed in this field is 50.
4 nTweak uint32_t An arbitrary value to add to the seed value in the hash function used by the bloom filter.
1 nFlags uint8_t A set of flags that control how outpoints corresponding to a matched pubkey script are added to the filter. See the table in the Updating A Bloom Filter subsection below.

The annotated hexdump below shows a filterload message. (The message header has been omitted.) For an example of how this payload was created, see the filterload example.

02 ......... Filter bytes: 2
b50f ....... Filter: 1010 1101 1111 0000
0b000000 ... nHashFuncs: 11
00000000 ... nTweak: 0/none
00 ......... nFlags: BLOOM_UPDATE_NONE

Initializing A Bloom Filter

Filters have two core parameters: the size of the bit field and the number of hash functions to run against each data element. The following formulas from BIP37 will allow you to automatically select appropriate values based on the number of elements you plan to insert into the filter (n) and the false positive rate (p) you desire to maintain plausible deniability.

  • Size of the bit field in bytes (nFilterBytes), up to a maximum of 36,000: (-1 / log(2)**2 * n * log(p)) / 8

  • Hash functions to use (nHashFuncs), up to a maximum of 50: nFilterBytes * 8 / n * log(2)

Note that the filter matches parts of transactions (transaction elements), so the false positive rate is relative to the number of elements checked—not the number of transactions checked. Each normal transaction has a minimum of four matchable elements (described in the comparison subsection below), so a filter with a false-positive rate of 1 percent will match about 4 percent of all transactions at a minimum.

According to BIP37, the formulas and limits described above provide support for bloom filters containing 20,000 items with a false positive rate of less than 0.1 percent or 10,000 items with a false positive rate of less than 0.0001 percent.

Once the size of the bit field is known, the bit field should be initialized as all zeroes.

Populating A Bloom Filter

The bloom filter is populated using between 1 and 50 unique hash functions (the number specified per filter by the nHashFuncs field). Instead of using up to 50 different hash function implementations, a single implementation is used with a unique seed value for each function.

The seed is nHashNum * 0xfba4c795 + nTweak as a uint32_t, where the values are:

  • nHashNum is the sequence number for this hash function, starting at 0 for the first hash iteration and increasing up to the value of the nHashFuncs field (minus one) for the last hash iteration.

  • 0xfba4c795 is a constant optimized to create large differences in the seed for different values of nHashNum.

  • nTweak is a per-filter constant set by the client to require the use of an arbitrary set of hash functions.

If the seed resulting from the formula above is larger than four bytes, it must be truncated to its four most significant bytes (for example, 0x8967452301 & 0xffffffff → 0x67452301).

The actual hash function implementation used is the 32-bit Murmur3 hash function.

Warning icon Warning: the Murmur3 hash function has separate 32-bit and 64-bit versions that produce different results for the same input. Only the 32-bit Murmur3 version is used with Bitcoin bloom filters.

The data to be hashed can be any transaction element which the bloom filter can match. See the next subsection for the list of transaction elements checked against the filter. The largest element which can be matched is a script data push of 520 bytes, so the data should never exceed 520 bytes.

The example below from Bitcoin Core bloom.cpp combines all the steps above to create the hash function template. The seed is the first parameter; the data to be hashed is the second parameter. The result is a uint32_t modulo the size of the bit field in bits.

MurmurHash3(nHashNum * 0xFBA4C795 + nTweak, vDataToHash) % (vData.size() * 8)

Each data element to be added to the filter is hashed by nHashFuncs number of hash functions. Each time a hash function is run, the result will be the index number (nIndex) of a bit in the bit field. That bit must be set to 1. For example if the filter bit field was 00000000 and the result is 5, the revised filter bit field is 00000100 (the first bit is bit 0).

It is expected that sometimes the same index number will be returned more than once when populating the bit field; this does not affect the algorithm—after a bit is set to 1, it is never changed back to 0.

After all data elements have been added to the filter, each set of eight bits is converted into a little-endian byte. These bytes are the value of the filter field.

Comparing Transaction Elements To A Bloom Filter

To compare an arbitrary data element against the bloom filter, it is hashed using the same parameters used to create the bloom filter. Specifically, it is hashed nHashFuncs times, each time using the same nTweak provided in the filter, and the resulting output is modulo the size of the bit field provided in the filter field. After each hash is performed, the filter is checked to see if the bit at that indexed location is set. For example if the result of a hash is 5 and the filter is 01001110, the bit is considered set.

If the result of every hash points to a set bit, the filter matches. If any of the results points to an unset bit, the filter does not match.

The following transaction elements are compared against bloom filters. All elements will be hashed in the byte order used in blocks (for example, TXIDs will be in internal byte order).

  • TXIDs: the transaction’s SHA256(SHA256()) hash.

  • Outpoints: each 36-byte outpoint used this transaction’s input section is individually compared to the filter.

  • Signature Script Data: each element pushed onto the stack by a data-pushing opcode in a signature script from this transaction is individually compared to the filter. This includes data elements present in P2SH redeem scripts when they are being spent.

  • PubKey Script Data: each element pushed onto the the stack by a data-pushing opcode in any pubkey script from this transaction is individually compared to the filter. (If a pubkey script element matches the filter, the filter will be immediately updated if the BLOOM_UPDATE_ALL flag was set; if the pubkey script is in the P2PKH format and matches the filter, the filter will be immediately updated if the BLOOM_UPDATE_P2PUBKEY_ONLY flag was set. See the subsection below for details.)

The following annotated hexdump of a transaction is from the raw transaction format section; the elements which would be checked by the filter are emphasized in bold. Note that this transaction’s TXID (01000000017b1eab[...]) would also be checked, and that the outpoint TXID and index number below would be checked as a single 36-byte element.

01000000 ................................... Version

01 ......................................... Number of inputs
|
| 7b1eabe0209b1fe794124575ef807057
| c77ada2138ae4fa8d6c4de0398a14f3f ......... Outpoint TXID
| 00000000 ................................. Outpoint index number
|
| 49 ....................................... Bytes in sig. script: 73
| | 48 ..................................... Push 72 bytes as data
| | | 30450221008949f0cb400094ad2b5eb3
| | | 99d59d01c14d73d8fe6e96df1a7150de
| | | b388ab8935022079656090d7f6bac4c9
| | | a94e0aad311a4268e082a725f8aeae05
| | | 73fb12ff866a5f01 ..................... Secp256k1 signature
|
| ffffffff ................................. Sequence number: UINT32_MAX

01 ......................................... Number of outputs
| f0ca052a01000000 ......................... Satoshis (49.99990000 BTC)
|
| 19 ....................................... Bytes in pubkey script: 25
| | 76 ..................................... OP_DUP
| | a9 ..................................... OP_HASH160
| | 14 ..................................... Push 20 bytes as data
| | | cbc20a7664f2f69e5355aa427045bc15
| | | e7c6c772 ............................. PubKey hash
| | 88 ..................................... OP_EQUALVERIFY
| | ac ..................................... OP_CHECKSIG

00000000 ................................... locktime: 0 (a block height)

Updating A Bloom Filter

Clients will often want to track inputs that spend outputs (outpoints) relevant to their wallet, so the filterload field nFlags can be set to allow the filtering node to update the filter when a match is found. When the filtering node sees a pubkey script that pays a pubkey, address, or other data element matching the filter, the filtering node immediately updates the filter with the outpoint corresponding to that pubkey script.

Automatically Updating Bloom Filters

If an input later spends that outpoint, the filter will match it, allowing the filtering node to tell the client that one of its transaction outputs has been spent.

The nFlags field has three allowed values:

Value Name Description
0 BLOOM_UPDATE_NONE The filtering node should not update the filter.
1 BLOOM_UPDATE_ALL If the filter matches any data element in a pubkey script, the corresponding outpoint is added to the filter.
2 BLOOM_UPDATE_P2PUBKEY_ONLY If the filter matches any data element in a pubkey script and that script is either a P2PKH or non-P2SH pay-to-multisig script, the corresponding outpoint is added to the filter.

In addition, because the filter size stays the same even though additional elements are being added to it, the false positive rate increases. Each false positive can result in another element being added to the filter, creating a feedback loop that can (after a certain point) make the filter useless. For this reason, clients using automatic filter updates need to monitor the actual false positive rate and send a new filter when the rate gets too high.

GetAddr

The getaddr message requests an addr message from the receiving node, preferably one with lots of IP addresses of other receiving nodes. The transmitting node can use those IP addresses to quickly update its database of available nodes rather than waiting for unsolicited addr messages to arrive over time.

There is no payload in a getaddr message. See the message header section for an example of a message without a payload.

Ping

The ping message helps confirm that the receiving peer is still connected. If a TCP/IP error is encountered when sending the ping message (such as a connection timeout), the transmitting node can assume that the receiving node is disconnected. The response to a ping message is the pong message.

Before protocol version 60000, the ping message had no payload. As of protocol version 60001 and all later versions, the message includes a single field, the nonce.

Bytes Name Data Type Description
8 nonce uint64_t Added in protocol version 60001 as described by BIP31.

Random nonce assigned to this ping message. The responding pong message will include this nonce to identify the ping message to which it is replying.

The annotated hexdump below shows a ping message. (The message header has been omitted.)

0094102111e2af4d ... Nonce

Pong

Added in protocol version 60001 as described by BIP31.

The pong message replies to a ping message, proving to the pinging node that the ponging node is still alive. Bitcoin Core will, by default, disconnect from any clients which have not responded to a ping message within 20 minutes.

To allow nodes to keep track of latency, the pong message sends back the same nonce received in the ping message it is replying to.

The format of the pong message is identical to the ping message; only the message header differs.

Reject

Added in protocol version 70002 as described by BIP61.

Deprecated in Bitcoin Core 0.18.0.

The reject message informs the receiving node that one of its previous messages has been rejected.

Bytes Name Data Type Description
Varies message bytes compactSize uint The number of bytes in the following message field.
Varies message string The type of message rejected as ASCII text without null padding. For example: “tx”, “block”, or “version”.
1 code char The reject message code. See the table below.
Varies reason bytes compactSize uint The number of bytes in the following reason field. May be 0x00 if a text reason isn’t provided.
Varies reason string The reason for the rejection in ASCII text. This should not be displayed to the user; it is only for debugging purposes.
Varies extra data varies Optional additional data provided with the rejection. For example, most rejections of tx messages or block messages include the hash of the rejected transaction or block header. See the code table below.

The following table lists message reject codes. Codes are tied to the type of message they reply to; for example there is a 0x10 reject code for transactions and a 0x10 reject code for blocks.

Code In Reply To Extra Bytes Extra Type Description
0x01 any message 0 N/A Message could not be decoded. Be careful of reject message feedback loops where two peers each don’t understand each other’s reject messages and so keep sending them back and forth forever.
0x10 block message 32 char[32] Block is invalid for some reason (invalid proof-of-work, invalid signature, etc). Extra data may include the rejected block’s header hash.
0x10 tx message 32 char[32] Transaction is invalid for some reason (invalid signature, output value greater than input, etc.). Extra data may include the rejected transaction’s TXID.
0x11 block message 32 char[32] The block uses a version that is no longer supported. Extra data may include the rejected block’s header hash.
0x11 version message 0 N/A Connecting node is using a protocol version that the rejecting node considers obsolete and unsupported.
0x12 tx message 32 char[32] Duplicate input spend (double spend): the rejected transaction spends the same input as a previously-received transaction. Extra data may include the rejected transaction’s TXID.
0x12 version message 0 N/A More than one version message received in this connection.
0x40 tx message 32 char[32] The transaction will not be mined or relayed because the rejecting node considers it non-standard—a transaction type or version unknown by the server. Extra data may include the rejected transaction’s TXID.
0x41 tx message 32 char[32] One or more output amounts are below the dust threshold. Extra data may include the rejected transaction’s TXID.
0x42 tx message   char[32] The transaction did not have a large enough fee or priority to be relayed or mined. Extra data may include the rejected transaction’s TXID.
0x43 block message 32 char[32] The block belongs to a block chain which is not the same block chain as provided by a compiled-in checkpoint. Extra data may include the rejected block’s header hash.

The annotated hexdump below shows a reject message. (The message header has been omitted.)

02 ................................. Number of bytes in message: 2
7478 ............................... Type of message rejected: tx
12 ................................. Reject code: 0x12 (duplicate)
15 ................................. Number of bytes in reason: 21
6261642d74786e732d696e707574732d
7370656e74 ......................... Reason: bad-txns-inputs-spent
394715fcab51093be7bfca5a31005972
947baf86a31017939575fb2354222821 ... TXID

SendHeaders

The sendheaders message tells the receiving peer to send new block announcements using a headers message rather than an inv message.

There is no payload in a sendheaders message. See the message header section for an example of a message without a payload.

VerAck

Added in protocol version 209.

The verack message acknowledges a previously-received version message, informing the connecting node that it can begin to send other messages. The verack message has no payload; for an example of a message with no payload, see the message headers section.

Version

The version message provides information about the transmitting node to the receiving node at the beginning of a connection. Until both peers have exchanged version messages, no other messages will be accepted.

If a version message is accepted, the receiving node should send a verack message—but no node should send a verack message before initializing its half of the connection by first sending a version message.

Bytes Name Data Type Required/Optional Description
4 version int32_t Required The highest protocol version understood by the transmitting node. See the protocol version section.
8 services uint64_t Required The services supported by the transmitting node encoded as a bitfield. See the list of service codes below.
8 timestamp int64_t Required The current Unix epoch time according to the transmitting node’s clock. Because nodes will reject blocks with timestamps more than two hours in the future, this field can help other nodes to determine that their clock is wrong.
8 addr_recv services uint64_t Required The services supported by the receiving node as perceived by the transmitting node. Same format as the ‘services’ field above. Bitcoin Core will attempt to provide accurate information. BitcoinJ will, by default, always send 0.
16 addr_recv IP address char[16] Required The IPv6 address of the receiving node as perceived by the transmitting node in big endian byte order. IPv4 addresses can be provided as IPv4-mapped IPv6 addresses. Bitcoin Core will attempt to provide accurate information. BitcoinJ will, by default, always return ::ffff:127.0.0.1
2 addr_recv port uint16_t Required The port number of the receiving node as perceived by the transmitting node in big endian byte order.
8 addr_trans services uint64_t Required Added in protocol version 106.

The services supported by the transmitting node. Should be identical to the ‘services’ field above.
16 addr_trans IP address char[16] Required Added in protocol version 106.

The IPv6 address of the transmitting node in big endian byte order. IPv4 addresses can be provided as IPv4-mapped IPv6 addresses. Set to ::ffff:127.0.0.1 if unknown.
2 addr_trans port uint16_t Required Added in protocol version 106.

The port number of the transmitting node in big endian byte order.
8 nonce uint64_t Required Added in protocol version 106.

A random nonce which can help a node detect a connection to itself. If the nonce is 0, the nonce field is ignored. If the nonce is anything else, a node should terminate the connection on receipt of a version message with a nonce it previously sent.
Varies user_agent bytes compactSize uint Required Added in protocol version 106.

Number of bytes in following user_agent field. If 0x00, no user agent field is sent.
Varies user_agent string Required if user_agent bytes > 0 Added in protocol version 106. Renamed in protocol version 60000.

User agent as defined by BIP14. Previously called subVer.
4 start_height int32_t Required Added in protocol version 209.

The height of the transmitting node’s best block chain or, in the case of an SPV client, best block header chain.
1 relay bool Optional Added in protocol version 70001 as described by BIP37.

Transaction relay flag. If 0x00, no inv messages or tx messages announcing new transactions should be sent to this client until it sends a filterload message or filterclear message. If the relay field is not present or is set to 0x01, this node wants inv messages and tx messages announcing new transactions.

The following service identifiers have been assigned.

Value Name Description
0x00 Unnamed This node is not a full node. It may not be able to provide any data except for the transactions it originates.
0x01 NODE_NETWORK This is a full node and can be asked for full blocks. It should implement all protocol features available in its self-reported protocol version.
0x02 NODE_GETUTXO This is a full node capable of responding to the getutxo protocol request. This is not supported by any currently-maintained Bitcoin node. See BIP64 for details on how this is implemented.
0x04 NODE_BLOOM This is a full node capable and willing to handle bloom-filtered connections. See BIP111 for details.
0x08 NODE_WITNESS This is a full node that can be asked for blocks and transactions including witness data. See BIP144 for details.
0x10 NODE_XTHIN This is a full node that supports Xtreme Thinblocks. This is not supported by any currently-maintained Bitcoin node.
0x0400 NODE_NETWORK_LIMITED This is the same as NODE_NETWORK but the node has at least the last 288 blocks (last 2 days). See BIP159 for details on how this is implemented.

Note: Protocol version 70001 introduced the optional relay field, adding the possibility of an additional byte to the version message. This introduces an incompatibility with implementations of lower protocol versions which validate the version message size. When implementing support for protocol versions less than 70001 you may want to handle the case of a peer potentially sending an extra byte, treating it as invalid only in the case of a requested protocol version less than 70001.

The following annotated hexdump shows a version message. (The message header has been omitted and the actual IP addresses have been replaced with RFC5737 reserved IP addresses.)

72110100 ........................... Protocol version: 70002
0100000000000000 ................... Services: NODE_NETWORK
bc8f5e5400000000 ................... Epoch time: 1415483324

0100000000000000 ................... Receiving node's services
00000000000000000000ffffc61b6409 ... Receiving node's IPv6 address
208d ............................... Receiving node's port number

0100000000000000 ................... Transmitting node's services
00000000000000000000ffffcb0071c0 ... Transmitting node's IPv6 address
208d ............................... Transmitting node's port number

128035cbc97953f8 ................... Nonce

0f ................................. Bytes in user agent string: 15
2f5361746f7368693a302e392e332f ..... User agent: /Satoshi:0.9.3/

cf050500 ........................... Start height: 329167
01 ................................. Relay flag: true

Bitcoin Core APIs

Hash Byte Order

Bitcoin Core RPCs accept and return the byte-wise reverse of computed SHA-256 hash values. For example, the Unix sha256sum command displays the SHA256(SHA256()) hash of mainnet block 300,000’s header as:

> /bin/echo -n '020000007ef055e1674d2e6551dba41cd214debbee34aeb544c7ec670000000000000000d3998963f80c5bab43fe8c26228e98d030edf4dcbe48a666f5c39e2d7a885c9102c86d536c890019593a470d' | xxd -r -p | sha256sum -b | xxd -r -p | sha256sum -b
5472ac8b1187bfcf91d6d218bbda1eb2405d7c55f1f8cc820000000000000000

The result above is also how the hash appears in the previous-header-hash part of block 300,001’s header:

020000005472ac8b1187bfcf91d6d218bbda1eb2405d7c55f1f8cc82000\
0000000000000ab0aaa377ca3f49b1545e2ae6b0667a08f42e72d8c24ae\
237140e28f14f3bb7c6bcc6d536c890019edd83ccf

However, Bitcoin Core’s RPCs use the byte-wise reverse for hashes, so if you want to get information about block 300,000 using the getblock RPC, you need to reverse the requested hash:

> bitcoin-cli getblock \
  000000000000000082ccf8f1557c5d40b21edabb18d2d691cfbf87118bac7254

(Note: hex representation uses two characters to display each byte of data, which is why the reversed string looks somewhat mangled.)

The rationale for the reversal is unknown, but it likely stems from Bitcoin Core’s use of hashes (which are byte arrays in C++) as integers for the purpose of determining whether the hash is below the network target. Whatever the reason for reversing header hashes, the reversal also extends to other hashes used in RPCs, such as TXIDs and merkle roots.

As header hashes and TXIDs are widely used as global identifiers in other Bitcoin software, this reversal of hashes has become the standard way to refer to certain objects. The table below should make clear where each byte order is used.

Data Internal Byte Order RPC Byte Order
Example: SHA256(SHA256(0x00)) Hash: 1406…539a Hash: 9a53…0614
Header Hashes: SHA256(SHA256(block header)) Used when constructing block headers Used by RPCs such as getblock; widely used in block explorers
Merkle Roots: SHA256(SHA256(TXIDs and merkle rows)) Used when constructing block headers Returned by RPCs such as getblock
TXIDs: SHA256(SHA256(transaction)) Used in transaction inputs Used by RPCs such as gettransaction and transaction data parts of getblock; widely used in wallet programs
P2PKH Hashes: RIPEMD160(SHA256(pubkey)) Used in both addresses and pubkey scripts N/A: RPCs use addresses which use internal byte order
P2SH Hashes: RIPEMD160(SHA256(redeem script)) Used in both addresses and pubkey scripts N/A: RPCs use addresses which use internal byte order

Note: RPCs which return raw results, such as getrawtransaction or the raw mode of getblock, always display hashes as they appear in blocks (internal byte order).

The code below may help you check byte order by generating hashes from raw hex.

#!/usr/bin/env python

from sys import byteorder
from hashlib import sha256

## You can put in $data an 80-byte block header to get its header hash,
## or a raw transaction to get its txid
data = "00".decode("hex")
hash = sha256(sha256(data).digest()).digest()

print "Warning: this code only tested on a little-endian x86_64 arch"
print
print "System byte order:", byteorder
print "Internal-Byte-Order Hash: ", hash.encode('hex_codec')
print "RPC-Byte-Order Hash:      ", hash[::-1].encode('hex_codec')

Remote Procedure Calls (RPCs)

Bitcoin Core provides a remote procedure call (RPC) interface for various administrative tasks, wallet operations, and queries about network and block chain data.

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

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

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

The Bitcoin Core RPC service listens for HTTP POST requests on port 8332 in mainnet mode or 18332 in testnet or regtest mode. The port number can be changed by setting rpcport in bitcoin.conf. By default the RPC service binds to your server’s localhost loopback network interface so it’s not accessible from other servers. Authentication is implemented using HTTP basic authentication. RPC HTTP requests must include a Content-Type header set to text/plain and a Content-Length header set to the size of the request body.

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

Name Type Presence Description
Request object Required
(exactly 1)
The JSON-RPC request object

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

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

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

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

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

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

  • “→” indicates an argument that is the child of a JSON array or JSON object. For example, “→ → Parameter” above means Parameter is the child of the params array which itself is a child of the Request object.

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

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

  • “Type” is the JSON data type and the specific Bitcoin Core type.

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

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

Name Type Presence Description
Response object Required
(exactly 1)
The JSON-RPC response object.

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

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

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

As an example, here is the JSON-RPC request object for the hash of the genesis block:

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

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

bitcoin-cli getblockhash 0

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

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

The HTTP response data for this request would be:

{
    "result": "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f",
    "error": null,
    "id": "foo"
}

Note: In order to minimize its size, the raw JSON response from Bitcoin Core doesn’t include any extraneous whitespace characters. Here we’ve added whitespace to make the object more readable. Speaking of which, bitcoin-cli also transforms the raw response to make it more human-readable. It:

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

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

000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f

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

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

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

error: {"code": -8, "message": "Block height out of range"}

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

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

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

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

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

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

Quick Reference

Blockchain RPCs

Control RPCs

  • GetMemoryInfo: returns an object containing information about memory usage.
  • GetRpcInfo: returns details of the RPC server.
  • Help: list all commands, or get help for a specified command.
  • Logging: gets and sets the logging configuration.
  • Stop: stop Bitcoin server.
  • Uptime: returns the total uptime of the server.

Generating RPCs

Mining RPCs

Network RPCs

Rawtransactions RPCs

Util RPCs

Wallet RPCs

Note: the wallet RPCs are only available if Bitcoin Core was built with wallet support, which is the default.

RPCs

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 a pubkey 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.

AbandonTransaction

Added in Bitcoin Core 0.12.0

The abandontransaction RPC marks an in-wallet transaction and all its in-wallet descendants as abandoned. This allows their inputs to be respent.

Mark in-wallet transaction <txid> as abandoned This will mark this transaction and all its in-wallet descendants as abandoned which will allow for their inputs to be respent. It can be used to replace “stuck” or evicted transactions.

It only works on transactions which are not included in a block and are not currently in the mempool.

It has no effect on transactions which are already abandoned.

Parameter #1—txid

Name Type Presence Description
txid string (hex) Required
(exactly 1)
The transaction id

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli abandontransaction "1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d"

See also

AbortRescan

The abortrescan RPC Stops current wallet rescan

Stops current wallet rescan triggered by an RPC call, e.g. by an importprivkey call.

Parameters: none

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

Import a private key

bitcoin-cli importprivkey "mykey"

Abort the running wallet rescan

bitcoin-cli abortrescan
AddMultiSigAddress

Requires wallet support.

The addmultisigaddress RPC adds a P2SH multisig address to the wallet.

Add a nrequired-to-sign multisignature address to the wallet. Requires a new wallet backup.

Each key is a Bitcoin address or hex-encoded public key.

This functionality is only intended for use with non-watchonly addresses.

See importaddress for watchonly p2sh address support.

If ‘label’ is specified, assign address to that label.

Parameter #1—nrequired

Name Type Presence Description
nrequired number (int) Required
(exactly 1)
The number of required signatures out of the n keys or addresses.

Parameter #2—keys

Name Type Presence Description
keys json array Required
(exactly 1)
A json array of bitcoin addresses or hex-encoded public keys
[
  "key",      (string) bitcoin address or hex-encoded public key
  ...
]

Parameter #3—label

Name Type Presence Description
label string Optional A label to assign the addresses to.

Parameter #4—address_type

Name Type Presence Description
address_type string Optional
Default=set by -addresstype
The address type to use. Options are “legacy”, “p2sh-segwit”, and “bech32”.

Result

{
  "address":"multisigaddress",    (string) The value of the new multisig address.
  "redeemScript":"script"         (string) The string value of the hex-encoded redemption script.
}

Example

Add a multisig address from 2 addresses

bitcoin-cli addmultisigaddress 2 "[\"16sSauSf5pF2UkUwvKGq4qjNRzBZYqgEL5\",\"171sgjn4YtPu27adkKGrdDwzRTxnRkBfKV\"]"

See also

AddNode

The addnode RPC attempts to add or remove a node from the addnode list.

Or try a connection to a node once.

Nodes added using addnode (or -connect) are protected from DoS disconnection and are not required to be full nodes/support SegWit as other outbound peers are (though such peers will not be synced from).

Parameter #1—node

Name Type Presence Description
node string Required
(exactly 1)
The node (see getpeerinfo for nodes). The node to add as a string in the form of <IP address>:<port>. The IP address may be a hostname resolvable through DNS, an IPv4 address, an IPv4-as-IPv6 address, or an IPv6 address

Parameter #2—command

Name Type Presence Description
command string Required
(exactly 1)
‘add’ to add a node to the list, ‘remove’ to remove a node from the list, ‘onetry’ to try a connection to the node once. What to do with the IP address above. Options are:
add to add a node to the addnode list. Up to 8 nodes can be added additional to the default 8 nodes. Not limited by -maxconnections
remove to remove a node from the list. If currently connected, this will disconnect immediately
onetry to immediately attempt connection to the node even if the outgoing connection slots are full; this will only attempt the connection once

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli addnode "192.168.0.6:8333" "onetry"

See also

  • GetAddedNodeInfo: returns information about the given added node, or all added nodes (note that onetry addnodes are not listed here).
AnalyzePsbt

Added in Bitcoin Core 0.18.0

The analyzepsbt RPC analyzes and provides information about the current status of a PSBT and its inputs.

Parameter #1—psbt

Name Type Presence Description
psbt string Required
(exactly 1)
A base64 string of a PSBT

Result

{
  "inputs" : [                      (array of json objects)
    {
      "has_utxo" : true|false     (boolean) Whether a UTXO is provided
      "is_final" : true|false     (boolean) Whether the input is finalized
      "missing" : {               (json object, optional) Things that are missing that are required to complete this input
        "pubkeys" : [             (array, optional)
          "keyid"                 (string) Public key ID, hash160 of the public key, of a public key whose BIP 32 derivation path is missing
        ]
        "signatures" : [          (array, optional)
          "keyid"                 (string) Public key ID, hash160 of the public key, of a public key whose signature is missing
        ]
        "redeemscript" : "hash"   (string, optional) Hash160 of the redeemScript that is missing
        "witnessscript" : "hash"  (string, optional) SHA256 of the witnessScript that is missing
      }
      "next" : "role"             (string, optional) Role of the next person that this input needs to go to
    }
    ,...
  ]
  "estimated_vsize" : vsize       (numeric, optional) Estimated vsize of the final signed transaction
  "estimated_feerate" : feerate   (numeric, optional) Estimated feerate of the final signed transaction in BTC/kB. Shown only if all UTXO slots in the PSBT have been filled.
  "fee" : fee                     (numeric, optional) The transaction fee paid. Shown only if all UTXO slots in the PSBT have been filled.
  "next" : "role"                 (string) Role of the next person that this psbt needs to go to
}

Example

bitcoin-cli analyzepsbt "psbt"
BackupWallet

Requires wallet support.

The backupwallet RPC safely copies current wallet file to destination, which can be a directory or a path with filename.

Parameter #1—destination

Name Type Presence Description
destination string Required
(exactly 1)
The destination directory or file

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli backupwallet "backup.dat"

See also

BumpFee

Added in Bitcoin Core 0.14.0

The bumpfee RPC bumps the fee of an opt-in-RBF transaction T, replacing it with a new transaction B.

An opt-in RBF transaction with the given txid must be in the wallet.

The command will pay the additional fee by decreasing (or perhaps removing) its change output.

If the change output is not big enough to cover the increased fee, the command will currently fail instead of adding new inputs to compensate. (A future implementation could improve this.) The command will fail if the wallet or mempool contains a transaction that spends one of T’s outputs.

By default, the new fee will be calculated automatically using estimatesmartfee.

The user can specify a confirmation target for estimatesmartfee.

Alternatively, the user can specify totalFee, or use RPC settxfee to set a higher fee rate.

At a minimum, the new fee rate must be high enough to pay an additional new relay fee (incrementalfee returned by getnetworkinfo) to enter the node’s mempool.

Parameter #1—txid

Name Type Presence Description
txid string Required
(exactly 1)
The txid to be bumped

Parameter #2—options

Name Type Presence Description
options json object Optional  
{
  "confTarget": n,           (numeric, optional, default=fallback to wallet's default) Confirmation target (in blocks)
  "totalFee": n,             (numeric, optional, default=fallback to 'confTarget') Total fee (NOT feerate) to pay, in satoshis.
                             In rare cases, the actual fee paid might be slightly higher than the specified
                             totalFee if the tx change output has to be removed because it is too close to
                             the dust threshold.
  "replaceable": bool,       (boolean, optional, default=true) Whether the new transaction should still be
                             marked bip-125 replaceable. If true, the sequence numbers in the transaction will
                             be left unchanged from the original. If false, any input sequence numbers in the
                             original transaction that were less than 0xfffffffe will be increased to 0xfffffffe
                             so the new transaction will not be explicitly bip-125 replaceable (though it may
                             still be replaceable in practice, for example if it has unconfirmed ancestors which
                             are replaceable).
  "estimate_mode": "str",    (string, optional, default=UNSET) The fee estimate mode, must be one of:
                             "UNSET"
                             "ECONOMICAL"
                             "CONSERVATIVE"
}

Result

{
  "txid":    "value",   (string)  The id of the new transaction
  "origfee":  n,         (numeric) Fee of the replaced transaction
  "fee":      n,         (numeric) Fee of the new transaction
  "errors":  [ str... ] (json array of strings) Errors encountered during processing (may be empty)
}

Example

Bump the fee, get the new transaction’s txid

bitcoin-cli bumpfee <txid>

See also

ClearBanned

Added in Bitcoin Core 0.12.0

The clearbanned RPC clear all banned IPs.

Parameters: none

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli clearbanned

See also

  • ListBanned: list all banned IPs/Subnets.
  • SetBan: attempts to add or remove an IP/Subnet from the banned list.
CombinePsbt

The combinepsbt RPC combine multiple partially signed Bitcoin transactions into one transaction.

Implements the Combiner role.

Parameter #1—txs

Name Type Presence Description
txs json array Required
(exactly 1)
A json array of base64 strings of partially signed transactions
[
  "psbt",    (string) A base64 string of a PSBT
  ...
]

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli combinepsbt ["mybase64_1", "mybase64_2", "mybase64_3"]
CombineRawTransaction

The combinerawtransaction RPC combine multiple partially signed transactions into one transaction.

The combined transaction may be another partially signed transaction or a fully signed transaction.

Parameter #1—txs

Name Type Presence Description
txs json array Required
(exactly 1)
A json array of hex strings of partially signed transactions
[
  "hexstring",    (string) A transaction hash
  ...
]

Result

Name Type Presence Description
result string (hex) Required
(exactly 1)
The hex-encoded raw transaction with signature(s)

Example

bitcoin-cli combinerawtransaction ["myhex1", "myhex2", "myhex3"]
ConvertToPsbt

The converttopsbt RPC converts a network serialized transaction to a PSBT.

This should be used only with createrawtransaction and fundrawtransaction createpsbt and walletcreatefundedpsbt should be used for new applications.

Parameter #1—hexstring

Name Type Presence Description
hexstring string Required
(exactly 1)
The hex string of a raw transaction

Parameter #2—permitsigdata

Name Type Presence Description
permitsigdata boolean Optional
Default=false
If true, any signatures in the input will be discarded and conversion. will continue. If false, RPC will fail if any signatures are present.

Parameter #3—iswitness

Name Type Presence Description
iswitness boolean Optional
Default=depends on heuristic tests
Whether the transaction hex is a serialized witness transaction. If iswitness is not present, heuristic tests will be used in decoding. If true, only witness deserializaion will be tried. If false, only non-witness deserialization will be tried. Only has an effect if permitsigdata is true.

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

Create a transaction

bitcoin-cli createrawtransaction "[{\"txid\":\"myid\",\"vout\":0}]" "[{\"data\":\"00010203\"}]"

Convert the transaction to a PSBT

bitcoin-cli converttopsbt "rawtransaction"
CreateMultiSig

The createmultisig RPC creates a multi-signature address with n signature of m keys required.

It returns a json object with the address and redeemScript.

Parameter #1—nrequired

Name Type Presence Description
nrequired number (int) Required
(exactly 1)
The number of required signatures out of the n keys.

Parameter #2—keys

Name Type Presence Description
keys json array Required
(exactly 1)
A json array of hex-encoded public keys.
[
  "key",      (string) The hex-encoded public key
  ...
]

Parameter #3—address_type

Name Type Presence Description
address_type string Optional
Default=legacy
The address type to use. Options are “legacy”, “p2sh-segwit”, and “bech32”.

Result

{
  "address":"multisigaddress",  (string) The value of the new multisig address.
  "redeemScript":"script"       (string) The string value of the hex-encoded redemption script.
}

Example

Create a multisig address from 2 public keys

bitcoin-cli createmultisig 2 "[\"03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd\",\"03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626\"]"

See also

CreatePsbt

The createpsbt RPC creates a transaction in the Partially Signed Transaction format.

Implements the Creator role.

Parameter #1—inputs

Name Type Presence Description
inputs json array Required
(exactly 1)
A json array of json objects
[
  {                       (json object)
    "txid": "hex",        (string, required) The transaction id
    "vout": n,            (numeric, required) The output number
    "sequence": n,        (numeric, optional, default=depends on the value of the 'replaceable' and 'locktime' arguments) The sequence number
  },
  ...
]

Parameter #2—outputs

Name Type Presence Description
outputs json array Required
(exactly 1)
a json array with outputs (key-value pairs), where none of the keys are duplicated. That is, each address can only appear once and there can only be one ‘data’ object. For compatibility reasons, a dictionary, which holds the key-value pairs directly, is also accepted as second parameter.
[
  {                       (json object)
    "address": amount,    (numeric or string, required) A key-value pair. The key (string) is the bitcoin address, the value (float or string) is the amount in BTC
  },
  {                       (json object)
    "data": "hex",        (string, required) A key-value pair. The key must be "data", the value is hex-encoded data
  },
  ...
]

Parameter #3—locktime

Name Type Presence Description
locktime number (int) Optional
Default=0
Raw locktime. Non-0 value also locktime-activates inputs

Parameter #4—replaceable

Name Type Presence Description
replaceable boolean Optional
Default=false
Marks this transaction as BIP125 replaceable. Allows this transaction to be replaced by a transaction with higher fees. If provided, it is an error if explicit sequence numbers are incompatible.

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli createpsbt "[{\"txid\":\"myid\",\"vout\":0}]" "[{\"data\":\"00010203\"}]"
CreateRawTransaction

The createrawtransaction RPC create a transaction spending the given inputs and creating new outputs.

Outputs can be addresses or data.

Returns hex-encoded raw transaction.

Note that the transaction’s inputs are not signed, and it is not stored in the wallet or transmitted to the network.

Parameter #1—inputs

Name Type Presence Description
inputs json array Required
(exactly 1)
A json array of json objects
[
  {                       (json object)
    "txid": "hex",        (string, required) The transaction id
    "vout": n,            (numeric, required) The output number
    "sequence": n,        (numeric, optional, default=depends on the value of the 'replaceable' and 'locktime' arguments) The sequence number
  },
  ...
]

Parameter #2—outputs

Name Type Presence Description
outputs json array Required
(exactly 1)
a json array with outputs (key-value pairs), where none of the keys are duplicated. That is, each address can only appear once and there can only be one ‘data’ object. For compatibility reasons, a dictionary, which holds the key-value pairs directly, is also accepted as second parameter.
[
  {                       (json object)
    "address": amount,    (numeric or string, required) A key-value pair. The key (string) is the bitcoin address, the value (float or string) is the amount in BTC
  },
  {                       (json object)
    "data": "hex",        (string, required) A key-value pair. The key must be "data", the value is hex-encoded data
  },
  ...
]

Parameter #3—locktime

Name Type Presence Description
locktime number (int) Optional
Default=0
Raw locktime. Non-0 value also locktime-activates inputs

Parameter #4—replaceable

Name Type Presence Description
replaceable boolean Optional
Default=false
Marks this transaction as BIP125-replaceable. Allows this transaction to be replaced by a transaction with higher fees. If provided, it is an error if explicit sequence numbers are incompatible.

Result

Name Type Presence Description
result string (hex) Required
(exactly 1)
hex string of the transaction

Example

bitcoin-cli createrawtransaction "[{\"txid\":\"myid\",\"vout\":0}]" "[{\"address\":0.01}]"
bitcoin-cli createrawtransaction "[{\"txid\":\"myid\",\"vout\":0}]" "[{\"data\":\"00010203\"}]"

See also

CreateWallet

The createwallet RPC creates and loads a new wallet.

Parameter #1—wallet_name

Name Type Presence Description
wallet_name string Required
(exactly 1)
The name for the new wallet. If this is a path, the wallet will be created at the path location.

Parameter #2—disable_private_keys

Name Type Presence Description
disable_private_keys boolean Optional
Default=false
Disable the possibility of private keys (only watchonlys are possible in this mode).

Parameter #3—blank

Name Type Presence Description
blank boolean Optional
Default=false
Create a blank wallet. A blank wallet has no keys or HD seed. One can be set using sethdseed.

Result

{
  "name" :    <wallet_name>,        (string) The wallet name if created successfully. If the wallet was created using a full path, the wallet_name will be the full path.
  "warning" : <warning>,            (string) Warning message if wallet was not loaded cleanly.
}

Example

bitcoin-cli createwallet "testwallet"
DecodePsbt

The decodepsbt RPC return a JSON object representing the serialized, base64-encoded partially signed Bitcoin transaction.

Parameter #1—psbt

Name Type Presence Description
psbt string Required
(exactly 1)
The PSBT base64 string

Result

{
  "tx" : {                   (json object) The decoded network-serialized unsigned transaction.
    ...                                      The layout is the same as the output of decoderawtransaction.
  },
  "unknown" : {                (json object) The unknown global fields
    "key" : "value"            (key-value pair) An unknown key-value pair
     ...
  },
  "inputs" : [                 (array of json objects)
    {
      "non_witness_utxo" : {   (json object, optional) Decoded network transaction for non-witness UTXOs
        ...
      },
      "witness_utxo" : {            (json object, optional) Transaction output for witness UTXOs
        "amount" : x.xxx,           (numeric) The value in BTC
        "scriptPubKey" : {          (json object)
          "asm" : "asm",            (string) The asm
          "hex" : "hex",            (string) The hex
          "type" : "pubkeyhash",    (string) The type, eg 'pubkeyhash'
          "address" : "address"     (string) Bitcoin address if there is one
        }
      },
      "partial_signatures" : {             (json object, optional)
        "pubkey" : "signature",           (string) The public key and signature that corresponds to it.
        ,...
      }
      "sighash" : "type",                  (string, optional) The sighash type to be used
      "redeem_script" : {       (json object, optional)
          "asm" : "asm",            (string) The asm
          "hex" : "hex",            (string) The hex
          "type" : "pubkeyhash",    (string) The type, eg 'pubkeyhash'
        }
      "witness_script" : {       (json object, optional)
          "asm" : "asm",            (string) The asm
          "hex" : "hex",            (string) The hex
          "type" : "pubkeyhash",    (string) The type, eg 'pubkeyhash'
        }
      "bip32_derivs" : {          (json object, optional)
        "pubkey" : {                     (json object, optional) The public key with the derivation path as the value.
          "master_fingerprint" : "fingerprint"     (string) The fingerprint of the master key
          "path" : "path",                         (string) The path
        }
        ,...
      }
      "final_scriptsig" : {       (json object, optional)
          "asm" : "asm",            (string) The asm
          "hex" : "hex",            (string) The hex
        }
       "final_scriptwitness": ["hex", ...] (array of string) hex-encoded witness data (if any)
      "unknown" : {                (json object) The unknown global fields
        "key" : "value"            (key-value pair) An unknown key-value pair
         ...
      },
    }
    ,...
  ]
  "outputs" : [                 (array of json objects)
    {
      "redeem_script" : {       (json object, optional)
          "asm" : "asm",            (string) The asm
          "hex" : "hex",            (string) The hex
          "type" : "pubkeyhash",    (string) The type, eg 'pubkeyhash'
        }
      "witness_script" : {       (json object, optional)
          "asm" : "asm",            (string) The asm
          "hex" : "hex",            (string) The hex
          "type" : "pubkeyhash",    (string) The type, eg 'pubkeyhash'
      }
      "bip32_derivs" : [          (array of json objects, optional)
        {
          "pubkey" : "pubkey",                     (string) The public key this path corresponds to
          "master_fingerprint" : "fingerprint"     (string) The fingerprint of the master key
          "path" : "path",                         (string) The path
          }
        }
        ,...
      ],
      "unknown" : {                (json object) The unknown global fields
        "key" : "value"            (key-value pair) An unknown key-value pair
         ...
      },
    }
    ,...
  ]
  "fee" : fee                      (numeric, optional) The transaction fee paid if all UTXOs slots in the PSBT have been filled.
}

Example

bitcoin-cli decodepsbt "psbt"
DecodeRawTransaction

The decoderawtransaction RPC return a JSON object representing the serialized, hex-encoded transaction.

Parameter #1—hexstring

Name Type Presence Description
hexstring string Required
(exactly 1)
The transaction hex string

Parameter #2—iswitness

Name Type Presence Description
iswitness boolean Optional
Default=depends on heuristic tests
Whether the transaction hex is a serialized witness transaction If iswitness is not present, heuristic tests will be used in decoding

Result

{
  "txid" : "id",        (string) The transaction id
  "hash" : "id",        (string) The transaction hash (differs from txid for witness transactions)
  "size" : n,             (numeric) The transaction size
  "vsize" : n,            (numeric) The virtual transaction size (differs from size for witness transactions)
  "weight" : n,           (numeric) The transaction's weight (between vsize*4 - 3 and vsize*4)
  "version" : n,          (numeric) The version
  "locktime" : ttt,       (numeric) The lock time
  "vin" : [               (array of json objects)
     {
       "txid": "id",    (string) The transaction id
       "vout": n,         (numeric) The output number
       "scriptSig": {     (json object) The script
         "asm": "asm",  (string) asm
         "hex": "hex"   (string) hex
       },
       "txinwitness": ["hex", ...] (array of string) hex-encoded witness data (if any)
       "sequence": n     (numeric) The script sequence number
     }
     ,...
  ],
  "vout" : [             (array of json objects)
     {
       "value" : x.xxx,            (numeric) The value in BTC
       "n" : n,                    (numeric) index
       "scriptPubKey" : {          (json object)
         "asm" : "asm",          (string) the asm
         "hex" : "hex",          (string) the hex
         "reqSigs" : n,            (numeric) The required sigs
         "type" : "pubkeyhash",  (string) The type, eg 'pubkeyhash'
         "addresses" : [           (json array of string)
           "12tvKAXCxZjSmdNbao16dKXC8tRWfcF5oc"   (string) bitcoin address
           ,...
         ]
       }
     }
     ,...
  ],
}

Example

bitcoin-cli decoderawtransaction "hexstring"

See also

DecodeScript

The decodescript RPC decode a hex-encoded script.

Parameter #1—hexstring

Name Type Presence Description
hexstring string Required
(exactly 1)
the hex-encoded script

Result

{
  "asm":"asm",   (string) Script public key
  "hex":"hex",   (string) hex-encoded public key
  "type":"type", (string) The output type
  "reqSigs": n,    (numeric) The required signatures
  "addresses": [   (json array of string)
     "address"     (string) bitcoin address
     ,...
  ],
  "p2sh","address" (string) address of P2SH script wrapping this redeem script (not returned if the script is already a P2SH).
}

Example

bitcoin-cli decodescript "hexstring"

See also

DeriveAddresses

Added in Bitcoin Core 0.18.0

The deriveaddresses RPC derives one or more addresses corresponding to an output descriptor.

Examples of output descriptors are:

pkh(<pubkey>)                        P2PKH outputs for the given pubkey
wpkh(<pubkey>)                       Native segwit P2PKH outputs for the given pubkey
sh(multi(<n>,<pubkey>,<pubkey>,...)) P2SH-multisig outputs for the given threshold and pubkeys
raw(<hex script>)                    Outputs whose scriptPubKey equals the specified hex scripts

In the above, <pubkey> either refers to a fixed public key in hexadecimal notation, or to an xpub/xprv optionally followed by one or more path elements separated by “/”, where “h” represents a hardened child key.

For more information on output descriptors, see the documentation in the doc/descriptors.md file.

Parameter #1—descriptor

Name Type Presence Description
descriptor string Required
(exactly 1)
The descriptor.

Parameter #2—range

Name Type Presence Description
range numeric or array Optional If a ranged descriptor is used, this specifies the end or the range (in [begin,end] notation) to derive.

Result

[ address ] (array) the derived addresses

Example

First three native segwit receive addresses

bitcoin-cli deriveaddresses "wpkh([d34db33f/84h/0h/0h]xpub6DJ2dNUysrn5Vt36jH2KLBT2i1auw1tTSSomg8PhqNiUtx8QX2SvC9nrHu81fT41fvDUnhMjEzQgXnQjKEu3oaqMSzhSrHMxyyoEAmUHQbY/0/*)#trd0mf0l" "[0,2]"
DisconnectNode

Added in Bitcoin Core 0.12.0

The disconnectnode RPC immediately disconnects from the specified peer node.

Strictly one out of ‘address’ and ‘nodeid’ can be provided to identify the node.

To disconnect by nodeid, either set ‘address’ to the empty string, or call using the named ‘nodeid’ argument only.

Parameter #1—address

Name Type Presence Description
address string Optional
Default=fallback to nodeid
The IP address/port of the node

Parameter #2—nodeid

Name Type Presence Description
nodeid number (int) Optional
Default=fallback to address
The node ID (see getpeerinfo for node IDs)

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli disconnectnode "192.168.0.6:8333"
bitcoin-cli disconnectnode "" 1

See also

  • AddNode: attempts to add or remove a node from the addnode list.
  • GetAddedNodeInfo: returns information about the given added node, or all added nodes (note that onetry addnodes are not listed here).
DumpPrivKey

The dumpprivkey RPC reveals the private key corresponding to ‘address’.

Then the importprivkey can be used with this output

Parameter #1—address

Name Type Presence Description
address string Required
(exactly 1)
The bitcoin address for the private key

Result

Name Type Presence Description
result string (hex) Required
(exactly 1)
The private key

Example

bitcoin-cli dumpprivkey "myaddress"
bitcoin-cli importprivkey "mykey"

See also

DumpWallet

The dumpwallet RPC dumps all wallet keys in a human-readable format to a server-side file.

This does not allow overwriting existing files.

Imported scripts are included in the dumpfile, but corresponding BIP173 addresses, etc. may not be added automatically by importwallet.

Note that if your wallet contains keys which are not derived from your HD seed (e.g. imported keys), these are not covered by only backing up the seed itself, and must be backed up too (e.g. ensure you back up the whole dumpfile).

Parameter #1—filename

Name Type Presence Description
filename string Required
(exactly 1)
The filename with path (either absolute or relative to bitcoind)

Result

{                           (json object)
  "filename" : {        (string) The filename with full absolute path
}

Example

bitcoin-cli dumpwallet "test"

See also

  • BackupWallet: safely copies current wallet file to destination, which can be a directory or a path with filename.
  • ImportWallet: imports keys from a wallet dump file (see dumpwallet).
EncryptWallet

The encryptwallet RPC encrypts the wallet with ‘passphrase’.

This is for first time encryption.

After this, any calls that interact with private keys such as sending or signing will require the passphrase to be set prior the making these calls.

Use the walletpassphrase call for this, and then walletlock call.

If the wallet is already encrypted, use the walletpassphrasechange call.

Parameter #1—passphrase

Name Type Presence Description
passphrase string Required
(exactly 1)
The pass phrase to encrypt the wallet with. It must be at least 1 character, but should be long.

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

Encrypt your wallet

bitcoin-cli encryptwallet "my pass phrase"

Now set the passphrase to use the wallet, such as for signing or sending bitcoin

bitcoin-cli walletpassphrase "my pass phrase"

Now we can do something like sign

bitcoin-cli signmessage "address" "test message"

Now lock the wallet again by removing the passphrase

bitcoin-cli walletlock

See also

EstimateSmartFee

The estimatesmartfee RPC estimates the approximate fee per kilobyte needed for a transaction to begin confirmation within conf_target blocks if possible and return the number of blocks for which the estimate is valid.

Uses virtual transaction size as defined in BIP 141 (witness data is discounted).

Parameter #1—conf_target

Name Type Presence Description
conf_target number (int) Required
(exactly 1)
Confirmation target in blocks (1 - 1008)

Parameter #2—estimate_mode

Name Type Presence Description
estimate_mode string Optional
Default=CONSERVATIVE
The fee estimate mode. Whether to return a more conservative estimate which also satisfies a longer history. A conservative estimate potentially returns a higher feerate and is more likely to be sufficient for the desired target, but is not as responsive to short term drops in the prevailing fee market. Must be one of: “UNSET” “ECONOMICAL” “CONSERVATIVE”

Result

{
  "feerate" : x.x,     (numeric, optional) estimate fee rate in BTC/kB
  "errors": [ str... ] (json array of strings, optional) Errors encountered during processing
  "blocks" : n         (numeric) block number where estimate was found
}

Example

bitcoin-cli estimatesmartfee 6
FinalizePsbt

The finalizepsbt RPC finalize the inputs of a PSBT.

If the transaction is fully signed, it will produce a network serialized transaction which can be broadcast with sendrawtransaction. Otherwise a PSBT will be created which has the final_scriptSig and final_scriptWitness fields filled for inputs that are complete.

Implements the Finalizer and Extractor roles.

Parameter #1—psbt

Name Type Presence Description
psbt string Required
(exactly 1)
A base64 string of a PSBT

Parameter #2—extract

Name Type Presence Description
extract boolean Optional
Default=true
If true and the transaction is complete, extract and return the complete transaction in normal network serialization instead of the PSBT.

Result

{
  "psbt" : "value",          (string) The base64-encoded partially signed transaction if not extracted
  "hex" : "value",           (string) The hex-encoded network transaction if extracted
  "complete" : true|false,   (boolean) If the transaction has a complete set of signatures
  ]
}

Example

bitcoin-cli finalizepsbt "psbt"
FundRawTransaction

Added in Bitcoin Core 0.12.0

The fundrawtransaction RPC add inputs to a transaction until it has enough in value to meet its out value.

This will not modify existing inputs, and will add at most one change output to the outputs.

No existing outputs will be modified unless “subtractFeeFromOutputs” is specified.

Note that inputs which were signed may need to be resigned after completion since in/outputs have been added.

The inputs added will not be signed, use signrawtransactionwithkey or signrawtransactionwithwallet for that.

Note that all existing inputs must have their previous output transaction be in the wallet.

Note that all inputs selected must be of standard form and P2SH scripts must be in the wallet using importaddress or addmultisigaddress (to calculate fees).

You can see whether this is the case by checking the “solvable” field in the listunspent output.

Only pay-to-pubkey, multisig, and P2SH versions thereof are currently supported for watch-only

Parameter #1—hexstring

Name Type Presence Description
hexstring string Required
(exactly 1)
The hex string of the raw transaction

Parameter #2—options

Name Type Presence Description
options json object Optional for backward compatibility: passing in a true instead of an object will result in {“includeWatching”:true} “replaceable”: bool, (boolean, optional, default=fallback to wallet’s default) Marks this transaction as BIP125 replaceable. Allows this transaction to be replaced by a transaction with higher fees “conf_target”: n, (numeric, optional, default=fallback to wallet’s default) Confirmation target (in blocks) “estimate_mode”: “str”, (string, optional, default=UNSET) The fee estimate mode, must be one of: “UNSET” “ECONOMICAL” “CONSERVATIVE” }
{
  "changeAddress": "str",        (string, optional, default=pool address) The bitcoin address to receive the change
  "changePosition": n,           (numeric, optional, default=random) The index of the change output
  "change_type": "str",          (string, optional, default=set by -changetype) The output type to use. Only valid if changeAddress is not specified. Options are "legacy", "p2sh-segwit", and "bech32".
  "includeWatching": bool,       (boolean, optional, default=false) Also select inputs which are watch only
  "lockUnspents": bool,          (boolean, optional, default=false) Lock selected unspent outputs
  "feeRate": amount,             (numeric or string, optional, default=not set: makes wallet determine the fee) Set a specific fee rate in BTC/kB
  "subtractFeeFromOutputs": [    (json array, optional, default=empty array) A json array of integers.
                                 The fee will be equally deducted from the amount of each specified output.
                                 Those recipients will receive less bitcoins than you enter in their corresponding amount field.
                                 If no outputs are specified here, the sender pays the fee.
    vout_index,                  (numeric) The zero-based output index, before a change output is added.
    ...
  ],

Parameter #3—iswitness

Name Type Presence Description
iswitness boolean Optional
Default=depends on heuristic tests
Whether the transaction hex is a serialized witness transaction If iswitness is not present, heuristic tests will be used in decoding

Result

{
  "hex":       "value", (string)  The resulting raw transaction (hex-encoded string)
  "fee":       n,         (numeric) Fee in BTC the resulting transaction pays
  "changepos": n          (numeric) The position of the added change output, or -1
}

Example

Create a transaction with no inputs

bitcoin-cli createrawtransaction "[]" "{\"myaddress\":0.01}"

Add sufficient unsigned inputs to meet the output value

bitcoin-cli fundrawtransaction "rawtransactionhex"

Sign the transaction

bitcoin-cli signrawtransactionwithwallet "fundedtransactionhex"

Send the transaction

bitcoin-cli sendrawtransaction "signedtransactionhex"

See also

Generate

Added in Bitcoin Core 0.11.0

The generate RPC mine up to nblocks blocks immediately (before the RPC call returns) to an address in the wallet.

Parameter #1—nblocks

Name Type Presence Description
nblocks number (int) Required
(exactly 1)
How many blocks are generated immediately.

Parameter #2—maxtries

Name Type Presence Description
maxtries number (int) Optional
Default=1000000
How many iterations to try.

Result

[ blockhashes ]     (array) hashes of blocks generated

Example

Generate 11 blocks

bitcoin-cli generate 11

See also

GenerateToAddress

Added in Bitcoin Core 0.13.0

The generatetoaddress RPC mine blocks immediately to a specified address (before the RPC call returns).

Parameter #1—nblocks

Name Type Presence Description
nblocks number (int) Required
(exactly 1)
How many blocks are generated immediately.

Parameter #2—address

Name Type Presence Description
address string Required
(exactly 1)
The address to send the newly generated bitcoin to.

Parameter #3—maxtries

Name Type Presence Description
maxtries number (int) Optional
Default=1000000
How many iterations to try.

Result

[ blockhashes ]     (array) hashes of blocks generated

Example

Generate 11 blocks to myaddress

bitcoin-cli generatetoaddress 11 "myaddress"

If you are running the bitcoin core wallet, you can get a new address to send the newly generated bitcoin to with:

bitcoin-cli getnewaddress

See also

  • Generate: mine up to nblocks blocks immediately (before the RPC call returns) to an address in the wallet.
  • GetMiningInfo: returns a json object containing mining-related information.
  • GetBlockTemplate: if the request parameters include a ‘mode’ key, that is used to explicitly select between the default ‘template’ request or a ‘proposal’.
GetAddedNodeInfo

The getaddednodeinfo RPC returns information about the given added node, or all added nodes (note that onetry addnodes are not listed here).

Parameter #1—node

Name Type Presence Description
node string Optional
Default=all nodes
If provided, return information about this specific node, otherwise all nodes are returned.

Result

[
  {
    "addednode" : "192.168.0.201",   (string) The node IP address or name (as provided to addnode)
    "connected" : true|false,          (boolean) If connected
    "addresses" : [                    (list of objects) Only when connected = true
       {
         "address" : "192.168.0.201:8333",  (string) The bitcoin server IP and port we're connected to
         "connected" : "outbound"           (string) connection, inbound or outbound
       }
     ]
  }
  ,...
]

Example

bitcoin-cli getaddednodeinfo "192.168.0.201"

See also

GetAddressesByLabel

Added in Bitcoin Core 0.17.0

The getaddressesbylabel RPC returns the list of addresses assigned the specified label.

Parameter #1—label

Name Type Presence Description
label string Required
(exactly 1)
The label.

Result

{ (json object with addresses as keys)
  "address": { (json object with information about address)
    "purpose": "string" (string)  Purpose of address ("send" for sending address, "receive" for receiving address)
  },...
}

Example

bitcoin-cli getaddressesbylabel "tabby"
GetAddressInfo

Added in Bitcoin Core 0.17.0

The getaddressinfo RPC return information about the given bitcoin address.

Some information requires the address to be in the wallet.

Parameter #1—address

Name Type Presence Description
address string Required
(exactly 1)
The bitcoin address to get the information of.

Result

{
  "address" : "address",        (string) The bitcoin address validated
  "scriptPubKey" : "hex",       (string) The hex-encoded scriptPubKey generated by the address
  "ismine" : true|false,        (boolean) If the address is yours or not
  "iswatchonly" : true|false,   (boolean) If the address is watchonly
  "solvable" : true|false,      (boolean) Whether we know how to spend coins sent to this address, ignoring the possible lack of private keys
  "desc" : "desc",            (string, optional) A descriptor for spending coins sent to this address (only when solvable)
  "isscript" : true|false,      (boolean) If the key is a script
  "ischange" : true|false,      (boolean) If the address was used for change output
  "iswitness" : true|false,     (boolean) If the address is a witness address
  "witness_version" : version   (numeric, optional) The version number of the witness program
  "witness_program" : "hex"     (string, optional) The hex value of the witness program
  "script" : "type"             (string, optional) The output script type. Only if "isscript" is true and the redeemscript is known. Possible types: nonstandard, pubkey, pubkeyhash, scripthash, multisig, nulldata, witness_v0_keyhash, witness_v0_scripthash, witness_unknown
  "hex" : "hex",                (string, optional) The redeemscript for the p2sh address
  "pubkeys"                     (string, optional) Array of pubkeys associated with the known redeemscript (only if "script" is "multisig")
    [
      "pubkey"
      ,...
    ]
  "sigsrequired" : xxxxx        (numeric, optional) Number of signatures required to spend multisig output (only if "script" is "multisig")
  "pubkey" : "publickeyhex",    (string, optional) The hex value of the raw public key, for single-key addresses (possibly embedded in P2SH or P2WSH)
  "embedded" : {...},           (object, optional) Information about the address embedded in P2SH or P2WSH, if relevant and known. It includes all getaddressinfo output fields for the embedded address, excluding metadata ("timestamp", "hdkeypath", "hdseedid") and relation to the wallet ("ismine", "iswatchonly").
  "iscompressed" : true|false,  (boolean, optional) If the pubkey is compressed
  "label" :  "label"         (string) The label associated with the address, "" is the default label
  "timestamp" : timestamp,      (number, optional) The creation time of the key if available in seconds since epoch (Jan 1 1970 GMT)
  "hdkeypath" : "keypath"       (string, optional) The HD keypath if the key is HD and available
  "hdseedid" : "<hash160>"      (string, optional) The Hash160 of the HD seed
  "hdmasterfingerprint" : "<hash160>" (string, optional) The fingperint of the master key.
  "labels"                      (object) Array of labels associated with the address.
    [
      { (json object of label data)
        "name": "labelname" (string) The label
        "purpose": "string" (string) Purpose of address ("send" for sending address, "receive" for receiving address)
      },...
    ]
}

Example

bitcoin-cli getaddressinfo "1PSSGeFHDnKNxiEyFrD1wcEaHr9hrQDDWc"
GetBalance

The getbalance RPC returns the total available balance.

The available balance is what the wallet considers currently spendable, and is thus affected by options which limit spendability such as -spendzeroconfchange.

Parameter #1—dummy

Name Type Presence Description
dummy string Optional Remains for backward compatibility. Must be excluded or set to “*”.

Parameter #2—minconf

Name Type Presence Description
minconf number (int) Optional
Default=0
Only include transactions confirmed at least this many times.

Parameter #3—include_watchonly

Name Type Presence Description
include_watchonly boolean Optional
Default=false
Also include balance in watch-only addresses (see ‘importaddress’)

Result

Name Type Presence Description
result number (int) Required
(exactly 1)
The total amount in BTC received for this wallet.

Example

The total amount in the wallet with 1 or more confirmations

bitcoin-cli getbalance

The total amount in the wallet at least 6 blocks confirmed

bitcoin-cli getbalance "*" 6

See also

GetBestBlockHash

The getbestblockhash RPC returns the hash of the best (tip) block in the longest blockchain.

Parameters: none

Result

Name Type Presence Description
result string (hex) Required
(exactly 1)
the block hash, hex-encoded

Example

bitcoin-cli getbestblockhash

See also

GetBlock

The getblock RPC gets a block with a particular header hash from the local block database either as a JSON object or as a serialized block.

If verbosity is 0, returns a string that is serialized, hex-encoded data for block ‘hash’.

If verbosity is 1, returns an Object with information about block ‘hash’.

If verbosity is 2, returns an Object with information about block ‘hash’ and information about each transaction.

Parameter #1—blockhash

Name Type Presence Description
blockhash string (hex) Required
(exactly 1)
The block hash

Parameter #2—verbosity

Name Type Presence Description
verbosity number (int) Optional
Default=1
0 for hex-encoded data, 1 for a json object, and 2 for json object with transaction data

Result—(for verbosity = 0)

Name Type Presence Description
result string (hex) Required
(exactly 1)
A string that is serialized, hex-encoded data for block ‘hash’.

Result—(for verbosity = 1)

{
  "hash" : "hash",     (string) the block hash (same as provided)
  "confirmations" : n,   (numeric) The number of confirmations, or -1 if the block is not on the main chain
  "size" : n,            (numeric) The block size
  "strippedsize" : n,    (numeric) The block size excluding witness data
  "weight" : n           (numeric) The block weight as defined in BIP 141
  "height" : n,          (numeric) The block height or index
  "version" : n,         (numeric) The block version
  "versionHex" : "00000000", (string) The block version formatted in hexadecimal
  "merkleroot" : "xxxx", (string) The merkle root
  "tx" : [               (array of string) The transaction ids
     "transactionid"     (string) The transaction id
     ,...
  ],
  "time" : ttt,          (numeric) The block time in seconds since epoch (Jan 1 1970 GMT)
  "mediantime" : ttt,    (numeric) The median block time in seconds since epoch (Jan 1 1970 GMT)
  "nonce" : n,           (numeric) The nonce
  "bits" : "1d00ffff", (string) The bits
  "difficulty" : x.xxx,  (numeric) The difficulty
  "chainwork" : "xxxx",  (string) Expected number of hashes required to produce the chain up to this block (in hex)
  "nTx" : n,             (numeric) The number of transactions in the block.
  "previousblockhash" : "hash",  (string) The hash of the previous block
  "nextblockhash" : "hash"       (string) The hash of the next block
}

Result—(for verbosity = 2)

{
  ...,                     Same output as verbosity = 1.
  "tx" : [               (array of Objects) The transactions in the format of the getrawtransaction RPC. Different from verbosity = 1 "tx" result.
         ,...
  ],
  ,...                     Same output as verbosity = 1.
}

Example

bitcoin-cli getblock "00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"

See also

GetBlockChainInfo

The getblockchaininfo RPC returns an object containing various state info regarding blockchain processing.

Parameters: none

Result

{
  "chain": "xxxx",              (string) current network name as defined in BIP70 (main, test, regtest)
  "blocks": xxxxxx,             (numeric) the current number of blocks processed in the server
  "headers": xxxxxx,            (numeric) the current number of headers we have validated
  "bestblockhash": "...",       (string) the hash of the currently best block
  "difficulty": xxxxxx,         (numeric) the current difficulty
  "mediantime": xxxxxx,         (numeric) median time for the current best block
  "verificationprogress": xxxx, (numeric) estimate of verification progress [0..1]
  "initialblockdownload": xxxx, (bool) (debug information) estimate of whether this node is in Initial Block Download mode.
  "chainwork": "xxxx"           (string) total amount of work in active chain, in hexadecimal
  "size_on_disk": xxxxxx,       (numeric) the estimated size of the block and undo files on disk
  "pruned": xx,                 (boolean) if the blocks are subject to pruning
  "pruneheight": xxxxxx,        (numeric) lowest-height complete block stored (only present if pruning is enabled)
  "automatic_pruning": xx,      (boolean) whether automatic pruning is enabled (only present if pruning is enabled)
  "prune_target_size": xxxxxx,  (numeric) the target size used by pruning (only present if automatic pruning is enabled)
  "softforks": [                (array) status of softforks in progress
     {
        "id": "xxxx",           (string) name of softfork
        "version": xx,          (numeric) block version
        "reject": {             (object) progress toward rejecting pre-softfork blocks
           "status": xx,        (boolean) true if threshold reached
        },
     }, ...
  ],
  "bip9_softforks": {           (object) status of BIP9 softforks in progress
     "xxxx" : {                 (string) name of the softfork
        "status": "xxxx",       (string) one of "defined", "started", "locked_in", "active", "failed"
        "bit": xx,              (numeric) the bit (0-28) in the block version field used to signal this softfork (only for "started" status)
        "startTime": xx,        (numeric) the minimum median time past of a block at which the bit gains its meaning
        "timeout": xx,          (numeric) the median time past of a block at which the deployment is considered failed if not yet locked in
        "since": xx,            (numeric) height of the first block to which the status applies
        "statistics": {         (object) numeric statistics about BIP9 signalling for a softfork (only for "started" status)
           "period": xx,        (numeric) the length in blocks of the BIP9 signalling period
           "threshold": xx,     (numeric) the number of blocks with the version bit set required to activate the feature
           "elapsed": xx,       (numeric) the number of blocks elapsed since the beginning of the current period
           "count": xx,         (numeric) the number of blocks with the version bit set in the current period
           "possible": xx       (boolean) returns false if there are not enough blocks left in this period to pass activation threshold
        }
     }
  }
  "warnings" : "...",           (string) any network and blockchain warnings.
}

Example

bitcoin-cli getblockchaininfo

See also

GetBlockCount

The getblockcount RPC returns the number of blocks in the longest blockchain.

Parameters: none

Result

Name Type Presence Description
result number (int) Required
(exactly 1)
The current block count

Example

bitcoin-cli getblockcount

See also

GetBlockHash

The getblockhash RPC returns hash of block in best-block-chain at height provided.

Parameter #1—height

Name Type Presence Description
height number (int) Required
(exactly 1)
The height index

Result

Name Type Presence Description
result string (hex) Required
(exactly 1)
The block hash

Example

bitcoin-cli getblockhash 1000

See also

GetBlockHeader

Added in Bitcoin Core 0.12.0

The getblockheader RPC if verbose is false, returns a string that is serialized, hex-encoded data for blockheader ‘hash’.

If verbose is true, returns an Object with information about blockheader ‘hash’.

Parameter #1—blockhash

Name Type Presence Description
blockhash string Required
(exactly 1)
The block hash

Parameter #2—verbose

Name Type Presence Description
verbose boolean Optional
Default=true
true for a json object, false for the hex-encoded data

Result—(for verbose = true)

{
  "hash" : "hash",     (string) the block hash (same as provided)
  "confirmations" : n,   (numeric) The number of confirmations, or -1 if the block is not on the main chain
  "height" : n,          (numeric) The block height or index
  "version" : n,         (numeric) The block version
  "versionHex" : "00000000", (string) The block version formatted in hexadecimal
  "merkleroot" : "xxxx", (string) The merkle root
  "time" : ttt,          (numeric) The block time in seconds since epoch (Jan 1 1970 GMT)
  "mediantime" : ttt,    (numeric) The median block time in seconds since epoch (Jan 1 1970 GMT)
  "nonce" : n,           (numeric) The nonce
  "bits" : "1d00ffff", (string) The bits
  "difficulty" : x.xxx,  (numeric) The difficulty
  "chainwork" : "0000...1f3"     (string) Expected number of hashes required to produce the current chain (in hex)
  "nTx" : n,             (numeric) The number of transactions in the block.
  "previousblockhash" : "hash",  (string) The hash of the previous block
  "nextblockhash" : "hash",      (string) The hash of the next block
}

Result—(for verbose=false)

Name Type Presence Description
result string (hex) Required
(exactly 1)
A string that is serialized, hex-encoded data for block ‘hash’.

Example

bitcoin-cli getblockheader "00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"

See also

GetBlockStats

The getblockstats RPC compute per block statistics for a given window.

All amounts are in satoshis.

It won’t work for some heights with pruning.

It won’t work without -txindex for utxo_size_inc, *fee or *feerate stats.

Parameter #1—hash_or_height

Name Type Presence Description
hash_or_height string or numeric Required
(exactly 1)
The block hash or height of the target block

Parameter #2—stats

Name Type Presence Description
stats json array Optional
Default=all values
Values to plot (see result below)
[
  "height",     (string) Selected statistic
  "time",       (string) Selected statistic
  ...
]

Result

{                           (json object)
  "avgfee": xxxxx,          (numeric) Average fee in the block
  "avgfeerate": xxxxx,      (numeric) Average feerate (in satoshis per virtual byte)
  "avgtxsize": xxxxx,       (numeric) Average transaction size
  "blockhash": xxxxx,       (string) The block hash (to check for potential reorgs)
  "feerate_percentiles": [  (array of numeric) Feerates at the 10th, 25th, 50th, 75th, and 90th percentile weight unit (in satoshis per virtual byte)
      "10th_percentile_feerate",      (numeric) The 10th percentile feerate
      "25th_percentile_feerate",      (numeric) The 25th percentile feerate
      "50th_percentile_feerate",      (numeric) The 50th percentile feerate
      "75th_percentile_feerate",      (numeric) The 75th percentile feerate
      "90th_percentile_feerate",      (numeric) The 90th percentile feerate
  ],
  "height": xxxxx,          (numeric) The height of the block
  "ins": xxxxx,             (numeric) The number of inputs (excluding coinbase)
  "maxfee": xxxxx,          (numeric) Maximum fee in the block
  "maxfeerate": xxxxx,      (numeric) Maximum feerate (in satoshis per virtual byte)
  "maxtxsize": xxxxx,       (numeric) Maximum transaction size
  "medianfee": xxxxx,       (numeric) Truncated median fee in the block
  "mediantime": xxxxx,      (numeric) The block median time past
  "mediantxsize": xxxxx,    (numeric) Truncated median transaction size
  "minfee": xxxxx,          (numeric) Minimum fee in the block
  "minfeerate": xxxxx,      (numeric) Minimum feerate (in satoshis per virtual byte)
  "mintxsize": xxxxx,       (numeric) Minimum transaction size
  "outs": xxxxx,            (numeric) The number of outputs
  "subsidy": xxxxx,         (numeric) The block subsidy
  "swtotal_size": xxxxx,    (numeric) Total size of all segwit transactions
  "swtotal_weight": xxxxx,  (numeric) Total weight of all segwit transactions divided by segwit scale factor (4)
  "swtxs": xxxxx,           (numeric) The number of segwit transactions
  "time": xxxxx,            (numeric) The block time
  "total_out": xxxxx,       (numeric) Total amount in all outputs (excluding coinbase and thus reward [ie subsidy + totalfee])
  "total_size": xxxxx,      (numeric) Total size of all non-coinbase transactions
  "total_weight": xxxxx,    (numeric) Total weight of all non-coinbase transactions divided by segwit scale factor (4)
  "totalfee": xxxxx,        (numeric) The fee total
  "txs": xxxxx,             (numeric) The number of transactions (excluding coinbase)
  "utxo_increase": xxxxx,   (numeric) The increase/decrease in the number of unspent outputs
  "utxo_size_inc": xxxxx,   (numeric) The increase/decrease in size for the utxo index (not discounting op_return and similar)
}

Example

bitcoin-cli getblockstats 1000 '["minfeerate","avgfeerate"]'
GetBlockTemplate

The getblocktemplate RPC if the request parameters include a ‘mode’ key, that is used to explicitly select between the default ‘template’ request or a ‘proposal’.

It returns data needed to construct a block to work on.

For full specification, see BIPs 22, 23, 9, and 145:

https://github.com/bitcoin/bips/blob/master/bip-0022.mediawiki
https://github.com/bitcoin/bips/blob/master/bip-0023.mediawiki
https://github.com/bitcoin/bips/blob/master/bip-0009.mediawiki#getblocktemplate_changes
https://github.com/bitcoin/bips/blob/master/bip-0145.mediawiki

Parameter #1—template_request

Name Type Presence Description
template_request json object Required
(exactly 1)
A json object in the following spec “rules”: [ (json array, required) A list of strings “support”, (string) client side supported softfork deployment … ], }
{
  "mode": "str",       (string, optional) This must be set to "template", "proposal" (see BIP 23), or omitted
  "capabilities": [    (json array, optional) A list of strings
    "support",         (string) client side supported feature, 'longpoll', 'coinbasetxn', 'coinbasevalue', 'proposal', 'serverlist', 'workid'
    ...
  ],

Result

{
  "version" : n,                    (numeric) The preferred block version
  "rules" : [ "rulename", ... ],    (array of strings) specific block rules that are to be enforced
  "vbavailable" : {                 (json object) set of pending, supported versionbit (BIP 9) softfork deployments
      "rulename" : bitnumber          (numeric) identifies the bit number as indicating acceptance and readiness for the named softfork rule
      ,...
  },
  "vbrequired" : n,                 (numeric) bit mask of versionbits the server requires set in submissions
  "previousblockhash" : "xxxx",     (string) The hash of current highest block
  "transactions" : [                (array) contents of non-coinbase transactions that should be included in the next block
      {
         "data" : "xxxx",             (string) transaction data encoded in hexadecimal (byte-for-byte)
         "txid" : "xxxx",             (string) transaction id encoded in little-endian hexadecimal
         "hash" : "xxxx",             (string) hash encoded in little-endian hexadecimal (including witness data)
         "depends" : [                (array) array of numbers
             n                          (numeric) transactions before this one (by 1-based index in 'transactions' list) that must be present in the final block if this one is
             ,...
         ],
         "fee": n,                    (numeric) difference in value between transaction inputs and outputs (in satoshis); for coinbase transactions, this is a negative Number of the total collected block fees (ie, not including the block subsidy); if key is not present, fee is unknown and clients MUST NOT assume there isn't one
         "sigops" : n,                (numeric) total SigOps cost, as counted for purposes of block limits; if key is not present, sigop cost is unknown and clients MUST NOT assume it is zero
         "weight" : n,                (numeric) total transaction weight, as counted for purposes of block limits
      }
      ,...
  ],
  "coinbaseaux" : {                 (json object) data that should be included in the coinbase's scriptSig content
      "flags" : "xx"                  (string) key name is to be ignored, and value included in scriptSig
  },
  "coinbasevalue" : n,              (numeric) maximum allowable input to coinbase transaction, including the generation award and transaction fees (in satoshis)
  "coinbasetxn" : { ... },          (json object) information for coinbase transaction
  "target" : "xxxx",                (string) The hash target
  "mintime" : xxx,                  (numeric) The minimum timestamp appropriate for next block time in seconds since epoch (Jan 1 1970 GMT)
  "mutable" : [                     (array of string) list of ways the block template may be changed
     "value"                          (string) A way the block template may be changed, e.g. 'time', 'transactions', 'prevblock'
     ,...
  ],
  "noncerange" : "00000000ffffffff",(string) A range of valid nonces
  "sigoplimit" : n,                 (numeric) limit of sigops in blocks
  "sizelimit" : n,                  (numeric) limit of block size
  "weightlimit" : n,                (numeric) limit of block weight
  "curtime" : ttt,                  (numeric) current timestamp in seconds since epoch (Jan 1 1970 GMT)
  "bits" : "xxxxxxxx",              (string) compressed target of next block
  "height" : n                      (numeric) The height of the next block
}

Example

bitcoin-cli getblocktemplate {"rules": ["segwit"]}

See also

GetChainTips

The getchaintips RPC return information about all known tips in the block tree, including the main chain as well as orphaned branches.

Parameters: none

Result

[
  {
    "height": xxxx,         (numeric) height of the chain tip
    "hash": "xxxx",         (string) block hash of the tip
    "branchlen": 0          (numeric) zero for main chain
    "status": "active"      (string) "active" for the main chain
  },
  {
    "height": xxxx,
    "hash": "xxxx",
    "branchlen": 1          (numeric) length of branch connecting the tip to the main chain
    "status": "xxxx"        (string) status of the chain (active, valid-fork, valid-headers, headers-only, invalid)
  }
]

Example

bitcoin-cli getchaintips

See also

GetChainTxStats

The getchaintxstats RPC compute statistics about the total number and rate of transactions in the chain.

Parameter #1—nblocks

Name Type Presence Description
nblocks number (int) Optional
Default=one month
Size of the window in number of blocks

Parameter #2—blockhash

Name Type Presence Description
blockhash string Optional
Default=chain tip
The hash of the block that ends the window.

Result

{
  "time": xxxxx,                         (numeric) The timestamp for the final block in the window in UNIX format.
  "txcount": xxxxx,                      (numeric) The total number of transactions in the chain up to that point.
  "window_final_block_hash": "...",      (string) The hash of the final block in the window.
  "window_block_count": xxxxx,           (numeric) Size of the window in number of blocks.
  "window_tx_count": xxxxx,              (numeric) The number of transactions in the window. Only returned if "window_block_count" is > 0.
  "window_interval": xxxxx,              (numeric) The elapsed time in the window in seconds. Only returned if "window_block_count" is > 0.
  "txrate": x.xx,                        (numeric) The average rate of transactions per second in the window. Only returned if "window_interval" is > 0.
}

Example

bitcoin-cli getchaintxstats
GetConnectionCount

The getconnectioncount RPC returns the number of connections to other nodes.

Parameters: none

Result

Name Type Presence Description
result number (int) Required
(exactly 1)
The connection count

Example

bitcoin-cli getconnectioncount

See also

  • GetNetTotals: returns information about network traffic, including bytes in, bytes out, and current time.
  • GetPeerInfo: returns data about each connected network node as a json array of objects.
  • GetNetworkInfo: returns an object containing various state info regarding P2P networking.
GetDescriptorInfo

Added in Bitcoin Core 0.18.0

The getdescriptorinfo RPC analyses a descriptor.

Parameter #1—descriptor

Name Type Presence Description
descriptor string Required
(exactly 1)
The descriptor.

Result

{
  "descriptor" : "desc",         (string) The descriptor in canonical form, without private keys
  "isrange" : true|false,        (boolean) Whether the descriptor is ranged
  "issolvable" : true|false,     (boolean) Whether the descriptor is solvable
  "hasprivatekeys" : true|false, (boolean) Whether the input descriptor contained at least one private key
}

Example

Analyse a descriptor

bitcoin-cli getdescriptorinfo "wpkh([d34db33f/84h/0h/0h]0279be667ef9dcbbac55a06295Ce870b07029Bfcdb2dce28d959f2815b16f81798)"
GetDifficulty

The getdifficulty RPC returns the proof-of-work difficulty as a multiple of the minimum difficulty.

Parameters: none

Result

Name Type Presence Description
result number (int) Required
(exactly 1)
the proof-of-work difficulty as a multiple of the minimum difficulty.

Example

bitcoin-cli getdifficulty

See also

GetMemoryInfo

Added in Bitcoin Core 0.14.0

The getmemoryinfo RPC returns an object containing information about memory usage.

Parameter #1—mode

Name Type Presence Description
mode string Optional
Default=”stats”
determines what kind of information is returned. - “stats” returns general statistics about memory usage in the daemon. - “mallocinfo” returns an XML string describing low-level heap state (only available if compiled with glibc 2.10+).

Result—(mode “stats”)

{
  "locked": {               (json object) Information about locked memory manager
    "used": xxxxx,          (numeric) Number of bytes used
    "free": xxxxx,          (numeric) Number of bytes available in current arenas
    "total": xxxxxxx,       (numeric) Total number of bytes managed
    "locked": xxxxxx,       (numeric) Amount of bytes that succeeded locking. If this number is smaller than total, locking pages failed at some point and key data could be swapped to disk.
    "chunks_used": xxxxx,   (numeric) Number allocated chunks
    "chunks_free": xxxxx,   (numeric) Number unused chunks
  }
}

Result—(mode “mallocinfo”)

"<malloc version="1">..."

Example

bitcoin-cli getmemoryinfo

See also

  • GetMemPoolInfo: returns details on the active state of the TX memory pool.
GetMemPoolAncestors

Added in Bitcoin Core 0.13.0

The getmempoolancestors RPC if txid is in the mempool, returns all in-mempool ancestors.

Parameter #1—txid

Name Type Presence Description
txid string Required
(exactly 1)
The transaction id (must be in mempool)

Parameter #2—verbose

Name Type Presence Description
verbose boolean Optional
Default=false
True for a json object, false for array of transaction ids

Result—(for verbose = false)

[                       (json array of strings)
  "transactionid"           (string) The transaction id of an in-mempool ancestor transaction
  ,...
]

Result—(for verbose = true)

{                           (json object)
  "transactionid" : {       (json object)
    "size" : n,             (numeric) virtual transaction size as defined in BIP 141. This is different from actual serialized size for witness transactions as witness data is discounted.
    "fee" : n,              (numeric) transaction fee in BTC (DEPRECATED)
    "modifiedfee" : n,      (numeric) transaction fee with fee deltas used for mining priority (DEPRECATED)
    "time" : n,             (numeric) local time transaction entered pool in seconds since 1 Jan 1970 GMT
    "height" : n,           (numeric) block height when transaction entered pool
    "descendantcount" : n,  (numeric) number of in-mempool descendant transactions (including this one)
    "descendantsize" : n,   (numeric) virtual transaction size of in-mempool descendants (including this one)
    "descendantfees" : n,   (numeric) modified fees (see above) of in-mempool descendants (including this one) (DEPRECATED)
    "ancestorcount" : n,    (numeric) number of in-mempool ancestor transactions (including this one)
    "ancestorsize" : n,     (numeric) virtual transaction size of in-mempool ancestors (including this one)
    "ancestorfees" : n,     (numeric) modified fees (see above) of in-mempool ancestors (including this one) (DEPRECATED)
    "wtxid" : hash,         (string) hash of serialized transaction, including witness data
    "fees" : {
        "base" : n,         (numeric) transaction fee in BTC
        "modified" : n,     (numeric) transaction fee with fee deltas used for mining priority in BTC
        "ancestor" : n,     (numeric) modified fees (see above) of in-mempool ancestors (including this one) in BTC
        "descendant" : n,   (numeric) modified fees (see above) of in-mempool descendants (including this one) in BTC
    }
    "depends" : [           (array) unconfirmed transactions used as inputs for this transaction
        "transactionid",    (string) parent transaction id
       ... ]
    "spentby" : [           (array) unconfirmed transactions spending outputs from this transaction
        "transactionid",    (string) child transaction id
       ... ]
    "bip125-replaceable" : true|false,  (boolean) Whether this transaction could be replaced due to BIP125 (replace-by-fee)
  }, ...
}

Example

bitcoin-cli getmempoolancestors "mytxid"

See also

GetMemPoolDescendants

Added in Bitcoin Core 0.13.0

The getmempooldescendants RPC if txid is in the mempool, returns all in-mempool descendants.

Parameter #1—txid

Name Type Presence Description
txid string Required
(exactly 1)
The transaction id (must be in mempool)

Parameter #2—verbose

Name Type Presence Description
verbose boolean Optional
Default=false
True for a json object, false for array of transaction ids

Result—(for verbose = false)

[                       (json array of strings)
  "transactionid"           (string) The transaction id of an in-mempool descendant transaction
  ,...
]

Result—(for verbose = true)

{                           (json object)
  "transactionid" : {       (json object)
    "size" : n,             (numeric) virtual transaction size as defined in BIP 141. This is different from actual serialized size for witness transactions as witness data is discounted.
    "fee" : n,              (numeric) transaction fee in BTC (DEPRECATED)
    "modifiedfee" : n,      (numeric) transaction fee with fee deltas used for mining priority (DEPRECATED)
    "time" : n,             (numeric) local time transaction entered pool in seconds since 1 Jan 1970 GMT
    "height" : n,           (numeric) block height when transaction entered pool
    "descendantcount" : n,  (numeric) number of in-mempool descendant transactions (including this one)
    "descendantsize" : n,   (numeric) virtual transaction size of in-mempool descendants (including this one)
    "descendantfees" : n,   (numeric) modified fees (see above) of in-mempool descendants (including this one) (DEPRECATED)
    "ancestorcount" : n,    (numeric) number of in-mempool ancestor transactions (including this one)
    "ancestorsize" : n,     (numeric) virtual transaction size of in-mempool ancestors (including this one)
    "ancestorfees" : n,     (numeric) modified fees (see above) of in-mempool ancestors (including this one) (DEPRECATED)
    "wtxid" : hash,         (string) hash of serialized transaction, including witness data
    "fees" : {
        "base" : n,         (numeric) transaction fee in BTC
        "modified" : n,     (numeric) transaction fee with fee deltas used for mining priority in BTC
        "ancestor" : n,     (numeric) modified fees (see above) of in-mempool ancestors (including this one) in BTC
        "descendant" : n,   (numeric) modified fees (see above) of in-mempool descendants (including this one) in BTC
    }
    "depends" : [           (array) unconfirmed transactions used as inputs for this transaction
        "transactionid",    (string) parent transaction id
       ... ]
    "spentby" : [           (array) unconfirmed transactions spending outputs from this transaction
        "transactionid",    (string) child transaction id
       ... ]
    "bip125-replaceable" : true|false,  (boolean) Whether this transaction could be replaced due to BIP125 (replace-by-fee)
  }, ...
}

Example

bitcoin-cli getmempooldescendants "mytxid"

See also

  • GetMemPoolAncestors: if txid is in the mempool, returns all in-mempool ancestors.
  • GetRawMemPool: returns all transaction ids in memory pool as a json array of string transaction ids.
GetMemPoolEntry

Added in Bitcoin Core 0.13.0

The getmempoolentry RPC returns mempool data for given transaction.

Parameter #1—txid

Name Type Presence Description
txid string Required
(exactly 1)
The transaction id (must be in mempool)

Result

{                           (json object)
    "size" : n,             (numeric) virtual transaction size as defined in BIP 141. This is different from actual serialized size for witness transactions as witness data is discounted.
    "fee" : n,              (numeric) transaction fee in BTC (DEPRECATED)
    "modifiedfee" : n,      (numeric) transaction fee with fee deltas used for mining priority (DEPRECATED)
    "time" : n,             (numeric) local time transaction entered pool in seconds since 1 Jan 1970 GMT
    "height" : n,           (numeric) block height when transaction entered pool
    "descendantcount" : n,  (numeric) number of in-mempool descendant transactions (including this one)
    "descendantsize" : n,   (numeric) virtual transaction size of in-mempool descendants (including this one)
    "descendantfees" : n,   (numeric) modified fees (see above) of in-mempool descendants (including this one) (DEPRECATED)
    "ancestorcount" : n,    (numeric) number of in-mempool ancestor transactions (including this one)
    "ancestorsize" : n,     (numeric) virtual transaction size of in-mempool ancestors (including this one)
    "ancestorfees" : n,     (numeric) modified fees (see above) of in-mempool ancestors (including this one) (DEPRECATED)
    "wtxid" : hash,         (string) hash of serialized transaction, including witness data
    "fees" : {
        "base" : n,         (numeric) transaction fee in BTC
        "modified" : n,     (numeric) transaction fee with fee deltas used for mining priority in BTC
        "ancestor" : n,     (numeric) modified fees (see above) of in-mempool ancestors (including this one) in BTC
        "descendant" : n,   (numeric) modified fees (see above) of in-mempool descendants (including this one) in BTC
    }
    "depends" : [           (array) unconfirmed transactions used as inputs for this transaction
        "transactionid",    (string) parent transaction id
       ... ]
    "spentby" : [           (array) unconfirmed transactions spending outputs from this transaction
        "transactionid",    (string) child transaction id
       ... ]
    "bip125-replaceable" : true|false,  (boolean) Whether this transaction could be replaced due to BIP125 (replace-by-fee)
}

Example

bitcoin-cli getmempoolentry "mytxid"

See also

GetMemPoolInfo

The getmempoolinfo RPC returns details on the active state of the TX memory pool.

Parameters: none

Result

{
  "size": xxxxx,               (numeric) Current tx count
  "bytes": xxxxx,              (numeric) Sum of all virtual transaction sizes as defined in BIP 141. Differs from actual serialized size because witness data is discounted
  "usage": xxxxx,              (numeric) Total memory usage for the mempool
  "maxmempool": xxxxx,         (numeric) Maximum memory usage for the mempool
  "mempoolminfee": xxxxx       (numeric) Minimum fee rate in BTC/kB for tx to be accepted. Is the maximum of minrelaytxfee and minimum mempool fee
  "minrelaytxfee": xxxxx       (numeric) Current minimum relay fee for transactions
}

Example

bitcoin-cli getmempoolinfo

See also

GetMiningInfo

The getmininginfo RPC returns a json object containing mining-related information.

Parameters: none

Result

{
  "blocks": nnn,             (numeric) The current block
  "currentblockweight": nnn, (numeric, optional) The block weight of the last assembled block (only present if a block was ever assembled)
  "currentblocktx": nnn,     (numeric, optional) The number of block transactions of the last assembled block (only present if a block was ever assembled)
  "difficulty": xxx.xxxxx    (numeric) The current difficulty
  "networkhashps": nnn,      (numeric) The network hashes per second
  "pooledtx": n              (numeric) The size of the mempool
  "chain": "xxxx",           (string) current network name as defined in BIP70 (main, test, regtest)
  "warnings": "..."          (string) any network and blockchain warnings
}

Example

bitcoin-cli getmininginfo

See also

  • GetMemPoolInfo: returns details on the active state of the TX memory pool.
  • GetRawMemPool: returns all transaction ids in memory pool as a json array of string transaction ids.
  • GetBlockTemplate: if the request parameters include a ‘mode’ key, that is used to explicitly select between the default ‘template’ request or a ‘proposal’.
  • Generate: mine up to nblocks blocks immediately (before the RPC call returns) to an address in the wallet.
GetNetTotals

The getnettotals RPC returns information about network traffic, including bytes in, bytes out, and current time.

Parameters: none

Result

{
  "totalbytesrecv": n,   (numeric) Total bytes received
  "totalbytessent": n,   (numeric) Total bytes sent
  "timemillis": t,       (numeric) Current UNIX time in milliseconds
  "uploadtarget":
  {
    "timeframe": n,                         (numeric) Length of the measuring timeframe in seconds
    "target": n,                            (numeric) Target in bytes
    "target_reached": true|false,           (boolean) True if target is reached
    "serve_historical_blocks": true|false,  (boolean) True if serving historical blocks
    "bytes_left_in_cycle": t,               (numeric) Bytes left in current time cycle
    "time_left_in_cycle": t                 (numeric) Seconds left in current time cycle
  }
}

Example

bitcoin-cli getnettotals

See also

GetNetworkHashPs

The getnetworkhashps RPC returns the estimated network hashes per second based on the last n blocks.

Pass in [blocks] to override # of blocks, -1 specifies since last difficulty change.

Pass in [height] to estimate the network speed at the time when a certain block was found.

Parameter #1—nblocks

Name Type Presence Description
nblocks number (int) Optional
Default=120
The number of blocks, or -1 for blocks since last difficulty change.

Parameter #2—height

Name Type Presence Description
height number (int) Optional
Default=-1
To estimate at the time of the given height.

Result

Name Type Presence Description
result number (int) Required
(exactly 1)
Hashes per second estimated

Example

bitcoin-cli getnetworkhashps

See also

GetNetworkInfo

The getnetworkinfo RPC returns an object containing various state info regarding P2P networking.

Parameters: none

Result

{
  "version": xxxxx,                      (numeric) the server version
  "subversion": "/Satoshi:x.x.x/",     (string) the server subversion string
  "protocolversion": xxxxx,              (numeric) the protocol version
  "localservices": "xxxxxxxxxxxxxxxx", (string) the services we offer to the network
  "localrelay": true|false,              (bool) true if transaction relay is requested from peers
  "timeoffset": xxxxx,                   (numeric) the time offset
  "connections": xxxxx,                  (numeric) the number of connections
  "networkactive": true|false,           (bool) whether p2p networking is enabled
  "networks": [                          (array) information per network
  {
    "name": "xxx",                     (string) network (ipv4, ipv6 or onion)
    "limited": true|false,               (boolean) is the network limited using -onlynet?
    "reachable": true|false,             (boolean) is the network reachable?
    "proxy": "host:port"               (string) the proxy that is used for this network, or empty if none
    "proxy_randomize_credentials": true|false,  (string) Whether randomized credentials are used
  }
  ,...
  ],
  "relayfee": x.xxxxxxxx,                (numeric) minimum relay fee for transactions in BTC/kB
  "incrementalfee": x.xxxxxxxx,          (numeric) minimum fee increment for mempool limiting or BIP 125 replacement in BTC/kB
  "localaddresses": [                    (array) list of local addresses
  {
    "address": "xxxx",                 (string) network address
    "port": xxx,                         (numeric) network port
    "score": xxx                         (numeric) relative score
  }
  ,...
  ]
  "warnings": "..."                    (string) any network and blockchain warnings
}

Example

bitcoin-cli getnetworkinfo

See also

GetNewAddress

The getnewaddress RPC returns a new Bitcoin address for receiving payments.

If ‘label’ is specified, it is added to the address book so payments received with the address will be associated with ‘label’.

Parameter #1—label

Name Type Presence Description
label string Optional
Default=””
The label name for the address to be linked to. It can also be set to the empty string “” to represent the default label. The label does not need to exist, it will be created if there is no label by the given name.

Parameter #2—address_type

Name Type Presence Description
address_type string Optional
Default=set by -addresstype
The address type to use. Options are “legacy”, “p2sh-segwit”, and “bech32”.

Result

Name Type Presence Description
result string (hex) Required
(exactly 1)
The new bitcoin address

Example

bitcoin-cli getnewaddress

See also

GetNodeAddresses

Added in Bitcoin Core 0.18.0

The getnodeaddresses RPC return known addresses which can potentially be used to find new nodes in the network.

Parameter #1—count

Name Type Presence Description
count number (int) Optional
Default=1
How many addresses to return. Limited to the smaller of 2500 or 23% of all known addresses.

Result

[
  {
    "time": ttt,                (numeric) Timestamp in seconds since epoch (Jan 1 1970 GMT) keeping track of when the node was last seen
    "services": n,              (numeric) The services offered
    "address": "host",          (string) The address of the node
    "port": n                   (numeric) The port of the node
  }
  ,....
]

Example

bitcoin-cli getnodeaddresses 8
GetPeerInfo

The getpeerinfo RPC returns data about each connected network node as a json array of objects.

Parameters: none

Result

[
  {
    "id": n,                   (numeric) Peer index
    "addr":"host:port",      (string) The IP address and port of the peer
    "addrbind":"ip:port",    (string) Bind address of the connection to the peer
    "addrlocal":"ip:port",   (string) Local address as reported by the peer
    "services":"xxxxxxxxxxxxxxxx",   (string) The services offered
    "relaytxes":true|false,    (boolean) Whether peer has asked us to relay transactions to it
    "lastsend": ttt,           (numeric) The time in seconds since epoch (Jan 1 1970 GMT) of the last send
    "lastrecv": ttt,           (numeric) The time in seconds since epoch (Jan 1 1970 GMT) of the last receive
    "bytessent": n,            (numeric) The total bytes sent
    "bytesrecv": n,            (numeric) The total bytes received
    "conntime": ttt,           (numeric) The connection time in seconds since epoch (Jan 1 1970 GMT)
    "timeoffset": ttt,         (numeric) The time offset in seconds
    "pingtime": n,             (numeric) ping time (if available)
    "minping": n,              (numeric) minimum observed ping time (if any at all)
    "pingwait": n,             (numeric) ping wait (if non-zero)
    "version": v,              (numeric) The peer version, such as 70001
    "subver": "/Satoshi:0.8.5/",  (string) The string version
    "inbound": true|false,     (boolean) Inbound (true) or Outbound (false)
    "addnode": true|false,     (boolean) Whether connection was due to addnode/-connect or if it was an automatic/inbound connection
    "startingheight": n,       (numeric) The starting height (block) of the peer
    "banscore": n,             (numeric) The ban score
    "synced_headers": n,       (numeric) The last header we have in common with this peer
    "synced_blocks": n,        (numeric) The last block we have in common with this peer
    "inflight": [
       n,                        (numeric) The heights of blocks we're currently asking from this peer
       ...
    ],
    "whitelisted": true|false, (boolean) Whether the peer is whitelisted
    "minfeefilter": n,         (numeric) The minimum fee rate for transactions this peer accepts
    "bytessent_per_msg": {
       "msg": n,               (numeric) The total bytes sent aggregated by message type
                               When a message type is not listed in this json object, the bytes sent are 0.
                               Only known message types can appear as keys in the object.
       ...
    },
    "bytesrecv_per_msg": {
       "msg": n,               (numeric) The total bytes received aggregated by message type
                               When a message type is not listed in this json object, the bytes received are 0.
                               Only known message types can appear as keys in the object and all bytes received of unknown message types are listed under '*other*'.
       ...
    }
  }
  ,...
]

Example

bitcoin-cli getpeerinfo

See also

  • GetAddedNodeInfo: returns information about the given added node, or all added nodes (note that onetry addnodes are not listed here).
  • GetNetTotals: returns information about network traffic, including bytes in, bytes out, and current time.
  • GetNetworkInfo: returns an object containing various state info regarding P2P networking.
GetRawChangeAddress

The getrawchangeaddress RPC returns a new Bitcoin address, for receiving change.

This is for use with raw transactions, NOT normal use.

Parameter #1—address_type

Name Type Presence Description
address_type string Optional
Default=set by -changetype
The address type to use. Options are “legacy”, “p2sh-segwit”, and “bech32”.

Result

Name Type Presence Description
result string (hex) Required
(exactly 1)
The address

Example

bitcoin-cli getrawchangeaddress

See also

GetRawMemPool

The getrawmempool RPC returns all transaction ids in memory pool as a json array of string transaction ids.

Hint: use getmempoolentry to fetch a specific transaction from the mempool.

Parameter #1—verbose

Name Type Presence Description
verbose boolean Optional
Default=false
True for a json object, false for array of transaction ids

Result—(for verbose = false)

[                     (json array of string)
  "transactionid"     (string) The transaction id
  ,...
]

Result—(for verbose = true)

{                           (json object)
  "transactionid" : {       (json object)
    "size" : n,             (numeric) virtual transaction size as defined in BIP 141. This is different from actual serialized size for witness transactions as witness data is discounted.
    "fee" : n,              (numeric) transaction fee in BTC (DEPRECATED)
    "modifiedfee" : n,      (numeric) transaction fee with fee deltas used for mining priority (DEPRECATED)
    "time" : n,             (numeric) local time transaction entered pool in seconds since 1 Jan 1970 GMT
    "height" : n,           (numeric) block height when transaction entered pool
    "descendantcount" : n,  (numeric) number of in-mempool descendant transactions (including this one)
    "descendantsize" : n,   (numeric) virtual transaction size of in-mempool descendants (including this one)
    "descendantfees" : n,   (numeric) modified fees (see above) of in-mempool descendants (including this one) (DEPRECATED)
    "ancestorcount" : n,    (numeric) number of in-mempool ancestor transactions (including this one)
    "ancestorsize" : n,     (numeric) virtual transaction size of in-mempool ancestors (including this one)
    "ancestorfees" : n,     (numeric) modified fees (see above) of in-mempool ancestors (including this one) (DEPRECATED)
    "wtxid" : hash,         (string) hash of serialized transaction, including witness data
    "fees" : {
        "base" : n,         (numeric) transaction fee in BTC
        "modified" : n,     (numeric) transaction fee with fee deltas used for mining priority in BTC
        "ancestor" : n,     (numeric) modified fees (see above) of in-mempool ancestors (including this one) in BTC
        "descendant" : n,   (numeric) modified fees (see above) of in-mempool descendants (including this one) in BTC
    }
    "depends" : [           (array) unconfirmed transactions used as inputs for this transaction
        "transactionid",    (string) parent transaction id
       ... ]
    "spentby" : [           (array) unconfirmed transactions spending outputs from this transaction
        "transactionid",    (string) child transaction id
       ... ]
    "bip125-replaceable" : true|false,  (boolean) Whether this transaction could be replaced due to BIP125 (replace-by-fee)
  }, ...
}

Example

bitcoin-cli getrawmempool true

See also

GetRawTransaction

The getrawtransaction RPC return the raw transaction data.

By default this function only works for mempool transactions. When called with a blockhash argument, getrawtransaction will return the transaction if the specified block is available and the transaction is found in that block. When called without a blockhash argument, getrawtransaction will return the transaction if it is in the mempool, or if -txindex is enabled and the transaction is in a block in the blockchain.

Hint: Use gettransaction for wallet transactions.

If verbose is ‘true’, returns an Object with information about ‘txid’.

If verbose is ‘false’ or omitted, returns a string that is serialized, hex-encoded data for ‘txid’.

Parameter #1—txid

Name Type Presence Description
txid string Required
(exactly 1)
The transaction id

Parameter #2—verbose

Name Type Presence Description
verbose boolean Optional
Default=false
If false, return a string, otherwise return a json object

Parameter #3—blockhash

Name Type Presence Description
blockhash string Optional The block in which to look for the transaction

Result—(if verbose is not set or set to false)

Name Type Presence Description
result string (hex) Required
(exactly 1)
The serialized, hex-encoded data for ‘txid

Result—(if verbose is set to true)

{
  "in_active_chain": b, (bool) Whether specified block is in the active chain or not (only present with explicit "blockhash" argument)
  "hex" : "data",       (string) The serialized, hex-encoded data for 'txid'
  "txid" : "id",        (string) The transaction id (same as provided)
  "hash" : "id",        (string) The transaction hash (differs from txid for witness transactions)
  "size" : n,             (numeric) The serialized transaction size
  "vsize" : n,            (numeric) The virtual transaction size (differs from size for witness transactions)
  "weight" : n,           (numeric) The transaction's weight (between vsize*4-3 and vsize*4)
  "version" : n,          (numeric) The version
  "locktime" : ttt,       (numeric) The lock time
  "vin" : [               (array of json objects)
     {
       "txid": "id",    (string) The transaction id
       "vout": n,         (numeric)
       "scriptSig": {     (json object) The script
         "asm": "asm",  (string) asm
         "hex": "hex"   (string) hex
       },
       "sequence": n      (numeric) The script sequence number
       "txinwitness": ["hex", ...] (array of string) hex-encoded witness data (if any)
     }
     ,...
  ],
  "vout" : [              (array of json objects)
     {
       "value" : x.xxx,            (numeric) The value in BTC
       "n" : n,                    (numeric) index
       "scriptPubKey" : {          (json object)
         "asm" : "asm",          (string) the asm
         "hex" : "hex",          (string) the hex
         "reqSigs" : n,            (numeric) The required sigs
         "type" : "pubkeyhash",  (string) The type, eg 'pubkeyhash'
         "addresses" : [           (json array of string)
           "address"        (string) bitcoin address
           ,...
         ]
       }
     }
     ,...
  ],
  "blockhash" : "hash",   (string) the block hash
  "confirmations" : n,      (numeric) The confirmations
  "blocktime" : ttt         (numeric) The block time in seconds since epoch (Jan 1 1970 GMT)
  "time" : ttt,             (numeric) Same as "blocktime"
}

Example

bitcoin-cli getrawtransaction "mytxid"
bitcoin-cli getrawtransaction "mytxid" true
bitcoin-cli getrawtransaction "mytxid" false "myblockhash"
bitcoin-cli getrawtransaction "mytxid" true "myblockhash"

See also

GetReceivedByAddress

The getreceivedbyaddress RPC returns the total amount received by the given address in transactions with at least minconf confirmations.

Parameter #1—address

Name Type Presence Description
address string Required
(exactly 1)
The bitcoin address for transactions.

Parameter #2—minconf

Name Type Presence Description
minconf number (int) Optional
Default=1
Only include transactions confirmed at least this many times.

Result

Name Type Presence Description
result number (int) Required
(exactly 1)
The total amount in BTC received at this address.

Example

The amount from transactions with at least 1 confirmation

bitcoin-cli getreceivedbyaddress "1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XX"

The amount including unconfirmed transactions, zero confirmations

bitcoin-cli getreceivedbyaddress "1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XX" 0

The amount with at least 6 confirmations

bitcoin-cli getreceivedbyaddress "1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XX" 6
GetReceivedByLabel

Added in Bitcoin Core 0.17.0

The getreceivedbylabel RPC returns the total amount received by addresses with

Parameter #1—label

Name Type Presence Description
label string Required
(exactly 1)
The selected label, may be the default label using “”.

Parameter #2—minconf

Name Type Presence Description
minconf number (int) Optional
Default=1
Only include transactions confirmed at least this many times.

Result

Name Type Presence Description
result number (int) Required
(exactly 1)
The total amount in BTC received for this label.

Example

Amount received by the default label with at least 1 confirmation

bitcoin-cli getreceivedbylabel ""

Amount received at the tabby label including unconfirmed amounts with zero confirmations

bitcoin-cli getreceivedbylabel "tabby" 0

The amount with at least 6 confirmations

bitcoin-cli getreceivedbylabel "tabby" 6
GetRpcInfo

Added in Bitcoin Core 0.18.0

The getrpcinfo RPC returns details of the RPC server.

Parameters: none

Result

{
 "active_commands" (array) All active commands
  [
   {               (object) Information about an active command
    "method"       (string)  The name of the RPC command
    "duration"     (numeric)  The running time in microseconds
   },...
  ]
}

Example

bitcoin-cli getrpcinfo
GetTransaction

The gettransaction RPC get detailed information about in-wallet transaction <txid>.

Parameter #1—txid

Name Type Presence Description
txid string Required
(exactly 1)
The transaction id

Parameter #2—include_watchonly

Name Type Presence Description
include_watchonly boolean Optional
Default=false
Whether to include watch-only addresses in balance calculation and details[]

Result

{
  "amount" : x.xxx,        (numeric) The transaction amount in BTC
  "fee": x.xxx,            (numeric) The amount of the fee in BTC. This is negative and only available for the
                              'send' category of transactions.
  "confirmations" : n,     (numeric) The number of confirmations
  "blockhash" : "hash",  (string) The block hash
  "blockindex" : xx,       (numeric) The index of the transaction in the block that includes it
  "blocktime" : ttt,       (numeric) The time in seconds since epoch (1 Jan 1970 GMT)
  "txid" : "transactionid",   (string) The transaction id.
  "time" : ttt,            (numeric) The transaction time in seconds since epoch (1 Jan 1970 GMT)
  "timereceived" : ttt,    (numeric) The time received in seconds since epoch (1 Jan 1970 GMT)
  "bip125-replaceable": "yes|no|unknown",  (string) Whether this transaction could be replaced due to BIP125 (replace-by-fee);
                                                   may be unknown for unconfirmed transactions not in the mempool
  "details" : [
    {
      "address" : "address",          (string) The bitcoin address involved in the transaction
      "category" :                      (string) The transaction category.
                   "send"                  Transactions sent.
                   "receive"               Non-coinbase transactions received.
                   "generate"              Coinbase transactions received with more than 100 confirmations.
                   "immature"              Coinbase transactions received with 100 or fewer confirmations.
                   "orphan"                Orphaned coinbase transactions received.
      "amount" : x.xxx,                 (numeric) The amount in BTC
      "label" : "label",              (string) A comment for the address/transaction, if any
      "vout" : n,                       (numeric) the vout value
      "fee": x.xxx,                     (numeric) The amount of the fee in BTC. This is negative and only available for the
                                           'send' category of transactions.
      "abandoned": xxx                  (bool) 'true' if the transaction has been abandoned (inputs are respendable). Only available for the
                                           'send' category of transactions.
    }
    ,...
  ],
  "hex" : "data"         (string) Raw data for transaction
}

Example

bitcoin-cli gettransaction "1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d"
bitcoin-cli gettransaction "1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d" true

See also

GetTxOut

The gettxout RPC returns details about an unspent transaction output.

Parameter #1—txid

Name Type Presence Description
txid string Required
(exactly 1)
The transaction id

Parameter #2—n

Name Type Presence Description
n number (int) Required
(exactly 1)
vout number

Parameter #3—include_mempool

Name Type Presence Description
include_mempool boolean Optional
Default=true
Whether to include the mempool. Note that an unspent output that is spent in the mempool won’t appear.

Result

{
  "bestblock":  "hash",    (string) The hash of the block at the tip of the chain
  "confirmations" : n,       (numeric) The number of confirmations
  "value" : x.xxx,           (numeric) The transaction value in BTC
  "scriptPubKey" : {         (json object)
     "asm" : "code",       (string)
     "hex" : "hex",        (string)
     "reqSigs" : n,          (numeric) Number of required signatures
     "type" : "pubkeyhash", (string) The type, eg pubkeyhash
     "addresses" : [          (array of string) array of bitcoin addresses
        "address"     (string) bitcoin address
        ,...
     ]
  },
  "coinbase" : true|false   (boolean) Coinbase or not
}

Example

Get unspent transactions

bitcoin-cli listunspent

View the details

bitcoin-cli gettxout "txid" 1

See also

GetTxOutProof

Added in Bitcoin Core 0.11.0

The gettxoutproof RPC returns a hex-encoded proof that

NOTE: By default this function only works sometimes. This is when there is an unspent output in the utxo for this transaction. To make it always work, you need to maintain a transaction index, using the -txindex command line option or specify the block in which the transaction is included manually (by blockhash).

Parameter #1—txids

Name Type Presence Description
txids json array Required
(exactly 1)
A json array of txids to filter
[
  "txid",    (string) A transaction hash
  ...
]

Parameter #2—blockhash

Name Type Presence Description
blockhash string Optional If specified, looks for txid in the block with this hash

Result

Name Type Presence Description
result string (hex) Required
(exactly 1)
A string that is a serialized, hex-encoded data for the proof.

See also

  • VerifyTxOutProof: verifies that a proof points to a transaction in a block, returning the transaction it commits to and throwing an RPC error if the block is not in our best chain.
  • merkleblock message: A description of the format used for the proof.
GetTxOutSetInfo

The gettxoutsetinfo RPC returns statistics about the unspent transaction output set.

Note this call may take some time.

Parameters: none

Result

{
  "height":n,     (numeric) The current block height (index)
  "bestblock": "hex",   (string) The hash of the block at the tip of the chain
  "transactions": n,      (numeric) The number of transactions with unspent outputs
  "txouts": n,            (numeric) The number of unspent transaction outputs
  "bogosize": n,          (numeric) A meaningless metric for UTXO set size
  "hash_serialized_2": "hash", (string) The serialized hash
  "disk_size": n,         (numeric) The estimated size of the chainstate on disk
  "total_amount": x.xxx          (numeric) The total amount
}

Example

bitcoin-cli gettxoutsetinfo

See also

GetUnconfirmedBalance

The getunconfirmedbalance RPC returns the server’s total unconfirmed balance.

Parameters: none

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

See also

  • GetBalance: returns the total available balance.
GetWalletInfo

The getwalletinfo RPC returns an object containing various wallet state info.

Parameters: none

Result

{
  "walletname": xxxxx,               (string) the wallet name
  "walletversion": xxxxx,            (numeric) the wallet version
  "balance": xxxxxxx,                (numeric) the total confirmed balance of the wallet in BTC
  "unconfirmed_balance": xxx,        (numeric) the total unconfirmed balance of the wallet in BTC
  "immature_balance": xxxxxx,        (numeric) the total immature balance of the wallet in BTC
  "txcount": xxxxxxx,                (numeric) the total number of transactions in the wallet
  "keypoololdest": xxxxxx,           (numeric) the timestamp (seconds since Unix epoch) of the oldest pre-generated key in the key pool
  "keypoolsize": xxxx,               (numeric) how many new keys are pre-generated (only counts external keys)
  "keypoolsize_hd_internal": xxxx,   (numeric) how many new keys are pre-generated for internal use (used for change outputs, only appears if the wallet is using this feature, otherwise external keys are used)
  "unlocked_until": ttt,             (numeric) the timestamp in seconds since epoch (midnight Jan 1 1970 GMT) that the wallet is unlocked for transfers, or 0 if the wallet is locked
  "paytxfee": x.xxxx,                (numeric) the transaction fee configuration, set in BTC/kB
  "hdseedid": "<hash160>"            (string, optional) the Hash160 of the HD seed (only present when HD is enabled)
  "private_keys_enabled": true|false (boolean) false if privatekeys are disabled for this wallet (enforced watch-only wallet)
}

Example

bitcoin-cli getwalletinfo

See also

  • ListTransactions: if a label name is provided, this will return only incoming transactions paying to addresses with the specified label.
Help

The help RPC list all commands, or get help for a specified command.

Parameter #1—command

Name Type Presence Description
command string Optional
Default=all commands
The command to get help on

Result

Name Type Presence Description
result string (hex) Required
(exactly 1)
The help text
ImportAddress

The importaddress RPC adds an address or script (in hex) that can be watched as if it were in your wallet but cannot be used to spend.

Requires a new wallet backup.

Note: This call can take over an hour to complete if rescan is true, during that time, other rpc calls may report that the imported address exists but related transactions are still missing, leading to temporarily incorrect/bogus balances and unspent outputs until rescan completes.

If you have the full public key, you should call importpubkey instead of this.

Note: If you import a non-standard raw script in hex form, outputs sending to it will be treated as change, and not show up in many RPCs.

Parameter #1—address

Name Type Presence Description
address string Required
(exactly 1)
The Bitcoin address (or hex-encoded script)

Parameter #2—label

Name Type Presence Description
label string Optional
Default=””
An optional label

Parameter #3—rescan

Name Type Presence Description
rescan boolean Optional
Default=true
Rescan the wallet for transactions

Parameter #4—p2sh

Name Type Presence Description
p2sh boolean Optional
Default=false
Add the P2SH version of the script as well

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

Import an address with rescan

bitcoin-cli importaddress "myaddress"

Import using a label without rescan

bitcoin-cli importaddress "myaddress" "testing" false

See also

ImportMulti

Added in Bitcoin Core 0.14.0

The importmulti RPC import addresses/scripts (with private or public keys, redeem script (P2SH)), optionally rescanning the blockchain from the earliest creation time of the imported scripts.

Requires a new wallet backup.

If an address/script is imported without all of the private keys required to spend from that address, it will be watchonly. The ‘watchonly’ option must be set to true in this case or a warning will be returned.

Conversely, if all the private keys are provided and the address/script is spendable, the watchonly option must be set to false, or a warning will be returned.

Note: This call can take over an hour to complete if rescan is true, during that time, other rpc calls may report that the imported keys, addresses or scripts exists but related transactions are still missing.

Parameter #1—requests

Name Type Presence Description
requests json array Required
(exactly 1)
Data to be imported “range”: n or [n,n], (numeric or array) If a ranged descriptor is used, this specifies the end or the range (in the form [begin,end]) to import “internal”: bool, (boolean, optional, default=false) Stating whether matching outputs should be treated as not incoming payments (also known as change) “watchonly”: bool, (boolean, optional, default=false) Stating whether matching outputs should be considered watchonly. “label”: “str”, (string, optional, default=’’) Label to assign to the address, only allowed with internal=false “keypool”: bool, (boolean, optional, default=false) Stating whether imported public keys should be added to the keypool for when users request new addresses. Only allowed when wallet private keys are disabled }, … ]
[
  {                                                            (json object)
    "desc": "str",                                             (string) Descriptor to import. If using descriptor, do not also provide address/scriptPubKey, scripts, or pubkeys
    "scriptPubKey": "<script>" | { "address":"<address>" },    (string / json, required) Type of scriptPubKey (string for script, json for address). Should not be provided if using a descriptor
    "timestamp": timestamp | "now",                            (integer / string, required) Creation time of the key in seconds since epoch (Jan 1 1970 GMT),
                                                               or the string "now" to substitute the current synced blockchain time. The timestamp of the oldest
                                                               key will determine how far back blockchain rescans need to begin for missing wallet transactions.
                                                               "now" can be specified to bypass scanning, for keys which are known to never have been used, and
                                                               0 can be specified to scan the entire blockchain. Blocks up to 2 hours before the earliest key
                                                               creation time of all keys being imported by the importmulti call will be scanned.
    "redeemscript": "str",                                     (string) Allowed only if the scriptPubKey is a P2SH or P2SH-P2WSH address/scriptPubKey
    "witnessscript": "str",                                    (string) Allowed only if the scriptPubKey is a P2SH-P2WSH or P2WSH address/scriptPubKey
    "pubkeys": [                                               (json array, optional, default=empty array) Array of strings giving pubkeys to import. They must occur in P2PKH or P2WPKH scripts. They are not required when the private key is also provided (see the "keys" argument).
      "pubKey",                                                (string)
      ...
    ],
    "keys": [                                                  (json array, optional, default=empty array) Array of strings giving private keys to import. The corresponding public keys must occur in the output or redeemscript.
      "key",                                                   (string)
      ...
    ],

Parameter #2—options

Name Type Presence Description
options json object Optional  
{
  "rescan": bool,                                              (boolean, optional, default=true) Stating if should rescan the blockchain after all imports
}

Result

Response is an array with the same size as the input that has the execution result :

Example

bitcoin-cli importmulti '[{ "scriptPubKey": { "address": "<my address>" }, "timestamp":1455191478 }, { "scriptPubKey": { "address": "<my 2nd address>" }, "label": "example 2", "timestamp": 1455191480 }]'
bitcoin-cli importmulti '[{ "scriptPubKey": { "address": "<my address>" }, "timestamp":1455191478 }]' '{ "rescan": false}'

See also

ImportPrivKey

The importprivkey RPC adds a private key (as returned by dumpprivkey) to your wallet.

Requires a new wallet backup.

Hint: use importmulti to import more than one private key.

Note: This call can take over an hour to complete if rescan is true, during that time, other rpc calls may report that the imported key exists but related transactions are still missing, leading to temporarily incorrect/bogus balances and unspent outputs until rescan completes.

Parameter #1—privkey

Name Type Presence Description
privkey string Required
(exactly 1)
The private key (see dumpprivkey)

Parameter #2—label

Name Type Presence Description
label string Optional An optional label

Parameter #3—rescan

Name Type Presence Description
rescan boolean Optional
Default=true
Rescan the wallet for transactions

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

Dump a private key

bitcoin-cli dumpprivkey "myaddress"

Import the private key with rescan

bitcoin-cli importprivkey "mykey"

Import using a label and without rescan

bitcoin-cli importprivkey "mykey" "testing" false

Import using default blank label and without rescan

bitcoin-cli importprivkey "mykey" "" false

See also

ImportPrunedFunds

Added in Bitcoin Core 0.13.0

The importprunedfunds RPC imports funds without rescan.

Corresponding address or script must previously be included in wallet. Aimed towards pruned wallets. The end-user is responsible to import additional transactions that subsequently spend the imported outputs or rescan after the point in the blockchain the transaction is included.

Parameter #1—rawtransaction

Name Type Presence Description
rawtransaction string Required
(exactly 1)
A raw transaction in hex funding an already-existing address in wallet

Parameter #2—txoutproof

Name Type Presence Description
txoutproof string Required
(exactly 1)
The hex output from gettxoutproof that contains the transaction

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

See also

ImportPubKey

The importpubkey RPC adds a public key (in hex) that can be watched as if it were in your wallet but cannot be used to spend.

Requires a new wallet backup.

Note: This call can take over an hour to complete if rescan is true, during that time, other rpc calls may report that the imported pubkey exists but related transactions are still missing, leading to temporarily incorrect/bogus balances and unspent outputs until rescan completes.

Parameter #1—pubkey

Name Type Presence Description
pubkey string Required
(exactly 1)
The hex-encoded public key

Parameter #2—label

Name Type Presence Description
label string Optional
Default=””
An optional label

Parameter #3—rescan

Name Type Presence Description
rescan boolean Optional
Default=true
Rescan the wallet for transactions

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

Import a public key with rescan

bitcoin-cli importpubkey "mypubkey"

Import using a label without rescan

bitcoin-cli importpubkey "mypubkey" "testing" false
ImportWallet

The importwallet RPC imports keys from a wallet dump file (see dumpwallet).

Requires a new wallet backup to include imported keys.

Parameter #1—filename

Name Type Presence Description
filename string Required
(exactly 1)
The wallet file

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

Dump the wallet

bitcoin-cli dumpwallet "test"

Import the wallet

bitcoin-cli importwallet "test"

Import using the json rpc call

See also

JoinPsbts

Added in Bitcoin Core 0.18.0

The joinpsbts RPC joins multiple distinct PSBTs with different inputs and outputs into one PSBT with inputs and outputs from all of the PSBTs No input in any of the PSBTs can be in more than one of the PSBTs.

Parameter #1—txs

Name Type Presence Description
txs json array Required
(exactly 1)
A json array of base64 strings of partially signed transactions
[
  "psbt",    (string, required) A base64 string of a PSBT
  ...
]

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli joinpsbts "psbt"
KeyPoolRefill

The keypoolrefill RPC fills the keypool.

Parameter #1—newsize

Name Type Presence Description
newsize number (int) Optional
Default=100
The new keypool size

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli keypoolrefill

See also

ListAddressGroupings

The listaddressgroupings RPC 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.

Parameters: none

Result

[
  [
    [
      "address",            (string) The bitcoin address
      amount,                 (numeric) The amount in BTC
      "label"               (string, optional) The label
    ]
    ,...
  ]
  ,...
]

Example

bitcoin-cli listaddressgroupings

See also

ListBanned

Added in Bitcoin Core 0.12.0

The listbanned RPC list all banned IPs/Subnets.

Parameters: none

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli listbanned

See also

  • SetBan: attempts to add or remove an IP/Subnet from the banned list.
  • ClearBanned: clear all banned IPs.
ListLabels

Added in Bitcoin Core 0.17.0

The listlabels RPC returns the list of all labels, or labels that are assigned to addresses with a specific purpose.

Parameter #1—purpose

Name Type Presence Description
purpose string Optional Address purpose to list labels for (‘send’,’receive’). An empty string is the same as not providing this argument.

Result

[               (json array of string)
  "label",      (string) Label name
  ...
]

Example

List all labels

bitcoin-cli listlabels

List labels that have receiving addresses

bitcoin-cli listlabels receive

List labels that have sending addresses

bitcoin-cli listlabels send
ListLockUnspent

The listlockunspent RPC returns list of temporarily unspendable outputs.

See the lockunspent call to lock and unlock transactions for spending.

Parameters: none

Result

[
  {
    "txid" : "transactionid",     (string) The transaction id locked
    "vout" : n                      (numeric) The vout value
  }
  ,...
]

Example

List the unspent transactions

bitcoin-cli listunspent

Lock an unspent transaction

bitcoin-cli lockunspent false "[{\"txid\":\"a08e6907dbbd3d809776dbfc5d82e371b764ed838b5655e72f463568df1aadf0\",\"vout\":1}]"

List the locked transactions

bitcoin-cli listlockunspent

Unlock the transaction again

bitcoin-cli lockunspent true "[{\"txid\":\"a08e6907dbbd3d809776dbfc5d82e371b764ed838b5655e72f463568df1aadf0\",\"vout\":1}]"

See also

ListReceivedByAddress

The listreceivedbyaddress RPC list balances by receiving address.

Parameter #1—minconf

Name Type Presence Description
minconf number (int) Optional
Default=1
The minimum number of confirmations before payments are included.

Parameter #2—include_empty

Name Type Presence Description
include_empty boolean Optional
Default=false
Whether to include addresses that haven’t received any payments.

Parameter #3—include_watchonly

Name Type Presence Description
include_watchonly boolean Optional
Default=false
Whether to include watch-only addresses (see ‘importaddress’).

Parameter #4—address_filter

Name Type Presence Description
address_filter string Optional If present, only return information on this address.

Result

[
  {
    "involvesWatchonly" : true,        (bool) Only returned if imported addresses were involved in transaction
    "address" : "receivingaddress",  (string) The receiving address
    "amount" : x.xxx,                  (numeric) The total amount in BTC received by the address
    "confirmations" : n,               (numeric) The number of confirmations of the most recent transaction included
    "label" : "label",               (string) The label of the receiving address. The default label is "".
    "txids": [
       "txid",                         (string) The ids of transactions received with the address
       ...
    ]
  }
  ,...
]

Example

bitcoin-cli listreceivedbyaddress
bitcoin-cli listreceivedbyaddress 6 true

See also

ListReceivedByLabel

Added in Bitcoin Core 0.17.0

The listreceivedbylabel RPC list received transactions by label.

Parameter #1—minconf

Name Type Presence Description
minconf number (int) Optional
Default=1
The minimum number of confirmations before payments are included.

Parameter #2—include_empty

Name Type Presence Description
include_empty boolean Optional
Default=false
Whether to include labels that haven’t received any payments.

Parameter #3—include_watchonly

Name Type Presence Description
include_watchonly boolean Optional
Default=false
Whether to include watch-only addresses (see ‘importaddress’).

Result

[
  {
    "involvesWatchonly" : true,   (bool) Only returned if imported addresses were involved in transaction
    "amount" : x.xxx,             (numeric) The total amount received by addresses with this label
    "confirmations" : n,          (numeric) The number of confirmations of the most recent transaction included
    "label" : "label"           (string) The label of the receiving address. The default label is "".
  }
  ,...
]

Example

bitcoin-cli listreceivedbylabel
bitcoin-cli listreceivedbylabel 6 true
ListSinceBlock

The listsinceblock RPC get all transactions in blocks since block [blockhash], or all transactions if omitted.

If “blockhash” is no longer a part of the main chain, transactions from the fork point onward are included.

Additionally, if include_removed is set, transactions affecting the wallet which were removed are returned in the “removed” array.

Parameter #1—blockhash

Name Type Presence Description
blockhash string Optional If set, the block hash to list transactions since, otherwise list all transactions.

Parameter #2—target_confirmations

Name Type Presence Description
target_confirmations number (int) Optional
Default=1
Return the nth block hash from the main chain. e.g. 1 would mean the best block hash. Note: this is not used as a filter, but only affects [lastblock] in the return value

Parameter #3—include_watchonly

Name Type Presence Description
include_watchonly boolean Optional
Default=false
Include transactions to watch-only addresses (see ‘importaddress’)

Parameter #4—include_removed

Name Type Presence Description
include_removed boolean Optional
Default=true
Show transactions that were removed due to a reorg in the “removed” array (not guaranteed to work on pruned nodes)

Result

{
  "transactions": [
    "address":"address",    (string) The bitcoin address of the transaction.
    "category":               (string) The transaction category.
                "send"                  Transactions sent.
                "receive"               Non-coinbase transactions received.
                "generate"              Coinbase transactions received with more than 100 confirmations.
                "immature"              Coinbase transactions received with 100 or fewer confirmations.
                "orphan"                Orphaned coinbase transactions received.
    "amount": x.xxx,          (numeric) The amount in BTC. This is negative for the 'send' category, and is positive
                                         for all other categories
    "vout" : n,               (numeric) the vout value
    "fee": x.xxx,             (numeric) The amount of the fee in BTC. This is negative and only available for the 'send' category of transactions.
    "confirmations": n,       (numeric) The number of confirmations for the transaction.
                                          When it's < 0, it means the transaction conflicted that many blocks ago.
    "blockhash": "hashvalue",     (string) The block hash containing the transaction.
    "blockindex": n,          (numeric) The index of the transaction in the block that includes it.
    "blocktime": xxx,         (numeric) The block time in seconds since epoch (1 Jan 1970 GMT).
    "txid": "transactionid",  (string) The transaction id.
    "time": xxx,              (numeric) The transaction time in seconds since epoch (Jan 1 1970 GMT).
    "timereceived": xxx,      (numeric) The time received in seconds since epoch (Jan 1 1970 GMT).
    "bip125-replaceable": "yes|no|unknown",  (string) Whether this transaction could be replaced due to BIP125 (replace-by-fee);
                                                   may be unknown for unconfirmed transactions not in the mempool
    "abandoned": xxx,         (bool) 'true' if the transaction has been abandoned (inputs are respendable). Only available for the 'send' category of transactions.
    "comment": "...",       (string) If a comment is associated with the transaction.
    "label" : "label"       (string) A comment for the address/transaction, if any
    "to": "...",            (string) If a comment to is associated with the transaction.
  ],
  "removed": [
    <structure is the same as "transactions" above, only present if include_removed=true>
    Note: transactions that were re-added in the active chain will appear as-is in this array, and may thus have a positive confirmation count.
  ],
  "lastblock": "lastblockhash"     (string) The hash of the block (target_confirmations-1) from the best block on the main chain. This is typically used to feed back into listsinceblock the next time you call it. So you would generally use a target_confirmations of say 6, so you will be continually re-notified of transactions until they've reached 6 confirmations plus any new ones
}

Example

bitcoin-cli listsinceblock
bitcoin-cli listsinceblock "000000000000000bacf66f7497b7dc45ef753ee9a7d38571037cdb1a57f663ad" 6

See also

ListTransactions

The listtransactions RPC if a label name is provided, this will return only incoming transactions paying to addresses with the specified label.

Returns up to ‘count’ most recent transactions skipping the first ‘from’ transactions.

Parameter #1—label

Name Type Presence Description
label string Optional If set, should be a valid label name to return only incoming transactions with the specified label, or “*” to disable filtering and return all transactions.

Parameter #2—count

Name Type Presence Description
count number (int) Optional
Default=10
The number of transactions to return

Parameter #3—skip

Name Type Presence Description
skip number (int) Optional
Default=0
The number of transactions to skip

Parameter #4—include_watchonly

Name Type Presence Description
include_watchonly boolean Optional
Default=false
Include transactions to watch-only addresses (see ‘importaddress’)

Result

[
  {
    "address":"address",    (string) The bitcoin address of the transaction.
    "category":               (string) The transaction category.
                "send"                  Transactions sent.
                "receive"               Non-coinbase transactions received.
                "generate"              Coinbase transactions received with more than 100 confirmations.
                "immature"              Coinbase transactions received with 100 or fewer confirmations.
                "orphan"                Orphaned coinbase transactions received.
    "amount": x.xxx,          (numeric) The amount in BTC. This is negative for the 'send' category, and is positive
                                        for all other categories
    "label": "label",       (string) A comment for the address/transaction, if any
    "vout": n,                (numeric) the vout value
    "fee": x.xxx,             (numeric) The amount of the fee in BTC. This is negative and only available for the
                                         'send' category of transactions.
    "confirmations": n,       (numeric) The number of confirmations for the transaction. Negative confirmations indicate the
                                         transaction conflicts with the block chain
    "trusted": xxx,           (bool) Whether we consider the outputs of this unconfirmed transaction safe to spend.
    "blockhash": "hashvalue", (string) The block hash containing the transaction.
    "blockindex": n,          (numeric) The index of the transaction in the block that includes it.
    "blocktime": xxx,         (numeric) The block time in seconds since epoch (1 Jan 1970 GMT).
    "txid": "transactionid", (string) The transaction id.
    "time": xxx,              (numeric) The transaction time in seconds since epoch (midnight Jan 1 1970 GMT).
    "timereceived": xxx,      (numeric) The time received in seconds since epoch (midnight Jan 1 1970 GMT).
    "comment": "...",       (string) If a comment is associated with the transaction.
    "bip125-replaceable": "yes|no|unknown",  (string) Whether this transaction could be replaced due to BIP125 (replace-by-fee);
                                                     may be unknown for unconfirmed transactions not in the mempool
    "abandoned": xxx          (bool) 'true' if the transaction has been abandoned (inputs are respendable). Only available for the
                                         'send' category of transactions.
  }
]

Example

List the most recent 10 transactions in the systems

bitcoin-cli listtransactions

List transactions 100 to 120

bitcoin-cli listtransactions "*" 20 100

See also

ListUnspent

The listunspent RPC returns array of unspent transaction outputs with between minconf and maxconf (inclusive) confirmations.

Optionally filter to only include txouts paid to specified addresses.

Parameter #1—minconf

Name Type Presence Description
minconf number (int) Optional
Default=1
The minimum confirmations to filter

Parameter #2—maxconf

Name Type Presence Description
maxconf number (int) Optional
Default=9999999
The maximum confirmations to filter

Parameter #3—addresses

Name Type Presence Description
addresses json array Optional
Default=empty array
A json array of bitcoin addresses to filter
[
  "address",                     (string) bitcoin address
  ...
]

Parameter #4—include_unsafe

Name Type Presence Description
include_unsafe boolean Optional
Default=true
Include outputs that are not safe to spend See description of “safe” attribute below.

Parameter #5—query_options

Name Type Presence Description
query_options json object Optional JSON with query options
{
  "minimumAmount": amount,       (numeric or string, optional, default=0) Minimum value of each UTXO in BTC
  "maximumAmount": amount,       (numeric or string, optional, default=unlimited) Maximum value of each UTXO in BTC
  "maximumCount": n,             (numeric, optional, default=unlimited) Maximum number of UTXOs
  "minimumSumAmount": amount,    (numeric or string, optional, default=unlimited) Minimum sum value of all UTXOs in BTC
}

Result

[                   (array of json object)
  {
    "txid" : "txid",          (string) the transaction id
    "vout" : n,               (numeric) the vout value
    "address" : "address",    (string) the bitcoin address
    "label" : "label",        (string) The associated label, or "" for the default label
    "scriptPubKey" : "key",   (string) the script key
    "amount" : x.xxx,         (numeric) the transaction output amount in BTC
    "confirmations" : n,      (numeric) The number of confirmations
    "redeemScript" : "script" (string) The redeemScript if scriptPubKey is P2SH
    "witnessScript" : "script" (string) witnessScript if the scriptPubKey is P2WSH or P2SH-P2WSH
    "spendable" : xxx,        (bool) Whether we have the private keys to spend this output
    "solvable" : xxx,         (bool) Whether we know how to spend this output, ignoring the lack of keys
    "desc" : xxx,             (string, only when solvable) A descriptor for spending this output
    "safe" : xxx              (bool) Whether this output is considered safe to spend. Unconfirmed transactions
                              from outside keys and unconfirmed replacement transactions are considered unsafe
                              and are not eligible for spending by fundrawtransaction and sendtoaddress.
  }
  ,...
]

Example

bitcoin-cli listunspent
bitcoin-cli listunspent 6 9999999 "[\"1PGFqEzfmQch1gKD3ra4k18PNj3tTUUSqg\",\"1LtvqCaApEdUGFkpKMM4MstjcaL4dKg8SP\"]"
bitcoin-cli listunspent 6 9999999 '[]' true '{ "minimumAmount": 0.005 }'

See also

ListWalletDir

Added in Bitcoin Core 0.18.0

The listwalletdir RPC returns a list of wallets in the wallet directory.

Parameters: none

Result

{
  "wallets" : [                (json array of objects)
    {
      "name" : "name"          (string) The wallet name
    }
    ,...
  ]
}

Example

bitcoin-cli listwalletdir
ListWallets

The listwallets RPC returns a list of currently loaded wallets.

For full information on the wallet, use “getwalletinfo”

Parameters: none

Result

[                         (json array of strings)
  "walletname"            (string) the wallet name
   ...
]

Example

bitcoin-cli listwallets
LoadWallet

The loadwallet RPC loads a wallet from a wallet file or directory.

Note that all wallet command-line options used when starting bitcoind will be applied to the new wallet (eg -zapwallettxes, upgradewallet, rescan, etc).

Parameter #1—filename

Name Type Presence Description
filename string Required
(exactly 1)
The wallet directory or .dat file.

Result

{
  "name" :    <wallet_name>,        (string) The wallet name if loaded successfully.
  "warning" : <warning>,            (string) Warning message if wallet was not loaded cleanly.
}

Example

bitcoin-cli loadwallet "test.dat"
LockUnspent

The lockunspent RPC updates list of temporarily unspendable outputs.

Temporarily lock (unlock=false) or unlock (unlock=true) specified transaction outputs.

If no transaction outputs are specified when unlocking then all current locked transaction outputs are unlocked.

A locked transaction output will not be chosen by automatic coin selection, when spending bitcoins.

Locks are stored in memory only. Nodes start with zero locked outputs, and the locked output list is always cleared (by virtue of process exit) when a node stops or fails.

Also see the listunspent call

Parameter #1—unlock

Name Type Presence Description
unlock boolean Required
(exactly 1)
Whether to unlock (true) or lock (false) the specified transactions

Parameter #2—transactions

Name Type Presence Description
transactions json array Optional
Default=empty array
A json array of objects. Each object the txid (string) vout (numeric).
[
  {                   (json object)
    "txid": "hex",    (string, required) The transaction id
    "vout": n,        (numeric, required) The output number
  },
  ...
]

Result

Name Type Presence Description
result boolean Required
(exactly 1)
Whether the command was successful or not

Example

List the unspent transactions

bitcoin-cli listunspent

Lock an unspent transaction

bitcoin-cli lockunspent false "[{\"txid\":\"a08e6907dbbd3d809776dbfc5d82e371b764ed838b5655e72f463568df1aadf0\",\"vout\":1}]"

List the locked transactions

bitcoin-cli listlockunspent

Unlock the transaction again

bitcoin-cli lockunspent true "[{\"txid\":\"a08e6907dbbd3d809776dbfc5d82e371b764ed838b5655e72f463568df1aadf0\",\"vout\":1}]"

See also

Logging

The logging RPC gets and sets the logging configuration.

When called without an argument, returns the list of categories with status that are currently being debug logged or not.

When called with arguments, adds or removes categories from debug logging and return the lists above.

The arguments are evaluated in order “include”, “exclude”.

If an item is both included and excluded, it will thus end up being excluded.

The valid logging categories are: net, tor, mempool, http, bench, zmq, db, rpc, estimatefee, addrman, selectcoins, reindex, cmpctblock, rand, prune, proxy, mempoolrej, libevent, coindb, qt, leveldb In addition, the following are available as category names with special meanings:

  • “all”, “1” : represent all logging categories.

  • “none”, “0” : even if other logging categories are specified, ignore all of them.

Parameter #1—include

Name Type Presence Description
include json array Optional A json array of categories to add debug logging
[
  "include_category",    (string) the valid logging category
  ...
]

Parameter #2—exclude

Name Type Presence Description
exclude json array Optional A json array of categories to remove debug logging
[
  "exclude_category",    (string) the valid logging category
  ...
]

Result

{                   (json object where keys are the logging categories, and values indicates its status
  "category": true|false,  (bool) if being debug logged or not. false:inactive, true:active
  ...
}

Example

bitcoin-cli logging "[\"all\"]" "[\"http\"]"
Ping

The ping RPC requests that a ping be sent to all other nodes, to measure ping time.

Results provided in getpeerinfo, pingtime and pingwait fields are decimal seconds.

Ping command is handled in queue with all other commands, so it measures processing backlog, not just network ping.

Parameters: none

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli ping

See also

PreciousBlock

Added in Bitcoin Core 0.14.0

The preciousblock RPC treats a block as if it were received before others with the same work.

A later preciousblock call can override the effect of an earlier one.

The effects of preciousblock are not retained across restarts.

Parameter #1—blockhash

Name Type Presence Description
blockhash string Required
(exactly 1)
the hash of the block to mark as precious

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli preciousblock "blockhash"
PrioritiseTransaction

The prioritisetransaction RPC accepts the transaction into mined blocks at a higher (or lower) priority.

Parameter #1—txid

Name Type Presence Description
txid string Required
(exactly 1)
The transaction id.

Parameter #2—dummy

Name Type Presence Description
dummy number (int) Optional API-Compatibility for previous API. Must be zero or null. DEPRECATED. For forward compatibility use named arguments and omit this parameter.

Parameter #3—fee_delta

Name Type Presence Description
fee_delta number (int) Required
(exactly 1)
The fee value (in satoshis) to add (or subtract, if negative). Note, that this value is not a fee rate. It is a value to modify absolute fee of the TX. The fee is not actually paid, only the algorithm for selecting transactions into a block considers the transaction as it would have paid a higher (or lower) fee.

Result

Name Type Presence Description
result boolean Required
(exactly 1)
Returns true

Example

bitcoin-cli prioritisetransaction "txid" 0.0 10000

See also

  • GetRawMemPool: returns all transaction ids in memory pool as a json array of string transaction ids.
  • GetBlockTemplate: if the request parameters include a ‘mode’ key, that is used to explicitly select between the default ‘template’ request or a ‘proposal’.
PruneBlockChain

Added in Bitcoin Core 0.14.0

The pruneblockchain RPC does PruneBlockChain.

Parameter #1—height

Name Type Presence Description
height number (int) Required
(exactly 1)
The block height to prune up to. May be set to a discrete height, or a unix timestamp to prune blocks whose block time is at least 2 hours older than the provided timestamp.

Result

Name Type Presence Description
result number (int) Required
(exactly 1)
Height of the last block pruned.

Example

bitcoin-cli pruneblockchain 1000

See also

RemovePrunedFunds

Added in Bitcoin Core 0.13.0

The removeprunedfunds RPC deletes the specified transaction from the wallet.

Meant for use with pruned wallets and as a companion to importprunedfunds. This will affect wallet balances.

Parameter #1—txid

Name Type Presence Description
txid string Required
(exactly 1)
The hex-encoded id of the transaction you are deleting

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli removeprunedfunds "a8d0c0184dde994a09ec054286f1ce581bebf46446a512166eae7628734ea0a5"

See also

RescanBlockChain

Added in Bitcoin Core 0.16.0

The rescanblockchain RPC rescan the local blockchain for wallet related transactions.

Parameter #1—start_height

Name Type Presence Description
start_height number (int) Optional
Default=0
block height where the rescan should start

Parameter #2—stop_height

Name Type Presence Description
stop_height number (int) Optional the last block height that should be scanned. If none is provided it will rescan up to the tip at return time of this call.

Result

{
  "start_height"     (numeric) The block height where the rescan started (the requested height or 0)
  "stop_height"      (numeric) The height of the last rescanned block. May be null in rare cases if there was a reorg and the call didn't scan any blocks because they were already scanned in the background.
}

Example

bitcoin-cli rescanblockchain 100000 120000
SaveMemPool

Added in Bitcoin Core 0.16.0

The savemempool RPC dumps the mempool to disk.

It will fail until the previous dump is fully loaded.

Parameters: none

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the command was successfull or a JSON with an error field on error.

Example

bitcoin-cli savemempool
ScanTxOutSet

The scantxoutset RPC eXPERIMENTAL warning: this call may be removed or changed in future releases.

Scans the unspent transaction output set for entries that match certain output descriptors.

Examples of output descriptors are:

addr(<address>)                      Outputs whose scriptPubKey corresponds to the specified address (does not include P2PK)
raw(<hex script>)                    Outputs whose scriptPubKey equals the specified hex scripts
combo(<pubkey>)                      P2PK, P2PKH, P2WPKH, and P2SH-P2WPKH outputs for the given pubkey
pkh(<pubkey>)                        P2PKH outputs for the given pubkey
sh(multi(<n>,<pubkey>,<pubkey>,...)) P2SH-multisig outputs for the given threshold and pubkeys

In the above, <pubkey> either refers to a fixed public key in hexadecimal notation, or to an xpub/xprv optionally followed by one or more path elements separated by “/”, and optionally ending in “/” (unhardened), or “/’” or “/*h” (hardened) to specify all unhardened or hardened child keys.

In the latter case, a range needs to be specified by below if different from 1000.

For more information on output descriptors, see the documentation in the doc/descriptors.md file.

Parameter #1—action

Name Type Presence Description
action string Required
(exactly 1)
The action to execute “start” for starting a scan “abort” for aborting the current scan (returns true when abort was successful) “status” for progress report (in %) of the current scan

Parameter #2—scanobjects

Name Type Presence Description
scanobjects json array Required
(exactly 1)
Array of scan objects Every scan object is either a string descriptor or an object:
[
  "descriptor",             (string) An output descriptor
  {                         (json object) An object with output descriptor and metadata
    "desc": "str",          (string, required) An output descriptor
    "range": n or [n,n],    (numeric or array, optional, default=1000) The range of HD chain indexes to explore (either end or [begin,end])
  },
  ...
]

Result

{
  "unspents": [
    {
    "txid" : "transactionid",     (string) The transaction id
    "vout": n,                    (numeric) the vout value
    "scriptPubKey" : "script",    (string) the script key
    "desc" : "descriptor",        (string) A specialized descriptor for the matched scriptPubKey
    "amount" : x.xxx,             (numeric) The total amount in BTC of the unspent output
    "height" : n,                 (numeric) Height of the unspent transaction output
   }
   ,...],
 "total_amount" : x.xxx,          (numeric) The total amount of all found unspent outputs in BTC
]
SendMany

The sendmany RPC send multiple times.

Amounts are double-precision floating point numbers.

Parameter #1—dummy

Name Type Presence Description
dummy string Required
(exactly 1)
Must be set to “” for backwards compatibility.

Parameter #2—amounts

Name Type Presence Description
amounts json object Required
(exactly 1)
A json object with addresses and amounts
{
  "address": amount,    (numeric or string, required) The bitcoin address is the key, the numeric amount (can be string) in BTC is the value
}

Parameter #3—minconf

Name Type Presence Description
minconf number (int) Optional
Default=1
Only use the balance confirmed at least this many times.

Parameter #4—comment

Name Type Presence Description
comment string Optional A comment

Parameter #5—subtractfeefrom

Name Type Presence Description
subtractfeefrom json array Optional A json array with addresses. The fee will be equally deducted from the amount of each selected address. Those recipients will receive less bitcoins than you enter in their corresponding amount field. If no addresses are specified here, the sender pays the fee.
[
  "address",            (string) Subtract fee from this address
  ...
]

Parameter #6—replaceable

Name Type Presence Description
replaceable boolean Optional
Default=fallback to wallet’s default
Allow this transaction to be replaced by a transaction with higher fees via BIP 125

Parameter #7—conf_target

Name Type Presence Description
conf_target number (int) Optional
Default=fallback to wallet’s default
Confirmation target (in blocks)

Parameter #8—estimate_mode

Name Type Presence Description
estimate_mode string Optional
Default=UNSET
The fee estimate mode, must be one of: “UNSET” “ECONOMICAL” “CONSERVATIVE”

Result

Name Type Presence Description
result string (hex) Required
(exactly 1)
The transaction id for the send. Only 1 transaction is created regardless of

Example

Send two amounts to two different addresses:

bitcoin-cli sendmany "" "{\"1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XX\":0.01,\"1353tsE8YMTA4EuV7dgUXGjNFf9KpVvKHz\":0.02}"

Send two amounts to two different addresses setting the confirmation and comment:

bitcoin-cli sendmany "" "{\"1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XX\":0.01,\"1353tsE8YMTA4EuV7dgUXGjNFf9KpVvKHz\":0.02}" 6 "testing"

Send two amounts to two different addresses, subtract fee from amount:

bitcoin-cli sendmany "" "{\"1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XX\":0.01,\"1353tsE8YMTA4EuV7dgUXGjNFf9KpVvKHz\":0.02}" 1 "" "[\"1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XX\",\"1353tsE8YMTA4EuV7dgUXGjNFf9KpVvKHz\"]"

See also