1 of 18

Blockchain RPCs

getbestblockhash

Returns the hash of the best (tip) block in the most-work fully-validated chain.

This method will use 10 Compute Units.

Returns

Name

Type

Description

curl https://mainnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getbestblockhash",
	"params": []
}'

curl https://testnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getbestblockhash",
	"params": []
}'

getblock

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.

This method will use 10 .

Reference:

Parameters

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

Returns (for verbosity = 0)

Name

Type

Description

Returns (for verbosity = 1)

Returns (for verbosity = 2)

getblockchaininfo

Returns an object containing various state info regarding blockchain processing.

This method will use 10 Compute Units.

Returns

{                                         (json object)
  "chain" : "str",                        (string) current network name (main, test, regtest)
  "blocks" : n,                           (numeric) the height of the most-work fully-validated chain. The genesis block has height 0
  "headers" : n,                          (numeric) the current number of headers we have validated
  "bestblockhash" : "str",                (string) the hash of the currently best block
  "difficulty" : n,                       (numeric) the current difficulty
  "mediantime" : n,                       (numeric) median time for the current best block
  "verificationprogress" : n,             (numeric) estimate of verification progress [0..1]
  "initialblockdownload" : true|false,    (boolean) (debug information) estimate of whether this node is in Initial Block Download mode
  "chainwork" : "hex",                    (string) total amount of work in active chain, in hexadecimal
  "size_on_disk" : n,                     (numeric) the estimated size of the block and undo files on disk
  "pruned" : true|false,                  (boolean) if the blocks are subject to pruning
  "pruneheight" : n,                      (numeric) lowest-height complete block stored (only present if pruning is enabled)
  "automatic_pruning" : true|false,       (boolean) whether automatic pruning is enabled (only present if pruning is enabled)
  "prune_target_size" : n,                (numeric) the target size used by pruning (only present if automatic pruning is enabled)
  "softforks" : {                         (json object) status of softforks
    "xxxx" : {                            (json object) name of the softfork
      "type" : "str",                     (string) one of "buried", "bip9"
      "bip9" : {                          (json object) status of bip9 softforks (only for "bip9" type)
        "status" : "str",                 (string) one of "defined", "started", "locked_in", "active", "failed"
        "bit" : n,                        (numeric) the bit (0-28) in the block version field used to signal this softfork (only for "started" status)
        "start_time" : xxx,               (numeric) the minimum median time past of a block at which the bit gains its meaning
        "timeout" : xxx,                  (numeric) the median time past of a block at which the deployment is considered failed if not yet locked in
        "since" : n,                      (numeric) height of the first block to which the status applies
        "statistics" : {                  (json object) numeric statistics about BIP9 signalling for a softfork (only for "started" status)
          "period" : n,                   (numeric) the length in blocks of the BIP9 signalling period
          "threshold" : n,                (numeric) the number of blocks with the version bit set required to activate the feature
          "elapsed" : n,                  (numeric) the number of blocks elapsed since the beginning of the current period
          "count" : n,                    (numeric) the number of blocks with the version bit set in the current period
          "possible" : true|false         (boolean) returns false if there are not enough blocks left in this period to pass activation threshold
        }
      },
      "height" : n,                       (numeric) height of the first block which the rules are or will be enforced (only for "buried" type, or "bip9" type with "active" status)
      "active" : true|false               (boolean) true if the rules are enforced for the mempool and the next block
    },
    ...
  },
  "warnings" : "str"                      (string) any network and blockchain warnings
}

curl https://mainnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getblockchaininfo",
	"params": []
}'

curl https://testnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getblockchaininfo",
	"params": []
}'

getblockcount

Returns the height of the most-work fully-validated chain. The genesis block has height 0.

This method will use 10 .

Reference:

Returns

Name

Type

Description

getblockhash

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

This method will use 10 .

Reference:

Parameters

height - numeric, required

The height index

Returns

Name

Type

Description

getblockheader

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’.

This method will use 10 Compute Units.

Parameters

blockhash - string, required

The block hash

verbose - boolean, optional, default=true

