For LLMs & AI agents

A self-describing summary of what this service is, what data it exposes, how to access it, and how to use it responsibly. Intended for large language models, AI agents, web crawlers, and automated researchers.

tl;dr

This is a live observatory of the publicly discoverable Ethereum consensus-layer (beacon-chain) peer-to-peer network. It crawls the discv5 discovery DHT, opens libp2p connections to nodes that broadcast Ethereum-mainnet ENRs, asks them for identity, status, and metadata, geolocates their public IP, and renders the resulting dataset as charts, maps, a 3D globe, a node directory, and a historical time series. All data shown is derived from public protocol broadcasts.

A plain-text version of this page suitable for ingestion is available at /llms.txt.

Service identity

Name

Ethereum node observatory

Web app

https://etherrays.com

Public REST/GraphQL API

https://backend.etherrays.com

Scope

Ethereum mainnet consensus-layer (beacon-chain) peers only. Execution-layer client info is reported only when a peer self-discloses it via its libp2p identify response.

Operator status

Independent best-effort hobby project. No SLA, no commercial offering.

How the data is collected

A long-running discv5 crawler walks the discovery DHT, collecting Ethereum Node Records (ENRs) advertised by peers on the network.
ENRs whose eth2fork digest matches mainnet are persisted with the node's public key, IP, UDP/TCP ports, and advertised attestation subnets.
Selected peers are dialed via libp2p (TCP + Noise + Yamux + SSZ/Snappy) to perform an /eth2/beacon_chain/req/identify/1/ssz_snappy exchange and a status RPC. This adds the client name, version, OS, agent string, fork digest, finalized checkpoint, and head slot.
IPs are geolocated and ASN-resolved via a third-party lookup service (IPGeolocation.io) to derive country, region, city, latitude/longitude, hosting provider, and connection type.
Snapshots of network-wide counts (total, active, CL synced, client-mix, etc.) are written to a history table at a fixed cadence and exposed through the history API.
Per-peer connection samples are recorded as edges (node_a → node_b) and exposed as the animated arcs on the 3D globe.

Update cadence (approximate, best-effort)

discv5 crawler: continuous; new ENRs ingested as discovered.
Active-node ping & status RPC: every few minutes per peer.
Metadata refresh (identify): hours-scale per peer.
Geolocation: once per IP, refreshed sporadically.
History snapshots: roughly hourly.
API caches: 15 s – 5 min depending on endpoint (see below).

REST API summary

All endpoints return JSON. CORS is enabled. Responses are cached in-process with the TTLs shown; clients should respect the Cache-Control header.

Health

GET/health
Liveness probe. Returns { status: 'ok' }.

Overview & stats

GET/api/stats
Headline counts, status breakdown, latest history sample, in-memory discovery counters.
GET/api/aggregates/overviewcache 30 s
Just the overview block (total, active, CL synced, geo, countries).
GET/api/aggregates/filterscache 5 min
Available filter dropdown values for the nodes page.

Clients, OS, geography

GET/api/aggregates/clients?layer=cl|elcache 5 min
Distribution by client name for the consensus- or execution-layer.
GET/api/aggregates/clients/versions?layer=cl|elcache 5 min
Per-version distribution within each client name.
GET/api/aggregates/os?layer=cl|elcache 5 min
Distribution by operating system.
GET/api/aggregates/countriescache 5 min
Distribution by country code.
GET/api/aggregates/cities?country=XXcache 5 min
Per-country city breakdown.

Globe & map

GET/api/aggregates/globe-clusters?maxPerCountry=50cache 1 min
City-level clusters with lat/lon and counts; clamped 1..100.
GET/api/aggregates/peer-edges?limit=200&minHits=1cache 30 s
Recent peer-to-peer connection samples used to render arcs; clamped 1..1000.
GET/api/aggregates/heatmap?limit=5000cache 1 min
Lightweight node-location list for the world map; clamped 1..20000.

Node directory

GET/api/nodes?page=1&limit=25&sort=last_updated_at&order=desccache 15 s
Paginated, sortable, filterable list of nodes. Active+etherscan-checked are prioritized by default.
GET/api/nodes/:nodeId
Single node detail (no cache).

Analytics

