API Overview

Architecture

TheRPC speaks the JSON-RPC 2.0 specification end to end, the same wire protocol every Ethereum execution client (geth, erigon, reth, nethermind, besu) implements, so anything you already wrote against a standard node works unchanged. Four things shape the API. You reach Ethereum mainnet over a standard HTTP endpoint for ordinary calls and a WebSocket endpoint for live subscriptions. Every request authenticates with your API key in the Authorization header. Responses come back in one consistent envelope whether they succeed or fail. And the same request format carries across every chain TheRPC serves, so moving code from chain 1 to a testnet like Sepolia is a one-line endpoint swap.

Communication Protocols

The HTTP endpoint fits the bulk of what most Ethereum apps do: one-off reads like eth_getBalance, eth_call against a contract, or broadcasting a signed transaction with eth_sendRawTransaction. Each call is a single POST that returns one response, which keeps simple integrations and serverless functions easy to reason about. See the HTTP / curl guide under Tools & SDKs for copy-paste request examples.

HTTP Endpoint

https://ethereum.therpc.io/YOUR_API_KEY

The WebSocket endpoint holds a connection open so the node can push data to you instead of you polling for it. This is what you want for watching new blocks arrive each 12-second slot, streaming logs as contracts emit events, or tracking pending transactions in real time. The eth_subscribe and eth_unsubscribe methods only work over WebSocket — see the eth_subscribe reference for newHeads, logs, newPendingTransactions, and syncing examples.

WebSocket Endpoint

wss://ethereum.therpc.io/YOUR_API_KEY

JSON-RPC Format

Every call is a JSON object with four fields. jsonrpc is the protocol version and is always the string "2.0". method names the call, like eth_blockNumber or eth_getTransactionReceipt. params is an array of arguments in the order the method expects — empty for methods that take none. id is a value you pick to match the response back to its request, which matters when you batch several calls in one HTTP POST and they may come back in any order.

Request Structure

1{
2  "jsonrpc": "2.0",
3  "method": "eth_blockNumber",
4  "params": [],
5  "id": 1
6}

Response Format

Responses echo the same jsonrpc version and the id you sent, then carry exactly one of two fields. A success has result, which on Ethereum is usually a hex-encoded value — block numbers, wei balances, and gas figures all arrive as hex strings you decode client-side. A failure has error with a numeric code and a message instead. Because the shape is fixed, your client can branch on whether error is present without parsing differently per method.

Success Response

1{
2  "jsonrpc": "2.0",
3  "id": 1,
4  "result": "0x..."
5}

Error Response

1{
2  "jsonrpc": "2.0",
3  "id": 1,
4  "error": {
5    "code": -32600,
6    "message": "Invalid Request"
7  }
8}

Authentication

Every request to chain 1 needs your API key, passed as a Bearer token in the Authorization header. Unauthenticated calls are rejected before they ever reach an Ethereum node. The Authentication guide covers generating a key, storing it in environment variables, rotating it, and reading auth error responses.

Authorization Header

1Authorization: Bearer YOUR_API_KEY

Method Categories

Methods split into standard and advanced groups. The standard set covers eth_ for the core protocol (balances, blocks, transactions, EIP-1559 fees, contract calls), net_ for network status, and web3_ for utilities like Keccak-256 hashing. The advanced set is heavier: debug_ for geth-style EVM tracing, trace_ for Erigon's flat transaction traces, and txpool_ for inspecting the mempool. Advanced namespaces run against archive nodes and cost more per call. Each prefix links through to its own method pages on the All Methods index.

Error Handling

Five standard JSON-RPC error codes cover the common failures. -32700 means the JSON itself could not be parsed. -32600 means the request was well-formed JSON but not a valid JSON-RPC object. -32601 means the method name does not exist — often a typo or an advanced method your plan does not include. -32602 means the params were wrong, such as a malformed address or a missing block tag. And -32603 is an internal error on the node. The FAQ walks through retry and backoff strategies for each.

Implementation Examples

JavaScript / TypeScript — fetch, axios, ethers.js, and web3.js against the Ethereum endpoint
Python — requests and web3.py for chain 1
HTTP / curl — raw JSON-RPC requests you can run from a terminal
Tools & SDKs — the full list of language clients and libraries