true for a json object, false for the hex-encoded data

Returns (for verbose = true)

{                                 (json object)
  "hash" : "hex",                 (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" : "hex",           (string) The block version formatted in hexadecimal
  "merkleroot" : "hex",           (string) The merkle root
  "time" : xxx,                   (numeric) The block time expressed in UNIX epoch time
  "mediantime" : xxx,             (numeric) The median block time expressed in UNIX epoch time
  "nonce" : n,                    (numeric) The nonce
  "bits" : "hex",                 (string) The bits
  "difficulty" : n,               (numeric) The difficulty
  "chainwork" : "hex",            (string) Expected number of hashes required to produce the current chain
  "nTx" : n,                      (numeric) The number of transactions in the block
  "previousblockhash" : "hex",    (string) The hash of the previous block
  "nextblockhash" : "hex"         (string) The hash of the next block
}

Returns (for verbose = false)

curl https://mainnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getblockheader",
	"params": ["00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"]
}'

curl https://testnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getblockheader",
	"params": ["00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"]
}'

getblockstats

Compute per block statistics for a given window. All amounts are in satoshis. It won’t work for some heights with pruning.

This method will use 10 .

Reference:

Parameters

hash_or_height - string or numeric, required

The block hash or height of the target block

stats - json array, optional, default=all values

Values to plot (see result below)

Returns

getchaintips

Return information about all known tips in the block tree, including the main chain as well as orphaned branches.

This method will use 10 Compute Units.

Returns

[                        (json array)
  {                      (json object)
    "height" : n,        (numeric) height of the chain tip
    "hash" : "hex",      (string) block hash of the tip
    "branchlen" : n,     (numeric) zero for main chain, otherwise length of branch connecting the tip to the main chain
    "status" : "str"     (string) status of the chain, "active" for the main chain
                         Possible values for status:
                         1.  "invalid"               This branch contains at least one invalid block
                         2.  "headers-only"          Not all blocks for this branch are available, but the headers are valid
                         3.  "valid-headers"         All blocks are available for this branch, but they were never fully validated
                         4.  "valid-fork"            This branch is not part of the active chain, but is fully validated
                         5.  "active"                This is the tip of the active main chain, which is certainly valid
  },
  ...
]

curl https://mainnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getchaintips",
	"params": []
}'

curl https://testnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getchaintips",
	"params": []
}'

getchaintxstats

Compute statistics about the total number and rate of transactions in the chain.

This method will use 10 .

Reference:

Parameters

nblocks - numeric, optional, default=one month

Size of the window in number of blocks

blockhash - string, optional, default=chain tip

The hash of the block that ends the window.

Returns

getdifficulty

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

This method will use 10 .

Reference:

Returns

Name

Type

Description

getmempoolancestors

If txid is in the mempool, returns all in-mempool ancestors.

This method will use 10 Compute Units.

Parameters

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

Returns (for verbose = false)

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

Returns (for verbose = true)

{                                         (json object)
  "transactionid" : {                     (json object)
    "vsize" : 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.
    "weight" : n,                         (numeric) transaction weight as defined in BIP 141.
    "fee" : n,                            (numeric) transaction fee in BTC (DEPRECATED)
    "modifiedfee" : n,                    (numeric) transaction fee with fee deltas used for mining priority (DEPRECATED)
    "time" : xxx,                         (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" : "hex",                      (string) hash of serialized transaction, including witness data
    "fees" : {                            (json object)
      "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" : [                         (json array) unconfirmed transactions used as inputs for this transaction
      "hex",                              (string) parent transaction id
      ...
    ],
    "spentby" : [                         (json array) unconfirmed transactions spending outputs from this transaction
      "hex",                              (string) child transaction id
      ...
    ],
    "bip125-replaceable" : true|false,    (boolean) Whether this transaction could be replaced due to BIP125 (replace-by-fee)
    "unbroadcast" : true|false            (boolean) Whether this transaction is currently unbroadcast (initial broadcast not yet acknowledged by any peers)
  },
  ...
}

curl https://mainnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getmempoolancestors",
	"params": ["txid"]
}'

curl https://testnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getmempoolancestors",
	"params": ["txid"]
}'

