JSON-RPC API Reference - Base Documentation

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

eth_blockNumber

Returns the number of the most recently mined block. Parameters This method takes no parameters. Returns

result

string

The current block number as a hexadecimal string.

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

eth_getBalance

Returns the ETH balance of a given address at a specified block. Parameters

address

string

required

The 20-byte address to check the balance for.

blockParameter

string

required

Block number in hexadecimal, or a block tag: latest, earliest, pending, safe, or finalized.

Returns

result

string

The account balance in wei as a hexadecimal string.

{
  "jsonrpc": "2.0",
  "method": "eth_getBalance",
  "params": [
    "0x4200000000000000000000000000000000000006",
    "latest"
  ],
  "id": 1
}

eth_getTransactionCount

Returns the number of transactions sent from an address — also known as the account nonce. Use the pending block parameter to include transactions that are in the mempool but not yet mined. Parameters

address

string

required

The 20-byte account address.

blockParameter

string

required

Block number in hexadecimal, or a block tag: latest, earliest, pending, safe, or finalized.

Returns

result

string

The number of transactions sent from the address as a hexadecimal integer.

{
  "jsonrpc": "2.0",
  "method": "eth_getTransactionCount",
  "params": [
    "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
    "latest"
  ],
  "id": 1
}

eth_getCode

Returns the compiled bytecode stored at a given contract address. Returns "0x" for externally owned accounts (EOAs). Parameters

address

string

required

The 20-byte address (typically a smart contract).

blockParameter

string

required

Block number in hexadecimal, or a block tag: latest, earliest, pending, safe, or finalized.

Returns

result

string

The bytecode at the address as a hex string. Returns "0x" if there is no code (EOA or self-destructed contract).

{
  "jsonrpc": "2.0",
  "method": "eth_getCode",
  "params": [
    "0x4200000000000000000000000000000000000006",
    "latest"
  ],
  "id": 1
}

eth_getStorageAt

Returns the raw value stored at a specific storage slot of a contract address. Parameters

address

string

required

The 20-byte contract address.

storagePosition

string

required

The hex-encoded integer position of the storage slot (e.g., "0x0" for slot 0).

blockParameter

string

required

Block number in hexadecimal, or a block tag: latest, earliest, pending, safe, or finalized.

Returns

result

string

The 32-byte value stored at the given storage position as a hex string.

{
  "jsonrpc": "2.0",
  "method": "eth_getStorageAt",
  "params": [
    "0x4200000000000000000000000000000000000006",
    "0x0",
    "latest"
  ],
  "id": 1
}

eth_call

Executes a message call against the current chain state without broadcasting a transaction. No gas is consumed on-chain. Used to read contract state or simulate calls. Parameters

transactionObject

object

required

The transaction call object.

Show Transaction object fields

from

string

The 20-byte address the call is sent from. Optional; defaults to the zero address.

string

The 20-byte address of the contract to call.

gas

string

Hex-encoded integer of gas to provide for the call. Defaults to a high limit if omitted.

gasPrice

string

Hex-encoded gas price in wei. For legacy transactions. Optional.

maxFeePerGas

string

EIP-1559 maximum total fee per gas. Optional.

maxPriorityFeePerGas

string

EIP-1559 maximum priority fee per gas. Optional.

value

string

Hex-encoded ETH value to send with the call in wei. Optional.

data

string

ABI-encoded call data: the 4-byte function selector followed by encoded arguments. Optional.

blockParameter

string

required

Block number in hexadecimal, or a block tag: latest, earliest, pending, safe, or finalized.

Returns

result

string

The return value of the executed contract call as a hex-encoded byte array.

{
  "jsonrpc": "2.0",
  "method": "eth_call",
  "params": [
    {
      "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "data": "0x70a082310000000000000000000000004200000000000000000000000000000000000006"
    },
    "latest"
  ],
  "id": 1
}

