Read the peaq Network RPC Head with Node.js
Use the Ethereum JSON-RPC eth_blockNumber method to read the latest block height reported by a peaq RPC endpoint, with validation and failure handling.
Use eth_blockNumber to read the latest block height reported by an RPC endpoint. Open the peaq network RPC page to obtain an endpoint, then set it in PEAQ_RPC_URL; this guide does not assume a particular provider URL.
Query the current head
This task checks RPC access only: it sends one JSON-RPC request and converts the hexadecimal block number into a decimal value. Save the following as peaq-head.js and run it with Node.js 18 or newer.
- Set
PEAQ_RPC_URLto an endpoint you are authorized to use. - The script uses the standard
eth_blockNumbermethod and does not require an indexing service.
const rpcUrl = process.env.PEAQ_RPC_URL;
if (!rpcUrl) {
console.error('Missing PEAQ_RPC_URL. Set it to a peaq JSON-RPC endpoint.');
process.exit(1);
}
try {
new URL(rpcUrl);
} catch {
console.error('PEAQ_RPC_URL is not a valid URL.');
process.exit(1);
}
const request = {
jsonrpc: '2.0',
id: 1,
method: 'eth_blockNumber',
params: []
};
try {
const response = await fetch(rpcUrl, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(request),
signal: AbortSignal.timeout(10000)
});
const text = await response.text();
let body;
try {
body = JSON.parse(text);
} catch {
throw new Error(`RPC returned non-JSON content (HTTP ${response.status}).`);
}
if (!response.ok) {
throw new Error(`RPC returned HTTP ${response.status}: ${text}`);
}
if (body.error) {
throw new Error(`JSON-RPC error ${body.error.code}: ${body.error.message}`);
}
if (typeof body.result !== 'string' || !/^0x[0-9a-fA-F]+$/.test(body.result)) {
throw new Error('RPC response did not contain a hexadecimal block number.');
}
console.log(JSON.stringify({
headHex: body.result,
headNumber: BigInt(body.result).toString()
}, null, 2));
} catch (error) {
console.error(`Head query failed: ${error.message}`);
process.exit(1);
}Run it with the endpoint you copied from the peaq network page: PEAQ_RPC_URL="<your-endpoint>" node peaq-head.js.
Interpret the response
A successful response contains headHex, the value returned by the RPC method, and headNumber, the same value converted from hexadecimal to decimal. The number is the head reported by that endpoint at request time; it is not a measurement of latency or a guarantee that every RPC endpoint reports the same value simultaneously.
- A result shaped like
{"headHex":"0x...","headNumber":"..."}indicates that the endpoint answered with a valid block height. - Repeat the request later if you need to observe movement, and record timestamps yourself if you want to calculate update intervals or response latency.
- Do not use this single RPC call as an indexed historical query; it only asks for the current block number.
Diagnose common failures
The script distinguishes configuration errors, network or timeout failures, HTTP failures, non-JSON responses, JSON-RPC errors, and malformed results. This keeps an unavailable endpoint from being mistaken for a valid head value.
- A timeout or connection error usually means the configured URL cannot be reached from the runtime; verify the URL, network access, and any required authentication.
- An HTTP error should be investigated with the status and response body. Do not retry indefinitely without a backoff policy.
- A JSON-RPC error means the server processed the request but rejected the method or request; inspect its returned code and message.
- If the method is unavailable, check the endpoint documentation before switching to an indexing or query API.
Know when RPC is not enough
RPC access lets an application submit protocol requests such as eth_blockNumber and retrieve data exposed by the node. Indexing and querying are separate concerns: a historical search, address activity report, decoded event dataset, or filtered pagination may require an indexer or a purpose-built query service.
- Use this head check for health checks, synchronization boundaries, or deciding which block range an application should process.
- For a broader introduction to blockchain data workflows, see OnFinality Learn.
- If you need help identifying the right RPC configuration or method, use the OnFinality RPC Assistant as the next step.