getBlockHeader

POSThttps://triport.io/rpc/ton

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

TON mainnetton:rpcfree+; ton_read_rpc_heavy: 15 / 20 / 100 / 250 RPS (free / basic / pro / business; default, unmeasured)

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 ls-17 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.

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": "$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 requests


resp = requests.post(
    "https://triport.io/rpc/ton",
    headers={
        "x-token": "$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)

ResponseExample

JSON

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