> ## Documentation Index
> Fetch the complete documentation index at: https://daehan-base.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tip>
  **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`](/base-chain/api-reference/flashblocks-api/newFlashblockTransactions), [`pendingLogs`](/base-chain/api-reference/flashblocks-api/pendingLogs), and [`newFlashblocks`](/base-chain/api-reference/flashblocks-api/newFlashblocks).
</Tip>

## Parameters

<ParamField body="subscriptionType" type="string" required>
  The event type to subscribe to.
</ParamField>

<ParamField body="filterOptions" type="object">
  Optional filter options. Only applicable for the `"logs"` subscription type.

  <Expandable title="Filter options (logs only)">
    <ParamField body="address" type="string | array">
      A contract address or array of addresses to filter by. Optional.
    </ParamField>

    <ParamField body="topics" type="array">
      Array of topic filters in the same format as `eth_getLogs`. Optional.
    </ParamField>
  </Expandable>
</ParamField>

## 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

<ResponseField name="result" type="string">
  A hex-encoded subscription ID. All event notifications from this subscription include this ID in `params.subscription`.
</ResponseField>

Event notifications arrive as unsolicited JSON-RPC messages:

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

## Example

<CodeGroup>
  ```json Subscribe to newHeads theme={null}
  {"jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"], "id": 1}
  ```

  ```json Subscribe to logs (with filter) theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_subscribe",
    "params": [
      "logs",
      {
        "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
      }
    ]
  }
  ```

  ```json Subscription ID Response theme={null}
  {"jsonrpc": "2.0", "id": 1, "result": "0x1887ec8b9589ccad00000000000532da"}
  ```

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

  ```json logs Event theme={null}
  {
    "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
      }
    }
  }
  ```
</CodeGroup>