Skip to main content
The RPC API enables you to query the network and get details about specific blocks or chunks.

​
Quick Reference

MethodDescriptionParameters
blockGet block details by height, hash, or finalityfinality OR block_id
block_effectsGet changes in a specific blockfinality OR block_id
chunkGet chunk details by chunk_id or block_id + shard_idchunk_id OR [block_id, shard_id]

​
Block details

Queries network and returns block for given height or hash. You can also use finality param to return latest block details.
You may choose to search by a specific block or finality, you can not choose both.
​
method
string
required
block
​
finality
string
Block finality (optimistic, near-final, or final). See finality param.
​
block_id
number | string
Block height or hash. See block_id param.

​
Query by finality

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "block",
  "params": {
    "finality": "final"
  }
}

​
Query by block height

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "block",
  "params": {
    "block_id": 187310138
  }
}

​
Query by block hash

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "block",
  "params": {
    "block_id": "6RWmTYhXCzjMjoY3Mz1rfFcnBm8E6XeDDbFEPUA4sv1w"
  }
}
For error handling information, see the RPC Errors documentation.

​
Block Effects

Returns changes in block for given block height or hash over all transactions for all the types. Includes changes like account_touched, access_key_touched, data_touched, contract_code_touched. You can also use finality param to return latest block details.
You may choose to search by a specific block or finality, you can not choose both.
​
method
string
required
block_effects
​
finality
string
Block finality. See finality param.
​
block_id
number | string
Block height or hash. See block_id param.
{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "block_effects",
  "params": {
    "finality": "final"
  }
}

​
Chunk Details

Returns details of a specific chunk. You can run a block details query to get a valid chunk hash.
​
method
string
required
chunk
​
chunk_id
string
Chunk hash
​
block_id
number | string
Block height or hash. See block_id param.
​
shard_id
number
Shard ID (required when using block_id)

​
Query by chunk_id

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "chunk",
  "params": {
    "chunk_id": "CzPafxtJmM1FnRoasKWAVhceJzZzkz9RKUBQQ4kY9V1v"
  }
}

​
Query by block_id and shard_id

{
  "jsonrpc": "2.0",
  "id": "dontcare",
  "method": "chunk",
  "params": {
    "block_id": 187310138,
    "shard_id": 0
  }
}

​
Error Handling

​
Common Error Types

Error CodeDescriptionSolution
UNKNOWN_BLOCKBlock not found or garbage-collectedCheck block validity; use archival node for old blocks
UNKNOWN_CHUNKChunk not found in databaseVerify chunk ID; use archival node for old chunks
INVALID_SHARD_IDShard ID does not existProvide valid shard ID for existing shard
NOT_SYNCED_YETNode still syncingWait for sync completion or use different node
PARSE_ERRORInvalid request parametersCheck parameter format and completeness
INTERNAL_ERRORServer-side issueRetry request or try different RPC endpoint

​
Response Validation

  • Block responses: Always include block_hash, block_height, and header fields
  • Chunk responses: Contain author, header, receipts, and transactions arrays
  • Changes responses: Include block_hash and block_effects array with change details

​
Best Practices

  • Cache block data: Block information is immutable once finalized, ideal for caching
  • Use archival nodes for old data: Blocks older than 5 epochs require archival nodes
  • Validate shard IDs: Ensure shard IDs are within the network’s shard range

Build docs developers (and LLMs) love

Get started for freeTalk to us