Code	Message	Description
`-32000`	execution reverted	The call reverted. The `data` field in the error object contains the ABI-encoded revert reason when available.

Block Methods

eth_getBlockByNumber

Returns information about a block by its block number. Parameters

blockParameter

string

required

Block number in hexadecimal, or a block tag: latest, earliest, pending, safe, or finalized.

fullTransactions

boolean

required

If true, returns full transaction objects in the transactions array. If false, returns only transaction hashes.

Returns

result

object | null

A block object, or null if no block was found.

Show Block object fields

number

string

Block number as a hex string. null when the block is pending.

hash

string

32-byte hash of the block. null when the block is pending.

parentHash

string

32-byte hash of the parent block.

nonce

string

8-byte proof-of-work nonce. Always "0x0000000000000000" on Base (proof-of-stake).

sha3Uncles

string

32-byte SHA3 hash of the uncles data in the block. Always the empty-uncle-list hash on Base.

logsBloom

string

256-byte bloom filter for the logs of the block.

transactionsRoot

string

32-byte root of the transaction trie.

stateRoot

string

32-byte root of the final state trie.

receiptsRoot

string

32-byte root of the receipts trie.

miner

string

20-byte address of the fee recipient (block proposer on Base).

difficulty

string

Block difficulty. Always "0x0" on Base (proof-of-stake).

totalDifficulty

string

Total chain difficulty. Always "0x0" on Base (proof-of-stake).

extraData

string

Hex-encoded extra data field of the block.

size

string

Integer size of the block in bytes as a hexadecimal.

gasLimit

string

Maximum gas allowed in this block.

gasUsed

string

Total gas used by all transactions in this block.

timestamp

string

Unix timestamp of when the block was collated.

transactions

array

Array of transaction hashes (when fullTransactions is false) or full transaction objects (when true).

uncles

array

Array of uncle block hashes. Always [] on Base.

baseFeePerGas

string

Base fee per gas in this block (EIP-1559).

withdrawals

array

Array of validator withdrawals included in the block (EIP-4895).

withdrawalsRoot

string

32-byte root of the withdrawals trie (EIP-4895).

{
  "jsonrpc": "2.0",
  "method": "eth_getBlockByNumber",
  "params": ["latest", false],
  "id": 1
}

eth_getBlockByHash

Returns information about a block by its hash. Parameters

blockHash

string

required

The 32-byte hash of the block.

fullTransactions

boolean

required

If true, returns full transaction objects. If false, returns only transaction hashes.

Returns

result

object | null

A block object with the same fields as eth_getBlockByNumber, or null if no block was found.

{
  "jsonrpc": "2.0",
  "method": "eth_getBlockByHash",
  "params": [
    "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
    false
  ],
  "id": 1
}

eth_getBlockReceipts

Returns all transaction receipts for a given block. More efficient than calling eth_getTransactionReceipt individually for each transaction. Parameters

blockParameter

string

required

Block number in hexadecimal, or a block tag: latest, earliest, pending, safe, or finalized.

Returns

result

array | null

An array of transaction receipt objects for every transaction in the block, or null if the block was not found. Each receipt has the same structure as eth_getTransactionReceipt.

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

eth_getBlockTransactionCountByNumber

Returns the number of transactions in a block identified by block number. Parameters

blockParameter

string

required

Block number in hexadecimal, or a block tag: latest, earliest, pending, safe, or finalized.

Returns

result

string | null

The number of transactions in the block as a hexadecimal integer, or null if no block was found.

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

eth_getBlockTransactionCountByHash

Returns the number of transactions in a block identified by block hash. Parameters

blockHash

string

required

The 32-byte hash of the block.

Returns

result

string | null

The number of transactions in the block as a hexadecimal integer, or null if no block was found.

{
  "jsonrpc": "2.0",
  "method": "eth_getBlockTransactionCountByHash",
  "params": [
    "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3"
  ],
  "id": 1
}

Transaction Methods

eth_getTransactionByHash

