Skip to main content
netspecsEthereum networking

4.4.2.Builder API

Stage
In progress
Version
Sources
builder-specs/builder-oapi.yaml78a5546bellatrix/validator.md78a5546fulu/builder.md78a5546gloas/validator.md78a5546gloas/builder.md78a5546gloas/p2p-interface.md3cbd26f
Related
Block productionePBS bidsePBS envelopes
Content
Pending reconstruction — no completeness claim is made.

The Builder API lets a consensus client use an external block builder. It is an HTTP service with JSON and, for selected bodies, SSZ encodings. A successful HTTP response does not remove the proposer’s duty to check signatures and payload commitments.

GET /eth/v1/builder/status is a health check. It carries no proof that a later bid or payload will be valid or timely.

Builder API with ePBS

The bid and reveal contracts use consensus-native objects. The Builder API remains a direct path between a proposer and builder.

Slot-scoped preferences

The proposer submits BuilderPreferencesRequestV1, including its maximum execution payment, and SignedRequestAuthV1.

The authentication message binds the slot and service URL. The builder checks the BLS signature against the path validator public key. It returns:

  • 202 for accepted preferences;
  • 400 for bad slot, URL, or preference values;
  • 401 for a bad signature; or
  • 500 for an internal failure.

A validator may submit preferences during the prior epoch when proposer lookahead already names its slot.

Bid request

The request names the slot, execution parent hash, beacon parent root, and proposer public key. It may carry signed request authentication.

The builder gets max_execution_payment only from the preference endpoint. If it has no accepted preferences, it treats that value as zero and does not add an execution payment to the bid.

200 returns a Gloas SignedExecutionPayloadBid. 204 means no bid. A builder can require authentication and return 401; otherwise the body is optional.

A valid direct response can enter the same local validation and selection path as a bid learned from consensus gossip. The HTTP route does not bypass consensus bid rules.

The pinned sources disagree on nonzero execution payments. The Builder API allows preferences and bids to carry them, while the consensus p2p validation rejects a bid whose execution_payment is nonzero. Until those sources align, a nonzero payment is not an interoperable Glamsterdam path. The ePBS bids page records the conflict in detail.

Signed beacon block submission

After it includes the selected bid and signs the beacon block, the proposer can submit the full signed beacon block to the builder. 202 means the builder accepted it. The builder then publishes the execution payload envelope. The proposer does not submit a blinded block and does not wait for an HTTP payload reveal.

Common encoding and errors

The Eth-Consensus-Version header identifies a versioned SSZ request or response where required. JSON responses also carry a version discriminator for fork-specific objects.

  • 400 means invalid request data.
  • 401 means failed or required request authentication on ePBS endpoints.
  • 406 means the requested response encoding is not available.
  • 415 means the request media type is not supported.
  • 500 means the service failed internally.

Clients treat timeouts separately from these replies. A timeout has unknown server outcome and must not be mistaken for a valid bid, reveal, or publication.