eth_subscribe

Creates a real-time WebSocket subscription for new blocks, logs, and pending transactions.

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.

The public Base endpoints (mainnet.base.org, sepolia.base.org) are HTTP only. WebSocket connections are not available on public Base endpoints — use a node provider such as Alchemy or QuickNode that offers WebSocket support for Base.

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	Full block header object — identical shape to eth_getBlockByNumber with hydrated: false
logs	Fires for each new log matching filter criteria	Log object (see below)
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}

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

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

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x1887ec8b9589ccad00000000000532da",
    "result": {
      "baseFeePerGas": "0x4c4b40",
      "blobGasUsed": "0x5384cc",
      "difficulty": "0x0",
      "excessBlobGas": "0x0",
      "extraData": "0x01000000640000000500000000004c4b40",
      "gasLimit": "0x17d78400",
      "gasUsed": "0x2155bc7",
      "hash": "0x491bca01d4bc076d60833dbd973fe031a74e7ae31866bf70d077619e09edb6ff",
      "logsBloom": "0x00...00",
      "miner": "0x4200000000000000000000000000000000000011",
      "mixHash": "0x47aecef0e1afa26b8e1f428e9a8696cf53d85c62587d8c2cea079c715cd29626",
      "nonce": "0x0000000000000000",
      "number": "0x2c31b0b",
      "parentBeaconBlockRoot": "0x15b9e7c8ac4cbe92dafc849ed30a23e91624bbe5cbe199c0ccea3f7de7fc6d49",
      "parentHash": "0x89f4c9e23a2f706f0afa9ca8f770c4b7dcbcb73ba7e9b1c29c4a8c1b90c31d24",
      "receiptsRoot": "0x5a428d77344334537d7adaf85a45eb6d7977bc807a68c669f36cb043600da6d2",
      "requestsHash": "0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "size": "0x1bb3b",
      "stateRoot": "0x1b1525af0cdd504147b89f2a7ce1838ccb70c5439c45ce55522c2e2529801e87",
      "timestamp": "0x6a1092f9",
      "transactionsRoot": "0x6b9c9fcbdf98a8f4d38a3c16d099e9f0c7b7b474c2f5e044af7c91949c04a234",
      "withdrawals": [],
      "withdrawalsRoot": "0x57f4414a70a4af5e1a97b5fd8b8c6c870c00e8d9dbc0fde0059ce46e2cd28e5b"
    }
  }
}

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x2a7bc8d4e3f5a6b1c2d3e4f5a6b7c8d9",
    "result": {
      "address": "0xef5997c2cf2f6c138196f8a6203afc335206b3c1",
      "blockHash": "0xc104d3b3a4008d854c21f25ff41917e2bff0f0d28eacd348cc664b891d9db00c",
      "blockNumber": "0x2c70f90",
      "blockTimestamp": "0x6a187c03",
      "data": "0x0000000000000000000000000000000000000000000000078e0cf33a1d658000",
      "logIndex": "0x0",
      "removed": false,
      "topics": [
        "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
        "..."
      ],
      "transactionHash": "0x9efe32df11e30a345c5908ff4db248895c8e4b0d83c4d368fe14042ebbd3a130",
      "transactionIndex": "0x2"
    }
  }
}