ExBitcoin v0.3.0 ExBitcoin.Core View Source
General blockchain RPC
Link to this section Summary
Functions
getbestblockhash
getblock “blockhash” ( verbosity )
getblockchaininfo Returns an object containing various state info regarding blockchain processing
getblockcount
getblockhash height
getblockheader “hash” ( verbose )
getchaintips Return information about all known tips in the block tree, including the main chain as well as orphaned branches
getchaintxstats ( nblocks blockhash )
getdifficulty
getmempoolancestors txid (verbose)
getmempooldescendants txid (verbose)
getmempoolentry txid
getmempoolinfo
getrawmempool ( verbose )
gettxout “txid” n ( include_mempool )
gettxoutproof [“txid”,…] ( blockhash )
gettxoutsetinfo
preciousblock “blockhash”
pruneblockchain
verifychain ( checklevel nblocks )
verifytxoutproof “proof”
Link to this section Functions
getbestblockhash
Returns the hash of the best (tip) block in the longest blockchain.
Result: “hex” (string) the block hash hex encoded
Examples:
bitcoin-cli getbestblockhash curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getbestblockhash”, “params”: [] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getblock(:"String.t", :"String.t") :: any()
getblock “blockhash” ( verbosity )
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
Arguments:
- “blockhash” (string, required) The block hash
- verbosity (numeric, 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): “data” (string) 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) “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. }
Examples:
bitcoin-cli getblock “00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09” curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getblock”, “params”: [“00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09”] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getblockchaininfo Returns an object containing various state info regarding blockchain processing.
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] “chainwork”: “xxxx” (string) total amount of work in active chain, in hexadecimal “pruned”: xx, (boolean) if the blocks are subject to pruning “pruneheight”: xxxxxx, (numeric) lowest-height complete block stored “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
}
}
} }
Examples:
bitcoin-cli getblockchaininfo curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getblockchaininfo”, “params”: [] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getblockcount
Returns the number of blocks in the longest blockchain.
Result: n (numeric) The current block count
Examples:
bitcoin-cli getblockcount curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getblockcount”, “params”: [] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getblockhash height
Returns hash of block in best-block-chain at height provided.
Arguments:
- height (numeric, required) The height index
Result: “hash” (string) The block hash
Examples:
bitcoin-cli getblockhash 1000 curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getblockhash”, “params”: [1000] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getblockheader(:"String.t", :"String.t") :: any()
getblockheader “hash” ( verbose )
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
Arguments:
- “hash” (string, required) The block hash
- 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) “previousblockhash” : “hash”, (string) The hash of the previous block “nextblockhash” : “hash”, (string) The hash of the next block }
Result (for verbose=false): “data” (string) A string that is serialized, hex-encoded data for block ‘hash’.
Examples:
bitcoin-cli getblockheader “00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09” curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getblockheader”, “params”: [“00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09”] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getchaintips Return information about all known tips in the block tree, including the main chain as well as orphaned branches.
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)
} ] Possible values for status:
- “invalid” This branch contains at least one invalid block
- “headers-only” Not all blocks for this branch are available, but the headers are valid
- “valid-headers” All blocks are available for this branch, but they were never fully validated
- “valid-fork” This branch is not part of the active chain, but is fully validated
- “active” This is the tip of the active main chain, which is certainly valid
Examples:
bitcoin-cli getchaintips curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getchaintips”, “params”: [] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getchaintxstats(:"String.t", :"String.t") :: any()
getchaintxstats ( nblocks blockhash )
Compute statistics about the total number and rate of transactions in the chain.
Arguments:
- nblocks (numeric, optional) Size of the window in number of blocks (default: one month).
- “blockhash” (string, optional) The hash of the block that ends the window.
Result: { “time”: xxxxx, (numeric) The timestamp for the statistics in UNIX format. “txcount”: xxxxx, (numeric) The total number of transactions in the chain up to that point. “txrate”: x.xx, (numeric) The average rate of transactions per second in the window. }
Examples:
bitcoin-cli getchaintxstats curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getchaintxstats”, “params”: [2016] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getdifficulty
Returns the proof-of-work difficulty as a multiple of the minimum difficulty.
Result: n.nnn (numeric) the proof-of-work difficulty as a multiple of the minimum difficulty.
Examples:
bitcoin-cli getdifficulty curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getdifficulty”, “params”: [] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getmempoolancestors(:"String.t", :"String.t") :: any()
getmempoolancestors txid (verbose)
If txid is in the mempool, returns all in-mempool ancestors.
Arguments:
- “txid” (string, required) The transaction id (must be in mempool)
- 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
"modifiedfee" : n, (numeric) transaction fee with fee deltas used for mining priority
"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)
"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)
"depends" : [ (array) unconfirmed transactions used as inputs for this transaction
"transactionid", (string) parent transaction id
... ]
}, … }
Examples:
bitcoin-cli getmempoolancestors “mytxid” curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getmempoolancestors”, “params”: [“mytxid”] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getmempooldescendants(:"String.t", :"String.t") :: any()
getmempooldescendants txid (verbose)
If txid is in the mempool, returns all in-mempool descendants.
Arguments:
- “txid” (string, required) The transaction id (must be in mempool)
- 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
"modifiedfee" : n, (numeric) transaction fee with fee deltas used for mining priority
"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)
"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)
"depends" : [ (array) unconfirmed transactions used as inputs for this transaction
"transactionid", (string) parent transaction id
... ]
}, … }
Examples:
bitcoin-cli getmempooldescendants “mytxid” curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getmempooldescendants”, “params”: [“mytxid”] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getmempoolentry txid
Returns mempool data for given transaction
Arguments:
- “txid” (string, required) 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
"modifiedfee" : n, (numeric) transaction fee with fee deltas used for mining priority
"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)
"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)
"depends" : [ (array) unconfirmed transactions used as inputs for this transaction
"transactionid", (string) parent transaction id
... ]
}
Examples:
bitcoin-cli getmempoolentry “mytxid” curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getmempoolentry”, “params”: [“mytxid”] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getmempoolinfo
Returns details on the active state of the TX memory pool.
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 feerate (BTC per KB) for tx to be accepted }
Examples:
bitcoin-cli getmempoolinfo curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getmempoolinfo”, “params”: [] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
getrawmempool ( verbose )
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.
Arguments:
- 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
"modifiedfee" : n, (numeric) transaction fee with fee deltas used for mining priority
"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)
"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)
"depends" : [ (array) unconfirmed transactions used as inputs for this transaction
"transactionid", (string) parent transaction id
... ]
}, … }
Examples:
bitcoin-cli getrawmempool true curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “getrawmempool”, “params”: [true] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
gettxout(:"String.t", :"String.t", :"String.t") :: any()
gettxout “txid” n ( include_mempool )
Returns details about an unspent transaction output.
Arguments:
- “txid” (string, required) The transaction id
- “n” (numeric, required) vout number
- “include_mempool” (boolean, optional) Whether to include the mempool. Default: true. Note that an unspent output that is spent in the mempool won’t appear.
Result: { “bestblock” : “hash”, (string) the block hash “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 }
Examples:
Get unspent transactions
bitcoin-cli listunspent
View the details
bitcoin-cli gettxout “txid” 1
As a json rpc call
curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “gettxout”, “params”: [“txid”, 1] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
gettxoutproof(:"String.t", :"String.t") :: any()
gettxoutproof [“txid”,…] ( blockhash )
Returns a hex-encoded proof that “txid” was included in a block.
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).
Arguments:
- “txids” (string) A json array of txids to filter [ “txid” (string) A transaction hash ,… ]
- “blockhash” (string, optional) If specified, looks for txid in the block with this hash
Result: “data” (string) A string that is a serialized, hex-encoded data for the proof.
gettxoutsetinfo
Returns statistics about the unspent transaction output set. Note this call may take some time.
Result: { “height”:n, (numeric) The current block height (index) “bestblock”: “hex”, (string) the best block hash hex “transactions”: n, (numeric) The number of transactions “txouts”: n, (numeric) The number of output transactions “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 }
Examples:
bitcoin-cli gettxoutsetinfo curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “gettxoutsetinfo”, “params”: [] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
preciousblock “blockhash”
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.
Arguments:
- “blockhash” (string, required) the hash of the block to mark as precious
Result:
Examples:
bitcoin-cli preciousblock “blockhash” curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “preciousblock”, “params”: [“blockhash”] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
pruneblockchain
Arguments:
- “height” (numeric, required) 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: n (numeric) Height of the last block pruned.
Examples:
bitcoin-cli pruneblockchain 1000 curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “pruneblockchain”, “params”: [1000] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
verifychain(:"String.t", :"String.t") :: any()
verifychain ( checklevel nblocks )
Verifies blockchain database.
Arguments:
- checklevel (numeric, optional, 0-4, default=3) How thorough the block verification is.
- nblocks (numeric, optional, default=6, 0=all) The number of blocks to check.
Result: true|false (boolean) Verified or not
Examples:
bitcoin-cli verifychain curl —user myusername —data-binary ‘{“jsonrpc”: “1.0”, “id”:”curltest”, “method”: “verifychain”, “params”: [] }’ -H ‘content-type: text/plain;’ http://127.0.0.1:8332/
verifytxoutproof “proof”
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
Arguments:
- “proof” (string, required) The hex-encoded proof generated by gettxoutproof
Result: [“txid”] (array, strings) The txid(s) which the proof commits to, or empty array if the proof is invalid