eth_subscribe

Creates a real-time WebSocket subscription. Flashblocks endpoints add three extra subscription types and emit newHeads every ~200ms.

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

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

Parameters

subscriptionType · string · required

The event type to subscribe to.

filterOptions · object

Optional filter options. Only applicable for the "logs" subscription type.

Show Filter options (logs only)

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 filter criteria	Log object
newPendingTransactions	Fires for each new transaction hash added to the mempool	Transaction hash string

Returns

result · string

A hex-encoded subscription ID. All event notifications from this subscription include this ID in 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}