Skip to main content
POST
๐Ÿ’Ž Builder Entities
Experimental. This endpoint returns data only on chains past the Glamsterdam hard fork. Hoodi forks first; mainnet returns 404 until it forks. The request and response may change before the mainnet release. See Glamsterdam API.

Authorizations

Authorization
string
header
required

Authorization header with value: Bearer YOUR_TOKEN. Refer to the API Keys section to create your API key.

Body

application/json
range
Fixed Window ยท object
required
chain
enum<string>
default:mainnet

The Ethereum chain to query.

Available options:
mainnet,
hoodi
cursor
string
default:""

Cursor value for pagination. See our pagination guide for more details.

page_size
integer
default:10

The number of items to return per page.

Required range: 1 <= x <= 10
sort_by
enum<string>
default:blocks_won

The 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
Available options:
blocks_won,
bid_value_total
Example:

"blocks_won"

sort_order
enum<string>
default:desc

The sort order for the results.

  • asc: Ascending order (lowest first)
  • desc: Descending order (highest first, default)
Available options:
asc,
desc

Response

Successful response.

Response containing the market share of the curated builder entities over the evaluation window, next to the network totals.

data
object[]
required
network
object
required

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.

range
object
required

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.

paging
object