Returns transaction information for a given transaction hash. Parameters

transactionHash

string

required

The 32-byte transaction hash.

Returns

result

object | null

A transaction object, or null if no transaction was found.

Show Transaction object fields

hash

string

32-byte hash of the transaction.

nonce

string

Number of transactions sent by the sender prior to this one.

blockHash

string

32-byte hash of the block this transaction is in. null if pending.

blockNumber

string

Block number this transaction is in. null if pending.

transactionIndex

string

Transaction’s index position in the block. null if pending.

from

string

20-byte address of the sender.

string

20-byte address of the receiver. null for contract creation transactions.

value

string

Value transferred in wei as a hexadecimal.

gas

string

Gas provided by the sender.

gasPrice

string

Gas price in wei. For EIP-1559 transactions, this is the effective gas price paid.

maxFeePerGas

string

Maximum total fee per gas the sender is willing to pay (EIP-1559). Only present for type 0x2 transactions.

maxPriorityFeePerGas

string

Maximum priority fee per gas (EIP-1559). Only present for type 0x2 transactions.

input

string

ABI-encoded call data sent with the transaction. "0x" for plain ETH transfers.

type

string

Transaction type: "0x0" (legacy), "0x1" (EIP-2930 access list), "0x2" (EIP-1559), "0x7e" (deposit transaction on Base).

chainId

string

Chain ID the transaction is valid for. "0x2105" for Base Mainnet, "0x14a34" for Base Sepolia.

accessList

array

List of addresses and storage keys the transaction accesses (EIP-2930). Only present for type 0x1 and 0x2 transactions.

string

ECDSA recovery ID.

string

32-byte ECDSA signature component r.

string

32-byte ECDSA signature component s.

{
  "jsonrpc": "2.0",
  "method": "eth_getTransactionByHash",
  "params": [
    "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
  ],
  "id": 1
}

eth_getTransactionByBlockHashAndIndex

Returns transaction information for a given block hash and transaction index position. Parameters

blockHash

string

required

The 32-byte hash of the block.

transactionIndex

string

required

The transaction’s index position in the block as a hexadecimal integer (e.g., "0x0" for the first transaction).

Returns

result

object | null

A transaction object with the same fields as eth_getTransactionByHash, or null if no transaction was found at that position.

{
  "jsonrpc": "2.0",
  "method": "eth_getTransactionByBlockHashAndIndex",
  "params": [
    "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
    "0x0"
  ],
  "id": 1
}

eth_getTransactionByBlockNumberAndIndex

Returns transaction information for a given block number and transaction index position. Parameters

blockParameter

string

required

Block number in hexadecimal, or a block tag: latest, earliest, pending, safe, or finalized.

transactionIndex

string

required

The transaction’s index position in the block as a hexadecimal integer.

Returns

result

object | null

A transaction object with the same fields as eth_getTransactionByHash, or null if no transaction was found at that position.

{
  "jsonrpc": "2.0",
  "method": "eth_getTransactionByBlockNumberAndIndex",
  "params": ["latest", "0x0"],
  "id": 1
}

eth_getTransactionReceipt

Returns the receipt for a mined transaction. Receipts are only available after the transaction has been included in a block.

For preconfirmed transaction receipts before a block is sealed, use a Flashblocks-aware endpoint.

Parameters

transactionHash

string

required

The 32-byte hash of the transaction.

Returns

result

object | null

A transaction receipt object, or null if the transaction is not found or is still pending.

Show Transaction receipt fields

transactionHash

string

32-byte hash of the transaction.

transactionIndex

string

Transaction’s index position in the block.

blockHash

string

32-byte hash of the block this transaction is in.

blockNumber

string

Block number this transaction is in.

from

string

20-byte address of the sender.

string

20-byte address of the receiver. null for contract creation transactions.

cumulativeGasUsed

string

Total gas used in the block at the point this transaction was executed.

effectiveGasPrice

string

Actual gas price paid per unit of gas for this transaction.

