# Supported Realtime RPC Methods Advanced users can interact with the [real-time builder endpoint](/overview/realtime/builder-rpc-private-orderflow.md) if do not want the transaction to appear in the public mempool. | Network | URL | Websocket | | ------- | --------------------------------------- | ---------------------------------------- | | Mainnet | | | | Hoodi | | | All modifications done to the existing Ethereum JSON RPC methods are confined to overloading the existing `pending` tag except a few JSON RPC methods which become inherently aware of the preconfirmation state. Originally, this tag was designed to return block data being processed by the node's internal miner It's fitting that we now use it for a similar purpose: exposing blocks in their preconfirmation stage. When queried with the pending tag, the endpoint uses the preconfirmation state to construct the response. The response might include not only transactions but also block metadata like state root and receipt root. The tag is currently in a soft-deprecated state due to inconsistent implementations across clients, particularly after The Merge. However, it's worth noting that it's still actively used for certain endpoints, particularly `eth_getTransactionCount` where it serves the important function of returning the next available nonce for an account (including transactions in the mempool). This presents an opportunity: the tag is well-defined enough to be supported by client libraries, yet loosely defined enough to allow for our preconfirmation use case. While there's a possibility of the tag being removed in the future (see [EIP discussions](https://github.com/ethereum/execution-apis/issues/495)), the design could adapt by introducing a realtime block specific tag if needed. We repurpose the pending tag in the following RPC calls to enable consuming preconfirmed state: * `eth_call` * `eth_estimateGas` * `eth_getBlockByNumber` * `eth_getBalance` * `eth_getTransactionCount` * `eth_subscribe` {% hint style="info" %} **Not all RPC methods explicitly require a "pending" tag to tap into the real time state's awareness.** {% endhint %} The following RPC methods implicitly incorporate realtime block awareness like that whenever possible: * `eth_getTransactionReceipt` * `eth_getTransactionByHash` *** ### **eth\_getTransactionReceipt** {% tabs %} {% tab title="Request" %} ```json { "method": "eth_getTransactionReceipt", "params": ["0x..."], // Transaction hash "id": 1, "jsonrpc": "2.0" } ``` {% endtab %} {% tab title="Response" %} ```json { "transactionHash": "0x...", "blockHash": "0x0", // Empty hash as placeholder "blockNumber": "0x...", // Current pending block number "transactionIndex": "0x0", "from": "0x...", "to": "0x...", "gasUsed": "0x...", "status": "0x1", "cumulativeGasUsed": "0x...", "effectiveGasPrice": "0x...", "contractAddress": "0x...", // For contract creations "logs": [], "logsBloom": "0x..." } ``` {% endtab %} {% endtabs %} When queried, this endpoint first checks the preconfirmation state for the requested transaction hash before falling back to the standard chain lookup. Some fields in the response cannot be final at the preconfirmation stage and require placeholder values: * `blockHash`: Uses empty hash as placeholder * `blockNumber`: Can be set to the current block number being processed *** ### **eth\_getTransactionByHash** {% tabs %} {% tab title="Request" %} ```json { "method": "eth_getTransactionByHash", "params": ["0x..."], // Transaction hash of the potentially pre-confirmed transaction "id": 1, "jsonrpc": "2.0" } ``` {% endtab %} {% tab title="Response" %} ```json { "id": 1, "result": { "blockHash": "0x...", "blockNumber": "0x...", "hash": "0x...", "transactionIndex": "0x0", "type": "0x2", "nonce": "0x...", "from": "0x...", "to": "0x...", "gas": "0x...", "value": "0x...", "gasPrice": "0x...", "chainId": "0x..." }, "jsonrpc": "2.0" } ``` {% endtab %} {% endtabs %} When queried, this endpoint first checks the preconfirmation state for the requested transaction hash before falling back to the standard chain state lookup. Some fields in the response cannot be final at the preconfirmation stage and require placeholder values: * `blockHash`: Uses the block hash of the pending blocks at the time the transaction was preconfirmed * `blockNumber`: Can be set to the curent block number being processed *** ### **eth\_getBlockByNumber** {% tabs %} {% tab title="Request" %} ```json { "method": "eth_getBlockByNumber", "params": ["pending", false], // Second parameter indicates full transaction objects (true) or only hashes (false) "id": 1, "jsonrpc": "2.0" } ``` {% endtab %} {% tab title="Response" %} ```json { "hash": "0x0", // Empty hash as placeholder "parentHash": "0x...", "stateRoot": "0x...", "transactionsRoot": "0x...", "receiptsRoot": "0x...", "number": "0x...", // Current pending block number "gasUsed": "0x...", "gasLimit": "0x...", "timestamp": "0x...", "extraData": "0x...", "mixHash": "0x...", "nonce": "0x...", // // Used to signal realtime block index "transactions": [] // Array of transaction hashes or full transaction objects } ``` {% endtab %} {% endtabs %} The endpoing implements an append-only pattern - multiple queries during the same block's preconfirmation phase will show an expanding list of transactions as new realtime blocks are processed. Each query reflects the current state of all preconfirmed transactions at that moment. *** ### **eth\_getBalance** {% tabs %} {% tab title="Request" %} ```json { "method": "eth_getBalance", "params": ["0x...", "pending"], // Account address and block parameter "id": 1, "jsonrpc": "2.0" } ``` {% endtab %} {% tab title="Response" %} ```json "0x..." // Balance in wei ``` {% endtab %} {% endtabs %} When queried with the `pending` tag, the endpoint uses the preconfirmation state to return the account balance. If the requested account appears in the AccountMetadata of a received realtime block with a non-null balance field, the RPC provider can directly return this value without needing toa ccess the full state. The response reflects all changes from preconfirmed transactions that affect the requested account's balance. *** ### **eth\_call** {% tabs %} {% tab title="Request" %} ```json { "method": "eth_call", "params": [{"to": "0x...", "data": "0x..."}, "pending"], // Transaction call object and block parameter "id": 1, "jsonrpc": "2.0" } ``` {% endtab %} {% tab title="Response" %} ```json "0x..." // Return data from the call ``` {% endtab %} {% endtabs %} When queried with the `pending` tag, the endpoint uses the preconfirmation state to return the call result. For this endpoint to work, the preconfirmation stream needs to include state differences for both accounts and storage after each realtime block. Similar to current override functionality in `eth_call` where EVM transitions are executed on top of modified state, this implementation executes the call on top of the preconfirmation state changes. *** ### eth\_estimateGas Generates and returns an estimate of how much gas is necessary to allow the transaction to complete considering the latest pre-confirmed state. {% tabs %} {% tab title="Request" %} ```json { "jsonrpc": "2.0", "method": "eth_estimateGas", "params": [{"from":"0x...","to":"0x...","value":"0x..."}, "pending"], "id": 1 } ``` {% endtab %} {% tab title="Response" %} ```json { "jsonrpc": "2.0", "id": "1", "result": "0x..." // The estimated amount of gas required for the transaction, as a hexadecimal string. } ``` {% endtab %} {% endtabs %} *** ### eth\_getTransactionCount {% tabs %} {% tab title="Request" %} ```json { "method": "eth_getTransactionCount", "params": ["0x...", "pending"],// Account address and block parameter "id": 1, "jsonrpc": "2.0" } ``` {% endtab %} {% tab title="Response" %} ```json { "jsonrpc": "2.0", "id": "1", "result": "0x..."// Nonce value as a hex string } ``` {% endtab %} {% endtabs %} When queried with the `pending` tag, the endpoint returns the transaction count (nonce) of the account from the preconfirmation state. If the requested account appears in the AccountMetadata of a received realtime block, the RPC provider can directly use the nonce field without additional state access. *** ### eth\_subscribe - newFlashblocks Subscribe to receive notifications each time a new flashblock is processed. #### Description Fires a notification with the current pending block state whenever a new flashblock arrives. Each flashblock represents an incremental update to the pending block, so multiple notifications may be emitted for the same block height as new flashblocks are processed. #### Parameters | Position | Name | Type | Description | | -------- | ----------------- | -------- | -------------------------- | | 0 | Subscription type | `string` | Must be `"newFlashblocks"` | #### Returns A unique identifier for the subscription, returned as a 32-byte hex string. {% tabs %} {% tab title="Request" %} ```json { "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblocks"] } ``` {% endtab %} {% tab title="Response" %} ```json { "jsonrpc": "2.0", "id": 1, "result": "0x9c7c3f3c3c63b1b89ac0c1e0b0d3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8090a1b" } ``` {% endtab %} {% endtabs %} *** ### eth\_subscribe - pendingLogs Subscribe to receive logs from flashblocks pending state that match specified filter criteria. #### Description Returns logs from the current pending flashblock state. Unlike the standard `logs` subscription which only includes logs from confirmed blocks, this subscription provides logs from preconfirmed transactions in flashblocks, giving users earlier visibility into contract events. #### Parameters | Position | Name | Type | Description | | -------- | ----------------- | ------------------- | ------------------------------------------- | | 0 | Subscription type | `string` | Must be `"pendingLogs"` | | 1 | Filter | `object` (optional) | Log filter criteria (same as `eth_getLogs`) | **Filter Object** | Field | Type | Description | | --------- | --------------------------------- | ------------------------------------------------------------------- | | `address` | `string` or `string[]` (optional) | Contract address or array of addresses to filter | | `topics` | `array` (optional) | Array of topic filters (32-byte hex strings or arrays for OR logic) | If no filter is provided, all logs from pending flashblocks will be returned. #### Returns A unique identifier for the subscription, returned as a 32-byte hex string. {% tabs %} {% tab title="Request" %} ```json { "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": [ "pendingLogs", { "address": "0x1234567890123456789012345678901234567890", "topics": [ "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" ] } ] } ``` {% endtab %} {% tab title="Response" %} ```json { "jsonrpc": "2.0", "id": 1, "result": "0x9c7c3f3c3c63b1b89ac0c1e0b0d3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8090a1b" } ``` {% endtab %} {% endtabs %} *** ### eth\_subscribe - newFlashblockTransactions Subscribe to receive preconfirmed transasctions #### Description Returns transactions from flashblocks that have been included by the realtime block builder and are effectively preconfirmed. #### Parameters
PositionNameTypeDescription
0Subscription typestringMust be "newFlashblockTransactions"
1Full transactionsboolean (optional)true for full transaction objects, false or omitted for hashes only (default)
#### Returns A unique identifier for the subscription, returned as a 32-byte hex string. #### Example - Hash Mode (Default) {% tabs %} {% tab title="Request" %} ```json { "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblockTransactions"] } ``` {% endtab %} {% tab title="Response" %} ```json { "jsonrpc": "2.0", "id": 1, "result": "0x9c7c3f3c3c63b1b89ac0c1e0b0d3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8090a1b" } ``` {% endtab %} {% endtabs %} #### Example - Full Transaction Mode {% tabs %} {% tab title="Request" %} *** ```json { "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newFlashblockTransactions", true] } ``` {% endtab %} {% tab title="Response" %} ```json { "jsonrpc": "2.0", "id": 1, "result": "0x9c7c3f3c3c63b1b89ac0c1e0b0d3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8090a1b" } ``` {% endtab %} {% endtabs %} *** ### eth\_unsubscribing All subscription types can be unsubscribed using the standard `eth_unsubscribe` method with the subscription ID. {% tabs %} {% tab title="Request" %} ```json { "jsonrpc": "2.0", "id": 1, "method": "eth_unsubscribe", "params": ["0x9c7c3f3c3c63b1b89ac0c1e0b0d3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8090a1b"] } ``` {% endtab %} {% tab title="Response" %} ```json { "jsonrpc": "2.0", "id": 1, "result": true } ``` {% endtab %} {% endtabs %} --- # 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.ethgas.com/overview/realtime/supported-realtime-rpc-methods.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.