Skip to main content
The API now names two entities for each validator: its owner, the entity that owns it, and its operator, the entity that runs it. They replace the entity and sub-entity of the old model, and the endpoints and fields below that use the old model are deprecated.
Sunset: 2026-12-17 10:00:00 UTC. Until then, the old endpoints and fields keep working, and their responses carry Deprecation and Sunset headers. From the sunset on, they return 410 Gone, and validators/metadata returns its new schema to requests that do not ask for a version.
Premium access: the entities validator selector, entities/owners and entities/operators require a Scale or Enterprise plan, as the entity endpoints they replace do.

What changes

How entities are organized

  • Each entity has an id, a path and a name. Select an entity by its id or its path.
  • Owners and operators are separate lists: owner takes an entity from entities/owners, operator one from entities/operators. When you give both, a validator must match both.
  • Entities form a tree: a path is the parent’s path and the entity’s own segment, joined by /. Selecting an entity includes the entities below it, so lido selects every Lido validator and lido/csm only those of Lido’s CSM module.
  • A merged entity selects the entity it was merged into.

Find an entity’s new path

Entities can be named and grouped differently from the old ones. Look an entity up with the search filter of entities/owners or entities/operators, which matches the start of an entity’s name or path, ignoring case:
For example, the old entities Lido, Lido CSM and Lido Simple DVT are the owners lido/curated, lido/csm and lido/simple-dvt. All three are below lido, so lido selects more validators than the old Lido did. Three rules cover most old names:
  • A name that was not regrouped works as a path. Paths are compared ignoring case, with every run of spaces or punctuation read as one hyphen, so Rocket Pool selects rocket-pool and ether.fi selects ether-fi. A regrouped name does not: Lido CSM is not a path, because the entity is now lido/csm.
  • An entity that was named by an address is a whale. The old entity 0x8e60… has the path whale-0x8e60… and the name Whale_0x8e60…; the bare address is not a path. search finds it by the start of the address.
  • A sub-entity is an operator. Look its name up in entities/operators.
An owner or operator that names no entity returns 404, as does an owner given as operator or an operator given as owner. The old entity selector answered 404 to an unknown name on most endpoints, and entity/mev-timing an empty list.
An entity that kept its name can still cover different validators: the old model gave each validator one entity, and the new one gives it an owner and an operator. Its validator_count, beaconscore and net_share can therefore differ from the old entity’s. Compare the figures of the entities you track once, before you switch.

Select validators by entity

Every endpoint that takes the validator selector takes entities in place of entity. Before:
After:
The validators an entities selection matches are refreshed hourly.

Read owners and operators from validators/metadata

Ask for the v2.1 schema with the Accept header:
Read owner and operator instead of entity and sub_entity. Each is an object with the entity’s id, path and name, or null when no entity is known. A validator with an owner can have no operator, and an operator known only by its address is a whale or a bare address, not a named company. The v2.1 schema answers 400 to the entity selector, and v2 answers 400 to entities, so switch the selector and the schema together.

Replace the entities overview and entity/sub-entities

List entities with entities/owners and entities/operators. Both return each entity’s validator count, BeaconScore® and net share, sorted by validator_count, largest first. sort_by sorts by beaconscore or net_share instead. range sets the window of beaconscore, 30d unless given: every window ends at the latest hourly count, so the validator counts and net_share are the same in every window. This request ranks owners by net share, as the entities overview did:
Neither has a filter for the entities below one. child_count gives how many there are, and search finds them by path: lido also finds lido/csm.

What changes in the list responses

Two things change what the rows add up to:
  • A parent and the entities below it are separate rows. lido is a row, and so are lido/curated, lido/csm and lido/simple-dvt, whose validators lido already counts. To add up counts or shares, or to rank entities without counting a validator twice, keep only the rows whose ancestors is empty.
  • Each list has its own Unknown row. The entities overview returned the validators without an entity as the entity Unknown. entities/owners returns the validators without an owner as Unknown, and entities/operators those without an operator, so neither matches the overview’s. It has no id or path, is left out when there are none, and search leaves it out. With the rows whose ancestors is empty, it counts every validator once, and their shares add up to 1, except after an entity is merged or removed, until the next hourly count.

Replace entity/sub-entities

For the operators that run an owner’s validators, the closest to the old sub-entities, give entities/operators the owner filter. Each operator’s validator_count, beaconscore and net_share then cover only the validators it runs for that owner, and its direct_validator_count is null; net_share stays their share of the whole network’s stake, as the old sub-entities’ did. entity/sub-entities answered 404 for an entity without sub-entities; an owner without operators returns only its Unknown row, and an owner the old model gave no sub-entities can have operators:
Unknown then holds the owner’s validators without an operator, which the old sub-entities did not list, so the top-level operators and Unknown count each of the owner’s validators once.

Replace entity/mev-timing

Send the entity as the validator selector of validators/mev-timing, which returns the same daily rows:
For one operator within an owner, the old sub-entity, give both owner and operator. Two things differ:
  • Every day counts the validators the entity has at the time of the call. entity/mev-timing counts those the entity had on that day, so days before an entity gained or lost validators can differ.
  • An entity that does not exist, and a selection that matches no validator, return 404 instead of an empty list.

Find the calls you still need to migrate

Until the sunset, responses to deprecated calls carry two headers:
Deprecation (RFC 9745) gives the day the deprecation was announced as a Unix timestamp, and Sunset (RFC 8594) the sunset as an HTTP date. Log the requests whose responses carry them.

After the sunset

The deprecated endpoints and the entity selector return 410 Gone with a message that names the replacement, for example:
validators/metadata returns the v2.1 schema to requests that do not ask for a version, and 410 Gone to requests for application/vnd.beaconcha.in.v2+json. API Error Messages lists every message.