💎 Builder Fee Recipients

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/builders/fee-recipients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "hoodi",
  "fee_recipients": [
    "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
  ]
}
'

import requests

url = "https://beaconcha.in/api/v2/ethereum/builders/fee-recipients"

payload = {
    "chain": "hoodi",
    "fee_recipients": ["0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({chain: 'hoodi', fee_recipients: ['0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97']})
};

fetch('https://beaconcha.in/api/v2/ethereum/builders/fee-recipients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://beaconcha.in/api/v2/ethereum/builders/fee-recipients",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'chain' => 'hoodi',
    'fee_recipients' => [
        '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://beaconcha.in/api/v2/ethereum/builders/fee-recipients"

	payload := strings.NewReader("{\n  \"chain\": \"hoodi\",\n  \"fee_recipients\": [\n    \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://beaconcha.in/api/v2/ethereum/builders/fee-recipients")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"chain\": \"hoodi\",\n  \"fee_recipients\": [\n    \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://beaconcha.in/api/v2/ethereum/builders/fee-recipients")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"chain\": \"hoodi\",\n  \"fee_recipients\": [\n    \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "fee_recipient": "0x388C818CA8B9251b393131C08a736A67ccB19297",
      "entity": "Titan"
    }
  ]
}

{
  "error": "Bad request. Please check your input and try again."
}

{
  "error": "Unauthorized. Please provide a valid API key."
}

{
  "error": "endpoint not allowed for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing."
}

{
  "error": "The requested resource was not found."
}

{
  "error": "method not allowed: GET. all public API endpoints use POST."
}

{
  "error": "Rate limit exceeded. Please try again later."
}

{
  "error": "internal server error. please try again later."
}

{
  "error": "An unexpected error occurred."
}

Builders

💎 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 and v2/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 and apply these checks in order. The first check that applies gives the result. Compare addresses case-insensitively.

self_built is true: self-built. The proposer built the payload.
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.
fee_recipient is the zero address (0x0000000000000000000000000000000000000000): unattributed.
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.
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, 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.

POST

api

ethereum

builders

fee-recipients

💎 Builder Fee Recipients

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/builders/fee-recipients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "hoodi",
  "fee_recipients": [
    "0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"
  ]
}
'

import requests

url = "https://beaconcha.in/api/v2/ethereum/builders/fee-recipients"

payload = {
    "chain": "hoodi",
    "fee_recipients": ["0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({chain: 'hoodi', fee_recipients: ['0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97']})
};

fetch('https://beaconcha.in/api/v2/ethereum/builders/fee-recipients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://beaconcha.in/api/v2/ethereum/builders/fee-recipients",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'chain' => 'hoodi',
    'fee_recipients' => [
        '0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://beaconcha.in/api/v2/ethereum/builders/fee-recipients"

	payload := strings.NewReader("{\n  \"chain\": \"hoodi\",\n  \"fee_recipients\": [\n    \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://beaconcha.in/api/v2/ethereum/builders/fee-recipients")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"chain\": \"hoodi\",\n  \"fee_recipients\": [\n    \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://beaconcha.in/api/v2/ethereum/builders/fee-recipients")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"chain\": \"hoodi\",\n  \"fee_recipients\": [\n    \"0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "fee_recipient": "0x388C818CA8B9251b393131C08a736A67ccB19297",
      "entity": "Titan"
    }
  ]
}

{
  "error": "Bad request. Please check your input and try again."
}

{
  "error": "Unauthorized. Please provide a valid API key."
}

{
  "error": "endpoint not allowed for your subscription tier. upgrade your subscription at https://beaconcha.in/pricing."
}

{
  "error": "The requested resource was not found."
}

{
  "error": "method not allowed: GET. all public API endpoints use POST."
}

{
  "error": "Rate limit exceeded. Please try again later."
}

{
  "error": "internal server error. please try again later."
}

{
  "error": "An unexpected error occurred."
}

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.

Authorizations

Authorization

string

header

required

Authorization header with value: Bearer YOUR_TOKEN. Refer to the API Keys section to create your API key.

Body

application/json

fee_recipients

string[]

required

Execution payload fee recipients to look up, such as execution_payload.fee_recipient from v2/ethereum/validators/proposal-slots. Up to 100 per request.

Required array length: 1 - 100 elements

A standard Ethereum address (20-byte hex string with 0x prefix).

Pattern: ^0x[a-fA-F0-9]{40}$

chain

enum<string>

default:mainnet

The Ethereum chain to query.

Available options:

mainnet,

hoodi

Response

Successful response.

data

object[]

required

One row per requested fee recipient, in the order of the request.

Show child attributes

Introduction

V2 API Docs

V1 API Docs

💎 Builder Fee Recipients

Authorizations

Body

Response