EVM JSON-RPC Endpoints

Complete reference for Ethereum-compatible JSON-RPC API endpoints supported by Citrea. These endpoints provide compatibility with existing EVM tooling and libraries.

Base URLs

• Local node: http://0.0.0.0:8080

• Public Testnet: https://rpc.testnet.citrea.xyz

• Alchemy: https://citrea-testnet.g.alchemy.com/v2/{apiKey}

  • You can also view/test RPC endpoints using Alchemy's documentation / playground.

---

Supported JSON-RPC Methods

Web3 Methods

• web3_clientVersion - Returns the current client version

• web3_sha3 - Returns Keccak-256 hash of the given data

Net Methods

• net_version - Returns the current network ID

Ethereum Methods

Synchronization & Status

• eth_syncing - Returns sync status object or false if fully synced

• eth_chainId - Returns the chain ID

Gas & Fees

• eth_gasPrice - Returns current gas price estimate

• eth_feeHistory - Returns historical base fees and reward percentiles (EIP-1559)

• eth_maxPriorityFeePerGas - Returns suggested priority fee (tip) per gas

• eth_maxFeePerGas - Returns estimated maximum fee per gas

  • curl -H "Content-type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"eth_maxFeePerGas","params":[],"id":1}' https://rpc.testnet.citrea.xyz | jq .

Account & Balance

• eth_blockNumber - Returns the latest block number

• eth_getBalance - Returns account balance at given address and block

• eth_getStorageAt - Returns storage value at address/key for given block

• eth_getTransactionCount - Returns nonce for an address

• eth_getCode - Returns contract bytecode at address

Block Information

• eth_getBlockTransactionCountByHash - Returns number of transactions in block by hash

• eth_getBlockTransactionCountByNumber - Returns number of transactions in block by number

• eth_getBlockByHash - Returns block by hash

  • Note: There is an extra field in the response, l1FeeRate.

• eth_getBlockByNumber - Returns block by number

  • Note: There is an extra field in this response, l1FeeRate.

• eth_getUncleByBlockHashAndIndex - Returns null (no uncles in Citrea)

Transaction Methods

• eth_sendRawTransaction - Submits a signed transaction

• eth_getTransactionByHash - Returns transaction details by hash

• eth_getTransactionByBlockHashAndIndex - Returns transaction by block hash and index

• eth_getTransactionByBlockNumberAndIndex - Returns transaction by block number and index

• eth_getTransactionReceipt - Returns transaction receipt by hash

  • Note: There are extra fields in the response, l1FeeRate and l1DiffSize.

Call & Execution

• eth_call - Executes a read-only call

• eth_estimateGas - Returns gas estimate for a transaction

  • Note: eth_estimateGas carries a tiny overhead for the L1 fee costs. For a more precise estimation that separates L1 and L2 costs, please use eth_estimateDiffSize (Citrea-specific).

Logs

• eth_getLogs - Returns logs matching filter criteria

State Proofs & Access Lists

• eth_getProof - Returns account and storage proof (EIP-1186)

• eth_createAccessList - Generates access list for transaction (EIP-2930)

Bulk Operations

• eth_getBlockReceipts - Returns all transaction receipts for a block

  • Note: There are extra fields in some objects of the response, such as l1FeeRate and l1DiffSize.

Citrea-Specific Extensions

• eth_estimateDiffSize - Estimates L1 data diff size for rollup transaction

Debug Endpoints

• debug_traceTransaction - Traces execution of a transaction (requires full node)

• debug_traceBlockByHash - Traces all transactions in a block by hash

• debug_traceBlockByNumber - Traces all transactions in a block by number

Subscription Methods (WebSocket only)

• eth_subscribe - Creates subscription for events

• eth_unsubscribe - Cancels active subscription

---

Notes

• Almost all methods follow the standard Ethereum JSON-RPC specification formats (see notes above)

• You can use WebSocket connections for subscription methods (eth_subscribe/eth_unsubscribe) on your full node

• You can use eth_getLogs for log filtering instead of filter-based methods

• Please visit Citrea-Specific RPC Documentation for Citrea-specific endpoints