gasUsed

string

Gas used by this specific transaction.

contractAddress

string | null

The address of the contract created by this transaction, if it was a contract creation. Otherwise null.

logs

array

Array of log objects generated by this transaction.

logsBloom

string

256-byte bloom filter for the logs of this transaction.

status

string

"0x1" for a successful transaction, "0x0" for a failed (reverted) transaction.

type

string

Transaction type: "0x0" (legacy), "0x1" (EIP-2930), "0x2" (EIP-1559).

{
  "jsonrpc": "2.0",
  "method": "eth_getTransactionReceipt",
  "params": [
    "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
  ],
  "id": 1
}

Code	Message	Description
`-32000`	transaction indexing is in progress	The node is still indexing transactions. Retry after the node has finished syncing.

eth_sendRawTransaction

Submits a signed, RLP-encoded transaction to the network for broadcast. The transaction must be signed offline using the sender’s private key before calling this method. Parameters

signedTransactionData

string

required

The signed transaction data as a hex-encoded RLP-encoded string. Typically generated by a wallet library such as ethers.js, viem, or web3.js.

Returns

result

string

The 32-byte transaction hash if the transaction was accepted into the mempool.

{
  "jsonrpc": "2.0",
  "method": "eth_sendRawTransaction",
  "params": [
    "0x02f86b82210501843b9aca008477359400825208944200000000000000000000000000000000000006872c68af0bb1400080c001a01a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2ba02b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c"
  ],
  "id": 1
}

Code	Message	Description
`-32000`	nonce too low	The transaction nonce is lower than the current account nonce
`-32000`	insufficient funds for gas * price + value	The sender’s balance cannot cover gas cost and value
`-32000`	already known	An identical transaction is already in the mempool
`-32000`	replacement transaction underpriced	A replacement transaction must pay a higher gas price

Gas & Fee Methods

eth_gasPrice

Returns the current gas price suggested for legacy (type 0x0) transactions. Parameters This method takes no parameters. Returns

result

string

Current gas price in wei as a hexadecimal string.

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

eth_maxPriorityFeePerGas

Returns the suggested maxPriorityFeePerGas (tip) for EIP-1559 transactions. Add this to the current baseFeePerGas to derive a maxFeePerGas. Parameters This method takes no parameters. Returns

result

string

Suggested priority fee per gas in wei as a hexadecimal string.

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

eth_feeHistory

Returns historical base fees, gas usage ratios, and priority fee percentiles for a range of blocks. Useful for building accurate EIP-1559 fee estimates. Parameters

blockCount

string | number

required

Number of blocks to include in the history. Must be between 1 and 1024. Can be a decimal integer or a hex string (e.g., 4 or "0x4").

newestBlock

string

required

The newest block in the requested range. Block number in hexadecimal, or a block tag: latest, safe, or finalized.

rewardPercentiles

array

Optional. An array of percentile values between 0 and 100. For each block, the node returns the effective priority fee at each percentile from the transactions in that block. For example, [25, 50, 75] returns 25th, 50th, and 75th percentile values.

Returns

result

object

Fee history data for the requested range.

Show Fee history fields

oldestBlock

string

Block number of the oldest block in the returned range.

baseFeePerGas

array

Array of base fees per gas for each block in the range, plus one extra entry for the next block after the range. Length is blockCount + 1.

gasUsedRatio

array

Array of gas used ratios (values between 0 and 1) for each block in the range.

reward

array

Array of arrays containing the priority fees at each requested percentile for each block. Only present when rewardPercentiles is provided.

{
  "jsonrpc": "2.0",
  "method": "eth_feeHistory",
  "params": [4, "latest", [25, 75]],
  "id": 1
}

eth_estimateGas

Estimates the amount of gas required to execute a transaction. The estimate may be higher than the gas actually used at execution time. Parameters

transactionObject

object

required

The transaction object to estimate gas for.

Show Transaction object fields

from

string