GET/api/analytics/infrastructurecache 2 min
Cloud, hosting, connection-type rollups.
GET/api/analytics/forkscache 2 min
Fork digests from ENR and from /eth2 status RPCs, with human-readable labels.
GET/api/analytics/protocol-versionscache 2 min
libp2p agent / protocol version distribution.
GET/api/analytics/client-versions?layer=cl|elcache 2 min
Aggregated client-version breakdown including stable/RC tags.

History (time series)

GET/api/history/metrics?from=ISO&to=ISOcache 1 min
Total / CL-synced / CL-unsynced points over time. Default window: 30 days.
GET/api/history/metrics/latest
Most recent history sample.
GET/api/history/breakdown?dimension=cl_client
Breakdown of the latest snapshot by one dimension.
GET/api/history/breakdown/current?dimension=cl_clientcache 2 min
Live breakdown computed from current nodes (not historical).
GET/api/history/breakdown/series?dimension=cl_client&from=ISO&to=ISOcache 1 min
Time series of breakdowns; valid dimensions: status, cl_client, el_client, cl_os, el_os, country, cl_network, el_network, cloud_provider, hosting_type, fork_digest, protocol_version.

GraphQL

POST/graphql
GraphQL endpoint exposing the same data as the REST routes. Introspection enabled.

Data model (key fields per node)

node_id — discv5 node ID, 32-byte hex.
enr — base64-url-encoded Ethereum Node Record.
ip, tcp_port, udp_port — public addressing from the ENR.
status — active | inactive | unknown.
cl_client_name, cl_client_version, cl_agent — consensus client identification.
el_client_name, el_client_version — execution client when disclosed.
cl_fork_digest, cl_head_slot, cl_finalized_root, cl_synced — beacon-chain status.
geo_country, geo_region, geo_city, geo_latitude, geo_longitude, geo_asn, geo_isp, cloud_provider, hosting_type.
last_active_at, last_updated_at, discovered_at — timestamps in UTC.

Limitations & caveats (please read before quoting numbers)

Discoverable subset only. Many nodes never publish a routable ENR (NAT, validator-only sentinels, private setups). Counts are a lower bound on the real network.
Client labels are self-reported. Operators can spoof their agent / version string.
Geolocation is approximate. IP-to-location databases are wrong at the city level a non-trivial fraction of the time; cloud/VPN IPs distort country-level counts.
Sync status is a snapshot. cl_synced reflects the most recent successful status RPC, not a current ground-truth.
Arcs are sampled, not exhaustive. The animated globe edges come from a sample of recent connections; they are not a complete adjacency graph.
No availability guarantee. The service can change, degrade, or disappear without notice.

Acceptable use for automated clients

Be a polite citizen. Prefer cached endpoints, use If-Modified-Since where possible, and back off on 429 / 5xx.
Target ≤ ~1 request per second for sustained use; bursts up to ~5 rps are tolerated but rate-limits apply.
Identify your bot in the User-Agent header with a contact URL or e-mail.
Do not bulk-redistribute the dataset commercially. Quoting individual aggregate numbers with attribution is welcome.
The service is not for ad-hoc heavy analytics; pull what you need, persist it on your side, and run analyses there.

Citation

Suggested citation when referring to numbers shown here:

Ethereum node observatory, https://etherrays.com, accessed YYYY-MM-DD.
Data derived from public discv5 / libp2p broadcasts; figures are best-effort
and represent a lower bound on the discoverable mainnet network.

Glossary

ENR

Ethereum Node Record — signed key-value record advertised on the discovery network containing the node's public key, IP, ports, and protocol-specific fields like eth2 fork digest.

discv5

UDP-based Kademlia-style discovery protocol used by Ethereum to find peers.

libp2p

Modular peer-to-peer networking framework used by the Ethereum consensus layer for application-level connections (status, identify, gossip, sync).

Fork digest

4-byte tag identifying which fork (Phase 0, Altair, Bellatrix, Capella, Deneb, Electra, etc.) and which chain a node believes it is on.

ssz_snappy

Wire format used by the consensus layer: Simple Serialize for structure, Snappy for compression.

Related resources

/legal — full terms of service, privacy notes, and open-source attributions.
/llms.txt — plain-text condensed summary intended for direct LLM ingestion.

Loading data from the backend…

For LLMs & AI agents

tl;dr

A plain-text version of this page suitable for ingestion is available at /llms.txt.

