Ethereum Blockchain API: JSON-RPC Methods, WebSocket & Examples

How the Ethereum Blockchain API Works

The Ethereum blockchain API is the JSON-RPC interface exposed by Ethereum execution clients. Every request is a JSON object with jsonrpc, method, params, and id fields. Responses return either a result or an error object.

The API is transport-agnostic, but most providers offer HTTPS for standard calls and WebSocket for subscriptions. OnFinality documents both transports and current plan-dependent limits on the /networks/eth page.

• Mainnet chain ID: 1; Sepolia chain ID: 11155111. Never mix them when signing transactions.
• Execution-layer JSON-RPC (eth_*) is separate from the Beacon consensus API, which serves validator and slot data via REST.
• For testnet access, see the Sepolia guide at /rpc-assistant/sepolia-eth-rpc.

Core JSON-RPC Methods: eth_call, eth_getLogs, eth_sendRawTransaction, Receipts, and Gas Estimation

These methods cover most dApp workflows. Use eth_call to simulate a transaction without changing state; eth_getLogs to query event logs; eth_sendRawTransaction to broadcast a signed transaction; eth_getTransactionReceipt to confirm status and retrieve logs; and eth_estimateGas to plan gas before sending.

Always sign transactions locally before calling eth_sendRawTransaction. Never send a private key to an RPC endpoint.

• eth_call: executes a read-only contract call at a specific block number or latest.
• eth_getLogs: returns logs matching an address and optional topic filter, often used with block range pagination.
• eth_sendRawTransaction: submits a raw, signed transaction; returns a transaction hash immediately.
• eth_getTransactionReceipt: returns status (0x1 success), cumulative gas used, logs, and contract address after mining.
• eth_estimateGas: returns an estimate, not a guarantee; add a buffer for complex interactions.

HTTP vs WebSocket: Choosing the Right Transport

HTTP is ideal for one-off reads and writes. Each request gets a single response and the connection can be reused. WebSocket maintains a persistent connection and pushes notifications, making it the right choice for real-time features.

• Use HTTPS for user-initiated actions, balance checks, transaction submission, and batch requests.
• Use WebSocket for eth_subscribe streams such as new block headers, filtered logs, and pending transactions.
• Many production systems combine both: HTTP for user requests and WebSocket for background indexing or monitoring.
• WebSocket connections require reconnect and resubscription logic; do not assume they stay open indefinitely.

WebSocket Subscription Workflows

WebSocket subscriptions use JSON-RPC eth_subscribe with a subscription name and optional filter. The server returns a subscription ID, then pushes eth_subscription notifications as events arrive.

Example subscription to new heads: ``json {"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]} ``

For logs, include an address and topics filter in params. For pending transactions, use newPendingTransactions, but note that mempool visibility depends on node configuration.

• Handle reconnection by re-subscribing after a dropped WebSocket.
• Use a unique id per request to match responses and notifications.
• WebSocket availability and rate limits are plan-dependent; verify on /networks/eth.

Trace and Debug API Entry Points

Trace (trace_*) and Debug (debug_*) APIs are optional, often provider-specific entry points. They are not part of the core Ethereum JSON-RPC methods and may require archive nodes or special permissions. Do not confuse them with standard eth_* methods or with the Beacon consensus API.

Use Trace/Debug for internal transaction inspection, call tracing, state diffs, and storage analysis. Common methods include trace_transaction, trace_replayTransaction, debug_traceTransaction, and debug_traceCall.

• Trace namespace is typically Parity/OpenEthereum style; Debug is Geth style. Availability varies.
• These methods can be expensive and heavily rate-limited. Check current plan details and archive support on /networks/eth.
• For most dApps, core methods like eth_call and eth_getTransactionReceipt are sufficient; add Trace/Debug only for analytics or debugging.

Minimal curl and JavaScript Examples

The following examples use placeholder endpoints. Replace YOUR_ETHEREUM_ENDPOINT with the HTTPS or WSS URL from the OnFinality network page.

curl to get the latest block number: ```bash curl -X POST https://YOUR_ETHEREUM_ENDPOINT \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' ```

JavaScript with ethers.js to read a contract symbol and latest block: ``javascript import { ethers } from "ethers"; const provider = new ethers.JsonRpcProvider("https://YOUR_ETHEREUM_ENDPOINT"); const blockNumber = await provider.getBlockNumber(); console.log("Latest block:", blockNumber); const contract = new ethers.Contract( "0x0000000000000000000000000000000000000000", // replace with contract address ["function symbol() view returns (string)"], provider ); const symbol = await contract.symbol(); console.log("Symbol:", symbol); ``

Always keep private keys in a secure signer, never in the RPC request.

Production Integration Checklist

For additional provider evaluation criteria, see /rpc-assistant/leading-ethereum-rpc-solutions-guide.

Next steps: Ethereum RPC Providers.

Frequently Asked Questions