# 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` * **Mainnet:** `https://rpc.mainnet.citrea.xyz` * **Testnet:** `https://rpc.testnet.citrea.xyz` * [**Alchemy**](https://alchemy.com)**:** [`https://citrea-mainnet.g.alchemy.com/v2/{apiKey}`](https://citrea-mainnet.g.alchemy.com/v2/%7BapiKey%7D) * You can also view/test RPC endpoints using [Alchemy's documentation / playground](https://www.alchemy.com/docs/node/citrea/citrea-api-endpoints/citrea-get-l-2-status-heights-by-l-1-height). *** ## Supported JSON-RPC Methods ### Web3 Methods * [**`web3_clientVersion`**](https://ethereum.org/en/developers/docs/apis/json-rpc#web3_clientversion) - Returns the current client version * [**`web3_sha3`**](https://ethereum.org/en/developers/docs/apis/json-rpc#web3_sha3) - Returns Keccak-256 hash of the given data ### Net Methods * [**`net_version`**](https://ethereum.org/en/developers/docs/apis/json-rpc#net_version) - Returns the current network ID ### Ethereum Methods #### Synchronization & Status * [**`eth_syncing`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_syncing) - Returns sync status object or false if fully synced * [**`eth_chainId`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_chainid) - Returns the chain ID #### Gas & Fees * [**`eth_gasPrice`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_gasprice) - Returns current gas price estimate * [**`eth_feeHistory`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_feehistory) - Returns historical base fees and reward percentiles (EIP-1559) * [**`eth_maxPriorityFeePerGas`**](https://docs.blastapi.io/blast-documentation/apis-documentation/core-api/ethereum/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`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_blocknumber) - Returns the latest block number * [**`eth_getBalance`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_getbalance) - Returns account balance at given address and block * [**`eth_getStorageAt`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_getstorageat) - Returns storage value at address/key for given block * [**`eth_getTransactionCount`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_gettransactioncount) - Returns nonce for an address * [**`eth_getCode`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_getcode) - Returns contract bytecode at address #### Block Information * [**`eth_getBlockTransactionCountByHash`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_getblocktransactioncountbyhash) - Returns number of transactions in block by hash * [**`eth_getBlockTransactionCountByNumber`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_getblocktransactioncountbynumber) - Returns number of transactions in block by number * [**`eth_getBlockByHash`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_getblockbyhash) - Returns block by hash * *Note*: There is an extra field in the response, `l1FeeRate`. * [**`eth_getBlockByNumber`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_getblockbynumber) - Returns block by number * *Note*: There is an extra field in this response, `l1FeeRate`. * [**`eth_getUncleByBlockHashAndIndex`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_getunclebyblockhashAndindex) - Returns null (no uncles in Citrea) #### Transaction Methods * [**`eth_sendRawTransaction`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_sendrawtransaction) - Submits a signed transaction * [**`eth_sendRawTransactionSync`**](https://eips.ethereum.org/EIPS/eip-7966) - Submits a signed transaction and waits for it to be included in a block before returning (EIP-7966) * [**`eth_getTransactionByHash`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_gettransactionbyhash) - Returns transaction details by hash * [**`eth_getTransactionByBlockHashAndIndex`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_gettransactionbyblockhashAndindex) - Returns transaction by block hash and index * [**`eth_getTransactionByBlockNumberAndIndex`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_gettransactionbyblocknumberandindex) - Returns transaction by block number and index * [**`eth_getTransactionReceipt`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_gettransactionreceipt) - Returns transaction receipt by hash * *Note*: There are extra fields in the response, `l1FeeRate` and `l1DiffSize`. #### Call & Execution * [**`eth_call`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_call) - Executes a read-only call * [**`eth_estimateGas`**](https://ethereum.org/en/developers/docs/apis/json-rpc#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`](https://docs.citrea.xyz/developer-documentation/citrea-rpc-documentation#eth_estimatediffsize) (Citrea-specific). #### Logs * [**`eth_getLogs`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_getlogs) - Returns logs matching filter criteria #### Filters * [**`eth_newFilter`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_newfilter) - Creates a log filter and returns its ID * [**`eth_newBlockFilter`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_newblockfilter) - Creates a filter for new blocks and returns its ID * [**`eth_uninstallFilter`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_uninstallfilter) - Uninstalls a filter by ID * [**`eth_getFilterChanges`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_getfilterchanges) - Returns changes since the last poll for a filter * [**`eth_getFilterLogs`**](https://ethereum.org/en/developers/docs/apis/json-rpc#eth_getfilterlogs) - Returns all logs matching a given filter ID ### State Proofs & Access Lists * [**`eth_getProof`**](https://docs.blastapi.io/blast-documentation/apis-documentation/core-api/ethereum/eth_getproof) - Returns account and storage proof (EIP-1186) * [**`eth_createAccessList`**](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-eth#eth-createaccesslist) - Generates access list for transaction (EIP-2930) ### Bulk Operations * [**`eth_getBlockReceipts`**](https://docs.blastapi.io/blast-documentation/erigon-api/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`**](https://docs.citrea.xyz/developer-documentation/citrea-rpc-documentation#eth_estimatediffsize) - Estimates L1 data diff size for rollup transaction ### Debug Endpoints * [**`debug_traceTransaction`**](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#debug-tracetransaction) - Traces execution of a transaction (requires full node) * [**`debug_traceBlockByHash`**](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#debug-traceblockbyhash) - Traces all transactions in a block by hash * [**`debug_traceBlockByNumber`**](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#debug-traceblockbynumber) - Traces all transactions in a block by number * [**`debug_traceCall`**](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug#debug-tracecall) - Traces execution of a read-only call without creating a transaction ### Subscription Methods (WebSocket only) * [**`eth_subscribe`**](https://docs.blastapi.io/blast-documentation/apis-documentation/core-api/ethereum/eth_subscribe) - Creates subscription for events * [**`eth_unsubscribe`**](https://docs.blastapi.io/blast-documentation/apis-documentation/core-api/ethereum/eth_unsubscribe) - Cancels active subscription * [**`debug_subscribe`**](https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-debug) - Creates a subscription for debug-namespace events *** ## 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 * Please visit [Citrea-Specific RPC Documentation](https://docs.citrea.xyz/developer-documentation/rpc-documentation/citrea-rpc-documentation) for Citrea-specific endpoints --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.citrea.xyz/developer-documentation/rpc-documentation/eth-rpc-endpoints.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.