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.
External builder flow before ePBS
Validator registration
The validator submits a list of signed registrations. Each registration binds:
- the validator public key;
- its preferred execution fee recipient;
- its preferred gas limit; and
- a timestamp.
The service returns 200 only after the registrations pass validation and
must apply accepted policy to later blocks. Invalid registration returns
400.
Header request
The proposer requests a header for one slot, execution parent hash, and validator public key. It can send a request timestamp and timeout hint.
200 returns a versioned SignedBuilderBid. 204 means that no header is
available.
The bid also commits to the blob KZG commitments.
Before selection, the proposer checks:
- the builder BLS signature and allowed builder;
- slot, parent hash, and proposer public key;
- non-zero value and any local value policy;
- timestamp, fee recipient, gas-limit relation, and block hash;
- every withdrawal, execution-request, and auxiliary-data field that the active fork uses;
- transaction root and every other fork-specific payload-header field; and
- the count and values of blob commitments when the active fork carries them.
Only then can it compare the bid with another bid or a local execution payload.
Blinded block reveal
The proposer signs a blinded beacon block and submits it. The signed block binds the proposer to the selected header.
200 returns the matching execution payload and its blob bundle.
The proposer recomputes the header from the returned payload. It checks the block hash, transactions root, and all active-fork header, request, commitment, and proof fields against its signed block. A mismatch makes the response unusable.
The v1 endpoint is deprecated.
The v2 form returns 202 after it validates the signed blinded block. The
builder then publishes the signed unblinded beacon block and blob data instead
of returning the payload in the response. This shifts publication work to the
builder but keeps the proposer’s signed commitment unchanged.
Failure boundary
A proposer may keep a local payload build active while it waits for headers. A
timeout or 204 lets it use that local path. After it signs the blinded block,
it cannot safely switch payloads. A bad or missing reveal can therefore cause a
missed slot.
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.
400means invalid request data.401means failed or required request authentication on ePBS endpoints.406means the requested response encoding is not available.415means the request media type is not supported.500means 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.