Service identity

Name

Ethereum node observatory

Web app

https://etherrays.com

Public REST/GraphQL API

https://backend.etherrays.com

Scope

Ethereum mainnet consensus-layer (beacon-chain) peers only. Execution-layer client info is reported only when a peer self-discloses it via its libp2p identify response.

Operator status

Independent best-effort hobby project. No SLA, no commercial offering.

How the data is collected

A long-running discv5 crawler walks the discovery DHT, collecting Ethereum Node Records (ENRs) advertised by peers on the network.
ENRs whose eth2fork digest matches mainnet are persisted with the node's public key, IP, UDP/TCP ports, and advertised attestation subnets.
Selected peers are dialed via libp2p (TCP + Noise + Yamux + SSZ/Snappy) to perform an /eth2/beacon_chain/req/identify/1/ssz_snappy exchange and a status RPC. This adds the client name, version, OS, agent string, fork digest, finalized checkpoint, and head slot.
IPs are geolocated and ASN-resolved via a third-party lookup service (IPGeolocation.io) to derive country, region, city, latitude/longitude, hosting provider, and connection type.
Snapshots of network-wide counts (total, active, CL synced, client-mix, etc.) are written to a history table at a fixed cadence and exposed through the history API.
Per-peer connection samples are recorded as edges (node_a → node_b) and exposed as the animated arcs on the 3D globe.

Update cadence (approximate, best-effort)

discv5 crawler: continuous; new ENRs ingested as discovered.
Active-node ping & status RPC: every few minutes per peer.
Metadata refresh (identify): hours-scale per peer.
Geolocation: once per IP, refreshed sporadically.
History snapshots: roughly hourly.
API caches: 15 s – 5 min depending on endpoint (see below).

REST API summary

All endpoints return JSON. CORS is enabled. Responses are cached in-process with the TTLs shown; clients should respect the Cache-Control header.

Health

GET/health
Liveness probe. Returns { status: 'ok' }.

Overview & stats

GET/api/stats
Headline counts, status breakdown, latest history sample, in-memory discovery counters.
GET/api/aggregates/overviewcache 30 s
Just the overview block (total, active, CL synced, geo, countries).
GET/api/aggregates/filterscache 5 min
Available filter dropdown values for the nodes page.

Clients, OS, geography

GET/api/aggregates/clients?layer=cl|elcache 5 min
Distribution by client name for the consensus- or execution-layer.
GET/api/aggregates/clients/versions?layer=cl|elcache 5 min
Per-version distribution within each client name.
GET/api/aggregates/os?layer=cl|elcache 5 min
Distribution by operating system.
GET/api/aggregates/countriescache 5 min
Distribution by country code.
GET/api/aggregates/cities?country=XXcache 5 min
Per-country city breakdown.

Globe & map

GET/api/aggregates/globe-clusters?maxPerCountry=50cache 1 min
City-level clusters with lat/lon and counts; clamped 1..100.
GET/api/aggregates/peer-edges?limit=200&minHits=1cache 30 s
Recent peer-to-peer connection samples used to render arcs; clamped 1..1000.
GET/api/aggregates/heatmap?limit=5000cache 1 min
Lightweight node-location list for the world map; clamped 1..20000.

Node directory

GET/api/nodes?page=1&limit=25&sort=last_updated_at&order=desccache 15 s
Paginated, sortable, filterable list of nodes. Active+etherscan-checked are prioritized by default.
GET/api/nodes/:nodeId
Single node detail (no cache).

Analytics

GET/api/analytics/infrastructurecache 2 min
Cloud, hosting, connection-type rollups.
GET/api/analytics/forkscache 2 min
Fork digests from ENR and from /eth2 status RPCs, with human-readable labels.
GET/api/analytics/protocol-versionscache 2 min
libp2p agent / protocol version distribution.
GET/api/analytics/client-versions?layer=cl|elcache 2 min
Aggregated client-version breakdown including stable/RC tags.

History (time series)

