Get branch block hashes

Block hash endpoints return block hashes from the specified chain database. Generally, block hashes are returned in ascending order and include hashes from orphaned blocks.

If you only want to query for blocks that are included in the canonical version of the chain, you can use this /hash/branch endpoint. The /hash/branch endpoint returns blocks in descending order starting from the leafs of branches of the block chain.

Note that this endpoint uses the POST method so you can specify lower and upper bounds for retrieving blocks in the request body.

Request format

Use POST http://{baseURL}/chain/{chain}/hash/branch to get block hashes from the branches of the block chain in descending order. This call only returns blocks that are ancestors of the same block in the set of upper bounds and that are not ancestors of any block in the set of lower bounds.

Path parameters

Parameter	Type	Description
chain (required)	integer >= 0	Specifies the chain identifier of the chain you want to send the request to. Valid values are 0 to 19. For example, to get block hashes for the first chain (0), the request is POST http://{baseURL}/chain/0/hash/branch.

Query parameters

Parameter	Type	Description
limit	integer >= 0	Specifies the maximum number of records that should be returned. The actual number of records returned might be lower than the limit you set. For example: limit=3.
next	string	Specifies the cursor value to retrieve the next page of results. You can find the value to specify in the next property returned by the previous page in a successful response. For example: "inclusive:qgsxD1G5m8dGZ4W9nMKBotU2I10ilURkRIE3_UKHlLM".
minheight	integer >= 0	Specifies the minimum block height for the returned hashes. For example: minheight=4471908.
maxheight	integer >= 0	Specifies the maximum block height for the returned hashes. For example: maxheight=4953816.

Request body schema

Use the following parameters to specify the upper and lower bounds for the queried branches.

Parameter	Type	Description
lower	Array of strings	Specifies the lower bound for the query. No block hashes are returned that are predecessors of any block with a hash from this array. Each block hash consists of 43 characters from the a-zA-Z0-9_- character set.
upper	Array of strings	Specifies the upper bound for the query. All returned block hashes are predecessors of a block with an hash from this array. Each block hash consists of 43 characters from the a-zA-Z0-9_- character set.

The following examples illustrate setting lower and upper bounds for the query parameters.

To return all of the ancestors of the "w5pM1MLEpJcBdMS5KT3tcxEj86hCO4Qv-q-xMysGmOw" block:

{
    "upper": ["w5pM1MLEpJcBdMS5KT3tcxEj86hCO4Qv-q-xMysGmOw"]
}

To return all of the ancestors of the "QxGCAz5AY1Y41nh1yWtgqhKhZ9pPiPRagFdIKNqBH74" block that are not ancestors of the "RClyuyZAacwvPpmLXKbTwrIRXWeUSjiNhJVP2esH8KM" block, you might specify bounds similar to the following:

{
  "lower": [
    "RClyuyZAacwvPpmLXKbTwrIRXWeUSjiNhJVP2esH8KM"
    ],
  "upper": [
    "QxGCAz5AY1Y41nh1yWtgqhKhZ9pPiPRagFdIKNqBH74"
    ]
}

Responses

Requests to POST http://{baseURL}/chain/{chain}/hash/branch return the following response codes:

• 200 OK indicates that the request succeeded and returns the requested block hashes. All block hashes that match the specified criteria are returned from the chain database, including hashes for orphaned blocks.
• 404 Not Found indicates that the requested block hashes could not be found.

Response headers

The response header parameters are the same for all successful and unsuccessful Chainweb node requests.

Parameter	Type	Description
x-peer-addr	string	Specifies the host address and port number of the client as observed by the remote Chainweb node. The host address can be a domain name or an IP address in IPv4 or IPv6 format. For example: "10.36.1.3:42988".
x-server‑timestamp	integer >= 0	Specifies the clock time of the remote Chainweb node using the UNIX epoch timestamp. For example: 1618597601.
x‑chainweb‑node‑version	string	Specifies the version of the remote Chainweb node. For example: "2.23".

Successful response schema

If the request is successful, the response returns application/json content with the following:

Parameter	Type	Description
items (required)	Array of strings	Returns an array of block hashes. Each block hash consists of 43 characters from the [a-zA-Z0-9_-] character set.
limit (required)	integer >= 0	Specifies the maximum number of items in the page. This number can be smaller but never larger than the number of requested items.
next (required)	string or null	Returns a value that can be used to query the next page. You can use this values for the next parameter in a follow-up request. The format for this parameter consists of two parts. The first part of the string can be inclusive, exclusive or null. The second part is the value that calls the next page of results or null if there are no more results to query.

Not found response schema

If there are no results matching the request criteria, the response returns the following:

Parameter	Type	Description
key	string	Specifies the base64Url-encoded block hash without padding. The block hash consists of 43 characters from the [a-zA-Z0-9_-] character set.
reason	string	Provides a placeholder for specifying the reason that no block hashes were found.

Examples

You can send a request to the Kadena main network—mainnet01—and chain 0 by calling the main network service endpoint:

POST http://api.chainweb.com/chainweb/0.0/mainnet01/chain/0/hash/branch

The request body for this query is:

{
    "lower" : ["RClyuyZAacwvPpmLXKbTwrIRXWeUSjiNhJVP2esH8KM"],
    "upper" : ["QxGCAz5AY1Y41nh1yWtgqhKhZ9pPiPRagFdIKNqBH74"]
}

This request returns one item in the response body:

{
    "limit": 1,
    "items": [
        "QxGCAz5AY1Y41nh1yWtgqhKhZ9pPiPRagFdIKNqBH74"
    ],
    "next": null
}

You can send a request to the Kadena test network—testnet04—and chain 18 by calling the testnet service endpoint like this:

POST http://api.testnet.chainweb.com/chainweb/0.0/testnet04/chain/18/hash/branch

The request body for this query is:

{
    "lower": ["egzXuuj9EWIadpIQipb59N1DFPgDE6Gdlo2LmReGAfI"],
    "upper": ["w5pM1MLEpJcBdMS5KT3tcxEj86hCO4Qv-q-xMysGmOw"]
}

This request returns four items in the response body:

{
    "limit": 4,
    "items": [
        "w5pM1MLEpJcBdMS5KT3tcxEj86hCO4Qv-q-xMysGmOw",
        "LfjtkAgRa6jt6al0VACE4Gylu8McHf34233qZjqETuo",
        "DRKyE0T_42ajfqC7kmBEn07pTMZbshFBWGzWT27cqwg",
        "5o4nH_H_mcDnfmXDnp9XqRU5qWcpaKGdfECMZB0CQ8s"
    ],
    "next": null
}

If you specify an upper or lower bound doesn't exist on the chain where you're sending the request, the response body indicates the reason no results matching the request criteria were found. For example:

{
    "key": "w5pM1MLEpJcBdMS5KT3tcxEj86hCO4Qv-q-xMysGmOw",
    "reason": "key not found"
}