๐ Builder Entities
Returns the market share of every curated builder entity over an evaluation window: one row per entity with the proposals its builders won and the value of their accepted bids, next to the totals of the whole network in network.
The share counts who signed the winning bid. A builder belongs to an entity when its registry entry withdraws to an execution layer address that beaconcha.in curated under the entityโs name. Every curated entity has a row, also when its builders won nothing in the window. Self-built proposals, and proposals won by a builder without a curated entity, are totals in network, not rows, so every rowโs entity is a value the builder_entity selector accepts. A relay, a service that forwards payloads from other builders, can sign bids for their payloads under its own registry entry. An entity of kind relay therefore counts the bids the relay signed, not the builders that built those payloads; to name those builders, see v2/ethereum/builders/fee-recipients.
Builder entity labels may take a few days after a chainโs Glamsterdam hard fork to settle, while we observe how builders operate in the first days. Until then data can list few or no entities, most proposals won by an external builder count in network.unattributed_blocks, and that is expected.
Only finalized slots whose execution payload status is decided count, and the window never reaches before the fork. The window ends at the last such slot, at most the last slot of the epoch before the head; range returns the window evaluated, or the requested window when no slot of it is decided yet. Bid values are stored in Gwei and returned in wei.
Results can be sorted by blocks_won or bid_value_total, descending by default, and are paginated with a default and maximum page size of 10.
Combine this endpoint with others for deeper insights:
- The record of one entityโs builders, with payload and payment outcomes: v2/ethereum/builders/performance-aggregate with a
builder_entityselector - The builders of an entity: v2/ethereum/builders/metadata
- The proposals of one entity, one row each: v2/ethereum/builders/proposal-slots with
builder_entityset to the rowโsentity
Premium Endpoint: This endpoint requires a Scale or Enterprise plan.
Authorizations
Body
The Ethereum chain to query.
mainnet, hoodi Cursor value for pagination. See our pagination guide for more details.
The number of items to return per page.
1 <= x <= 10The field to sort builder entities by. Entities with equal values are sorted by name.
blocks_won: Sort by the proposals won (default)bid_value_total: Sort by the summed value of the accepted bids
blocks_won, bid_value_total "blocks_won"
The sort order for the results.
asc: Ascending order (lowest first)desc: Descending order (highest first, default)
asc, desc Response
Successful response.
Response containing the market share of the curated builder entities over the evaluation window, next to the network totals.
Every canonical proposal of the network over the evaluation window. Self-built and unattributed proposals are totals here, not entity rows, so every row's entity stays a value the builder_entity selector accepts.
The time span actually covered by the returned results โ from the first to the last matching data point โ specified in slots, epochs, and Unix timestamps.
This reflects the data that was found, not the range that was queried. When the response is 200 but no data is found, it falls back to the requested range, or to the full available history if no range was given. Some endpoints answer 404 instead when no data is found.
For arbitrary (custom) time-range queries the queried range is expanded outward to whole UTC days, so the covered range may be wider than requested. As stated above, the reported range still reflects the data that was actually found โ a touched UTC day with no data for the selected validators will not extend it.

