--- updatedAt: 2025-09-18T22:07:02.000Z agentTools: projectIndex: https://docs.nodereal.io/llms.txt --- # Subscribe to beacon node events Provides endpoint to subscribe to beacon node Server-Sent-Events stream. Consumers should use [eventsource](https://html.spec.whatwg.org/multipage/server-sent-events.html#the-eventsource-interface) implementation to listen on those events. Servers _may_ send SSE comments beginning with `:` for any purpose, including to keep the event stream connection alive in the presence of proxy servers. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Eth Beacon Node API", "description": "API specification for the beacon node, which enables users to query and participate in Ethereum 2.0 phase 0 beacon chain.\n\nAll requests by default send and receive JSON, and as such should have either or both of the \"Content-Type: application/json\"\nand \"Accept: application/json\" headers. In addition, some requests can return data in the SSZ format. To indicate that SSZ\ndata is required in response to a request the header \"Accept: application/octet-stream\" should be sent. Note that only a subset\nof requests can respond with data in SSZ format; these are noted in each individual request.\n\nAPI endpoints are individually versioned. As such, there is no direct relationship between all v1 endpoints, all v2 endpoints,\n_etc._ and no such relationship should be inferred. All JSON responses return the requested data under a `data` key in the top\nlevel of their response. Additional metadata may or may not be present in other keys at the top level of the response, dependent\non the endpoint. The rules that require an increase in version number are as follows:\n\n - no field that is listed in an endpoint shall be removed without an increase in the version number\n - no field that is listed in an endpoint shall be altered in terms of format (_e.g._ from a string to an array) without an\n increase in the version number\n\nNote that it is possible for a field to be added to an endpoint's data or metadata without an increase in the version number.\n", "version": "v2.3.0 - Eth2Spec v1.1.0", "contact": { "name": "Ethereum Github", "url": "https://github.com/ethereum/beacon-apis/issues" }, "license": { "name": "CC0-1.0", "url": "https://creativecommons.org/publicdomain/zero/1.0/" } }, "servers": [ { "url": "{server_url}/{api_key}", "variables": { "server_url": { "description": "Beacon node API url", "default": "eth2-beacon-mainnet.nodereal.io/v1" }, "api_key": { "description": "Beacon node API key", "default": "api_key" } } } ], "tags": [ { "name": "Events", "description": "Set of endpoints to for event subscription." }, { "name": "ValidatorRequiredApi", "description": "Minimal set of endpoints to enable a working validator implementation.\n\n[Checkout validator flow](./validator-flow.md) to learn how to use this api.\n" } ], "paths": { "/eth/v1/events": { "get": { "operationId": "eventstream", "summary": "Subscribe to beacon node events", "tags": [ "Events", "ValidatorRequiredApi" ], "description": "Provides endpoint to subscribe to beacon node Server-Sent-Events stream.\nConsumers should use [eventsource](https://html.spec.whatwg.org/multipage/server-sent-events.html#the-eventsource-interface)\nimplementation to listen on those events.\n\nServers _may_ send SSE comments beginning with `:` for any purpose, including to keep the\nevent stream connection alive in the presence of proxy servers.\n", "parameters": [ { "name": "topics", "in": "query", "required": true, "description": "Event types to subscribe to", "schema": { "type": "array", "items": { "type": "string", "uniqueItems": true, "enum": [ "head", "block", "attestation", "voluntary_exit", "finalized_checkpoint", "chain_reorg", "contribution_and_proof" ] } } } ], "responses": { "200": { "description": "Opened SSE stream.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format" }, "examples": { "head": { "description": "The node has finished processing, resulting in a new head. previous_duty_dependent_root is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)` and current_duty_dependent_root is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1)`. Both dependent roots use the genesis block root in the case of underflow.", "value": "event: head\ndata: {\"slot\":\"10\", \"block\":\"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf\", \"state\":\"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9\", \"epoch_transition\":false, \"previous_duty_dependent_root\":\"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91\", \"current_duty_dependent_root\":\"0x5e0043f107cb57913498fbf2f99ff55e730bf1e151f02f221e977c91a90a0e91\", \"execution_optimistic\": false}\n" }, "block": { "description": "The node has received a valid block (from P2P or API)", "value": "event: block\ndata: {\"slot\":\"10\", \"block\":\"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf\", \"execution_optimistic\": false}\n" }, "attestation": { "description": "The node has received a valid attestation (from P2P or API)", "value": "event: attestation\ndata: {\"aggregation_bits\":\"0x01\", \"signature\":\"0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505\", \"data\":{\"slot\":\"1\", \"index\":\"1\", \"beacon_block_root\":\"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2\", \"source\":{\"epoch\":\"1\", \"root\":\"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2\"}, \"target\":{\"epoch\":\"1\", \"root\":\"0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2\"}}}\n" }, "voluntary_exit": { "description": "The node has received a valid voluntary exit (from P2P or API)", "value": "event: voluntary_exit\ndata: {\"message\":{\"epoch\":\"1\", \"validator_index\":\"1\"}, \"signature\":\"0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505\"}\n" }, "finalized_checkpoint": { "description": "Finalized checkpoint has been updated", "value": "event: finalized_checkpoint\ndata: {\"block\":\"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf\", \"state\":\"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9\", \"epoch\":\"2\", \"execution_optimistic\": false }\n" }, "chain_reorg": { "description": "The node has reorganized its chain", "value": "event: chain_reorg\ndata: {\"slot\":\"200\", \"depth\":\"50\", \"old_head_block\":\"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf\", \"new_head_block\":\"0x76262e91970d375a19bfe8a867288d7b9cde43c8635f598d93d39d041706fc76\", \"old_head_state\":\"0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf\", \"new_head_state\":\"0x600e852a08c1200654ddf11025f1ceacb3c2e74bdd5c630cde0838b2591b69f9\", \"epoch\":\"2\", \"execution_optimistic\": false}\n" }, "contribution_and_proof": { "description": "The node has received a valid sync committee SignedContributionAndProof (from P2P or API)", "value": "event: contribution_and_proof\ndata: {\"message\": {\"aggregator_index\": \"997\", \"contribution\": {\"slot\": \"168097\", \"beacon_block_root\": \"0x56f1fd4262c08fa81e27621c370e187e621a67fc80fe42340b07519f84b42ea1\", \"subcommittee_index\": \"0\", \"aggregation_bits\": \"0xffffffffffffffffffffffffffffffff\", \"signature\": \"0x85ab9018e14963026476fdf784cc674da144b3dbdb47516185438768774f077d882087b90ad642469902e782a8b43eed0cfc1b862aa9a473b54c98d860424a702297b4b648f3f30bdaae8a8b7627d10d04cb96a2cc8376af3e54a9aa0c8145e3\"}, \"selection_proof\": \"0x87c305f04bfe5db27c2b19fc23e00d7ac496ec7d3e759cbfdd1035cb8cf6caaa17a36a95a08ba78c282725e7b66a76820ca4eb333822bd399ceeb9807a0f2926c67ce67cfe06a0b0006838203b493505a8457eb79913ce1a3bcd1cc8e4ef30ed\"}, \"signature\": \"0xac118511474a94f857300b315c50585c32a713e4452e26a6bb98cdb619936370f126ed3b6bb64469259ee92e69791d9e12d324ce6fd90081680ce72f39d85d50b0ff977260a8667465e613362c6d6e6e745e1f9323ec1d6f16041c4e358839ac\"}\n" } } } } }, "400": { "description": "The topics supplied could not be parsed", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "code": { "description": "Either specific error code in case of invalid request or http status code", "type": "number", "example": 404 }, "message": { "description": "Message describing error", "type": "string" }, "stacktraces": { "description": "Optional stacktraces, sent when node is in debug mode", "type": "array", "items": { "type": "string" } } } }, { "example": { "code": 400, "message": "Invalid topic: weather_forecast" } } ] } } } }, "500": { "description": "Beacon node internal error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "Either specific error code in case of invalid request or http status code", "type": "number", "example": 404 }, "message": { "description": "Message describing error", "type": "string" }, "stacktraces": { "description": "Optional stacktraces, sent when node is in debug mode", "type": "array", "items": { "type": "string" } } } }, "example": { "code": 500, "message": "Internal server error" } } } } } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```