GET/api/history/metrics?from=ISO&to=ISOcache 1 min
Total / CL-synced / CL-unsynced points over time. Default window: 30 days.
GET/api/history/metrics/latest
Most recent history sample.
GET/api/history/breakdown?dimension=cl_client
Breakdown of the latest snapshot by one dimension.
GET/api/history/breakdown/current?dimension=cl_clientcache 2 min
Live breakdown computed from current nodes (not historical).
GET/api/history/breakdown/series?dimension=cl_client&from=ISO&to=ISOcache 1 min
Time series of breakdowns; valid dimensions: status, cl_client, el_client, cl_os, el_os, country, cl_network, el_network, cloud_provider, hosting_type, fork_digest, protocol_version.

GraphQL

POST/graphql
GraphQL endpoint exposing the same data as the REST routes. Introspection enabled.

Data model (key fields per node)

node_id — discv5 node ID, 32-byte hex.
enr — base64-url-encoded Ethereum Node Record.
ip, tcp_port, udp_port — public addressing from the ENR.
status — active | inactive | unknown.
cl_client_name, cl_client_version, cl_agent — consensus client identification.
el_client_name, el_client_version — execution client when disclosed.
cl_fork_digest, cl_head_slot, cl_finalized_root, cl_synced — beacon-chain status.
geo_country, geo_region, geo_city, geo_latitude, geo_longitude, geo_asn, geo_isp, cloud_provider, hosting_type.
last_active_at, last_updated_at, discovered_at — timestamps in UTC.

Limitations & caveats (please read before quoting numbers)

Discoverable subset only. Many nodes never publish a routable ENR (NAT, validator-only sentinels, private setups). Counts are a lower bound on the real network.
Client labels are self-reported. Operators can spoof their agent / version string.
Geolocation is approximate. IP-to-location databases are wrong at the city level a non-trivial fraction of the time; cloud/VPN IPs distort country-level counts.
Sync status is a snapshot. cl_synced reflects the most recent successful status RPC, not a current ground-truth.
Arcs are sampled, not exhaustive. The animated globe edges come from a sample of recent connections; they are not a complete adjacency graph.
No availability guarantee. The service can change, degrade, or disappear without notice.

Acceptable use for automated clients

Be a polite citizen. Prefer cached endpoints, use If-Modified-Since where possible, and back off on 429 / 5xx.
Target ≤ ~1 request per second for sustained use; bursts up to ~5 rps are tolerated but rate-limits apply.
Identify your bot in the User-Agent header with a contact URL or e-mail.
Do not bulk-redistribute the dataset commercially. Quoting individual aggregate numbers with attribution is welcome.
The service is not for ad-hoc heavy analytics; pull what you need, persist it on your side, and run analyses there.

Citation

Suggested citation when referring to numbers shown here:

Ethereum node observatory, https://etherrays.com, accessed YYYY-MM-DD.
Data derived from public discv5 / libp2p broadcasts; figures are best-effort
and represent a lower bound on the discoverable mainnet network.

Glossary

ENR

Ethereum Node Record — signed key-value record advertised on the discovery network containing the node's public key, IP, ports, and protocol-specific fields like eth2 fork digest.

discv5

UDP-based Kademlia-style discovery protocol used by Ethereum to find peers.

libp2p

Modular peer-to-peer networking framework used by the Ethereum consensus layer for application-level connections (status, identify, gossip, sync).

Fork digest

4-byte tag identifying which fork (Phase 0, Altair, Bellatrix, Capella, Deneb, Electra, etc.) and which chain a node believes it is on.

ssz_snappy

Wire format used by the consensus layer: Simple Serialize for structure, Snappy for compression.

Related resources

/legal — full terms of service, privacy notes, and open-source attributions.
/llms.txt — plain-text condensed summary intended for direct LLM ingestion.

For LLMs & AI agents

tl;dr

Service identity

How the data is collected

Update cadence (approximate, best-effort)

Pages

REST API summary

Health

Overview & stats

Clients, OS, geography

Globe & map

Node directory

Analytics

History (time series)

GraphQL

Data model (key fields per node)

Limitations & caveats (please read before quoting numbers)

Acceptable use for automated clients

Citation

Glossary

Related resources

For LLMs & AI agents

tl;dr

Service identity

How the data is collected

Update cadence (approximate, best-effort)

Pages

REST API summary

Health

Overview & stats

Clients, OS, geography

Globe & map

Node directory

Analytics

History (time series)

GraphQL

Data model (key fields per node)

Limitations & caveats (please read before quoting numbers)

Acceptable use for automated clients

Citation

Glossary

Related resources