---
title: "eth_subscribe"
description: "Opens a real-time WebSocket subscription. Flashblocks endpoints add three subscription types and emit newHeads roughly every 200ms."
source: https://basehub.org/api-reference/eth/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`](/api-reference/flashblocks/newFlashblockTransactions/), [`pendingLogs`](/api-reference/flashblocks/pendingLogs/), and [`newFlashblocks`](/api-reference/flashblocks/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:

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

## Example

### Subscribe to newHeads

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

### Subscribe to logs (with filter)

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

### Subscription ID response

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

### newHeads event

```json
{
  "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

```json
{
  "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
    }
  }
}
```