For AI agents: an LLM-friendly Markdown version of every page is available by appending .md to its URL or by sending an Accept: text/markdown request header. The full documentation index is at https://www.ankr.com/docs/llms.txt
Skip to main content

Bitcoin — Blockchain RPCs (1/3)

API reference for Bitcoin. All methods ->

Part 1 of 3: 1 · 2 · 3

Blockchain RPCs​

getbestblockhash​

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

getbestblockhash

Parameters​


  • id (string; required): a request ID (example: test).
  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
  • method (string; required): a method used for the request.
  • params (array; required): none.

Returns​

The block hash, hex-encoded.

Request example​

curl -X POST https://rpc.ankr.com/btc/YOUR_ANKR_API_KEY \
-d '{
      "id": "test",
      "method": "getbestblockhash",
      "params": []
}'

Response example​

{
    "result": "00000000000000000001e4696901be3535c9f1cb3f3111caa57e809666021f46",
    "error": null,
    "id": "test"
}

getblock​

Retrieves info about a specific block given its block hash.

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.

getblock "blockhash" ( verbosity )

Parameters​


  • id (string; required): a request ID (example: test).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • <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​

Verbosity=0:

A string that is serialized, hex-encoded data for the block hash.

Verbosity=1:

{                                 (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
  "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" : "hex",           (string) The block version formatted in hexadecimal
  "merkleroot" : "hex",           (string) The merkle root
  "tx" : [                        (json array) The transaction ids
    "hex",                        (string) The transaction id
    ...
  ],
  "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 chain up to this block (in hex)
  "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
}

Verbosity=2:

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

Request example​

curl -X POST https://rpc.ankr.com/btc/YOUR_ANKR_API_KEY \
-d '{
      "id": "test",
      "method": "getblock",
      "params": ["00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"]
}'

Response example​

{
    "result": {
        "hash": "00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09",
        "confirmations": 842553,
        "height": 1000,
        "version": 1,
        "versionHex": "00000001",
        "merkleroot": "fe28050b93faea61fa88c4c630f0e1f0a1c24d0082dd0e10d369e13212128f33",
        "time": 1232346882,
        "mediantime": 1232344831,
        "nonce": 2595206198,
        "bits": "1d00ffff",
        "difficulty": 1,
        "chainwork": "000000000000000000000000000000000000000000000000000003e903e903e9",
        "nTx": 1,
        "previousblockhash": "0000000008e647742775a230787d66fdf92c46a48c896bfbc85cdc8acc67e87d",
        "nextblockhash": "00000000a2887344f8db859e372e7e4bc26b23b9de340f725afbf2edb265b4c6",
        "strippedsize": 216,
        "size": 216,
        "weight": 864,
        "tx": [
            "fe28050b93faea61fa88c4c630f0e1f0a1c24d0082dd0e10d369e13212128f33"
        ]
    },
    "error": null,
    "id": "test"
}

getblockchaininfo​

Returns an object containing various state info regarding blockchain processing.

getblockchaininfo

Parameters​


  • id (string; required): a request ID (example: test).
  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
  • method (string; required): a method used for the request.
  • params (array; required): none.

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
}

Request example​

curl -X POST https://rpc.ankr.com/btc/YOUR_ANKR_API_KEY \
-d '{
      "id": "test",
      "method": "getblockchaininfo",
      "params": []
}'

Response example​

{
    "result": {
        "chain": "main",
        "blocks": 843552,
        "headers": 843552,
        "bestblockhash": "00000000000000000000961750bb966af043f98ac0cc9a00c433ccc455204bac",
        "difficulty": 83148355189239.77,
        "time": 1715765116,
        "mediantime": 1715761540,
        "verificationprogress": 0.999989001722265,
        "initialblockdownload": false,
        "chainwork": "000000000000000000000000000000000000000079805bf222b2b5d07d76e90c",
        "size_on_disk": 649426145409,
        "pruned": false,
        "warnings": ""
    },
    "error": null,
    "id": "test"
}

getblockcount​

Returns the height of the most-work fully-validated chain.

The genesis block has height 0.

getblockcount

Parameters​


  • id (string; required): a request ID (example: test).
  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
  • method (string; required): a method used for the request.
  • params (array; required): none.

Returns​

The current block count.

Request example​

curl -X POST https://rpc.ankr.com/btc/YOUR_ANKR_API_KEY \
-d '{
      "id": "test",
      "method": "getblockcount",
      "params": []
}'

Response example​

{
    "result": 843552,
    "error": null,
    "id": "test"
}

getblockfilter​

Retrieves a BIP 157 content filter for a particular block.

getblockfilter "blockhash" ( "filtertype" )

Parameters​


  • id (string; required): a request ID (example: test).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • <blockhash> (string; required): the hash of the block.
    • <filtertype> (string; optional; default=basic): the type name of the filter.

