TL;DR
Ethereum runs as two layers. The execution layer handles transactions, smart contracts, and balances, and you read it with JSON-RPC. The consensus layer handles proof of stake: validators, block proposals, and finality. The Beacon API is the REST interface for reading that consensus-layer data, and this guide covers what it is, the endpoints you’ll actually use, and how to read them safely in production.
The one thing to get right is which point in the chain you read from. Data at the tip can still change, while finalized data won’t. That single choice keeps production systems from acting on data that later gets reversed.
Why the Beacon API exists
Before September 15, 2022, Ethereum was one chain with one interface. You ran a node, you talked to it over JSON-RPC, done.
The Merge changed that. Ethereum retired proof-of-work mining and moved consensus onto a separate proof-of-stake chain called the Beacon Chain. The old chain became the execution layer. The Beacon Chain became the consensus layer. A node now runs two clients side by side: an execution client and a consensus client. (For the full history, here’s a step-by-step explainer on the Merge.)
So the interfaces split too. The execution layer kept JSON-RPC, which answers questions about accounts and transactions: a balance for an address, a receipt for a transaction hash, the result of a contract call. Consensus data has no addresses or transaction hashes at all. It’s organized by validator, slot, epoch, and checkpoint, so it has its own REST API: the Beacon API.
How the Beacon API works
The Beacon API is the standard HTTP interface to a consensus-layer node. It’s defined in the open ethereum/beacon-APIs specification, which every major client implements the same way.
It works differently from JSON-RPC. JSON-RPC sends a POST with a method name and a params array to a single endpoint. The Beacon API gives each resource its own URL, and you fetch it with GET:
GET /eth/v1/beacon/genesis
GET /eth/v1/node/syncing
GET /eth/v1/beacon/states/finalized/finality_checkpoints
Responses are JSON, with the payload under a data key. Large endpoints (full blocks, full states) also accept Accept: application/octet-stream to return SSZ, a compact binary encoding that’s faster to transfer and parse. JSON is the default and what you’ll use most of the time.
The words you need first
A few consensus terms show up in almost every response. Quick definitions:
- Slot: a 12-second window in which one validator can propose a block. Some slots stay empty.
- Epoch: 32 slots, about 6.4 minutes. Validator duties and finality are organized by epoch.
- Validator: a participant that staked at least 32 ETH to help run consensus. There are close to 1 million of them.
- Attestation: a validator’s vote that a block is valid and sits at the head of the chain.
- Justified, then finalized: a checkpoint that enough validators vote for becomes justified, and once a later checkpoint builds on it, it becomes finalized. Finalizing takes about two epochs, roughly 13 minutes. Finalized blocks are treated as permanent, for reasons we’ll get to in Reading consensus data safely in production.
Most of the endpoints below are just these concepts in JSON.
How a Beacon API request is shaped
Every Beacon API path follows one pattern:
/eth/v{version}/{namespace}/{resource}/{identifier}
Learn it once and the whole API gets predictable.
The main namespaces
- beacon: the chain itself. Blocks, states, validators, attestations, blobs. Where you’ll spend most of your time.
- node: health and sync status of the node you’re talking to.
- config: network constants and the fork schedule.
- validator: duties for validator clients, like who proposes a block and when. Mostly used by staking software.
- events: a live stream of chain events (covered below).
- debug: heavy state dumps for debugging. Expensive to serve, so keep it off the public internet.
- rewards: per-block and per-validator reward and penalty breakdowns, served under /eth/v1/beacon/rewards/….
State and block identifiers
The {identifier} is where the Beacon API gets its precision. Instead of a block number, you pass a label that names a point in chain history:
- head: the latest block this node knows about. Fast, but can be reorged away.
- finalized: the latest finalized checkpoint. Settled.
- justified: one step before finalized — valid for state reads, but not accepted as a block identifier.
- a slot number, like 7500000.
- a 0x-prefixed block root or state root.
So …/states/head/validators/… reads from the chain tip, while …/states/finalized/validators/… reads from settled state. The only thing that changed is the identifier, and it decides how much you can trust the result.
The endpoints you’ll actually use
A short tour. The examples use a Chainstack consensus endpoint, which has the shape https://beacon-nd-xxx-xxx-xxx.p2pify.com/AUTH_KEY/.
Is the node ready to serve?
curl https://beacon-nd-123-456-789.p2pify.com/AUTH_KEY/eth/v1/node/syncing
What’s finalized right now?
curl https://beacon-nd-123-456-789.p2pify.com/AUTH_KEY/eth/v1/beacon/states/finalized/finality_checkpoints
A validator’s status and balance, the core of any staking dashboard:
curl https://beacon-nd-123-456-789.p2pify.com/AUTH_KEY/eth/v1/beacon/states/head/validators/123456
The response includes a status such as active_ongoing, active_slashed, exited_unslashed, or pending_queued, plus the validator’s balance. That’s most of a staking monitor in one call. The same request in JavaScript:
“`
const BASE = “https://beacon-nd-123-456-789.p2pify.com/AUTH_KEY”;
const res = await fetch(`${BASE}/eth/v1/beacon/states/head/validators/123456`);
const { data } = await res.json();
console.log(data.status, data.balance);
“`
Streaming live data with the events endpoint
Polling for new blocks wastes requests. The events endpoint is a Server-Sent Events stream: open one connection and the node pushes events as they happen.
curl -N -H “Accept: text/event-stream” \
“https://beacon-nd-123-456-789.p2pify.com/AUTH_KEY/eth/v1/events?topics=head,finalized_checkpoint,chain_reorg”
The topics that matter most: head (a new chain head), finalized_checkpoint (a checkpoint just finalized), and chain_reorg (the head changed under you). An indexer subscribes to head to ingest blocks and to chain_reorg to know when to roll back. A bridge subscribes to finalized_checkpoint to catch the exact moment new state became irreversible.
A long-lived stream like this needs an endpoint that holds the connection open without dropping it, which is one reason teams point this at a managed provider instead of a home node on a flaky connection.
Worked example: reading a block’s blob data
Blobs are the data that L2 rollups post to Ethereum (introduced by EIP-4844 in March 2024). A block references its blobs, but the blob data itself isn’t kept on-chain permanently. The consensus layer holds blobs for about 18 days, then prunes them. So the Beacon API is where you read blob data, and only within that window.
The endpoint is blobs, keyed by a block identifier:
curl https://beacon-nd-123-456-789.p2pify.com/AUTH_KEY/eth/v1/beacon/blobs/head
Pulling the blobs for a specific slot in JavaScript:
“`
const BASE = “https://beacon-nd-123-456-789.p2pify.com/AUTH_KEY”;
const slot = 7500000;
const res = await fetch(`${BASE}/eth/v1/beacon/blobs/${slot}`);
const { data } = await res.json();
for (const [index, blob] of data.entries()) {
console.log(`blob ${index}: ${blob.length} hex chars`);
// each entry is the raw blob data itself, a 0x-prefixed hex string
}
“`
Reading consensus data safely in production
The same query can give a safe answer or a dangerous one depending on the identifier. Three habits keep you out of trouble.
Read finalized for anything irreversible. A bridge that releases funds when it sees a deposit at head can lose money if that block reorgs. Reading at finalized costs about 13 minutes of latency and removes that risk, because reversing a finalized block is expensive by design. Finalizing a checkpoint takes a two-thirds majority of validators, so two conflicting blocks can only both finalize if at least a third of them vote for both. That double-voting is provable, and the protocol punishes it by destroying the offending validators’ stake, a penalty called slashing. A third of all staked ETH is millions of ETH, worth tens of billions of dollars, so in practice a finalized block never reverts. Match the identifier to the cost of being wrong: head for speed, finalized for anything you can’t undo.
Check the execution_optimistic flag. Beacon API responses include a top-level execution_optimistic boolean. When it’s true, the node has accepted the block on the consensus side but hasn’t verified its execution payload yet, so the data can still change. Treat execution_optimistic: true as “not final, don’t act on it.” A companion finalized boolean in the response tells you whether the data came from finalized state.
Filter the heavy endpoints. The full validator set and the debug namespace can each return hundreds of megabytes. Always pass indices, a status filter, or a specific slot.
| Identifier | What it means | Use it for |
|---|---|---|
| head | Latest block, can reorg | UI, live feeds, indexer ingest |
| justified | One step from finality | Diagnostics, rarely |
| finalized | Settled, won’t revert | Bridges, exchanges, accounting |
| slot / root | An exact point in history | Backfills, audits, blob reads |
Getting a consensus-layer endpoint
The Beacon API only exists if you have a consensus-layer node to talk to. Running one yourself means an execution client plus a consensus client, a fast 2 TB SSD (Geth and a consensus client together; more for an archive node), and an initial sync that can take a day or more before the node is usable.
The shortcut is a provider. When you deploy an Ethereum node on Chainstack, you get both endpoints: the execution-layer JSON-RPC URL and the consensus-layer Beacon API URL, already synced. The Beacon endpoint is the beacon-nd-….p2pify.com URL used in the examples above, and every path is documented with runnable examples in the Beacon Chain API reference. For a staking dashboard or a bridge that only needs to read consensus data, that’s enough to start.
Conclusion
The Beacon API is how you read Ethereum’s consensus layer: validators, slots, attestations, and finality, served over plain REST. The path pattern is consistent, the namespaces are few, and most real work uses a handful of endpoints you can curl.
Most production bugs trace to one choice: which identifier you read from. head is fast and reversible, finalized is slower and settled, and execution_optimistic tells you when even a recent answer isn’t safe yet. Pick the one that matches what happens if you’re wrong, and the rest is just HTTP.
To use the Beacon API you need a consensus-layer node running alongside an execution client. Chainstack gives you both endpoints on the same Ethereum node deployment, already synced — the same beacon-nd-….p2pify.com URL used throughout this guide. Point your code at it and start querying.
FAQ
It’s the REST/HTTP interface to Ethereum’s consensus layer, the Beacon Chain. You use it to read validators, slots, epochs, attestations, finality checkpoints, and blob data. It’s a separate interface from JSON-RPC, which reads the execution layer (transactions, contracts, balances).
JSON-RPC is a single endpoint you POST method calls to, like eth_getBalance, and it returns execution-layer data. The Beacon API is REST: each resource has its own URL that you GET, and it returns consensus-layer data such as validators and finality. A full Ethereum node exposes both, because it runs both an execution client and a consensus client.
The execution layer runs transactions and smart contracts and tracks account balances. The consensus layer (the Beacon Chain) runs proof of stake: it selects who proposes blocks, collects validator votes, and decides finality. The Merge in September 2022 split these into two clients running inside one node.
Read /eth/v1/beacon/states/finalized/finality_checkpoints, or request your data at the finalized identifier instead of head. You can also watch the finalized_checkpoint topic on the events stream. Finalization happens about 13 minutes (two epochs) after a block is produced.
It’s a boolean flag at the top level of the response. true means the consensus client accepted the block but hasn’t verified its execution payload yet, so the data can still change. Wait for execution_optimistic: false before acting on the response in anything financial.
Send a GET to /eth/v1/beacon/states/head/validators/{index}, using either the validator index or its public key as the identifier. The response includes the validator’s status (for example active_ongoing or active_slashed) and balance. Avoid requesting the full validator set unfiltered, since it has close to 1 million entries.
Send a GET to /eth/v1/beacon/blobs/{block_id} for a block’s raw blob data. The older /eth/v1/beacon/blob_sidecars/{block_id} still works and adds each blob’s kzg_commitment, but it has been deprecated since the Fusaka upgrade (its kzg_proof field now returns empty). Blobs are pruned after about 18 days, so index anything you need for the long term. A block with no blobs returns an empty array, and some clients return 404 for that case.
Yes. A GET to /eth/v1/events?topics=head,finalized_checkpoint,chain_reorg opens a Server-Sent Events stream that pushes events as they happen, so you don’t have to poll for changes.
No. You can run a consensus client yourself, or use a provider. Chainstack gives you a consensus-layer endpoint alongside the execution-layer one when you deploy an Ethereum node, already synced.
A slot is a 12-second window in which one validator can propose a block. An epoch is 32 slots, about 6.4 minutes, and it’s the unit consensus uses to organize validator duties and finality.