What is JSON-RPC? A Developer’s Guide (2026)
Every Web3 application uses JSON-RPC. Most developers just don’t realize it.
When MetaMask checks your ETH balance, it sends a JSON-RPC request. When ethers.js reads a smart contract, it’s JSON-RPC. When a DeFi protocol monitors collateral ratios in real time, every single read is a JSON-RPC call hitting a blockchain node. JSON-RPC is the communication layer that makes blockchain development possible.
Yet most articles explaining JSON-RPC treat it as a generic network protocol. They miss the point. For Web3 developers, JSON-RPC is not one option among many. It is the standard. Ethereum, Solana, Polygon, Arbitrum, Base, BNB Chain: all of them expose their state through JSON-RPC, and every application that reads or writes to these chains goes through it.
This guide explains JSON-RPC from first principles, with real blockchain code examples, common methods, error handling, and what a JSON-RPC provider actually does.
What is JSON-RPC?
JSON-RPC is a lightweight, stateless remote procedure call protocol that uses JSON as its message format. It defines a standard way for a client to call a function on a remote server and receive a response, all encoded in plain JSON.
Breaking that down:
- Remote Procedure Call (RPC): your program calls a function that runs on a different machine, as if it were a local function call
- JSON: the data is serialized as JSON, not binary (like gRPC) or XML (like older protocols)
- Stateless: each request is independent. The server holds no session state between calls.
The current version is JSON-RPC 2.0, published in 2010. All major blockchain networks use 2.0. You can identify it by the "jsonrpc": "2.0" field in every request.
A JSON-RPC request has four fields:
{
"jsonrpc": "2.0",
"method": "eth_blockNumber",
"params": [],
"id": 1
}jsonrpc: always “2.0”method: the name of the function to call on the serverparams: an array of arguments passed to the functionid: a client-defined identifier so you can match responses to requests (useful for batching)
A JSON-RPC response has three fields:
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x13a5b2c"
}That’s the entire protocol. One request format. One response format. Simple by design, and that simplicity is why it became the universal standard for blockchain communication.
How JSON-RPC Works
A JSON-RPC call follows the same sequence every time:
1. The client builds a request object Your application (dApp, bot, wallet) constructs a JSON object with the method name and parameters.
2. The client sends it over HTTP or WebSocket JSON-RPC runs over standard transport protocols. HTTP for one-off requests. WebSocket for subscriptions and real-time data.
3. The server receives and routes the request
The server reads the method field and calls the corresponding function internally.
4. The server sends back the result
The response contains either a result field (success) or an error field (failure). Never both.
5. The client reads the response
Your application reads response.result and continues.
Here is a full request/response cycle: checking an Ethereum wallet balance.
// Request
{
"jsonrpc": "2.0",
"method": "eth_getBalance",
"params": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "latest"],
"id": 1
}// Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x1BC16D674EC80000"
}The result is a hex-encoded value in wei. 0x1BC16D674EC80000 = 2 ETH. Your frontend converts it to a human-readable number.
Same request in curl, so you can test it directly:
curl https://eu.endpoints.matrixed.link/rpc/ethereum?auth=YOUR_KEY \
-X POST \
-H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"method": "eth_getBalance",
"params": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "latest"],
"id": 1
}'JSON-RPC in Blockchain
JSON-RPC became the standard for blockchain communication because blockchain operations are actions, not resources.
REST is built around resources: GET /accounts/{address}, POST /transactions. That mental model fits web applications. It does not fit blockchain, where you need to call specific functions like eth_sendRawTransaction, eth_call, or eth_getLogs. These are procedures, not resources. JSON-RPC maps to them naturally.
Every major blockchain adopted JSON-RPC as its node interface:
EVM chains (Ethereum, Polygon, Arbitrum, Base, BNB Chain, Avalanche, Optimism) all implement the same Ethereum JSON-RPC specification. A method that works on Ethereum works identically on every EVM chain. This is by design.
Solana uses JSON-RPC with its own method names (getBalance, getLatestBlockhash, sendTransaction). Different methods, same protocol structure.
The result: any library that speaks JSON-RPC works across every major chain. ethers.js, web3.js, viem, wagmi: they all send JSON-RPC requests under the hood. You write provider.getBalance(address) and the library constructs the JSON-RPC request for you.
The protocol is predictable, standardized, and battle-tested at scale. It is what production infrastructure is built on.
Common Ethereum JSON-RPC Methods
These are the methods you will use most in production. All examples follow the same request/response structure.
eth_blockNumber
Returns the latest block number.
// Request
{
"jsonrpc": "2.0",
"method": "eth_blockNumber",
"params": [],
"id": 1
}
// Response
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x13a5b2c"
}Convert hex to decimal: 0x13a5b2c = block 20,528,940.
eth_getBalance
Returns the ETH balance of an address at a given block.
// Request
{
"jsonrpc": "2.0",
"method": "eth_getBalance",
"params": ["0xAddress", "latest"],
"id": 1
}Second param options: "latest" (current), "earliest" (block 0), or a specific block number in hex.
eth_call
Executes a read-only smart contract function without broadcasting a transaction. Used for reading state from contracts. This is what every DeFi protocol uses to check prices, balances, and collateral ratios.
{
"jsonrpc": "2.0",
"method": "eth_call",
"params": [{
"to": "0xContractAddress",
"data": "0x70a08231000000000000000000000000YourAddress"
}, "latest"],
"id": 1
}eth_sendRawTransaction
Broadcasts a signed transaction to the network.
{
"jsonrpc": "2.0",
"method": "eth_sendRawTransaction",
"params": ["0xSignedTransactionHex"],
"id": 1
}This is the only write operation in the list. Everything else above is a read.
eth_getLogs
Returns event logs matching a filter. Used heavily by indexers, DeFi protocols, analytics platforms.
{
"jsonrpc": "2.0",
"method": "eth_getLogs",
"params": [{
"fromBlock": "0x13A0000",
"toBlock": "latest",
"address": "0xContractAddress",
"topics": ["0xEventSignatureHash"]
}],
"id": 1
}eth_getTransactionReceipt
Returns the receipt of a transaction after it has been mined. Used to confirm a transaction succeeded and to read its emitted events.
{
"jsonrpc": "2.0",
"method": "eth_getTransactionReceipt",
"params": ["0xTransactionHash"],
"id": 1
}What is a JSON-RPC Provider?
A JSON-RPC provider is a service that runs blockchain nodes and exposes them via the JSON-RPC protocol. Your application sends JSON-RPC requests to the provider’s endpoint, the provider’s node processes them against the blockchain, and the response comes back.
The flow looks like this:
Your app → JSON-RPC request → Provider endpoint → Blockchain node → ResultWhy not run your own node?
Running a production Ethereum archive node costs between $3,000 and $10,000 per month in infrastructure. It requires a dedicated team to maintain, monitor, and update. It takes days to sync from scratch. If it goes down, your application goes down.
A JSON-RPC provider handles all of that. You get an endpoint URL, append your API key, and your application works immediately.
// Connect to Ethereum via BoltRPC in ethers.js
import { ethers } from "ethers";
const provider = new ethers.JsonRpcProvider(
"https://eu.endpoints.matrixed.link/rpc/ethereum?auth=YOUR_KEY"
);
const balance = await provider.getBalance("0xYourAddress");
console.log(ethers.formatEther(balance));// Same with viem
import { createPublicClient, http } from "viem";
import { mainnet } from "viem/chains";
const client = createPublicClient({
chain: mainnet,
transport: http("https://eu.endpoints.matrixed.link/rpc/ethereum?auth=YOUR_KEY"),
});
const balance = await client.getBalance({ address: "0xYourAddress" });BoltRPC processes 2 billion JSON-RPC requests daily across all supported networks, trusted by Chainlink, Gains Network, Enjin, Tiingo.
Supported networks: boltrpc.io/networks
JSON-RPC vs REST: The Key Difference
REST and JSON-RPC are both ways to communicate over HTTP. The difference is the mental model.
| JSON-RPC | REST | |
|---|---|---|
| Model | Call a function by name | Interact with a resource |
| HTTP method | Always POST | GET, POST, PUT, DELETE |
| Endpoint | Single endpoint (/) | One endpoint per resource |
| Operation | Defined by method field | Defined by HTTP verb + URL |
| Blockchain standard | Yes | No |
In REST, you’d read a balance with GET /accounts/{address}/balance. In JSON-RPC, you call eth_getBalance. The blockchain operation is a function call, not a resource read. JSON-RPC fits.
There is no REST interface for Ethereum. If you are building on any major blockchain, you are using JSON-RPC whether you know it or not. ethers.js, web3.js, viem all abstract it away, but they’re all sending JSON-RPC requests underneath.
JSON-RPC Errors: How to Read and Fix Them
JSON-RPC 2.0 defines standard error codes. When a request fails, the response contains an error object instead of result:
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32601,
"message": "Method not found"
}
}Standard error codes
| Code | Name | Cause | Fix |
|---|---|---|---|
| -32700 | Parse error | Malformed JSON in request | Validate your JSON syntax |
| -32600 | Invalid request | Missing required fields (jsonrpc, method, id) | Check request structure |
| -32601 | Method not found | Typo in method name | Check exact method spelling |
| -32602 | Invalid params | Wrong parameter type or count | Check method documentation |
| -32603 | Internal error | Node-side error | Retry, or check node status |
Common blockchain-specific errors
“execution reverted” The smart contract rejected the transaction. Causes: insufficient balance, invalid state, failed require() check. Read the revert reason in the error data field.
MetaMask “Internal JSON-RPC error” Almost always one of: wrong network selected, insufficient gas, or a reverted transaction. Check which network MetaMask is connected to and verify the transaction parameters.
“insufficient funds for gas” The wallet does not have enough ETH to cover the gas cost. Separate from the transaction value.
“nonce too low” A transaction with this nonce was already submitted. Increment the nonce.
Rate limit error (not a standard JSON-RPC code) Your provider is returning 429 or a custom error message. You have exceeded the request rate of your plan.
FAQ: JSON-RPC
What is the difference between JSON-RPC and JSON?
JSON is a data format for encoding structured data as text. JSON-RPC is a protocol that uses JSON to define how remote function calls are structured. JSON is the format; JSON-RPC is the communication standard built on top of it.
What is a JSON-RPC provider?
A JSON-RPC provider is a service that runs blockchain nodes and exposes them via the JSON-RPC protocol. Your application sends requests to the provider’s endpoint instead of running its own node. BoltRPC is a JSON-RPC provider for Ethereum, Solana, and 17 other networks.
What is the difference between JSON-RPC and REST?
REST organizes communication around resources and HTTP verbs (GET, POST, PUT). JSON-RPC organizes it around function calls using a single POST endpoint with a method field. Blockchain uses JSON-RPC because blockchain operations are function calls, not resource operations.
What is RPC in simple terms?
RPC (Remote Procedure Call) lets your program call a function that runs on a different computer and get the result back, as if the function ran locally. JSON-RPC is RPC that uses JSON to format the request and response.
Is JSON-RPC the same as REST?
No. They are two different communication patterns. REST uses HTTP verbs and resource URLs. JSON-RPC always uses POST with a JSON body containing the method name. All major blockchain networks use JSON-RPC, not REST.
How do I fix a JSON-RPC error?
Read the error code in the response. -32601 means wrong method name. -32602 means wrong parameters. -32603 is a node error. For blockchain-specific errors like “execution reverted”, read the revert reason in the error data field. For MetaMask errors, check network selection and gas settings first.
Conclusion
JSON-RPC is not just a protocol choice. For blockchain development, it is the only standard that exists. Every EVM chain, every wallet, every library: all of it runs over JSON-RPC.
Understanding the request structure, common methods, and error codes makes you a faster debugger and a better blockchain developer. When something breaks in your dApp, the problem is almost always in a JSON-RPC request or response. Knowing how to read both saves hours.
For teams building production applications on Ethereum, Solana, or any supported chain, BoltRPC provides JSON-RPC infrastructure handling 2 billion requests daily, trusted by Chainlink, Gains Network, Enjin, Tiingo.
Start your free 2-week trial, no credit card required: trial.boltrpc.io