eth_subscribe: Stream Heads, Logs and Pending Transactions

What eth_subscribe does

There are four subscription types. newHeads pushes a block header for every block the node imports. logs takes an eth_getLogs-style filter and pushes matching logs as blocks are executed. newPendingTransactions pushes transactions as they enter the node's mempool, hashes by default or full transaction objects when the second parameter is true on Geth. syncing reports sync status transitions and is mostly an operational tool.

Notifications do not look like responses. The initial call returns a normal JSON-RPC result containing the subscription id, and everything after that arrives as a server-initiated message with method eth_subscription and a params object holding the subscription id and the payload. Client libraries hide this, but if you are writing against a raw WebSocket you have to route messages by shape rather than by request id.

The subscription lives on the connection. Close the socket, lose the network, or let a proxy time the connection out, and the subscription is gone with no notification and no replay of what you missed. Every production consumer therefore pairs the stream with a cursor: remember the last block you fully processed, and on reconnect backfill the gap with eth_getLogs before trusting the stream again.

Parameters

What it returns

The immediate response is a hex subscription id. Afterwards the node pushes eth_subscription notifications carrying that id and a result whose shape depends on the type: a block header for newHeads, a log object for logs, a transaction hash (or full transaction) for newPendingTransactions.

eth_unsubscribe with the id stops the stream and returns true. Dropping the connection has the same effect without the courtesy of a confirmation.

// the call itself
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x9cef478923ff08bf67fde6c64013158d"
}

// then, one of these per imported block
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x9cef478923ff08bf67fde6c64013158d",
    "result": {
      "number": "0x18789ac",
      "hash": "0x7e9ea4877f25847c29ea338043948a8ea43383da1620ace955a20baf667c5ff5",
      "parentHash": "0x161ab6d812fb274e0d07f71f197b458be7f96451932b129af3001487d7829a0c",
      "timestamp": "0x6a6ddccb",
      "gasUsed": "0x1e513f7",
      "baseFeePerGas": "0x2e0a427"
    }
  }
}

Header trimmed; the real notification carries the full header including the state, transaction and receipt roots. Note that the notification has no id field, because the node initiated it.

import { WebSocketProvider, id } from "ethers";

// inside a BLAZED.sh container the node is one local socket away
const provider = new WebSocketProvider("ws://eth:8545");

// eth_subscribe("newHeads")
provider.on("block", (blockNumber) => console.log("head", blockNumber));

// eth_subscribe("logs", { address, topics })
provider.on(
  {
    address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    topics: [id("Transfer(address,address,uint256)")],
  },
  (log) => console.log("transfer in", log.blockNumber, log.transactionHash),
);

// eth_subscribe("newPendingTransactions"): the mempool as the node sees it
provider.on("pending", async (hash) => {
  const tx = await provider.getTransaction(hash);
  if (tx) console.log("pending", tx.from, "->", tx.to);
});

Gotchas and common errors

What eth_subscribe costs on BLAZED.sh

The eth_subscribe call itself costs 1 credit on BLAZED.sh, and WebSocket usage follows the same per-request credit model as HTTP. Compared with polling, the accounting is dramatically simpler: one subscription replaces a request every second forever. A newPendingTransactions stream is the one to watch, since the volume of pushed data on a busy chain is substantial. Running the consumer on the node host means that stream never crosses the public internet at all; it arrives over a local socket, which is where the sub-10ms round-trip on the follow-up calls comes from.

eth_subscribe: frequently asked questions