JSON-RPC API Reference

Complete reference for all JSON-RPC methods available on Base chain nodes, with parameters, return values, and examples for every method.

Base nodes implement the Ethereum JSON-RPC 2.0 specification. All HTTP methods accept POST requests to your RPC endpoint. WebSocket endpoints support the same methods plus real-time subscription methods.

For production use, connect through a node provider or run your own Base node. The public endpoints https://mainnet.base.org and https://sepolia.base.org are rate-limited and not suitable for production traffic.

Request & Response Format

All requests are HTTP POST with Content-Type: application/json. The body must be a JSON-RPC 2.0 request object:

Field	Type	Description
jsonrpc	string	Always "2.0"
method	string	The RPC method name
params	array	Method parameters in order
id	number | string	Identifier echoed back in the response

Success response:

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

Error response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}

Error Codes

Code	Name	Description
-32700	Parse error	Invalid JSON received by the server
-32600	Invalid request	The JSON sent is not a valid request object
-32601	Method not found	The method does not exist or is not available
-32602	Invalid params	Invalid method parameter(s)
-32603	Internal error	Internal JSON-RPC error
-32000	Server error	Node-specific error (see message for details)

Block Parameters

Methods that accept a block parameter support the following values:

Value	Description
"latest"	Most recently mined block (default when not specified)
"earliest"	Genesis block (block 0)
"pending"	Pending/preconfirmed state — use with Flashblocks endpoints
"safe"	Latest block considered safe by the consensus layer
"finalized"	Latest block considered finalized
"0x<n>"	Specific block number in hexadecimal

---

Account & State Methods

Method	Description
eth_blockNumber	Returns the most recently mined block number
eth_getBalance	Returns the ETH balance of an address
eth_getTransactionCount	Returns the transaction count (nonce) of an address
eth_getCode	Returns the bytecode at a contract address
eth_getStorageAt	Returns a raw storage slot value at a contract address
eth_call	Executes a read-only contract call without broadcasting

Block Methods

Method	Description
eth_getBlockByNumber	Returns a block by its number
eth_getBlockByHash	Returns a block by its hash
eth_getBlockReceipts	Returns all receipts for a block
eth_getBlockTransactionCountByNumber	Returns the transaction count for a block by number
eth_getBlockTransactionCountByHash	Returns the transaction count for a block by hash

Transaction Methods

Method	Description
eth_getTransactionByHash	Returns a transaction by its hash
eth_getTransactionByBlockHashAndIndex	Returns a transaction by block hash and index
eth_getTransactionByBlockNumberAndIndex	Returns a transaction by block number and index
eth_getTransactionReceipt	Returns the receipt for a mined transaction
eth_sendRawTransaction	Submits a signed transaction to the network

Gas & Fee Methods

Method	Description
eth_gasPrice	Returns the current suggested gas price
eth_maxPriorityFeePerGas	Returns the suggested EIP-1559 priority fee
eth_feeHistory	Returns historical base fees and priority fee percentiles
eth_estimateGas	Estimates gas required for a transaction

Log Methods

Method	Description
eth_getLogs	Returns logs matching a filter

Chain & Network Methods

Method	Description
eth_chainId	Returns the chain ID of the current network
eth_syncing	Returns the node’s sync status
net_version	Returns the network ID
web3_clientVersion	Returns the client software version string

Debug Methods

Debug methods require a node with debug APIs enabled. Availability and rate limits vary by node provider. These methods replay transactions and are computationally expensive — avoid calling them in hot paths.

Method	Description
debug_traceTransaction	Returns the full EVM execution trace for a transaction
debug_traceBlockByHash	Returns execution traces for all transactions in a block by hash
debug_traceBlockByNumber	Returns execution traces for all transactions in a block by number

WebSocket Methods

WebSocket methods are only available over WebSocket (WSS) connections. All HTTP methods are also available over WebSocket. Connect using your provider’s WSS endpoint and send JSON-RPC messages as UTF-8 text frames.

Method	Description
eth_subscribe	Creates a real-time subscription to on-chain events
eth_unsubscribe	Cancels an active subscription

---

Flashblocks Methods

These methods are exclusive to Flashblocks-aware endpoints (mainnet-preconf.base.org / sepolia-preconf.base.org). They provide access to preconfirmed block state and real-time Flashblock data streams — not available on standard Base endpoints.

See Flashblocks for an overview of the Flashblocks system and how to connect.

Simulation & Status

Method	Description
eth_simulateV1	Simulates transaction bundles against preconfirmed Flashblock state
base_transactionStatus	Checks whether a transaction is present in the node’s mempool

WebSocket Subscriptions

Subscription	Description
newFlashblockTransactions	Streams transactions as they are preconfirmed into Flashblocks
pendingLogs	Streams logs matching a filter as they are preconfirmed
newFlashblocks	Streams full block state updates for each new Flashblock