---
title: "gen_subscribe"
description: "Opens a subscription to a stream of GenLayer consensus events over the node's inbound WebSocket endpoint. Notifications are pushed as they occur, removing the…"
source: https://docs.genlayer.com/api-references/genlayer-node/gen/gen_subscribe
last_updated: 2026-10-19
---

# gen_subscribe

### gen_subscribe

Opens a subscription to a stream of GenLayer consensus events over the node's inbound WebSocket endpoint. Notifications are pushed as they occur, removing the need to poll `gen_getTransactionStatus`.

**Method:** `gen_subscribe`

**Transport:** WebSocket only. This method is not available over HTTP — an HTTP POST cannot receive push notifications. See the WebSocket endpoint section for the URL.

**Parameters:**

- `stream` (string, required): The event stream to subscribe to. One of `transactions`, `leadership`, `epochs`, `newHeads`.

**Returns:** A subscription id (UUID v4 string) used to correlate notifications and to cancel via `gen_unsubscribe`

**Streams:**

| Stream | Event kinds delivered |
|--------|-----------------------|
| `transactions` | `NewTransaction`, `TransactionActivated`, `TransactionReceiptProposed`, `VoteCommitted`, `VoteRevealed`, `TransactionAccepted`, `TransactionFinalized`, `TransactionUndetermined` |
| `leadership` | `TransactionLeaderRotated`, `TransactionLeaderTimeout`, `TransactionLeaderChanged`, `TransactionLeaderRevealed`, `LeaderIdlenessProcessed`, `AppealStarted` |
| `epochs` | `EpochAdvance`, `EpochFinalize`, `TimeoutsSet`, `SetEpochMinDuration` |
| `newHeads` | `NewHeader` |

**Notification Fields:**

| Field | Type | Description |
|-------|------|-------------|
| `kind` | string | The event name, matching the consensus contract's ABI event (e.g. `TransactionAccepted`) |
| `event` | object | The decoded event payload. `bytes32` values are 0x-prefixed hex; field names are camelCase |
| `event.raw` | object | The originating chain log (block hash, transaction hash, topics), for reconciling against `gen_getLogs` |

**Example Request:**

```json
{
  "jsonrpc": "2.0",
  "method": "gen_subscribe",
  "params": [
    "transactions"
  ],
  "id": 1
}
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": "b3f1c2de-9a44-4c1e-8f77-2b0a5d6e1c33",
  "id": 1
}
```

**Example Notification:**

```json
{
  "jsonrpc": "2.0",
  "method": "gen_subscription",
  "params": {
    "subscription": "b3f1c2de-9a44-4c1e-8f77-2b0a5d6e1c33",
    "result": {
      "kind": "TransactionAccepted",
      "event": {
        "txId": "0x9c1f3a7b8d2e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e",
        "raw": {
          "address": "0x1234567890abcdef1234567890abcdef12345678",
          "blockNumber": "0x151ec5",
          "transactionHash": "0x4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c"
        }
      }
    }
  }
}
```

**Notes:**

- The subscription id is a UUID v4 generated by this node; it is never an upstream chain subscription id
- Streams are coarse by design: one subscription covers a whole lifecycle, so following a transaction end to end costs one subscription rather than one per event kind
- The `kind` values are the consensus contracts' ABI event names, which are stable across node releases. They are deliberately not the node's internal topic names
- Every payload is derived from on-chain logs and contains no node-private data. The node's own GenVM sync position is not exposed here; use `gen_syncing`
- `newHeads` is served for convenience and duplicates `eth_subscribe("newHeads")`, which is fed from the same upstream. Latency-sensitive clients should prefer `eth_subscribe`
- Notifications are live only — there is no historical replay or backfill. Reconcile any gap with `gen_getLogs`
- Server-side filtering (for example by `txId`) is not supported; subscribe to the stream and filter client-side
- Subscribing to an unknown stream returns error code `-32602` with the list of supported streams
- Exceeding `max_subs_per_conn` returns error code `-32000` ("subscription limit reached")
- This method belongs to the `genlayer` endpoint group; disabling that group disables it on the WebSocket transport too
- Standard clients can consume this with their generic subscription API, since notifications use the conventional `gen_subscription` envelope. In go-ethereum: `client.Subscribe(ctx, "gen", ch, "transactions")`

**wscat Example:**

```bash
wscat -c ws://localhost:9151/ws
> {"jsonrpc":"2.0","method":"gen_subscribe","params":["transactions"],"id":1}
< {"jsonrpc":"2.0","result":"b3f1c2de-9a44-4c1e-8f77-2b0a5d6e1c33","id":1}
< {"jsonrpc":"2.0","method":"gen_subscription","params":{"subscription":"b3f1c2de-9a44-4c1e-8f77-2b0a5d6e1c33","result":{"kind":"NewTransaction","event":{"txId":"0x9c1f..."}}}}
```