Reading Blockchain Data With JSON-RPC

Every Ethereum-compatible blockchain exposes a JSON-RPC interface. Wallets, block explorers and dApps all use it to read balances, fetch transactions and send new ones. Many developers only interact with it through libraries, but understanding the raw requests makes debugging easier and lets you build lightweight tools without heavy dependencies.

The request format

JSON-RPC requests are simple HTTP POST requests with a JSON body:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_blockNumber",
  "params": []
}

The response includes the same id and either a result or an error:

{ "jsonrpc": "2.0", "id": 1, "result": "0x1a2b3c" }

You can send this with any HTTP client, including fetch in a browser or a serverless function.

Hex everywhere

JSON-RPC uses hexadecimal strings for numbers. Block numbers, balances, gas values and log indexes all arrive as strings starting with 0x. Convert them carefully:

• Use parseInt with base 16 for small values such as block numbers
• Use BigInt for token amounts and balances, which can exceed safe integer limits
• Send numbers back to the node as hex strings too

A common bug is converting a large token balance with parseInt and silently losing precision. BigInt avoids that.

Common read methods

Method	What it returns
eth_blockNumber	The latest block number
eth_getBalance	Native balance of an address
eth_call	Result of calling a contract function without sending a transaction
eth_getTransactionByHash	Transaction details
eth_getTransactionReceipt	Status, gas used and emitted logs
eth_getLogs	Event logs matching a filter
eth_getCode	Contract bytecode, or 0x for regular wallets
eth_chainId	The network's chain ID

These cover most read-only needs, from showing balances to detecting payments.

Calling contract functions

To read data from a contract, such as a token balance, you use eth_call with encoded call data. The first four bytes identify the function, followed by encoded arguments. For example, the balanceOf function on standard tokens takes an address padded to 32 bytes.

For simple calls, you can encode data by hand. For complex functions, use an encoding library. Either way, the node executes the function locally and returns the result without creating a transaction.

Receipts and status

A transaction hash alone does not tell you whether a transaction succeeded. Fetch the receipt:

• A status of 0x1 means success
• A status of 0x0 means the transaction reverted
• A null receipt means the transaction is not yet mined, or the hash is unknown

Receipts also contain logs, which record events such as token transfers.

Handling errors and limits

Nodes return errors in a structured format. Common issues include:

1. Rate limits on public endpoints
2. Block range limits for log queries
3. Missing historical data on non-archive nodes
4. Temporary network failures

Design your code to retry with backoff, fall back to a second provider and query logs in chunks. Always check both the HTTP status and the error field in the JSON response.

Batch requests

Many providers support batching several requests in a single HTTP call by sending an array of request objects. Batching reduces latency when you need multiple reads at once. Check your provider's limits, since some restrict batch size.

Security notes

Read-only RPC calls are safe to make from browsers, but avoid embedding private API keys for paid providers in frontend code. Proxy requests through your backend if you use keyed endpoints. Never send private keys to an RPC provider. Signing should happen in the wallet.

Putting it into practice

A small serverless function using only eth_blockNumber, eth_getLogs and eth_getTransactionReceipt can detect stablecoin payments reliably. That is exactly how Proud Globe confirms tile orders without a payment processor: plain JSON-RPC calls to public endpoints, with fallbacks and chunked log queries.