> ## 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 Proposal Slots > Returns the proposals a builder won, newest first, whichever validator proposed them. From the Glamsterdam hard fork on, builders register on the beacon chain and bid to build a slot's execution payload, the part of the block that carries its transactions. The proposer accepts one bid or builds the payload itself. A proposal is the builder's when the proposer accepted its bid. The rows have the same format as [v2/ethereum/validators/proposal-slots](/api-reference/ethereum/validators/proposal-slots). Each row's `validator` is the proposer, and its `execution_payload.builder_pubkey` and `execution_payload.builder_execution_address` name the builder that won it. - A proposal matches whatever `execution_payload.payload_status` is. The builder won the slot even when the chain did not include its payload (`empty`); `block` is then null. - Self-built payloads (`execution_payload.self_built` is true), missed slots and orphaned blocks never match. - `builder_index` selects the builder that holds the index now, with every proposal of its public key. `builder_entity` selects every builder whose execution address beaconcha.in curated under that name, so one request lists an entity's proposals. - A selector that matches no builder on the selected `chain` returns `404`. A registered builder without won proposals in the range returns an empty list, also when the range ends before the fork. - A chain that has not reached the fork returns `404`, so mainnet returns `404` until it forks. You can combine this endpoint with: - Reward: [v2/ethereum/block/rewards](/api-reference/ethereum/block/rewards) - Consensus slot information: [v2/ethereum/slot](/api-reference/ethereum/slot/overview) - Execution block information: [v2/ethereum/block](/api-reference/ethereum/block/overview) - The builder registry: [v2/ethereum/builders](/api-reference/ethereum/builders/overview) - The delivery and settlement record of the builder over a window: [v2/ethereum/builders/performance-aggregate](/api-reference/ethereum/builders/performance-aggregate) Results can be filtered by a time range. Note: This endpoint supports **only finalized** data at this time. **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. > [!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/proposal-slots 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/proposal-slots: post: tags: - Builders summary: 💎 Builder Proposal Slots description: > Returns the proposals a builder won, newest first, whichever validator proposed them. From the Glamsterdam hard fork on, builders register on the beacon chain and bid to build a slot's execution payload, the part of the block that carries its transactions. The proposer accepts one bid or builds the payload itself. A proposal is the builder's when the proposer accepted its bid. The rows have the same format as [v2/ethereum/validators/proposal-slots](/api-reference/ethereum/validators/proposal-slots). Each row's `validator` is the proposer, and its `execution_payload.builder_pubkey` and `execution_payload.builder_execution_address` name the builder that won it. - A proposal matches whatever `execution_payload.payload_status` is. The builder won the slot even when the chain did not include its payload (`empty`); `block` is then null. - Self-built payloads (`execution_payload.self_built` is true), missed slots and orphaned blocks never match. - `builder_index` selects the builder that holds the index now, with every proposal of its public key. `builder_entity` selects every builder whose execution address beaconcha.in curated under that name, so one request lists an entity's proposals. - A selector that matches no builder on the selected `chain` returns `404`. A registered builder without won proposals in the range returns an empty list, also when the range ends before the fork. - A chain that has not reached the fork returns `404`, so mainnet returns `404` until it forks. You can combine this endpoint with: - Reward: [v2/ethereum/block/rewards](/api-reference/ethereum/block/rewards) - Consensus slot information: [v2/ethereum/slot](/api-reference/ethereum/slot/overview) - Execution block information: [v2/ethereum/block](/api-reference/ethereum/block/overview) - The builder registry: [v2/ethereum/builders](/api-reference/ethereum/builders/overview) - The delivery and settlement record of the builder over a window: [v2/ethereum/builders/performance-aggregate](/api-reference/ethereum/builders/performance-aggregate) Results can be filtered by a time range. Note: This endpoint supports **only finalized** data at this time. **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan. operationId: GetBuilderProposalSlots requestBody: $ref: '#/components/requestBodies/builderProposalSlots' responses: '200': $ref: '#/components/responses/ValidatorProposals' '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: builderProposalSlots: x-go-name: BuilderProposalSlotsRequestBody content: application/json: schema: $ref: '#/components/schemas/BuilderProposalSlotsRequest' example: chain: hoodi builder: builder_pubkey: >- 0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3 page_size: 10 responses: ValidatorProposals: description: Successful response. content: application/json: schema: allOf: - $ref: '#/components/schemas/ValidatorProposals.ContainerList' - $ref: '#/components/schemas/PagingRangeTemplate' description: >- Response containing detailed proposal information of the validators. 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: BuilderProposalSlotsRequest: type: object properties: chain: $ref: '#/components/schemas/Chain' builder: $ref: '#/components/schemas/buildersSelector' range: $ref: '#/components/schemas/timeRangeSelectorNullable' cursor: $ref: '#/components/schemas/Cursor' page_size: $ref: '#/components/schemas/PageSize' required: - builder ValidatorProposals.ContainerList: type: object properties: data: type: array items: $ref: '#/components/schemas/ValidatorProposals.Data' required: - data PagingRangeTemplate: type: object properties: paging: $ref: '#/components/schemas/Paging' range: $ref: '#/components/schemas/ResultRange' required: - range Error: type: object properties: error: type: string Chain: type: string enum: - mainnet - hoodi default: mainnet description: The Ethereum chain to query. buildersSelector: description: > Select builders by one of these options. Every endpoint that uses this selector requires a Scale or Enterprise plan: - 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`. - 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: 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. Every option therefore resolves to builder public keys, and a proposal counts for a builder only from the epoch it took the index until the epoch the next builder took it. The builder registry exists from the Glamsterdam hard fork on. An option that matches no builder returns 404. A builder that matches but has nothing in the result returns an empty list or zero counts, not 404. oneOf: - $ref: '#/components/schemas/BuildersByPubkey' - $ref: '#/components/schemas/BuildersByIndex' - $ref: '#/components/schemas/BuildersByExecutionAddress' - $ref: '#/components/schemas/BuildersByEntity' timeRangeSelectorNullable: description: > Specify a time range using either Unix timestamps or epoch numbers. If left null, the API will query the entire available history of the selected validators. nullable: true default: null oneOf: - $ref: '#/components/schemas/timeRangeSelectorTime' - $ref: '#/components/schemas/timeRangeSelectorEpoch' - $ref: '#/components/schemas/timeRangeSelectorSlot' 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 ValidatorProposals.Data: type: object properties: validator: $ref: '#/components/schemas/validator' slot: $ref: '#/components/schemas/Slot' description: Slot number on the consensus layer. block: description: >- Block number on the execution layer, if there was a block proposed and included for this slot. Will be null for missed or orphaned blocks and pre-Merge proposals. From the Glamsterdam hard fork on, also null when the chain did not include this slot's execution payload; until the next canonical block is finalized, the value can still change to null. nullable: true allOf: - $ref: '#/components/schemas/Block' execution_payload: nullable: true allOf: - $ref: '#/components/schemas/ValidatorProposals.ExecutionPayload' description: > Whether the chain included this proposal's execution payload, and the builder bid the proposer accepted for it: its settlement and the proposer's execution layer reward. Null for slots before the Glamsterdam hard fork, for missed slots and for orphaned blocks. A settlement can be derived again when we correct our payment matching; such a change is announced in the changelog. Experimental: set only on chains past the Glamsterdam hard fork, which Hoodi reaches first, and may change before the mainnet release. See [Glamsterdam API](/api/glamsterdam). publish_time: nullable: true allOf: - $ref: '#/components/schemas/ValidatorProposals.PublishTime' description: > When one beaconcha.in node first received the block of this proposal, from the Glamsterdam hard fork on. Null for slots before the fork, for a missed slot when our node received no block for it, and while the explorer has no block or missed verdict for the slot. For earlier slots, [v2/ethereum/block/mev-timing](/api-reference/ethereum/block/mev-timing) measures proposal timing from relay bids; that measure is not comparable with this one, and the two are never merged. Experimental: set only on chains past the Glamsterdam hard fork, which Hoodi reaches first, and may change before the mainnet release. See [Glamsterdam API](/api/glamsterdam). finality: description: >- Finality of the consensus block in this slot. From the Glamsterdam hard fork on, `block` settles separately, once the next canonical block is finalized. allOf: - $ref: '#/components/schemas/FinalityParams' required: - slot - validator - finality 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 ResultRange: type: object description: > 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. properties: slot: $ref: '#/components/schemas/SlotRange' epoch: $ref: '#/components/schemas/EpochRange' timestamp: $ref: '#/components/schemas/TimeRange' required: - slot - epoch - timestamp 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 timeRangeSelectorTime: type: object title: Unix Timestamp description: Range provided via Unix timestamp (inclusive) properties: timestamp: $ref: '#/components/schemas/timeRangeStartEnd' required: - timestamp timeRangeSelectorEpoch: type: object title: Epoch description: Range provided via epoch number properties: epoch: $ref: '#/components/schemas/epochRangeStartEnd' required: - epoch timeRangeSelectorSlot: type: object title: Slot description: Range provided via slot number properties: slot: $ref: '#/components/schemas/slotRangeStartEnd' required: - slot validator: type: object properties: index: allOf: - $ref: '#/components/schemas/validatorIndex' nullable: true public_key: $ref: '#/components/schemas/validatorPublicKey' Slot: type: integer minimum: 0 description: Slot by number. Block: type: integer minimum: 0 description: Block by number. ValidatorProposals.ExecutionPayload: type: object description: >- The execution payload of a proposal from the Glamsterdam hard fork on, and the builder bid the proposer accepted for it. properties: payload_status: allOf: - $ref: '#/components/schemas/PayloadStatus' description: >- Whether the chain included this slot's execution payload. `pending` until the first canonical child block is finalized. empty_reason: nullable: true allOf: - $ref: '#/components/schemas/EmptyReason' description: >- Why the chain did not include the execution payload, from the payload timeliness committee's votes included on chain. Null when `payload_status` is not `empty`. self_built: type: boolean description: >- True when the proposer built the payload itself instead of accepting a builder's bid. The bid fields are then null, and `proposer_reward` comes from the payload's priority fees. builder_index: type: integer minimum: 0 nullable: true description: >- Index of the builder whose bid the proposer accepted. The chain gives the index of a builder that has exited and withdrawn its balance to the next new builder, so the index names this builder only at this slot; use `builder_pubkey` to follow a builder over time. Null for a self-built payload. builder_pubkey: type: string pattern: ^0x[a-fA-F0-9]{96}$ example: >- 0xab6b6d826c14b6141e3406c5227ead15b133993195e96edc05fdeba998d0e0fd96e4ec5f47f6c9eec1558a59042c03d1 nullable: true description: >- BLS public key of the builder that held `builder_index` in this slot's epoch. Null for a self-built payload, and when no registration of the builder at that epoch is known. builder_execution_address: nullable: true allOf: - $ref: '#/components/schemas/ExecutionLayerAddress' description: >- Execution layer address that the registry entry of this builder names for its withdrawals at this slot, the address the `builder_execution_address` option of 💎 [v2/ethereum/builders/proposal-slots](/api-reference/ethereum/builders/proposal-slots) matches. It is not the address the proposer is paid at; that is `bid_fee_recipient`. Null when `builder_pubkey` is null. bid_value: nullable: true allOf: - $ref: '#/components/schemas/wei' description: >- Value of the accepted bid, which the chain pays from the builder's balance to `bid_fee_recipient` as `settlement` describes. The chain stores it in Gwei; it is returned in wei. `0` for a bid that offers no payment the chain enforces; such a bid may or may not promise a trusted payment, see `trusted_payment`. Null for a self-built payload. bid_fee_recipient: nullable: true allOf: - $ref: '#/components/schemas/ExecutionLayerAddress' description: >- Execution layer address the accepted bid names for the proposer's payment. The chain pays `bid_value` to it without any check of who controls it. Null for a self-built payload. fee_recipient: nullable: true allOf: - $ref: '#/components/schemas/ExecutionLayerAddress' description: > Fee recipient of the slot's execution payload, the address that receives the payload's priority fees (the block's coinbase), and the address the `payload_fee_recipient` selector matches. The builder of the payload chooses it, and the chain does not tie it to the builder in `builder_pubkey`, because a relay can sign the winning bid for a payload that another builder built. By convention it names the builder that built the payload; [v2/ethereum/builders/fee-recipients](/api-reference/ethereum/builders/fee-recipients) gives the checks that turn it into a builder name. Null when the chain did not include the payload (`payload_status` `empty`), also when the builder revealed it; beaconcha.in's pages still name the builder of a payload that was revealed but not included, while this API returns null for it. While `payload_status` is `pending`, it can still change: from null once the payload arrives, or to null if the chain leaves the payload out. extra_data: nullable: true type: string pattern: ^0x([a-fA-F0-9]{2})*$ example: '0x546974616e' description: >- Extra data of the slot's execution payload, hex-encoded with the `0x` prefix. A free-form field of up to 32 bytes that the payload's builder fills, often with a readable tag. It can hint at who built the payload but proves nothing, because any builder can write any bytes into it. Null exactly when `fee_recipient` is null. settlement: nullable: true allOf: - $ref: '#/components/schemas/BuilderPaymentSettlement' description: >- Whether the chain paid `bid_value`. `pending` until the payment is decided and its withdrawal is found on chain. For an `empty` payload a verdict is final once `payment_quorum` is set. Null for a self-built payload and when `bid_value` is `0`, because the chain then has nothing to pay. settled_slot: nullable: true allOf: - $ref: '#/components/schemas/Slot' description: >- Slot whose execution payload carried the builder-payment withdrawal that paid `bid_value`; see [v2/ethereum/slot](/api-reference/ethereum/slot/overview). Set only when `settlement` is `paid`. payment_quorum: nullable: true allOf: - $ref: '#/components/schemas/BuilderPaymentQuorum' description: >- Whether same-slot attester weight reached the builder-payment quorum, six tenths of one slot's share of the total active balance, which decides at the end of the following epoch whether a bid whose payload the chain did not include is paid. Derived from the attestations included on chain. Null for a payload that a child block applied, because its payment settles without a quorum, for a self-built payload, for a bid without value, and while not derived yet. While it is null on an `empty` payload, `settlement` rests on the observed payments alone and is derived again once the quorum is known, so it can then change in either direction. trusted_payment: nullable: true allOf: - $ref: '#/components/schemas/wei' description: >- Trusted execution payment the accepted bid promised, an amount the builder transfers to `bid_fee_recipient` inside the payload. The chain never checks or enforces it. Stored in Gwei, returned in wei. Null for a self-built payload and when the bid promised none. trusted_payment_paid: nullable: true allOf: - $ref: '#/components/schemas/wei' description: >- Part of `trusted_payment` found delivered to `bid_fee_recipient` inside this slot's execution payload, capped at the promised amount. `0` when `payload_status` is `empty`, because the chain did not include the payload. Null when `trusted_payment` is null, and while the payload has not been checked yet. proposer_reward: nullable: true allOf: - $ref: '#/components/schemas/wei' description: >- Execution layer reward of this proposal, the amount [v2/ethereum/validators/rewards-list](/api-reference/ethereum/validators/rewards-list) counts for it. For a payload an external builder built, `bid_value` unless `settlement` is `forfeited` or `void_slashed`, plus `trusted_payment_paid`; for such a payload the chain included, it equals `total_reward` on [v2/ethereum/block/rewards](/api-reference/ethereum/block/rewards) for `block`. For a self-built payload, the payload's priority fees as rewards-list counts them, and `0` when the chain did not include the payload. It follows the current `settlement` and `trusted_payment_paid`, so it can change while they can. Null for a self-built payload whose priority fees are not measured yet. required: - payload_status - self_built ValidatorProposals.PublishTime: type: object description: >- When one beaconcha.in node first received a proposal's block, from the Glamsterdam hard fork on, where the proposer publishes its own block. Each node receives a block at its own time, so the figure is one node's view, and a proposer's setup gives it a stable offset to our node. The winning builder can also forward the block, so our node can receive it earlier than the proposer's own publishing alone would deliver it. Our node records the block once it has passed the block's gossip validation, so the time is an upper bound on when the block reached the node. properties: observation: $ref: '#/components/schemas/PublishTimeObservation' slot_offset_ms: type: integer nullable: true description: >- Milliseconds after the slot start at which our node received the block over the peer-to-peer gossip network, by our node's clock, so it can be negative. Null when `observation` is not `seen_on_gossip`. A block our node imported another way has no publish time, because the import time does not show when the proposer published the block. attestation_deadline_ms: type: integer description: >- The slot's attestation deadline in milliseconds after the slot start, `ATTESTATION_DUE_BPS_GLOAS` of the slot duration, which is 3000 at 12-second slots. Fork choice counts a block as timely only when it arrives before this deadline. seen_after_attestation_deadline: type: boolean nullable: true description: >- True when `slot_offset_ms` is at or after `attestation_deadline_ms`. It describes when our node received the block, not whether the chain counted the block as timely, which each node decides from its own arrival time. Null when `slot_offset_ms` is null. block_included: type: boolean description: >- Whether the chain included the block our node received. False for an orphaned block, and for a missed slot when our node received a block for it that the chain did not include. The arrival time alone does not show why a block was not included. Until the slot is finalized, the value can still change. required: - observation - attestation_deadline_ms - block_included FinalityParams: type: string description: | Indicates the finality status of the data provided. - Finalized data cannot be changed without slashing at least one-third of all validators, providing strong economic guarantees. - Data marked as not_finalized does not have this guarantee and may still change. enum: - not_finalized - finalized example: finalized SlotRange: type: object properties: start: $ref: '#/components/schemas/Slot' end: $ref: '#/components/schemas/Slot' required: - start - end EpochRange: type: object properties: start: $ref: '#/components/schemas/Epoch' end: $ref: '#/components/schemas/Epoch' required: - start - end TimeRange: type: object properties: start: $ref: '#/components/schemas/timestamp' end: $ref: '#/components/schemas/timestamp' required: - start - end 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. 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. ExecutionLayerAddress: type: string pattern: ^0x[a-fA-F0-9]{40}$ description: A standard Ethereum address (20-byte hex string with 0x prefix). example: '0x388C818CA8B9251b393131C08a736A67ccB19297' 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 timeRangeStartEnd: type: object description: Unix timestamp range (inclusive) properties: start: $ref: '#/components/schemas/timestamp' example: 0 description: Start Unix Timestamp end: $ref: '#/components/schemas/timestamp' example: 2147483647 description: End Unix Timestamp required: - start - end epochRangeStartEnd: type: object description: Epoch range (inclusive) properties: start: $ref: '#/components/schemas/EpochSelector' description: Start Epoch end: $ref: '#/components/schemas/EpochSelector' description: End Epoch required: - start - end slotRangeStartEnd: type: object description: Slot range (inclusive) properties: start: $ref: '#/components/schemas/SlotSelector' description: Start Slot end: $ref: '#/components/schemas/SlotSelector' description: End Slot validatorIndex: description: Validator Index type: integer minimum: 0 validatorPublicKey: type: string description: Public key of a validator pattern: ^0x[a-fA-F0-9]{96}$ example: >- 0xab6b6d826c14b6141e3406c5227ead15b133993195e96edc05fdeba998d0e0fd96e4ec5f47f6c9eec1558a59042c03d1 PayloadStatus: type: string enum: - full - empty - pending example: full description: >- Availability of the execution payload for this consensus block. Mirrors the consensus specification PayloadStatus enum. Null when the concept does not apply - slots before the Gloas hardfork, slots without a block, and orphaned blocks (an orphaned block never gains a canonical child, so its status would never resolve). EmptyReason: type: string enum: - withheld - skipped - no_verdict example: withheld description: >- Why the execution payload was empty, from the payload timeliness committee's votes included on chain. Set only when payload_status is 'empty'. 'withheld' means more than half of the committee's positions (PTC_SIZE / 2) voted that the payload was not present by the payload deadline; the chain does not distinguish a late payload from one never revealed. 'skipped' means more than half voted that the payload was present in time, yet the next canonical block did not build on it, which is not always the builder's doing, as its blob data may have arrived late. 'no_verdict' means neither side has a majority, or no block at the next slot could carry the votes. wei: type: string description: Amount in wei (1 ETH = 10^18 wei) pattern: ^(0|-?[1-9][0-9]*)$ example: '32000000000000000000' BuilderPaymentSettlement: type: string enum: - paid - pending - forfeited - void_slashed - ambiguous x-enum-varnames: - BuilderPaymentSettlementPaid - BuilderPaymentSettlementPending - BuilderPaymentSettlementForfeited - BuilderPaymentSettlementVoidSlashed - BuilderPaymentSettlementAmbiguous example: paid description: > Whether the chain paid the value of an accepted builder bid to the bid's fee recipient. - `paid`: the bid value was paid as a builder-payment withdrawal in a later execution payload. - `pending`: the payment is not decided yet, or it is decided and the withdrawal has not been found on chain yet. Withdrawals leave a first-in, first-out queue, so a backlog delays them. - `forfeited`: not paid. The chain did not include the payload, and same-slot attester weight stayed below the builder-payment quorum. A payload that a child block applied is never forfeited. - `void_slashed`: not paid, because the proposer was slashed while the payment was still pending. - `ambiguous`: we could not determine which payment, if any, discharged this bid. The bid value is still counted as the proposer's reward. BuilderPaymentQuorum: type: string enum: - reached - missed x-enum-varnames: - BuilderPaymentQuorumReached - BuilderPaymentQuorumMissed example: reached description: >- For a bid whose payload the chain did not include, whether same-slot attester weight reached the builder-payment quorum. `reached` means it met the quorum, so the chain pays the bid value unless the proposer is slashed first; `missed` means it did not, so the value is forfeited. PublishTimeObservation: type: string enum: - seen_on_gossip - not_seen_on_gossip - not_observed x-enum-varnames: - PublishTimeObservationSeenOnGossip - PublishTimeObservationNotSeenOnGossip - PublishTimeObservationNotObserved example: seen_on_gossip description: > How our node received the block. - `seen_on_gossip`: our node received the block over the peer-to-peer gossip network, and `slot_offset_ms` is set. - `not_seen_on_gossip`: our node imported the block, but did not receive it over gossip, for example while it was syncing or before it had verified the parent block's execution payload. The usual cause is our own node, not the proposer. - `not_observed`: our node has no record of the block, for example during an outage of our node. **Forward compatibility:** New values may be added to this enum. Treat a value you do not recognise as `not_observed`. Epoch: type: integer minimum: 0 timestamp: type: integer minimum: 0 EpochSelector: description: | Specify an epoch using one of the following methods. - epoch number - View: "latest", "finalized" oneOf: - $ref: '#/components/schemas/EpochByNumber' - $ref: '#/components/schemas/EpochByChainView' SlotSelector: description: | Specify a slot using one of the following methods. - Slot number - Consensus layer block root - View: "latest", "finalized" oneOf: - $ref: '#/components/schemas/SlotByNumber' - $ref: '#/components/schemas/SlotByConsensusLayerBlockRoot' - $ref: '#/components/schemas/SlotByChainView' default: latest EpochByNumber: title: Number type: object properties: number: $ref: '#/components/schemas/Epoch' required: - number EpochByChainView: title: View type: object properties: view: allOf: - $ref: '#/components/schemas/ChainView' description: > - "latest": Refers to the most recent epoch, which may not yet be finalized. - "finalized": Refers to the latest epoch that has been finalized and is not subject to change. required: - view SlotByNumber: title: Number type: object properties: number: $ref: '#/components/schemas/Slot' required: - number SlotByConsensusLayerBlockRoot: title: Root type: object properties: root: $ref: '#/components/schemas/ConsensusLayerBlockRoot' required: - root SlotByChainView: title: View type: object properties: view: allOf: - $ref: '#/components/schemas/ChainView' description: > - "latest": Refers to the most recent slot, which may be subject to reorganization. - "finalized": Refers to the latest slot that has been finalized and is not subject to change. required: - view ChainView: type: string enum: - latest - finalized description: > - "latest": Refers to the most recent block, which may be subject to reorganization. - "finalized": Refers to the latest block that has been finalized and is not subject to change. ConsensusLayerBlockRoot: type: string pattern: ^0x[a-fA-F0-9]{64}$ description: A 32-byte block root represented as a hex string with 0x prefix. 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.