eth_subscribe

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 — choose a WebSocket-capable provider from the Builder Stack.

Parameters

string

required

The event type to subscribe to.

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

Show Filter Options (Logs Only)

string | array

A contract address or array of addresses to filter by. Optional.

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

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:

Event Notification

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

Example

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

Overview

CLIs

Base Chain API

Tokenized Stocks API

Base Verify API

Migrated Documentation

Parameters

Subscription Types

Returns

Example

​Parameters

​Subscription Types

​Returns

​Example

Parameters

Subscription Types

Returns

Example