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.

POST /api/v2/getBlockHeader

Try it

Get block header

cURL

curl --request POST \
  --url https://toncenter.com/api/v2/getBlockHeader \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "workchain": "<string>",
  "shard": "<string>",
  "seqno": "<string>",
  "root_hash": "<string>",
  "file_hash": "<string>"
}
'

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

Body

application/json

workchain · required

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

shard · required

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

seqno · required

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

root_hash · string

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

file_hash · string

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

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.