Ethereum Beacon Chain API Guide: Consensus Layer RPC (2026)
The Ethereum Beacon Chain API is not a JSON-RPC interface. That distinction matters more than any other fact in this guide. Every other chain on BoltRPC uses JSON-RPC: you POST to a single endpoint with a method name and parameters. The Beacon Chain uses a REST API with dedicated URL paths per resource, standard HTTP GET requests, with responses that contain consensus layer data types: slots, epochs, validators, finality checkpoints. If you send a JSON-RPC call to a Beacon endpoint, you get nothing useful back.
This guide covers how the Beacon API works, which endpoints matter, how to connect with curl, JavaScript, and Python. It also covers what to watch out for in production. For endpoint setup and chain specs, see the Ethereum Beacon Chain endpoint page.
Execution Layer vs Consensus Layer: What Each API Covers
Ethereum runs as two layers. Understanding which layer you need determines which API you use.
Execution layer (JSON-RPC): This is the layer most developers work with. Smart contracts live here. Transactions are processed here. eth_call, eth_getBalance, eth_getLogs, eth_sendRawTransaction all belong to the execution layer. The Ethereum execution layer endpoint handles these requests.
Consensus layer (Beacon API): This layer manages validators, proof-of-stake consensus, finality, and coordination between the two layers. It has no concept of smart contract addresses, gas, or transaction hashes. Instead it exposes slots, epochs, validator indices, attestations, and finality checkpoints via REST.
You need the Beacon API if you are building:
- Staking dashboards or validator monitoring tools
- Liquid staking protocols that track validator status
- Bridges or cross-chain protocols that require finality confirmation
- MEV research or block proposal analysis
- Any application that needs to know when a block is truly finalized (not just included)
For standard dApp development, the execution layer JSON-RPC is all you need. The Beacon API adds the consensus layer on top.
Key Beacon Chain REST Endpoints
The Beacon API follows a consistent path structure: /eth/v[version]/[resource]/[identifier]. All requests are standard HTTP GET unless noted.
Node status
GET /eth/v1/node/syncing
Returns the current sync status of the beacon node. Use this first to verify your connection is working and the node is at the chain head before sending production queries.
Validator set
GET /eth/v1/beacon/states/head/validators
Returns the full current validator set. Query a specific validator by appending its index: /eth/v1/beacon/states/head/validators/{validator_index}. Status values: active_ongoing, active_exiting, active_slashed, pending_queued, pending_initialized, exited_unslashed, exited_slashed.
Finality checkpoints
GET /eth/v1/beacon/states/{state_id}/finality_checkpoints
Returns the latest justified and finalized checkpoints. The state_id can be head, finalized, justified, or a specific slot number. In production, use finalized as the state identifier when you need confirmed data.
Block retrieval
GET /eth/v2/beacon/blocks/{block_id}
Retrieves a full beacon block. The block_id can be head, genesis, finalized, or a slot number. Use v2 (not v1) for full block content including the execution payload.
Block headers
GET /eth/v1/beacon/headers/head
Returns the latest beacon block header including slot number, proposer index, and parent root. Lighter than fetching a full block when you only need the current slot position.
Connecting Step by Step
Authentication
The Beacon API uses Authorization: Bearer YOUR_KEY header authentication. This is different from the execution layer endpoint, which accepts ?auth=YOUR_KEY as a query parameter. Both patterns use the same API key from your BoltRPC account.
curl
Check sync status:
curl "https://eu.endpoints.matrixed.link/rpc/ethereum-beacon/eth/v1/node/syncing" \
-H "Authorization: Bearer YOUR_KEY"Fetch finality checkpoints:
curl "https://eu.endpoints.matrixed.link/rpc/ethereum-beacon/eth/v1/beacon/states/finalized/finality_checkpoints" \
-H "Authorization: Bearer YOUR_KEY"Get a specific validator by index:
curl "https://eu.endpoints.matrixed.link/rpc/ethereum-beacon/eth/v1/beacon/states/head/validators/12345" \
-H "Authorization: Bearer YOUR_KEY"JavaScript (fetch)
const BASE = "https://eu.endpoints.matrixed.link/rpc/ethereum-beacon";
const KEY = "YOUR_KEY";
async function beaconGet(path) {
const res = await fetch(`${BASE}${path}`, {
headers: { "Authorization": `Bearer ${KEY}` }
});
if (!res.ok) throw new Error(`Beacon API error: ${res.status}`);
return res.json();
}
// Check sync status
const sync = await beaconGet("/eth/v1/node/syncing");
console.log("Head slot:", sync.data.head_slot);
console.log("Syncing:", sync.data.is_syncing);
// Get validator status
const validator = await beaconGet("/eth/v1/beacon/states/head/validators/12345");
console.log("Status:", validator.data.status);
console.log("Balance:", validator.data.balance);
// Get finality checkpoint
const checkpoints = await beaconGet("/eth/v1/beacon/states/finalized/finality_checkpoints");
console.log("Finalized epoch:", checkpoints.data.finalized.epoch);Python (requests)
import requests
BASE = "https://eu.endpoints.matrixed.link/rpc/ethereum-beacon"
HEADERS = {"Authorization": "Bearer YOUR_KEY"}
def beacon_get(path):
resp = requests.get(f"{BASE}{path}", headers=HEADERS, timeout=10)
resp.raise_for_status()
return resp.json()
# Get latest block header
header = beacon_get("/eth/v1/beacon/headers/head")
slot = header["data"]["header"]["message"]["slot"]
print(f"Current slot: {slot}")
# Get finality checkpoints
checkpoints = beacon_get("/eth/v1/beacon/states/finalized/finality_checkpoints")
finalized_epoch = checkpoints["data"]["finalized"]["epoch"]
print(f"Finalized epoch: {finalized_epoch}")Use Cases
Staking dashboards. Validator monitoring tools query /eth/v1/beacon/states/head/validators/{index} at each epoch boundary (roughly every 6 minutes) to track balance changes, attestation performance, and status transitions. Each of these is a separate data point requiring a Beacon API call. A dashboard for a large staking operation may monitor thousands of validator indices simultaneously.
Liquid staking protocols. Protocols managing pooled ETH need to track validator activation queue entry, active status transitions, and withdrawal credential processing. The Beacon API is the only source for this data.
MEV research. Block proposal data from /eth/v2/beacon/blocks/{slot} includes the full execution payload and proposer index. Researchers analyzing MEV extraction patterns query this endpoint to reconstruct block-building decisions.
Bridge finality gates. Bridges that move assets between Ethereum and other chains use finality checkpoints from the Beacon API to determine when it is safe to release funds on the destination chain. Finalized blocks cannot be reorganized, making the finality checkpoint the correct signal for high-value bridge operations.
Protocol analytics. Tracking validator set growth, exit queue depth, and slashing events all require Beacon API access. None of this is available on the execution layer.
Common Issues
Wrong authentication format. Beacon API uses Authorization: Bearer YOUR_KEY in headers. Using ?auth=YOUR_KEY as a query parameter will return a 401. This is the most common connection error when developers switch from the execution layer endpoint.
Using head instead of finalized in production. The head state identifier returns the latest unfinalized data. Under normal conditions this is fine, but during periods of missed attestations or network stress, head can return data from a slot that is later reorganized. For bridge and settlement applications, always use finalized as the state identifier.
Requesting all validators at once. /eth/v1/beacon/states/head/validators without filtering returns the entire validator set, which is a large response. Filter by passing ?status=active_ongoing or request specific indices to keep response sizes manageable.
v1 vs v2 block endpoints. /eth/v1/beacon/blocks/{block_id} returns a legacy format that does not include the execution payload. Use /eth/v2/beacon/blocks/{block_id} for post-Merge blocks that include both the consensus block and the execution payload.
Choosing a Provider
For production staking infrastructure, the Beacon API endpoint is as critical as the execution layer endpoint. Missed attestation data or delayed finality information directly affects validator performance and bridge security.
Key criteria when evaluating a Beacon API provider:
- Paired execution and consensus access. Staking infrastructure almost always needs both layers. A provider that delivers both from one endpoint reduces configuration complexity.
- Archival or recent-state access. Some applications need to query historical state. Confirm whether the provider supports historical slot queries beyond a recent window.
- Security compliance. For liquid staking protocols and institutional staking operations, infrastructure compliance certifications (ISO 27001) matter for procurement.
BoltRPC’s Beacon endpoint runs on Matrixed.Link’s ISO 27001:2022 certified infrastructure and is paired with the Ethereum execution layer endpoint under the same API key. See the Ethereum Beacon Chain endpoint page for endpoint details and a free trial.
FAQ
What is the difference between the Beacon API and Ethereum JSON-RPC?
The Beacon API is a REST API serving consensus layer data: validators, slots, epochs, attestations, and finality checkpoints. Ethereum JSON-RPC is the execution layer interface for transactions, contract calls, and log queries. They are separate protocols for two separate layers of an Ethereum node. An eth_blockNumber call goes to the execution layer. A validator status query goes to the Beacon API.
Do I need a special endpoint for the Beacon API?
Yes. The Beacon API runs on a separate port and path from the execution layer JSON-RPC. BoltRPC provides a dedicated Beacon Chain endpoint at https://eu.endpoints.matrixed.link/rpc/ethereum-beacon. The execution layer endpoint is separate. Both use the same API key but different base URLs.
What state identifiers can I use in Beacon API paths?
The Beacon API accepts four state identifiers: head (latest slot, may not be finalized), finalized (latest finalized checkpoint), justified (latest justified checkpoint), or a specific slot number as an integer. For production applications that need settled data, use finalized rather than head.
How often does a new slot appear on the Beacon Chain? A new slot is produced approximately every 12 seconds. An epoch contains 32 slots, so epochs change roughly every 6.4 minutes. Finality occurs after two epochs, meaning transactions reach cryptographic finality in approximately 12 to 13 minutes under normal network conditions.