The 20-byte address the transaction is sent from. Optional.

string

The 20-byte destination address. Required for contract calls; omit for contract deployments.

gas

string

Gas limit for the estimate. Optional.

gasPrice

string

Gas price in wei for legacy transactions. Optional.

maxFeePerGas

string

EIP-1559 maximum total fee per gas. Optional.

maxPriorityFeePerGas

string

EIP-1559 maximum priority fee per gas. Optional.

value

string

ETH value to send with the transaction in wei. Optional.

data

string

ABI-encoded call data. Optional.

blockParameter

string

Optional block to estimate against. Defaults to latest.

Returns

result

string

The estimated gas amount as a hexadecimal integer.

{
  "jsonrpc": "2.0",
  "method": "eth_estimateGas",
  "params": [
    {
      "from": "0xd3CdA913deB6f4967b2Ef66ae97DE114a83bcc01",
      "to": "0x4200000000000000000000000000000000000006",
      "value": "0x2c68af0bb14000"
    }
  ],
  "id": 1
}

Code	Message	Description
`-32000`	execution reverted	The transaction would revert. The error data may contain a revert reason.

Log Methods

eth_getLogs

Returns an array of logs matching the given filter criteria. Particularly useful for indexing on-chain events.

Queries spanning large block ranges or high-activity contracts can time out or be rejected. Keep fromBlock-to-toBlock ranges under 2,000 blocks for reliable results. Node providers may enforce their own limits.

Parameters

filterObject

object

required

The log filter object. At least one filter criterion should be provided.

Show Filter object fields

fromBlock

string

Start of the block range. Block number in hexadecimal or a block tag. Defaults to "latest".

toBlock

string

End of the block range. Block number in hexadecimal or a block tag. Defaults to "latest".

address

string | array

A single contract address or array of addresses to filter logs by. Optional.

topics

array

Array of 32-byte topic filters. Each position can be null (match any), a single topic hex string, or an array of topic hex strings (match any in the array). Position 0 is typically the keccak256 hash of the event signature. Optional.

blockHash

string

A specific block hash to restrict results to that single block only. If provided, fromBlock and toBlock are ignored. Optional.

Returns

result

array

An array of log objects matching the filter.

Show Log object fields

address

string

20-byte address of the contract that emitted the log.

topics

array

Array of 0–4 indexed 32-byte topics. Topic 0 is the event signature hash for named events.

data

string

ABI-encoded non-indexed event parameters.

blockNumber

string

Block number in which this log was emitted.

transactionHash

string

32-byte hash of the transaction that emitted this log.

transactionIndex

string

Index of the transaction in the block.

blockHash

string

32-byte hash of the block.

logIndex

string

Log’s index position within the block.

removed

boolean

true if the log was removed due to a chain reorganization. false for valid logs.

{
  "jsonrpc": "2.0",
  "method": "eth_getLogs",
  "params": [
    {
      "fromBlock": "0x12ced00",
      "toBlock": "0x12ced28",
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
      ]
    }
  ],
  "id": 1
}

Chain & Network Methods

eth_chainId

Returns the chain ID of the current network per EIP-695. Parameters This method takes no parameters. Returns

result

string

The chain ID as a hexadecimal string. "0x2105" (8453) for Base Mainnet, "0x14a34" (84532) for Base Sepolia.

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

eth_syncing

Returns the synchronization status of the node. Parameters This method takes no parameters. Returns

result

object | boolean

Returns false if the node is fully synced with the network. Returns a sync status object if the node is still catching up.

Show Sync status object fields (when syncing)

startingBlock

string

Block number where the current sync started.

currentBlock

string

Current block the node has processed.

highestBlock

string

Estimated highest block number on the network.

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

net_version

Returns the network ID as a decimal string. For Base, this is the same value as the chain ID. Parameters This method takes no parameters. Returns

result

string

The network ID as a decimal string (not hex). "8453" for Base Mainnet, "84532" for Base Sepolia.

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

