> ## 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. # Builder Registry > Returns the beacon chain's builder registry, which exists from the Glamsterdam hard fork on: one row per tenure, the period in which one builder public key held one builder index, newest `deposit_epoch` first. Select builders with `builder`, or omit it to page through the whole registry; `status` narrows the result to one builder status. When a builder exits and withdraws its whole balance, the chain gives its index to the next new builder, so one index can name different builders over time, and a public key that registers again can get a different index. Use `builder_pubkey`, not `builder_index`, to follow one builder. A proposal belongs to a tenure when its accepted bid names `builder_index` in an epoch from `deposit_epoch` up to, but not including, `superseded_epoch`. beaconcha.in reads the registry from the finalized state at each new finalized checkpoint, so every row is a finalized snapshot, taken at its `snapshot_slot`. A tenure that has been superseded keeps the balance and status last observed while it held the index. Balances are stored in Gwei and returned in wei. A new builder appears once its registration is in a finalized state that beaconcha.in has read. Combine this endpoint with others for deeper insights: - The proposals each builder won, with the payload and payment of each: 💎 [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) with the same `builder` selector - The delivery and settlement record of a builder over a window: 💎 [v2/ethereum/builders/performance-aggregate](/api-reference/ethereum/builders/performance-aggregate) - The curated operator of each builder: 💎 [v2/ethereum/builders/metadata](/api-reference/ethereum/builders/metadata) Results are paginated with a default and maximum page size of 10. > [!WARNING] > > **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](https://docs.beaconcha.in/api/glamsterdam.md). ## OpenAPI ````yaml /v3/bundled.yaml post /api/v2/ethereum/builders openapi: 3.0.4 info: title: External Service API version: 1.0.3 servers: - url: https://beaconcha.in description: Production API security: - ApiKeyAuth: [] paths: /api/v2/ethereum/builders: post: tags: - Builders summary: Builder Registry description: > Returns the beacon chain's builder registry, which exists from the Glamsterdam hard fork on: one row per tenure, the period in which one builder public key held one builder index, newest `deposit_epoch` first. Select builders with `builder`, or omit it to page through the whole registry; `status` narrows the result to one builder status. When a builder exits and withdraws its whole balance, the chain gives its index to the next new builder, so one index can name different builders over time, and a public key that registers again can get a different index. Use `builder_pubkey`, not `builder_index`, to follow one builder. A proposal belongs to a tenure when its accepted bid names `builder_index` in an epoch from `deposit_epoch` up to, but not including, `superseded_epoch`. beaconcha.in reads the registry from the finalized state at each new finalized checkpoint, so every row is a finalized snapshot, taken at its `snapshot_slot`. A tenure that has been superseded keeps the balance and status last observed while it held the index. Balances are stored in Gwei and returned in wei. A new builder appears once its registration is in a finalized state that beaconcha.in has read. Combine this endpoint with others for deeper insights: - The proposals each builder won, with the payload and payment of each: 💎 [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) with the same `builder` selector - The delivery and settlement record of a builder over a window: 💎 [v2/ethereum/builders/performance-aggregate](/api-reference/ethereum/builders/performance-aggregate) - The curated operator of each builder: 💎 [v2/ethereum/builders/metadata](/api-reference/ethereum/builders/metadata) Results are paginated with a default and maximum page size of 10. operationId: GetBuilders requestBody: $ref: '#/components/requestBodies/builders' responses: '200': $ref: '#/components/responses/Builders' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '429': $ref: '#/components/responses/RateLimitExceeded' '500': $ref: '#/components/responses/InternalServerError' default: $ref: '#/components/responses/DefaultError' components: requestBodies: builders: x-go-name: BuildersRequestBody content: application/json: schema: $ref: '#/components/schemas/BuildersRequest' example: chain: hoodi builder: builder_index: 1889 page_size: 10 responses: Builders: description: Successful response. content: application/json: schema: allOf: - $ref: '#/components/schemas/Builders.ContainerList' - $ref: '#/components/schemas/PagingTemplate' description: >- Response containing the tenures in the beacon chain's builder registry, newest first. BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Bad request. Please check your input and try again. Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized. Please provide a valid API key. Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- endpoint not allowed for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing. NotFound: description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: The requested resource was not found. MethodNotAllowed: description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/Error' example: error: 'method not allowed: GET. all public API endpoints use POST.' RateLimitExceeded: description: Rate Limit Exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Rate limit exceeded. Please try again later. InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: internal server error. please try again later. DefaultError: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: An unexpected error occurred. schemas: BuildersRequest: type: object properties: chain: $ref: '#/components/schemas/Chain' builder: $ref: '#/components/schemas/nullableBuildersSelector' status: allOf: - $ref: '#/components/schemas/BuilderStatus' description: >- Optional. Return only the tenures whose `status` is this one. Tenures with a null `status` never match. cursor: $ref: '#/components/schemas/Cursor' page_size: $ref: '#/components/schemas/PageSize' Builders.ContainerList: type: object properties: data: type: array items: $ref: '#/components/schemas/Builders.Data' required: - data PagingTemplate: type: object properties: paging: $ref: '#/components/schemas/Paging' Error: type: object properties: error: type: string Chain: type: string enum: - mainnet - hoodi default: mainnet description: The Ethereum chain to query. nullableBuildersSelector: description: > Optional builder selector. If left null, the whole builder registry is returned. Free selectors available to all users: - builder_pubkey: One builder, by its public key, as in `execution_payload.builder_pubkey`. The best way to follow one builder over time. - builder_index: The builder that holds this index now. To select the builder of a past slot, use that slot's `builder_pubkey`. **Premium selectors** for Scale & Enterprise plans (https://beaconcha.in/pricing): - builder_execution_address: Every builder that withdraws to this execution layer address. Use it for all the builders of one operator. - builder_entity: Every builder that withdraws to an address that beaconcha.in curated under this name. Optionally include `builder_sub_entity`. Matching is case-sensitive. Note: Every option resolves to builder public keys, each with every period in which it held an index. An option that matches no builder returns 404. A matched builder whose tenures `status` filters out returns an empty list. nullable: true default: null oneOf: - $ref: '#/components/schemas/BuildersByPubkey' - $ref: '#/components/schemas/BuildersByIndex' - $ref: '#/components/schemas/BuildersByExecutionAddress' - $ref: '#/components/schemas/BuildersByEntity' BuilderStatus: type: string enum: - pending - active - exited x-enum-varnames: - BuilderStatusPending - BuilderStatusActive - BuilderStatusExited example: active description: > Status of a builder as the beacon node reports it, derived from the builder's registry entry and the finalized checkpoint. - `pending`: registered, but the finalized epoch has not passed its `deposit_epoch` yet, so it cannot bid yet. - `active`: can bid: the finalized epoch has passed its `deposit_epoch`, and it has not initiated an exit. - `exited`: it has initiated an exit, so it cannot bid; its balance becomes withdrawable at `withdrawable_epoch`. Cursor: type: string description: >- Cursor value for pagination. See our [pagination guide](/api/pagination) for more details. default: '' PageSize: type: integer description: The number of items to return per page. minimum: 1 maximum: 10 default: 10 Builders.Data: type: object description: >- One tenure in the beacon chain's builder registry, the period in which one builder public key held one builder index. properties: builder_index: allOf: - $ref: '#/components/schemas/BuilderIndex' description: >- Index the builder held during this tenure. The bids of this tenure are the bids under this index from `deposit_epoch` until `superseded_epoch`. builder_pubkey: $ref: '#/components/schemas/BuilderPublicKey' builder_execution_address: allOf: - $ref: '#/components/schemas/ExecutionLayerAddress' description: >- Execution layer address that the registry entry names for the builder's withdrawals, the address the `builder_execution_address` selector matches. It comes from the deposit that registered the builder and does not change during this tenure. Anyone can register a builder with any withdrawal address, so it does not prove that the owner of the address runs the builder. deposit_epoch: allOf: - $ref: '#/components/schemas/Epoch' description: >- The registry's deposit epoch of the builder, the epoch of the slot whose deposit registered it at this index. A builder registered at the Glamsterdam hard fork from a deposit made before the fork has the epoch of that deposit, which is before the fork. A builder can bid only after the finalized epoch has passed it. superseded_epoch: nullable: true allOf: - $ref: '#/components/schemas/Epoch' description: >- Epoch from which `builder_index` belongs to the next builder registered at it, that builder's `deposit_epoch`. Null while this builder still holds the index. It is not a field of the chain's registry; beaconcha.in records it when the next builder takes the index. withdrawable_epoch: nullable: true allOf: - $ref: '#/components/schemas/Epoch' description: >- Epoch from which the builder's balance can be withdrawn after it initiated an exit. Null while the builder has not initiated an exit, where the chain stores `FAR_FUTURE_EPOCH`. status: nullable: true allOf: - $ref: '#/components/schemas/BuilderStatus' description: >- Status of the builder as the beacon node reported it at `snapshot_slot`. Null for a tenure recorded before beaconcha.in read the status from the beacon node. balance: allOf: - $ref: '#/components/schemas/wei' description: >- Balance of the builder at `snapshot_slot`. The chain stores it in Gwei; it is returned in wei. pending_balance: nullable: true allOf: - $ref: '#/components/schemas/wei' description: >- Amount the builder owed at `snapshot_slot`, the sum of its pending builder payments and its pending builder withdrawals in the same state as `balance`. The chain accepts a bid of the builder only while `balance` minus `MIN_DEPOSIT_AMOUNT` (1 ETH) minus this amount covers the bid value. Stored in Gwei, returned in wei. Null when it could not be read for that state. snapshot_slot: allOf: - $ref: '#/components/schemas/Slot' description: >- Slot of the finalized state from which `balance`, `pending_balance`, `withdrawable_epoch` and `status` were read. beaconcha.in reads the registry at each new finalized checkpoint. A tenure that has been superseded keeps the values last observed while it held the index. required: - builder_index - builder_pubkey - builder_execution_address - deposit_epoch - superseded_epoch - withdrawable_epoch - status - balance - pending_balance - snapshot_slot Paging: type: object properties: next_cursor: description: >- Cursor to the next page of results. See our [pagination guide](/api/pagination) for more details. If empty, there are no more pages to fetch. type: string example: eyJfc2FtcGxlX2N1cnNvciI6MTIzNDU2Nzg5MH0 BuildersByPubkey: type: object title: Builder Public Key description: >- Select a builder by its public key in the beacon chain's builder registry. Use the key, not the builder index, to follow a builder over time. The chain gives the index of a builder that has exited and withdrawn its balance to the next new builder, and a builder that registers again with the same key can get a different index. The key matches every period in which the builder was registered. properties: builder_pubkey: $ref: '#/components/schemas/BuilderPublicKey' required: - builder_pubkey BuildersByIndex: type: object title: Builder Index description: >- Select the builder that holds this index now, with its full history, as `builder_pubkey` would. An index passes to a new builder after its builder exits and withdraws, so an index from an old slot may now name someone else. For the builder of a past slot, pass that slot's `execution_payload.builder_pubkey` from 💎 [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) or [v2/ethereum/validators/proposal-slots](/api-reference/ethereum/validators/proposal-slots) instead. properties: builder_index: $ref: '#/components/schemas/BuilderIndex' required: - builder_index BuildersByExecutionAddress: type: object title: 💎 Builder Execution Address description: >- Select every builder whose entry in the beacon chain's builder registry names this execution layer address for its withdrawals. One address can belong to many builders. The address comes from the deposit that registers the builder and does not change while that registration lasts. Anyone can register a builder with any withdrawal address, so a match does not prove that the owner of the address runs the builder. properties: builder_execution_address: allOf: - $ref: '#/components/schemas/ExecutionLayerAddress' example: '0x8f2e4c6a91b3d5e7f0a2c4e6b8d0f1a3c5e7b9d2' description: >- Execution layer address that a builder's registry entry names for its withdrawals. required: - builder_execution_address BuildersByEntity: type: object title: 💎 Builder Entity description: >- Select every builder whose registry entry withdraws to an execution layer address that beaconcha.in curated under this builder entity name, optionally only the addresses of one sub-entity. Names come from [v2/ethereum/builders/entities](/api-reference/ethereum/builders/entities). A name without a registered builder returns 404. 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 a name can return 404 because no address carries it yet. properties: builder_entity: $ref: '#/components/schemas/BuilderEntityName' builder_sub_entity: allOf: - $ref: '#/components/schemas/SubEntityName' description: >- Optional sub-entity of `builder_entity`. Omit it or pass an empty string to select the whole entity. Matching is case-sensitive. required: - builder_entity BuilderIndex: type: integer minimum: 0 example: 1889 maximum: 1099511627775 description: >- Index of a builder in the beacon chain's builder registry, which exists from the Glamsterdam hard fork on. Always below 2^40 (1099511627776). A builder payment withdrawal on chain carries the builder index plus 2^40 (`BUILDER_INDEX_FLAG`) as its validator index, so subtract 2^40 before you pass it here. When a builder exits and withdraws its whole balance, the chain gives its index to the next new builder, so one index can name different builders over time. BuilderPublicKey: type: string pattern: ^0x[a-fA-F0-9]{96}$ example: >- 0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3 description: >- BLS public key of a builder in the beacon chain's builder registry, which exists from the Glamsterdam hard fork on. The registry is separate from the builder keys that relays report, such as on [v2/ethereum/block/mev-bids](/api-reference/ethereum/block/mev-bids); a relay-reported key matches only if that builder also registered it on chain. ExecutionLayerAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: A standard Ethereum address (20-byte hex string with 0x prefix). example: '0x388C818CA8B9251b393131C08a736A67ccB19297' Epoch: type: integer minimum: 0 wei: type: string description: Amount in wei (1 ETH = 10^18 wei) pattern: ^(0|-?[1-9][0-9]*)$ example: '32000000000000000000' Slot: type: integer minimum: 0 description: Slot by number. BuilderEntityName: type: string example: Titan description: >- Curated name of a builder operator, such as a block builder or a relay. Builder entity names share one namespace with staking entity names, so one company has one name, and the same name can stand for a staking entity in a `validator` selector and for a builder operator in a `builder` selector. A relay's name ends in " relay", so a relay never shares an entity with a builder that the same company runs. Matching is case-sensitive. SubEntityName: type: string description: The name of the sub-entity. example: Lido CSM securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- Authorization header with value: Bearer YOUR_TOKEN. Refer to the [API Keys](/api/overview#api-keys) section to create your API key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.