eth_subscribe

Opens a real-time event subscription over a WebSocket connection. Returns a subscription ID; events arrive as eth_subscription notifications without the client needing to poll.

On wss://mainnet-preconf.base.org, newHeads fires every ~200ms (once per Flashblock) instead of every ~2 seconds. Three additional subscription types are exclusive to Flashblocks endpoints: newFlashblockTransactions, pendingLogs, and newFlashblocks.

Parameters

Name	Type	Required	Description
subscriptionType	string	Yes	The event type to subscribe to.
filterOptions	object	No	Optional filter object. Only applicable for the "logs" subscription type.

The filterOptions object accepts:

Field	Type	Description
address	string | array	A contract address or array of addresses to filter 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 appended to the chain	Block header object (~200ms on Flashblocks endpoints)
logs	Fires for each new log matching the filter criteria	Log object
newPendingTransactions	Fires for each new transaction hash added to the mempool	Transaction hash string

Returns

Field	Type	Description
result	string	A hex-encoded subscription ID. Every event notification from this subscription includes the same ID under params.subscription.

Event notifications arrive as unsolicited JSON-RPC messages:

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

Example

Subscribe to newHeads

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

Subscribe to logs (with filter)

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

Subscription ID response

{"jsonrpc": "2.0", "id": 1, "result": "0x1887ec8b9589ccad00000000000532da"}

newHeads event

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x1887ec8b9589ccad00000000000532da",
    "result": {
      "number": "0x12ced29",
      "hash": "0x4b5e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e4",
      "parentHash": "0x3a4e8c5d7f2b1a6e9d0c4f8b3e7a2d5c8f1b4e7a0d3c6f9b2e5a8d1c4f7b0e3",
      "gasLimit": "0x1c9c380",
      "gasUsed": "0xa410",
      "timestamp": "0x6783a5d2",
      "baseFeePerGas": "0x3b9aca00"
    }
  }
}

logs event

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x2a7bc8d4e3f5a6b1c2d3e4f5a6b7c8d9",
    "result": {
      "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x000000000000000000000000d3cda913deb6f4967b2ef66ae97de114a83bcc01",
        "0x0000000000000000000000004200000000000000000000000000000000000006"
      ],
      "data": "0x0000000000000000000000000000000000000000000000000000000005f5e100",
      "blockNumber": "0x12ced29",
      "transactionHash": "0xc903239f...",
      "blockHash": "0x4b5e8c5d...",
      "logIndex": "0x0",
      "removed": false
    }
  }
}