> ## 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 Fee Recipients

> Returns the curated builder name of each fee recipient in the request. By convention, a builder sets its own address as the fee recipient (the coinbase) of the payloads it builds, so `entity` here names the owner of the payload coinbase: who built the payload. On [v2/ethereum/builders/metadata](/api-reference/ethereum/builders/metadata) and [v2/ethereum/builders/entities](/api-reference/ethereum/builders/entities), `entity` names who signed the winning bid instead, and for a payload that a relay signed the two differ. An address without a curated name returns a null `entity`, so one unknown address never fails the batch.

From the Glamsterdam hard fork on, the builder that signs the winning bid is not always the builder that built the payload. A relay, a service that forwards payloads from other builders, can register as a builder and sign the bids for their payloads. `execution_payload.builder_pubkey` then names the relay. The fee recipient still names the builder that built the payload, but only by convention, because the chain does not check it. The result is an attribution, never a proof.

To name the builder of a proposal's payload, take `execution_payload` from [v2/ethereum/validators/proposal-slots](/api-reference/ethereum/validators/proposal-slots) and apply these checks in order. The first check that applies gives the result. Compare addresses case-insensitively.

1. `self_built` is true: **self-built**. The proposer built the payload.
2. `fee_recipient` is null: **no payload**. No included payload is known: the chain did not include it, or, while `payload_status` is `pending`, it has not arrived yet.
3. `fee_recipient` is the zero address (`0x0000000000000000000000000000000000000000`): **unattributed**.
4. `fee_recipient` equals `bid_fee_recipient`, the address the bid pays the proposer at: **unattributed**. The payload pays its fees to the proposer, which names no builder.
5. Otherwise, look up `fee_recipient` with this endpoint: the result is `entity`, or **unattributed** when `entity` is null.

beaconcha.in's builder pages apply the same checks, with one difference: they also name the builder of a payload that the builder revealed but the chain did not include (`payload_status` `empty`). This API returns a null `fee_recipient` for such a payload, so step 2 gives **no payload**.

Entity names share one namespace with the `builder_entity` selector and [v2/ethereum/builders/entities](/api-reference/ethereum/builders/entities), which name the builders that sign bids. A name selects builders there only when one of its execution addresses in the builder registry is curated too, and a relay's name ends in " relay".

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 most `entity` values are null.

**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/fee-recipients
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/fee-recipients:
    post:
      tags:
        - Builders
      summary: 💎 Builder Fee Recipients
      description: >
        Returns the curated builder name of each fee recipient in the request.
        By convention, a builder sets its own address as the fee recipient (the
        coinbase) of the payloads it builds, so `entity` here names the owner of
        the payload coinbase: who built the payload. On
        [v2/ethereum/builders/metadata](/api-reference/ethereum/builders/metadata)
        and
        [v2/ethereum/builders/entities](/api-reference/ethereum/builders/entities),
        `entity` names who signed the winning bid instead, and for a payload
        that a relay signed the two differ. An address without a curated name
        returns a null `entity`, so one unknown address never fails the batch.


        From the Glamsterdam hard fork on, the builder that signs the winning
        bid is not always the builder that built the payload. A relay, a service
        that forwards payloads from other builders, can register as a builder
        and sign the bids for their payloads. `execution_payload.builder_pubkey`
        then names the relay. The fee recipient still names the builder that
        built the payload, but only by convention, because the chain does not
        check it. The result is an attribution, never a proof.


        To name the builder of a proposal's payload, take `execution_payload`
        from
        [v2/ethereum/validators/proposal-slots](/api-reference/ethereum/validators/proposal-slots)
        and apply these checks in order. The first check that applies gives the
        result. Compare addresses case-insensitively.


        1. `self_built` is true: **self-built**. The proposer built the payload.

        2. `fee_recipient` is null: **no payload**. No included payload is
        known: the chain did not include it, or, while `payload_status` is
        `pending`, it has not arrived yet.

        3. `fee_recipient` is the zero address
        (`0x0000000000000000000000000000000000000000`): **unattributed**.

        4. `fee_recipient` equals `bid_fee_recipient`, the address the bid pays
        the proposer at: **unattributed**. The payload pays its fees to the
        proposer, which names no builder.

        5. Otherwise, look up `fee_recipient` with this endpoint: the result is
        `entity`, or **unattributed** when `entity` is null.


        beaconcha.in's builder pages apply the same checks, with one difference:
        they also name the builder of a payload that the builder revealed but
        the chain did not include (`payload_status` `empty`). This API returns a
        null `fee_recipient` for such a payload, so step 2 gives **no payload**.


        Entity names share one namespace with the `builder_entity` selector and
        [v2/ethereum/builders/entities](/api-reference/ethereum/builders/entities),
        which name the builders that sign bids. A name selects builders there
        only when one of its execution addresses in the builder registry is
        curated too, and a relay's name ends in " relay".


        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 most `entity` values are null.


        **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan.
      operationId: GetBuilderFeeRecipients
      requestBody:
        $ref: '#/components/requestBodies/builderFeeRecipients'
      responses:
        '200':
          $ref: '#/components/responses/BuilderFeeRecipients'
        '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:
    builderFeeRecipients:
      x-go-name: BuilderFeeRecipientsRequestBody
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BuilderFeeRecipientsRequest'
          example:
            chain: hoodi
            fee_recipients:
              - '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97'
  responses:
    BuilderFeeRecipients:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BuilderFeeRecipients.ContainerList'
    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:
    BuilderFeeRecipientsRequest:
      type: object
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        fee_recipients:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/ExecutionLayerAddress'
          description: >-
            Execution payload fee recipients to look up, such as
            `execution_payload.fee_recipient` from
            [v2/ethereum/validators/proposal-slots](/api-reference/ethereum/validators/proposal-slots).
            Up to 100 per request.
      required:
        - fee_recipients
    BuilderFeeRecipients.ContainerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BuilderFeeRecipients.Data'
          description: One row per requested fee recipient, in the order of the request.
      required:
        - data
    Error:
      type: object
      properties:
        error:
          type: string
    Chain:
      type: string
      enum:
        - mainnet
        - hoodi
      default: mainnet
      description: The Ethereum chain to query.
    ExecutionLayerAddress:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: A standard Ethereum address (20-byte hex string with 0x prefix).
      example: '0x388C818CA8B9251b393131C08a736A67ccB19297'
    BuilderFeeRecipients.Data:
      type: object
      properties:
        fee_recipient:
          allOf:
            - $ref: '#/components/schemas/ExecutionLayerAddress'
          description: The requested fee recipient, EIP-55 checksummed.
        entity:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/BuilderEntityName'
          description: >-
            Name of the builder that beaconcha.in curated for this fee
            recipient, the owner of the payload coinbase, so who built a payload
            that pays its fees to this address. On
            [v2/ethereum/builders/metadata](/api-reference/ethereum/builders/metadata)
            and
            [v2/ethereum/builders/entities](/api-reference/ethereum/builders/entities),
            `entity` names who signed the bid instead. Null when the address has
            no curated name; the zero address never has one. 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 most entities are null.
      required:
        - fee_recipient
        - entity
    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.
  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.