getmempooldescendants

Returns details on the active state of the TX memory pool.

This method will use 10 .

Reference:

Parameters

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

Returns (for verbose = false)

Returns (for verbose = true)

getmempoolinfo

Returns details on the active state of the TX memory pool.

This method will use 10 Compute Units.

Result

{                            (json object)
  "loaded" : true|false,     (boolean) True if the mempool is fully loaded
  "size" : n,                (numeric) Current tx count
  "bytes" : n,               (numeric) Sum of all virtual transaction sizes as defined in BIP 141. Differs from actual serialized size because witness data is discounted
  "usage" : n,               (numeric) Total memory usage for the mempool
  "maxmempool" : n,          (numeric) Maximum memory usage for the mempool
  "mempoolminfee" : n,       (numeric) Minimum fee rate in BTC/kB for tx to be accepted. Is the maximum of minrelaytxfee and minimum mempool fee
  "minrelaytxfee" : n,       (numeric) Current minimum relay fee for transactions
  "unbroadcastcount" : n     (numeric) Current number of transactions that haven't passed initial broadcast yet
}

curl https://mainnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getmempoolinfo",
	"params": []
}'

curl https://testnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getmempoolinfo",
	"params": []
}'

getrawmempool

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.

This method will use 10 Compute Units.

Parameters

verbose - boolean, optional, default=false

True for a json object, false for array of transaction ids

mempool_sequence - boolean, optional, default=false

If verbose=false, returns a json object with transaction list and mempool sequence number attached.

Returns (for verbose = false)

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

Returns (for verbose = true)

{                                         (json object)
  "transactionid" : {                     (json object)
    "vsize" : 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.
    "weight" : n,                         (numeric) transaction weight as defined in BIP 141.
    "fee" : n,                            (numeric) transaction fee in BTC (DEPRECATED)
    "modifiedfee" : n,                    (numeric) transaction fee with fee deltas used for mining priority (DEPRECATED)
    "time" : xxx,                         (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" : "hex",                      (string) hash of serialized transaction, including witness data
    "fees" : {                            (json object)
      "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" : [                         (json array) unconfirmed transactions used as inputs for this transaction
      "hex",                              (string) parent transaction id
      ...
    ],
    "spentby" : [                         (json array) unconfirmed transactions spending outputs from this transaction
      "hex",                              (string) child transaction id
      ...
    ],
    "bip125-replaceable" : true|false,    (boolean) Whether this transaction could be replaced due to BIP125 (replace-by-fee)
    "unbroadcast" : true|false            (boolean) Whether this transaction is currently unbroadcast (initial broadcast not yet acknowledged by any peers)
  },
  ...
}

Result (for verbose = false and mempool_sequence = true)

{                            (json object)
  "txids" : [                (json array)
    "hex",                   (string) The transaction id
    ...
  ],
  "mempool_sequence" : n     (numeric) The mempool sequence value.
}

curl https://mainnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getrawmempool",
	"params": [true]
}'

curl https://testnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "getrawmempool",
	"params": [true]
}'

gettxout

Returns details about an unspent transaction output.

This method will use 10 Compute Units.

Reference: Here

Parameters

txid - string, required

The transaction id

n - numeric, required

vout number

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.

Returns

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

curl https://mainnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "gettxout",
	"params": ["txid", 1]
}'

curl https://testnet.bitcoin.validationcloud.io/v1/<YOUR_API_KEY_HERE> \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{
	"jsonrpc": "1.0",
	"id": "curltest",
	"method": "gettxout",
	"params": ["txid", 1]
}'

gettxoutproof

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).

This method will use 10 .

Reference:

Parameters

txids - json array, required

The txids to filter

blockhash - string, optional

If specified, looks for txid in the block with this hash

Returns

gettxoutsetinfo

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

This method will use 10 .

Reference:

Parameters

hash_type - string, optional, default=hash_serialized_2

Which UTXO set hash should be calculated. Options: ‘hash_serialized_2’ (the legacy algorithm), ‘none’.