Get block header

Returns block metadata without the full transaction list. Includes timestamps, validator info, and references to previous blocks. Intended for block explorers and other use cases that require block information without transactions.

GET /api/v2/getBlockHeader

Get block header

cURL

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

import requests

url = "https://toncenter.com/api/v2/getBlockHeader"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://toncenter.com/api/v2/getBlockHeader', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://toncenter.com/api/v2/getBlockHeader",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://toncenter.com/api/v2/getBlockHeader"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://toncenter.com/api/v2/getBlockHeader")
  .header("X-API-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://toncenter.com/api/v2/getBlockHeader")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

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>"
}

{
  "ok": false,
  "code": 401,
  "error": "API key does not exist"
}

{
  "ok": false,
  "code": 403,
  "error": "Network not allowed"
}

{
  "ok": false,
  "code": 422,
  "error": "workchain required"
}

{
  "ok": false,
  "code": 429,
  "error": "Ratelimit exceeded"
}

{
  "ok": false,
  "code": 504,
  "error": "LITE_SERVER_NETWORK timeout"
}

Authorizations

APIKeyHeaderAPIKeyQuery

X-API-Key · string · header · required

API key header of the form X-API-Key: <token>, where <token> is the API key. Requests without a key are limited to 1 RPS. Refer to the authentication guide for details.

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

Masterchain block sequence number (block height). Used to query state at a specific point in time. If omitted, returns the current state.

root_hash · string

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

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

Returns the block header with merge/split flags, validator info, and timing data.

ok · boolean · default: true · required

Returns true if the request succeeded; otherwise false. See the error field for details.

result · object · required

Response data. Present only when ok is true.

Show child attributes

@extra · string

Optional request ID that can be passed in the request and received back in the response. Useful for matching async responses.