Get block header

Returns block metadata without the full transaction list. Includes timestamps, validator info, and references to previous blocks. Use this for block explorers or when you need block info but not the transactions inside.

GET /api/v2/getBlockHeader

Try it

Get block header

cURL

curl --request GET \
  --url https://toncenter.com/api/v2/getBlockHeader \
  --header 'X-API-Key: <api-key>'

200

{
  "ok": true,
  "result": {
    "@type": "blocks.header",
    "id": {
      "@type": "ton.blockIdExt",
      "workchain": 123,
      "shard": "<string>",
      "seqno": 123,
      "root_hash": "<string>",
      "file_hash": "<string>"
    },
    "global_id": 123,
    "version": 123,
    "after_merge": true,
    "after_split": true,
    "before_split": true,
    "want_merge": true,
    "want_split": true,
    "validator_list_hash_short": 123,
    "catchain_seqno": 123,
    "min_ref_mc_seqno": 123,
    "is_key_block": true,
    "prev_key_block_seqno": 123,
    "start_lt": "<string>",
    "end_lt": "<string>",
    "gen_utime": 123,
    "prev_blocks": [
      {
        "@type": "ton.blockIdExt",
        "workchain": 123,
        "shard": "<string>",
        "seqno": 123,
        "root_hash": "<string>",
        "file_hash": "<string>"
      }
    ]
  },
  "@extra": "<string>"
}

Authorizations

X-API-Key · string · header · required

Query Parameters

workchain · integer<int32> · required

The workchain to query. Use -1 for masterchain (validators, system contracts, config) or 0 for basechain (regular accounts and contracts). Most user transactions happen on workchain 0.

shard · string · required

The shard identifier. Masterchain always uses -9223372036854775808. For basechain, shards split and merge dynamically. Use the shards endpoint to discover current shard configuration.

seqno · integer<int32> · required

The block sequence number. Each shard numbers its blocks starting from 0. For masterchain, this is also called the block height. Higher numbers are more recent blocks.

root_hash · string

The block's root hash for verification. Together with file_hash, this uniquely and cryptographically identifies a block. Only needed when you require proof of block identity.

file_hash · string

The block's file hash for verification. Together with root_hash, this provides cryptographic proof of block identity. Only needed for trustless verification.

Response

200

application/json

OK

Response containing block header information.

ok · boolean · default: true · required

Indicates if the request succeeded. If false, check the error field for details.

result · object · required

The response data. Only present when ok is true.

Show child attributes

result. @type · enum<string> · default: blocks.header · required

Object type identifier.

Available options: blocks.header

result. id · object · required

Request ID. Pass any string and it will be echoed in the response.

Show child attributes

result.id. @type · enum<string> · default: ton.blockIdExt · required

Object type identifier.

Available options: ton.blockIdExt

result.id. workchain · integer · required

Workchain ID: -1 for masterchain, 0 for basechain. Most user transactions are on workchain 0.

result.id. shard · string · required

Shard identifier. A signed 64-bit integer. Masterchain uses -9223372036854775808.

result.id. seqno · integer · required

Block or wallet sequence number. For blocks, this is the block height. For wallets, increment this for each outgoing transaction.

result.id. root_hash · string · required

Merkle root hash of the block state tree. Used for cryptographic verification.

result.id. file_hash · string · required

Hash of the serialized block data. Together with root_hash, uniquely identifies a block.

result. global_id · integer · required

Global network identifier.

result. version · integer · required

Block format version.

result. after_merge · boolean · required

True if block was created after a merge.

result. after_split · boolean · required

True if block was created after a split.

result. before_split · boolean · required

True if block was created before a split.

result. want_merge · boolean · required

Indicates if validators wanted a merge.

result. want_split · boolean · required

Indicates if validators wanted a split.

result. validator_list_hash_short · integer · required

Short hash of validator list.

result. catchain_seqno · integer · required

Catchain sequence number.

result. min_ref_mc_seqno · integer · required

Minimum referenced masterchain seqno.

result. is_key_block · boolean · required

True if this block is a key block.

result. prev_key_block_seqno · integer · required

Previous key block sequence number.

result. start_lt · string · required

Starting logical time.

result. end_lt · string · required

Ending logical time.

result. gen_utime · integer · required

Block generation UNIX timestamp.

result. prev_blocks · object[] · required

List of previous block identifiers.

Show child attributes

result.prev_blocks. @type · enum<string> · default: ton.blockIdExt · required

Object type identifier.

Available options: ton.blockIdExt

result.prev_blocks. workchain · integer · required

Workchain ID: -1 for masterchain, 0 for basechain. Most user transactions are on workchain 0.

result.prev_blocks. shard · string · required

Shard identifier. A signed 64-bit integer. Masterchain uses -9223372036854775808.

result.prev_blocks. seqno · integer · required

Block or wallet sequence number. For blocks, this is the block height. For wallets, increment this for each outgoing transaction.

result.prev_blocks. root_hash · string · required

Merkle root hash of the block state tree. Used for cryptographic verification.

result.prev_blocks. file_hash · string · required

Hash of the serialized block data. Together with root_hash, uniquely identifies a block.

@extra · string

Optional request ID that you can pass in the request and receive back in the response. Useful for matching async responses.