lookupBlock

POSThttps://triport.io/rpc/ton

Resolves one TON block by sequence number, logical time, or Unix time.

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

lookupBlock finds a block within a specified workchain and shard. Select the target by exactly one of block sequence number, logical time, or Unix time. The result is the complete cryptographic block ID.

Use it when a caller has a position or time but still needs root_hash and file_hash before calling getBlock or getBlockHeader. It differs from getMasterchainInfo, which returns only the current masterchain reference.

Historical resolution follows the selected liteserver's retention window. A missing old block is surfaced as a retention boundary rather than a fabricated empty result.

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.

seqnointegeroptional

Non-negative block sequence number selector.

ltstringoptional

Unsigned logical-time selector encoded as decimal text.

unixtimeintegeroptional

Non-negative Unix-time selector.

Response

Response fields

Field	Type	Description
`jsonrpc`	string	JSON-RPC protocol version.
`id`	number or string	Correlates the response with the request.
`result`	object	Full cryptographic block ID.
`result.workchain`	integer	Workchain ID.
`result.shard`	string	Signed shard ID as decimal text.
`result.seqno`	integer	Resolved block sequence number.
`result.root_hash`	string	Resolved block root hash.
`result.file_hash`	string	Resolved serialized-block file hash.

The response is copied from the accepted live fixture.

Errors

See TON errors for the shared envelope and retention handling.

Code	Meaning	When it happens
`-32602`	Invalid params	Coordinates are malformed, or zero or multiple selectors are supplied.
`beyond_retention`	Block unavailable	The selected liteserver does not retain the requested historical block.
`-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: "lookup",
    method: "lookupBlock",
    params: { workchain: -1, shard: "-9223372036854775808", seqno: 90094747 },
  }),
});
const { result: blockId } = await response.json();

Notes

Selector exclusivity is part of the method contract: send exactly one of seqno, lt, and unixtime.
Pruned servers had a measured floor of 86 860 000. Two nodes answered from genesis, but ls-17 had a measured gap, so archive routing is best-effort.
Named params and batch response correlation by id are required.
No REST gateway or WebSocket block subscription is published for TON.
Related methods: getBlock, getBlockHeader, 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": "lookupBlock",
    "params": {
      "seqno": 90094747,
      "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": "lookupBlock",
    "params": {
      "seqno": 90094747,
      "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": "lookupBlock",
        "params": {
            "seqno": 90094747,
            "shard": "-9223372036854775808",
            "workchain": -1,
        },
    },
)
data = resp.json()
print(data)

ResponseExample

JSON

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "file_hash": "ljhAYAuYhdHFu7Y6elswSJIWyA7TT2pQqJFeLxsP0CM=",
    "root_hash": "DUslab1h6OJAIomy3egBOoh+oIKdIsHrOwCAQPMYiyU=",
    "seqno": 90094747,
    "shard": "-9223372036854775808",
    "workchain": -1
  }
}