These endpoints return block hashes from the chain database. Generally, block hashes are returned in ascending order and include hashes from orphaned blocks. For only querying blocks that are included in the winning branch of the chain the `branch` endpoint can be used, which returns blocks in descending order starting from the leafs of branches of the block chain.
openapi: 3.0.0
info:
title: Kadena Chainweb Node block blockhash API
description: 'API of [chainweb-node](https://github.com/kadena-io/chainweb-node)
Chainweb is a scalable Proof-Of-Work (PoW) consensus algorithm. It is an
conservative extension of Bitcoin''s Nakamoto consensus that extends
Bitcoin''s single chain algorithm to multiple chains. This allows for
unlimited transaction throughput by horizontally scaling the number of chains.
Feedback and bug reports for the content of this site are welcome. Please
open an issue at [this github repository](https://github.com/kadena-io/chainweb-openapi/issues).
'
version: '0.0'
x-logo:
url: https://cdn.sanity.io/images/agrhq0bu/production/73f06e78e066f86e21cb84f82292494fe04b9be8-1438x472.png
alttext: Kadena Chainweb Logo
servers:
- url: https://api.chainweb.com/chainweb/{apiVersion}/mainnet01
description: 'Chainweb mainnet service API. It also serves some endpoints of the P2P API.
'
variables:
apiVersion:
default: '0.0'
- url: https://api.testnet.chainweb.com/chainweb/{apiVersion}/testnet04
description: 'Chainweb testnet service API. It also serves some endpoints of the P2P API.
'
variables:
apiVersion:
default: '0.0'
- url: '{schema}://{domain}:{port}/chainweb/{apiVersion}/{chainwebVersion}'
description: 'An generic chainweb-node. It may serve only a subset of the endpoints.
'
variables:
schema:
default: http
enum:
- http
- https
domain:
default: api.chainweb.com
port:
default: '1848'
chainwebVersion:
default: mainnet01
enum:
- test-singleton
- development
- mainnet01
- testnet04
apiVersion:
default: '0.0'
- url: https://{location}.chainweb.com/chainweb/{apiVersion}/mainnet01
description: Chainweb mainnet P2P bootstrap node. Only P2P API endpoints are served.
variables:
location:
default: us-e1
enum:
- us-e1
- us-e2
- us-e3
- us-w1
- us-w2
- us-w3
- fr1
- fr2
- fr3
- jp1
- jp2
- jp3
apiVersion:
default: '0.0'
- url: https://{location}.testnet.chainweb.com/chainweb/{apiVersion}/testnet04
description: Chainweb testnet P2P bootstrap node. Only P2P API endpoints are served.
variables:
location:
default: us-e1
enum:
- us1
- us2
- eu1
- eu2
- ap1
- ap2
apiVersion:
default: '0.0'
tags:
- name: blockhash
x-displayName: Block Hashes Endpoints
description: 'These endpoints return block hashes from the chain database.
Generally, block hashes are returned in ascending order and include hashes
from orphaned blocks.
For only querying blocks that are included in the winning branch of the
chain the `branch` endpoint can be used, which returns blocks in descending
order starting from the leafs of branches of the block chain.
'
paths:
/chain/{chain}/hash:
get:
summary: Get Block Hashes
tags:
- blockhash
parameters:
- $ref: '#/components/parameters/chain'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/minheight'
- $ref: '#/components/parameters/maxheight'
responses:
'200':
description: 'A page of a collection of block hashes in **ascending** order
that satisfies query parameters. Any block hash from the chain
database is returned. **This includes hashes of orphaned blocks.**
'
headers:
x-peer-addr:
$ref: '#/components/headers/x-peer-addr'
x-server-timestamp:
$ref: '#/components/headers/x-server-timestamp'
x-chainweb-node-version:
$ref: '#/components/headers/x-chainweb-node-version'
content:
application/json:
schema:
allOf:
- properties:
items:
description: Array of block hashes
items:
$ref: '#/components/schemas/blockHash'
- $ref: '#/components/schemas/page'
example:
$ref: '#/components/examples/blockHashPage'
'404':
description: 'A parameter indicated a nonexistent block height.
'
content:
application/json:
schema:
properties:
reason:
type: string
key:
$ref: '#/components/schemas/blockHash'
/chain/{chain}/hash/branch:
post:
summary: Get Block Hash Branches
description: 'A page of block hashes from branches of the block chain in
**descending** order.
Only blocks are returned that are ancestors of the some block in the
set of upper bounds and are not ancestors of any block in the set of
lower bounds.
'
tags:
- blockhash
parameters:
- $ref: '#/components/parameters/chain'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/next'
- $ref: '#/components/parameters/minheight'
- $ref: '#/components/parameters/maxheight'
requestBody:
description: Upper and lower bounds of the queried branches
content:
application/json:
schema:
properties:
lower:
description: 'No block hashes are returned that are predecessors of any
block with a hash from this array.
'
type: array
items:
$ref: '#/components/schemas/blockHash'
upper:
description: 'Returned block hashes are predecessors of a block with an
hash from this array. This includes blocks with hashes from
this array.
'
type: array
items:
$ref: '#/components/schemas/blockHash'
examples:
singletonLimited:
value:
lower:
- RClyuyZAacwvPpmLXKbTwrIRXWeUSjiNhJVP2esH8KM
upper:
- QxGCAz5AY1Y41nh1yWtgqhKhZ9pPiPRagFdIKNqBH74
summary: Ancestors of block that are not acestors of another block
singleton:
value:
lower: []
upper:
- QxGCAz5AY1Y41nh1yWtgqhKhZ9pPiPRagFdIKNqBH74
summary: Ancestors of one block
empty:
value:
lower: []
upper: []
summary: Empty branch
empty2:
value:
lower:
- QxGCAz5AY1Y41nh1yWtgqhKhZ9pPiPRagFdIKNqBH74
upper:
- QxGCAz5AY1Y41nh1yWtgqhKhZ9pPiPRagFdIKNqBH74
summary: Another example that returns an empty page
responses:
'200':
description: The requested block hashes
headers:
x-peer-addr:
$ref: '#/components/headers/x-peer-addr'
x-server-timestamp:
$ref: '#/components/headers/x-server-timestamp'
x-chainweb-node-version:
$ref: '#/components/headers/x-chainweb-node-version'
content:
application/json:
schema:
allOf:
- properties:
items:
description: Array of block hashes
items:
$ref: '#/components/schemas/blockHash'
- $ref: '#/components/schemas/page'
example:
$ref: '#/components/examples/blockHashBranchPage'
'404':
description: The requested block hashes could not be found
headers:
x-peer-addr:
$ref: '#/components/headers/x-peer-addr'
x-server-timestamp:
$ref: '#/components/headers/x-server-timestamp'
x-chainweb-node-version:
$ref: '#/components/headers/x-chainweb-node-version'
content:
application/json:
schema:
properties:
reason:
type: string
key:
$ref: '#/components/schemas/blockHash'
components:
headers:
x-peer-addr:
description: Host and port of the client as observed by the remote node
schema:
$ref: '#/components/schemas/hostAddress'
example: 10.36.1.3:42988
x-server-timestamp:
description: The time of the clock of the remote node
schema:
$ref: '#/components/schemas/posixTimestamp'
example: 1618597601
x-chainweb-node-version:
description: The version of the remote chainweb node
schema:
type: string
example: '2.6'
schemas:
page:
title: Page
description: Page of a collection of items
required:
- next
- limit
- items
example:
$ref: '#/components/examples/base64HeaderPage'
properties:
limit:
description: 'The number of items in the page. This number can be smaller but
never be larger than the number of requested items.
'
type: integer
minimum: 0
items:
description: Items of the returned collection
type: array
next:
description: 'A cursor that can be used to query the next page. It should be used
literally as value for the `next` parameter in a follow-up request.
'
oneOf:
- type: 'null'
- type: string
nullable: true
pattern: ^(inclusive|exclusive):.*$
items:
description: 'The items in the page.
'
hostAddress:
title: Host Address
description: Host address containing IPv4 and port
type: string
pattern: ^\d{4}.\d{4}.\d{4}.\d{4}:\d+$
example: 10.36.1.3:42988
blockHash:
title: Block Hash
description: Base64Url (without padding) encoded block hash
example: QxGCAz5AY1Y41nh1yWtgqhKhZ9pPiPRagFdIKNqBH7
allOf:
- $ref: '#/components/schemas/sha256Hash'
sha256Hash:
title: SHA256 Hash
type: string
description: Base64Url (without padding) encoded SHA256 hash
pattern: ^[a-zA-Z0-9_-]{43}$
minLength: 43
maxLength: 43
example: y3aWL72-3wAy7vL9wcegGXnstH0lHi-q-cfxkhD5JCw
posixTimestamp:
title: POSIX Timestamp
type: integer
description: Seconds since POSIX epoch
example: 1619108524
minimum: 0
examples:
blockHashBranchPage:
value:
next: inclusive:o1S4NNFhKWg8T1HEkmDvsTH9Ut9l3_qHRpp00yRKZIk
items:
- QxGCAz5AY1Y41nh1yWtgqhKhZ9pPiPRagFdIKNqBH74
- RClyuyZAacwvPpmLXKbTwrIRXWeUSjiNhJVP2esH8KM
limit: 2
blockHashPage:
value:
next: inclusive:o1S4NNFhKWg8T1HEkmDvsTH9Ut9l3_qHRpp00yRKZIk
items:
- k0an0qEORusqQg9ZjKrxa-0Bo0-hQVYLXqWi5LHxg3k
- vhVa6Deh10RXLRf3L-MSQTYqaL-_IY_mi-v58MjP9R8
limit: 2
base64HeaderPage:
value:
next: inclusive:o1S4NNFhKWg8T1HEkmDvsTH9Ut9l3_qHRpp00yRKZIk
items:
- AAAAAAAAAABRoiLHW7EFAB2lwAatTykipYZ3CZNPzLe-f5S-zUt8COtu0H12f_OZAwAFAAAAMpic85rur2MYf3zli8s8bHxTFjriFoMPTr6ZPs8sjxMKAAAAVBKuhU_hQmuvKlx88A5o-FH0rzNo59NsdxmOGNBQ-ycPAAAAMItdqgHZxf7j6l0oE8X-G9-VyMbnQmZrtSniuRe_EJ9CtyxsSb7daPIIYAaXMgSEsQ3dkxY5GjJjLwAAAAAAABqWlmx5B6wo0YWPIShNKmdVrAQWht2P85BS1drGLpkAAAAAADUJ-ARn7blgHgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQEIPAAAAAAAFAAAA-na5gFuxBQAFL-3CY4YuAJNGp9KhDkbrKkIPWYyq8WvtAaNPoUFWC16louSx8YN5
- AAAAAAAAAAA0slHKW7EFAJNGp9KhDkbrKkIPWYyq8WvtAaNPoUFWC16louSx8YN5AwAFAAAAALcxv1ZiwwQ_QX9eOBZMbzIop6n7XtveS1FqOFwyvGMKAAAAC76ElC60qXSJQCHePpzzJxsCYvvrqvmkoHPyZnex-4QPAAAAKv0sz_rTANjoiJwMrdZFCJNFwdH0U_M5ouwMr3BXBfpCtyxsSb7daPIIYAaXMgSEsQ3dkxY5GjJjLwAAAAAAALJlIg1vY3w_9L63bePn1yk_5agvdEbIBBjm3adxc5xWAAAAAGzpBzdiVL9gHgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQUIPAAAAAAAFAAAA-na5gFuxBQALiBhXgqaHAb4VWug3oddEVy0X9y_jEkE2Kmi_vyGP5ovr-fDIz_Uf
limit: 2
parameters:
chain:
name: chain
in: path
description: the id of the chain to which the request is sent
required: true
schema:
type: integer
minimum: 0
example: 0
minheight:
name: minheight
in: query
description: Minimum block height of the returned headers
required: false
schema:
type: integer
minimum: 0
example: 500000
next:
name: next
in: query
description: 'The cursor for the next page. This value can be found as value of the
`next` property of the previous page.
'
required: false
schema:
type: string
limit:
name: limit
in: query
description: 'Maximum number of records that may be returned. The actual number may be
lower.
'
required: false
schema:
type: integer
minimum: 0
maxheight:
name: maxheight
in: query
description: Maximum block height of the returned headers
required: false
schema:
type: integer
minimum: 0
example: 500000
x-tagGroups:
- name: chainweb_p2p
x-displayName: Chainweb P2P API
tags:
- p2p_api
- cut
- blockhash
- header
- payload
- mempool
- peer
- config
- name: chainweb_service
x-displayName: Chainweb Service API
tags:
- service_api
- block
- misc
- mining
- pact
- name: Common HTTP Headers
tags:
- commonResponseHeaders
- name: Data Models
tags:
- cut_model
- header_model
- payload_model
- payloadWithOutputs_model
- peer_model
- nodeInfo_model
- page_model
- minerInfo_model
- miningUpdateEventStream_model
- name: Binary Encodings
tags:
- binaryHeader
- binaryWorkHeader