header - Cosmos

Example code for the header JSON-RPC method. Complete guide on how to use header JSON-RPC in GetBlock Web3 documentation.

Returns the block header at a specific height. Lighter alternative to block when you only need header data (chain id, height, time, hashes) without the full transaction list.

Parameters

Parameter

Type

Required

Description

height

integer

Block height (decimal). Defaults to the latest block

Request Example

# JSON-RPC over HTTP POST (canonical)
curl --location --request POST 'https://go.getblock.io/<ACCESS-TOKEN>/header' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "header",
    "params": {
        "height": 23456789
    },
    "id": "getblock.io"
}'

# URI over HTTP GET (alternate, for simple methods)
curl --location --request GET 'https://go.getblock.io/<ACCESS-TOKEN>/header?height=23456789'

import requests
import json

url = "https://go.getblock.io/<ACCESS-TOKEN>/header"

payload = json.dumps({
    "jsonrpc": "2.0",
    "method": "header",
    "params": {
        "height": 23456789
    },
    "id": "getblock.io"
})

headers = {
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
print(response.text)

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();

    let payload = json!({
        "jsonrpc": "2.0",
        "method": "header",
        "params": {
                "height": 23456789
        },
        "id": "getblock.io"
});

    let response = client
        .post("https://go.getblock.io/<ACCESS-TOKEN>/header")
        .header("Content-Type", "application/json")
        .json(&payload)
        .send()
        .await?;

    let result: serde_json::Value = response.json().await?;
    println!("{:#?}", result);

    Ok(())
}

Response Example

{
    "jsonrpc": "2.0",
    "id": "getblock.io",
    "result": {
        "header": {
            "version": {
                "block": "11",
                "app": "0"
            },
            "chain_id": "cosmoshub-4",
            "height": "23456789",
            "time": "2026-05-26T13:42:18.5273Z",
            "last_block_id": {
                "hash": "..."
            },
            "data_hash": "F8C44C8E2E4E8C0F2B7A8E6D4C2E0F1A3B5C7D9E",
            "validators_hash": "...",
            "next_validators_hash": "...",
            "consensus_hash": "...",
            "app_hash": "...",
            "proposer_address": "8E2B7A..."
        }
    }
}

Response Parameters

Field

Type

Description

result.header.chain_id

string

Chain ID

result.header.height

string

Block height

result.header.time

string

ISO 8601 block timestamp

result.header.data_hash

string

Hash of the block's transactions

result.header.app_hash

string

Hash of the application state after this block

result.header.proposer_address

string

Validator address that proposed this block

Use Cases

Lightweight chain-tip polling without fetching full block bodies
Header-only indexing in resource-constrained environments
Detecting reorgs by header chain reconciliation

Error Handling

Status Code

Error Message

Cause

404

Not Found

Missing or invalid <ACCESS-TOKEN>

-32602

Invalid params

Request parameters are missing or malformed

-32603

Internal error

Server-side error while processing the request

429

Too Many Requests

Rate limit exceeded for your plan

SDK Integration

import { Tendermint37Client, HttpClient } from '@cosmjs/tendermint-rpc';

const httpClient = new HttpClient('https://go.getblock.io/<ACCESS-TOKEN>/header');
const client = await Tendermint37Client.create(httpClient);

// CosmJS exposes typed methods on the client (e.g. client.status(), client.block()).
// For raw access to any RPC method:
const result = await httpClient.execute({"jsonrpc": "2.0", "id": "getblock.io", "method": "header", "params": {"height": 23456789}});
console.log(result);

# cosmpy wraps Cosmos REST / gRPC. For raw CometBFT RPC access, use requests.
import requests

response = requests.post('https://go.getblock.io/<ACCESS-TOKEN>/header', json={
    'jsonrpc': '2.0',
    'id': 'getblock.io',
    'method': 'header',
    'params': {"height": 23456789}
}})
print(response.json())

Previousheader_by_hash - Cosmos Nexthealth - Cosmos

Last updated 1 month ago

Was this helpful?