Beacon API: Ethereum Consensus Node REST Interface Explained

Scope and the two things called Beacon API

This page covers the Ethereum Beacon API: the RESTful HTTP interface exposed by a beacon node implementation of the consensus layer, specified in the ethereum/beacon-APIs repository and rendered as an OpenAPI document. It is the interface a validator client uses to talk to its beacon node, and the interface explorers, indexers, and monitoring tools use to read consensus data.

The name is overloaded. The browser navigator.sendBeacon() Web API is unrelated: it sends a small asynchronous POST when a page unloads, typically for analytics. If you arrived looking for that, the MDN and W3C Beacon documentation is the right reference. Everything below concerns the Ethereum consensus REST API, which is the meaning relevant to node operators and validator infrastructure.

• Ethereum Beacon API: REST/HTTP, JSON by default, SSZ for a subset of endpoints, versioned per endpoint.
• Browser Beacon API: a single navigator.sendBeacon() method, no response expected, not available in Web Workers.
• This article is about the former; the two share a name and nothing else.

Assumptions before you start

The procedure assumes you have access to a running beacon node, either self-hosted or through a managed RPC provider, and that you know whether its HTTP API is exposed on localhost or behind a gateway. Public exposure of a beacon node API is discouraged by the specification itself, because several endpoints trigger heavy processing and can be abused for denial-of-service. Treat the API as an internal service unless you have added authentication and rate limiting in front of it.

You also need curl and, for the SSZ examples, a tool that can write binary output to a file. No validator keys are required for the read-only diagnostics; submitting blocks or attestations does require a validator client and signing setup, which is out of scope here.

Mental model: beacon node, validator client, and the REST boundary

A beacon node maintains the state of the beacon chain by communicating with peers. Conceptually it does not hold validator keypairs. A validator client is a separate process that holds private keys, decides what to sign, and uses the beacon node's API to fetch duties, produce blocks and attestations, and broadcast signed messages. The API is therefore both a read surface (chain data, config, node info) and a write surface (pool submissions, block and attestation publication).

Endpoints are individually versioned. There is no relationship between all v1 endpoints and all v2 endpoints; you must read the version on each path. Responses return requested data under a top-level data key, with optional metadata in sibling keys. Fields may be added without a version bump, but removing or changing the format of a listed field requires one. That rule is what makes it safe to build clients that ignore unknown fields.

Endpoint groups and what each is for

The OpenAPI document groups endpoints by purpose. Knowing the groups helps you pick the right path and avoid accidentally exposing debug routes.

The Beacon group queries beacon chain state and objects: headers, blocks, states, and pools. The Config group returns chain configuration, specification values, and fork schedules. The Node group returns node identity and health information such as version and syncing status. The Validator group is intended for validator clients and includes the minimal set of endpoints needed for a working validator implementation, plus a documented validator flow. The Events group provides event subscriptions, typically over server-sent events. The Rewards group queries rewards and penalties. The Debug group is explicitly marked as not for public exposure.

• Read-only chain queries: Beacon group.
• Fork schedule and spec constants: Config group.
• Health and identity checks: Node group.
• Validator duties, block production, and submissions: Validator group.
• Streaming updates: Events group.
• Diagnostics only: Debug group, keep private.

JSON, SSZ, and content negotiation

By default requests send and receive JSON, so include Content-Type: application/json and Accept: application/json where a body is involved. A subset of endpoints can also accept or return SSZ, the consensus-layer serialization format. To send SSZ, set Content-Type: application/octet-stream. To prefer SSZ in a response, set an Accept header that ranks it above JSON, for example application/octet-stream;q=1.0,application/json;q=0.9.

The server contract is explicit: return 415 if the request Content-Type is unsupported, and 406 if it cannot produce a response in an accepted format. If no Accept header is sent, JSON is assumed. The server must indicate the response format in Content-Type. This matters when you write clients, because a 200 with an unexpected content type is a bug you should surface rather than parse blindly.

curl -sS -D - -o /dev/null \
  -H 'Accept: application/json' \
  "$BEACON_URL/eth/v1/node/version"

Runnable diagnostic: probe a beacon node in four calls

The following sequence is safe against any node you are authorized to query. It checks reachability, identity, sync status, and a chain read, and it records the HTTP status and content type for each call so you can distinguish a transport problem from a format problem. Set BEACON_URL to your node's base URL, for example http://127.0.0.1:5052 for a local node or your provider's HTTPS base URL.

Run each call and note the status code and Content-Type. A 200 with application/json on all four is the expected healthy result. A 415 or 406 points at your headers, not the node. A connection error points at the URL, firewall, or TLS. A 503 on the syncing endpoint is normal while the node is still catching up.

export BEACON_URL="http://127.0.0.1:5052"

# 1. Identity and version
curl -sS -w '\nHTTP %{http_code} %{content_type}\n' \
  -H 'Accept: application/json' \
  "$BEACON_URL/eth/v1/node/version"

# 2. Sync status
curl -sS -w '\nHTTP %{http_code} %{content_type}\n' \
  -H 'Accept: application/json' \
  "$BEACON_URL/eth/v1/node/syncing"