Returns​

{                      (json object)
  "filter" : "hex",    (string) the hex-encoded filter data
  "header" : "hex"     (string) the hex-encoded filter header
}

Request example​

curl -X POST https://rpc.ankr.com/btc/YOUR_ANKR_API_KEY \
-d '{
      "id": "test",
      "method": "getblockfilter",
      "params": ["00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09", "basic"]
}'

Response example​

{
    "result": {
        "filter": "0163cb10",
        "header": "4a242283a406a7c089f671bb8df7671e5d5e9ba577cea1047d30a7f4919df193"
    },
    "error": null,
    "id": "test"
}

getblockhash​

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

getblockhash height

Parameters​


  • id (string; required): a request ID (example: test).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • <height> (numeric; required): the height index.

Returns​

The hash of the block.

Request example​

curl -X POST https://rpc.ankr.com/btc/YOUR_ANKR_API_KEY \
-d '{
      "id": "test",
      "method": "getblockhash",
      "params": [1000]
}'

Response example​

{
    "result": "00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09",
    "error": null,
    "id": "test"
}

getblockheader​

Retrieves information about a specific block header

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.

getblockheader "blockhash" ( verbose )

Parameters​


  • id (string; required): a request ID (example: test).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • <blockhash> (string; required): the block hash.
    • <verbose> (boolean; optional; default=true): true for a json object, false for the hex-encoded data.

Returns​

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
}

Verbose=false:

A string that is serialized, hex-encoded data for block hash.

Request example​

curl -X POST https://rpc.ankr.com/btc/YOUR_ANKR_API_KEY \
-d '{
      "id": "test",
      "method": "getblockheader",
      "params": ["00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09"]
}'

Response example​

{
    "result": {
        "hash": "00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09",
        "confirmations": 842554,
        "height": 1000,
        "version": 1,
        "versionHex": "00000001",
        "merkleroot": "fe28050b93faea61fa88c4c630f0e1f0a1c24d0082dd0e10d369e13212128f33",
        "time": 1232346882,
        "mediantime": 1232344831,
        "nonce": 2595206198,
        "bits": "1d00ffff",
        "difficulty": 1,
        "chainwork": "000000000000000000000000000000000000000000000000000003e903e903e9",
        "nTx": 1,
        "previousblockhash": "0000000008e647742775a230787d66fdf92c46a48c896bfbc85cdc8acc67e87d",
        "nextblockhash": "00000000a2887344f8db859e372e7e4bc26b23b9de340f725afbf2edb265b4c6"
    },
    "error": null,
    "id": "test"
}

getblockstats​

Computes per block statistics for a given window.

All amounts are in satoshis. It won’t work for some heights with pruning.

getblockstats hash_or_height ( stats )

Parameters​


  • id (string; required): a request ID (example: test).

  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).

  • method (string; required): a method used for the request.

  • params (array; required):

    • <hash_or_height> (string/numeric; required): the block hash or height of the target block.

    • <stats> (json array; optional; default=all values):

      [
        "height",     (string) Selected statistic
        "time",       (string) Selected statistic
        ...
      ]

Returns​

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

Request example​

Block hash param:

curl -X POST https://rpc.ankr.com/btc/YOUR_ANKR_API_KEY \
-d '{
      "id": "test",
      "method": "getblockstats",
      "params": ["00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09", ["minfeerate","avgfeerate"]]
}'

Block height param:

curl -X POST https://rpc.ankr.com/btc/YOUR_ANKR_API_KEY \
-d '{
      "id": "test",
      "method": "getblockstats",
      "params": [1000, ["minfeerate","avgfeerate"]]
}'

Response example​

{
    "result": {
        "avgfeerate": 0,
        "minfeerate": 0
    },
    "error": null,
    "id": "test"
}

getchaintips​

Returns information about all known tips in the block tree.

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

getchaintips

Parameters​


  • id (string; required): a request ID (example: test).
  • jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
  • method (string; required): a method used for the request.
  • params (array; required): none.

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
  },
  ...
]

Request example​

curl -X POST https://rpc.ankr.com/btc/YOUR_ANKR_API_KEY \
-d '{
      "id": "test",
      "method": "getchaintips",
      "params": []
}'

Response example​

{
    "result": [
        {
            "height": 843553,
            "hash": "00000000000000000001f0d113bbcef2c1f52882bf8044a7df5299d364216734",
            "branchlen": 0,
            "status": "active"
        },
        {
            "height": 829613,
            "hash": "0000000000000000000357088139cba6dc295875d7d3b2dd1fd764705727e451",
            "branchlen": 1,
            "status": "valid-fork"
        }
    ],
    "error": null,
    "id": "test"
}