> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beaconcha.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to Owners and Operators

> How the entity endpoints, the entity validator selector and the entity fields of validators/metadata move to owners and operators, and when the old ones stop working

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.

> [!WARNING]
>
> **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`](https://docs.beaconcha.in/api-reference/ethereum/entities/owners) and [`entities/operators`](https://docs.beaconcha.in/api-reference/ethereum/entities/operators) require a Scale or Enterprise plan, as the entity endpoints they replace do.

## What changes

| Deprecated | Use instead | What differs |
| - | - | - |
| The `entity` validator selector | The `entities` validator selector | Selects by owner, operator, or both, each by `id` or `path` |
| `entity` and `sub_entity` of [`validators/metadata`](https://docs.beaconcha.in/api-reference/ethereum/validators/metadata) | `owner` and `operator` of its v2.1 schema | Send `Accept: application/vnd.beaconcha.in.v2.1+json`; each field is an object with `id`, `path` and `name` |
| `entities` | [`entities/owners`](https://docs.beaconcha.in/api-reference/ethereum/entities/owners) and [`entities/operators`](https://docs.beaconcha.in/api-reference/ethereum/entities/operators) | Sorted by `validator_count` unless `sort_by` is given, where the old default was `net_share`; `sub_entity_count` is `child_count`, which they do not sort by. Each row names its entity by `id`, `path` and `name` instead of `entity`, a parent and the entities below it are separate rows, and `Unknown` holds the validators without an owner, or without an operator: see [What changes in the list responses](#what-changes-in-the-list-responses) |
| `entity/sub-entities` | [`entities/operators`](https://docs.beaconcha.in/api-reference/ethereum/entities/operators) with the `owner` filter lists the operators that run an owner's validators; `entities` with both `owner` and `operator` selects those validators | Sorted by `validator_count` unless `sort_by` is given, where the old default was `net_share`; an owner that had no sub-entities can have operators, and `Unknown` holds the owner's validators without an operator |
| `entity/mev-timing` | [`validators/mev-timing`](https://docs.beaconcha.in/api-reference/ethereum/validators/mev-timing) with `entities` | Every day counts the entity's validators at the time of the call, and an unknown entity or a selection without validators returns `404` |

## 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`](https://docs.beaconcha.in/api-reference/ethereum/entities/owners), `operator` one from [`entities/operators`](https://docs.beaconcha.in/api-reference/ethereum/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`](https://docs.beaconcha.in/api-reference/ethereum/entities/owners) or [`entities/operators`](https://docs.beaconcha.in/api-reference/ethereum/entities/operators), which matches the start of an entity's name or path, ignoring case:

```bash theme={null}
curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/entities/owners \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "mainnet",
    "search": "lido"
  }'
```

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`](https://docs.beaconcha.in/api-reference/ethereum/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.

> [!NOTE]
>
> 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:

```json theme={null}
"validator": { "entity": "Lido", "sub_entity": "Chorus One" }
```

After:

```json theme={null}
"validator": {
  "entities": {
    "owner": { "path": "lido/curated" },
    "operator": { "path": "chorus-one" }
  }
}
```

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:

```bash theme={null}
curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/metadata \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Accept: application/vnd.beaconcha.in.v2.1+json' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "mainnet",
    "validator": { "validator_identifiers": [1] }
  }'
```

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`](https://docs.beaconcha.in/api-reference/ethereum/entities/owners) and [`entities/operators`](https://docs.beaconcha.in/api-reference/ethereum/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:

```bash theme={null}
curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/entities/owners \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "mainnet",
    "sort_by": "net_share"
  }'
```

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

| Old response | New response |
| - | - |
| `entity` or `sub_entity`, a name | `id`, `path` and `name`, and `ancestors`, the entities above this one, root first |
| `sub_entity_count` | `child_count`, the entities directly below this one |
| `validator_count` | `validator_count` covers the entity and every entity below it; `direct_validator_count` only the entity itself |
| `validator_count` and `net_share` always set | `validator_count`, `direct_validator_count`, `beaconscore` and `net_share` can be null: all four for an entity created since the latest hourly count, `beaconscore` also when the validators had no duties in the window |
| `range`, the slots, epochs and timestamps of the window | `range`, the same fields for the epochs `beaconscore` covers: it ends at the last epoch of the hourly count, not at the latest finalized one |
| `range` required in the request | Optional, `30d` when not given |

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:

```bash theme={null}
curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/entities/operators \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "mainnet",
    "owner": { "path": "lido/curated" }
  }'
```

`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`](https://docs.beaconcha.in/api-reference/ethereum/validators/mev-timing), which returns the same daily rows:

```bash theme={null}
curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/mev-timing \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "chain": "mainnet",
    "validator": { "entities": { "owner": { "path": "lido/curated" } } },
    "page_size": 10
  }'
```

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: @1794909600
Sunset: Thu, 17 Dec 2026 10:00:00 GMT
```

`Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) gives the day the deprecation was announced as a Unix timestamp, and `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) 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:

```json theme={null}
{
  "error": "entity/mev-timing was sunset on 2026-12-17 10:00:00 UTC; use validators/mev-timing with the entities selector instead"
}
```

`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](https://docs.beaconcha.in/api/error-handling.md) lists every message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.