# 3. Chain configuration (fork schedule)
curl -sS -w '\nHTTP %{http_code} %{content_type}\n' \
  -H 'Accept: application/json' \
  "$BEACON_URL/eth/v1/config/fork_schedule"

# 4. A recent block header by id
curl -sS -w '\nHTTP %{http_code} %{content_type}\n' \
  -H 'Accept: application/json' \
  "$BEACON_URL/eth/v1/beacon/headers/head"

Verification: what a correct result looks like

A correct run returns JSON bodies with a top-level data key on each endpoint. The version endpoint returns node identity fields. The syncing endpoint returns a boolean and head-slot information; if the node is not synced, the head slot will lag the network. The fork schedule returns the configured forks and epochs. The headers endpoint returns the head block header with its root and slot.

Record your observations in a table so the run is reproducible and comparable across nodes or over time. Do not fill in numbers you did not observe; the table below is a template, not a set of results.

• | Check | Endpoint | Expected status | Expected content type | Observed |
• | Identity | /eth/v1/node/version | 200 | application/json | (record) |
• | Sync | /eth/v1/node/syncing | 200 | application/json | (record) |
• | Forks | /eth/v1/config/fork_schedule | 200 | application/json | (record) |
• | Head header | /eth/v1/beacon/headers/head | 200 | application/json | (record) |

Measuring latency and consistency yourself

Provider performance claims are not portable, so measure against your own workload. A simple method is to time a fixed set of read-only calls repeatedly and record the distribution, not just the mean. Use curl's time_total or a small script, run enough iterations to see tail behavior, and separate cold connections from reused ones.

The script below times the syncing endpoint and prints each sample. Run it against two candidate endpoints and compare medians and maxima. Keep the sample size and time window identical between endpoints, and note the time of day, because consensus nodes are busiest around slot boundaries.

import json, statistics, time, urllib.request

BEACON_URL = "http://127.0.0.1:5052"
PATH = "/eth/v1/node/syncing"
N = 30

samples = []
for _ in range(N):
    start = time.perf_counter()
    req = urllib.request.Request(BEACON_URL + PATH, headers={"Accept": "application/json"})
    with urllib.request.urlopen(req, timeout=10) as resp:
        body = json.loads(resp.read())
    elapsed_ms = (time.perf_counter() - start) * 1000
    samples.append(elapsed_ms)
    print(f"{elapsed_ms:8.1f} ms  synced={body['data'].get('is_synced')}")

print(f"median={statistics.median(samples):.1f} ms  max={max(samples):.1f} ms")

Troubleshooting common Beacon API failures

Most failures fall into a few buckets: wrong base URL or path version, header mismatch, node not synced, or an endpoint that is intentionally restricted. Work through them in that order before assuming a node is broken.

If you get 404, check the endpoint version in the path against the OpenAPI document for the node's supported API version; versions are per endpoint and older nodes may not implement newer paths. If you get 415 or 406, your Content-Type or Accept header is the cause. If reads succeed but data looks stale, check the syncing endpoint and the head slot. If a validator client cannot start, verify it is pointed at the correct beacon node URL and that the required validator endpoints are reachable.

• Connection refused or timeout: URL, port, firewall, or TLS termination.
• 404: wrong path or unsupported endpoint version on that node.
• 415/406: request or response format negotiation.
• Stale data: node syncing or behind the network head.
• 403/401: gateway or provider authentication layer in front of the node.

Limitations and tradeoffs

The Beacon API is not designed to be a public internet service. The specification warns that exposing it without additional security layers opens the node to denial-of-service through heavy endpoints. If you need public read access, put a caching, rate-limiting gateway in front of it and expose only the read endpoints you need.

SSZ support is partial: only a subset of endpoints accept or return it, and each is noted individually. JSON is the safe default for tooling and debugging. Versioning is per endpoint, so pinning to a single API version across all paths is not meaningful; instead, read the version on each path you depend on and test against the node versions you actually run.

Finally, the API is a node-local interface, not a consensus guarantee. Two healthy nodes can return slightly different heads at the same instant. Design clients to tolerate that rather than treating any divergence as an error.

Next steps for production use

Once your diagnostics pass, move from ad hoc calls to a monitored integration. Wrap the four checks above in a health probe, alert on non-200 responses and on sync lag, and log content types so format regressions are visible. For validator infrastructure, follow the documented validator flow rather than assembling endpoints by hand.

If you would rather not operate consensus nodes yourself, compare managed options and measure them with the same procedure. Start with the OnFinality networks directory to see supported chains, review RPC pricing for throughput and request limits, and consider a dedicated node when you need predictable capacity or private API exposure. For concrete endpoint and provider recommendations, use the RPC Assistant rather than guessing at public URLs.

• Browse supported chains in the OnFinality networks directory.
• Review RPC pricing and request limits before sizing a workload.
• Evaluate a dedicated node for private or high-volume Beacon API access.
• See the broader RPC service overview and the RPC endpoints guide.