web3_clientVersion

Returns a string identifying the node client software and version. Parameters This method takes no parameters. Returns

result

string

A string in the format <client>/<version>/<os>/<runtime>.

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

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.

debug_traceTransaction

Replays a transaction and returns its complete EVM execution trace, including every opcode executed, gas consumed at each step, stack contents, and storage changes. Parameters

transactionHash

string

required

The 32-byte hash of the transaction to trace.

traceOptions

object

Optional tracing configuration.

Show Trace options fields

disableStorage

boolean

If true, omits storage capture from struct logs. Reduces response size. Defaults to false.

disableMemory

boolean

If true, omits memory capture from struct logs. Reduces response size. Defaults to false.

disableStack

boolean

If true, omits stack capture from struct logs. Defaults to false.

tracer

string

Name of a built-in tracer. Options: "callTracer" (returns a call tree), "prestateTracer" (returns the pre-execution state). Omit to use the default struct log tracer.

tracerConfig

object

Configuration for the selected tracer. For callTracer: { "onlyTopCall": true } skips internal calls.

timeout

string

Execution timeout as a Go duration string (e.g., "10s", "30s"). Defaults to "5s".

Returns

result

object

The execution trace. Format depends on the tracer option selected.

Show Default struct log trace fields

gas

number

Total gas provided for the transaction.

failed

boolean

Whether the transaction failed (reverted).

returnValue

string

Hex-encoded return value from the transaction execution.

structLogs

array

Array of struct log entries, one per EVM opcode executed.

Show Struct log entry fields

number

Program counter position.

string

EVM opcode name (e.g., "PUSH1", "SLOAD").

gas

number

Remaining gas at this step.

gasCost

number

Gas cost of this opcode.

depth

number

Call depth (1 = top-level call).

stack

array

EVM stack values at this step.

memory

array

EVM memory contents as 32-byte chunks.

storage

object

Contract storage changes at this step (slot → value).

Show callTracer result fields

type

string

Call type: "CALL", "STATICCALL", "DELEGATECALL", or "CREATE".

from

string

Sender address.

string

Recipient address.

value

string

ETH value sent with the call.

gas

string

Gas provided for the call.

gasUsed

string

Gas actually consumed.

input

string

Call data sent.

output

string

Return data from the call.

error

string

Error message if the call reverted. Optional.

calls

array

Array of nested call objects for internal calls.

{
  "jsonrpc": "2.0",
  "method": "debug_traceTransaction",
  "params": [
    "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
    {}
  ],
  "id": 1
}

debug_traceBlockByHash

Replays all transactions in a block identified by its hash and returns an execution trace for each transaction. Parameters

blockHash

string

required

The 32-byte hash of the block to trace.

traceOptions

object

Optional trace configuration. Accepts the same fields as debug_traceTransaction.

Returns

result

array

An array of trace result objects, one per transaction in the block.

Show Trace result object fields

txHash

string

The transaction hash.

result

object

The execution trace for this transaction. Same format as the result of debug_traceTransaction.

{
  "jsonrpc": "2.0",
  "method": "debug_traceBlockByHash",
  "params": [
    "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
    { "tracer": "callTracer" }
  ],
  "id": 1
}

debug_traceBlockByNumber

Replays all transactions in a block identified by its number and returns an execution trace for each transaction. Parameters

blockParameter

string

required

Block number in hexadecimal, or a block tag: latest, earliest, safe, or finalized.

traceOptions

object

Optional trace configuration. Accepts the same fields as debug_traceTransaction.

Returns

result

array

An array of trace result objects, one per transaction in the block. Same format as debug_traceBlockByHash.

{
  "jsonrpc": "2.0",
  "method": "debug_traceBlockByNumber",
  "params": ["latest", { "tracer": "callTracer" }],
  "id": 1
}

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.

eth_subscribe

