getBlockHeader — TON JSON-RPC

Status: Available

Returns block metadata and proof material without fetching the block body.

TON RPC node endpoint · Best TON RPC providers compared

POSThttps://triport.io/rpc/ton

Network: TON mainnet
Scope: ton:rpc
Auth: x-token: $TRIPORT_API_KEY
Rate limit: free+; ton_read_rpc_heavy: 15 / 20 / 100 / 250 RPS sustained · short burst 30 / 40 / 200 / 500 (free / basic / pro / business; default, unmeasured); Burst capacity

Request

cURLJavaScriptPython

curl https://triport.io/rpc/ton \
  -H "x-token: $TRIPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getBlockHeader",
    "params": {
      "file_hash": "f4s603388wwG3M7/vozPM0+udP9hT8Mfve2o/Q7/NsI=",
      "root_hash": "U8NZycgekJt9e0jZWlsjf1vuKKZbbZYEe3zkVh19a8w=",
      "seqno": 90110366,
      "shard": "-9223372036854775808",
      "workchain": -1
    }
  }'

const res = await fetch("https://triport.io/rpc/ton", {
  method: "POST",
  headers: {
    "x-token": process.env.TRIPORT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getBlockHeader",
    "params": {
      "file_hash": "f4s603388wwG3M7/vozPM0+udP9hT8Mfve2o/Q7/NsI=",
      "root_hash": "U8NZycgekJt9e0jZWlsjf1vuKKZbbZYEe3zkVh19a8w=",
      "seqno": 90110366,
      "shard": "-9223372036854775808",
      "workchain": -1
    }
  }),
});
const data = await res.json();
console.log(data);

import os


import requests


resp = requests.post(
    "https://triport.io/rpc/ton",
    headers={
        "x-token": os.environ["TRIPORT_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "getBlockHeader",
        "params": {
            "file_hash": "f4s603388wwG3M7/vozPM0+udP9hT8Mfve2o/Q7/NsI=",
            "root_hash": "U8NZycgekJt9e0jZWlsjf1vuKKZbbZYEe3zkVh19a8w=",
            "seqno": 90110366,
            "shard": "-9223372036854775808",
            "workchain": -1,
        },
    },
)
data = resp.json()
print(data)

Response

JSON

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": {
      "file_hash": "f4s603388wwG3M7/vozPM0+udP9hT8Mfve2o/Q7/NsI=",
      "root_hash": "U8NZycgekJt9e0jZWlsjf1vuKKZbbZYEe3zkVh19a8w=",
      "seqno": 90110366,
      "shard": "-9223372036854775808",
      "workchain": -1
    },
    "proof": "te6ccgEBAQEAAgAAAA=="
  }
}

Liteserver call over ADNL: liteServer.getBlockHeader. See lite_api.tl (checked 2026-10-25).

getBlockHeader reads metadata and proof material for a specific block. The block is addressed by workchain, shard, and sequence number, with optional root and file hashes when the caller already has a full cryptographic block ID.

Use this method to verify or inspect a block reference without transferring the serialized body returned by getBlock. If only a partial position or time is known, resolve the full ID with lookupBlock first.

Like other historical block reads, this call is limited by the selected liteserver's measured retention window. An old block that is outside that window produces a retention error rather than an empty object.

Parameters

JSON-RPC params is a by-name object.

Params: object (by-name).

workchainintegerrequired

Signed 32-bit workchain ID.

shardstringrequired

Signed 64-bit shard ID encoded as decimal text.

seqnointegerrequired

Non-negative block sequence number.

root_hashstringoptional

Optional root hash accepted as base64, base64url, or hexadecimal text.

file_hashstringoptional

Optional file hash accepted as base64, base64url, or hexadecimal text.

Response

Response fields

Field	Type	Description
`jsonrpc`	string	JSON-RPC protocol version.
`id`	number or string	Correlates the response with the request.
`result`	object	Header and proof result.
`result.id`	object	Full block ID.
`result.id.workchain`	integer	Workchain ID.
`result.id.shard`	string	Signed shard ID as decimal text.
`result.id.seqno`	integer	Block sequence number.
`result.id.root_hash`	string	Block root hash.
`result.id.file_hash`	string	Serialized block file hash.
`result.proof`	string	Proof material returned by the liteserver.

The JSON is copied from the accepted live fixture. The fixture sanitizer replaces proof bytes, so the displayed proof value is evidence of the response shape only.

Errors

See TON errors for the shared envelope and retention handling.

Code	Meaning	When it happens
`-32602`	Invalid params	Required coordinates are missing, a coordinate is malformed, or `params` is positional.
`beyond_retention`	Header unavailable	The requested block falls below the selected liteserver's retained window.
`-32601`	Method not found	The method is outside the published read-only catalog.
`401`	Unauthorized	The API key is missing or invalid.
`429`	Rate limited	The `ton_read_rpc_heavy` budget is exceeded.

Examples

JavaScript

const response = await fetch("https://triport.io/rpc/ton", {
  method: "POST",
  headers: { "x-token": process.env.TRIPORT_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "header",
    method: "getBlockHeader",
    params: { workchain: -1, shard: "-9223372036854775808", seqno: 90110366 },
  }),
});
const { result } = await response.json();

Notes

The response may contain implementation-defined metadata in addition to the schema's required id field.
Pruned liteservers had a measured floor of 86 860 000. Two nodes answered from genesis, but one measured server had a measured gap, so continuity is not universal.
TON has no published REST gateway or WebSocket header subscription here.
Related methods: getBlock, lookupBlock, and getMasterchainInfo.
TON RPC endpoint and plans.