Creates a real-time subscription to on-chain events. The node pushes event notifications to the client as JSON-RPC messages whenever a matching event occurs, without the client needing to poll. Parameters

subscriptionType

string

required

The event type to subscribe to. See subscription types below.

Optional filter options. Only applicable for the logs subscription type.

Show Filter options (logs only)

address

string | array

A single contract address or array of addresses to filter logs by. Optional.

topics

array

Array of topic filters in the same format as eth_getLogs. Optional.

Subscription Types

Type	Description	Notification payload
`newHeads`	Fires for each new block header appended to the chain	Block header object
`logs`	Fires for each new log matching the filter criteria	Log object
`newPendingTransactions`	Fires for each new pending transaction hash added to the mempool	Transaction hash string

Returns

result

string

A hex-encoded subscription ID. All subsequent event notifications from this subscription include this ID in params.subscription.

Event notifications arrive as unsolicited JSON-RPC messages with method: "eth_subscription":

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x1887ec8b9589ccad00000000000532da",
    "result": { ... }
  }
}

Subscribe to new block headers:

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

Subscribe to contract logs:

{
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
      ]
    }
  ],
  "id": 1
}

eth_unsubscribe

Cancels a subscription created by eth_subscribe. After cancellation, no further notifications are sent for that subscription ID. Parameters

subscriptionId

string

required

The hex-encoded subscription ID returned by eth_subscribe.

Returns

result

boolean

true if the subscription was successfully cancelled. false if the subscription ID was not found (e.g., already cancelled or never existed).

{
  "jsonrpc": "2.0",
  "method": "eth_unsubscribe",
  "params": ["0x1887ec8b9589ccad00000000000532da"],
  "id": 1
}

Quickstart

Reference

Network Information

Flashblocks

Node Operators

Builder Codes

Tools

Security

​Request & Response Format

​Error Codes

​Block Parameters

​Account & State Methods

​eth_blockNumber

​eth_getBalance

​eth_getTransactionCount

​eth_getCode

​eth_getStorageAt

​eth_call

​Block Methods

​eth_getBlockByNumber

​eth_getBlockByHash

​eth_getBlockReceipts

​eth_getBlockTransactionCountByNumber

​eth_getBlockTransactionCountByHash

​Transaction Methods

​eth_getTransactionByHash

​eth_getTransactionByBlockHashAndIndex

​eth_getTransactionByBlockNumberAndIndex

​eth_getTransactionReceipt

​eth_sendRawTransaction

​Gas & Fee Methods

​eth_gasPrice

​eth_maxPriorityFeePerGas

​eth_feeHistory

​eth_estimateGas

​Log Methods

​eth_getLogs

​Chain & Network Methods

​eth_chainId

​eth_syncing

​net_version

​web3_clientVersion

​Debug Methods

​debug_traceTransaction

​debug_traceBlockByHash

​debug_traceBlockByNumber

​WebSocket Methods

​eth_subscribe

​eth_unsubscribe

Request & Response Format

Error Codes

Block Parameters

Account & State Methods

eth_blockNumber

eth_getBalance

eth_getTransactionCount

eth_getCode

eth_getStorageAt

eth_call

Block Methods

eth_getBlockByNumber

eth_getBlockByHash

eth_getBlockReceipts

eth_getBlockTransactionCountByNumber

eth_getBlockTransactionCountByHash

Transaction Methods

eth_getTransactionByHash

eth_getTransactionByBlockHashAndIndex

eth_getTransactionByBlockNumberAndIndex

eth_getTransactionReceipt

eth_sendRawTransaction

Gas & Fee Methods

eth_gasPrice

eth_maxPriorityFeePerGas

eth_feeHistory

eth_estimateGas

Log Methods

eth_getLogs

Chain & Network Methods

eth_chainId

eth_syncing

net_version

web3_clientVersion

Debug Methods

debug_traceTransaction

debug_traceBlockByHash

debug_traceBlockByNumber

WebSocket Methods

eth_subscribe

eth_unsubscribe