💎 Builder Performance Aggregate

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/builders/performance-aggregate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "hoodi",
  "builder": {
    "builder_index": 1889
  },
  "range": {
    "evaluation_window": "30d"
  }
}
'

import requests

url = "https://beaconcha.in/api/v2/ethereum/builders/performance-aggregate"

payload = {
    "chain": "hoodi",
    "builder": { "builder_index": 1889 },
    "range": { "evaluation_window": "30d" }
}
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',
    builder: {builder_index: 1889},
    range: {evaluation_window: '30d'}
  })
};

fetch('https://beaconcha.in/api/v2/ethereum/builders/performance-aggregate', 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/performance-aggregate",
  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',
    'builder' => [
        'builder_index' => 1889
    ],
    'range' => [
        'evaluation_window' => '30d'
    ]
  ]),
  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/performance-aggregate"

	payload := strings.NewReader("{\n  \"chain\": \"hoodi\",\n  \"builder\": {\n    \"builder_index\": 1889\n  },\n  \"range\": {\n    \"evaluation_window\": \"30d\"\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/performance-aggregate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"chain\": \"hoodi\",\n  \"builder\": {\n    \"builder_index\": 1889\n  },\n  \"range\": {\n    \"evaluation_window\": \"30d\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"builder\": {\n    \"builder_index\": 1889\n  },\n  \"range\": {\n    \"evaluation_window\": \"30d\"\n  }\n}"

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

{
  "data": {
    "evaluation_window": "30d",
    "builder_count": 123,
    "winning_builder_count": 123,
    "blocks_won": 123,
    "bid_value_total": "32000000000000000000",
    "bid_value_max": "32000000000000000000",
    "payload": {
      "full": 123,
      "empty": 123,
      "withheld": 123,
      "skipped": 123,
      "no_verdict": 123
    },
    "settlement": {
      "paid": 123,
      "paid_value": "32000000000000000000",
      "forfeited": 123,
      "forfeited_value": "32000000000000000000",
      "pending": 123,
      "pending_value": "32000000000000000000",
      "void_slashed": 123,
      "ambiguous": 123,
      "no_payment": 123
    },
    "trusted_payment": {
      "bid_count": 123,
      "promised": "32000000000000000000",
      "delivered": "32000000000000000000",
      "unchecked_count": 123
    }
  },
  "range": {
    "slot": {
      "start": 1,
      "end": 1
    },
    "epoch": {
      "start": 1,
      "end": 1
    },
    "timestamp": {
      "start": 1,
      "end": 1
    }
  }
}

{
  "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 Performance Aggregate

Returns the delivery and settlement record of the selected builders over an evaluation window: the proposals whose accepted bid they won, what happened to the execution payloads, whether the chain paid the bid values, and how much of the promised trusted payments the payloads delivered. The figures are raw counts and amounts, not a score.

From the Glamsterdam hard fork on, a proposer accepts a builder’s bid and the builder reveals the execution payload later. The bid value is paid from the builder’s balance when the chain includes the payload, and also when same-slot attester weight reached the builder-payment quorum although the chain did not include it. A trusted payment is an amount the builder promises to transfer inside the payload; the chain never checks or enforces it.

Only finalized slots whose execution payload status is decided count, and the window never reaches before the fork. The window ends at the last such slot, at most the last slot of the epoch before the head; range returns the window evaluated, or the requested window when no slot of it is decided yet. A builder that won nothing in the window returns zero counts. Bid values and payments are stored in Gwei and returned in wei.

Combine this endpoint with others for deeper insights:

The proposals behind these figures, one row each: v2/ethereum/builders/proposal-slots with the same builder selector
The registry entries of the builders, with balances and status: v2/ethereum/builders
The market share of every curated builder entity: v2/ethereum/builders/entities

Premium Endpoint: This endpoint requires a Scale or Enterprise plan.

POST

api

ethereum

builders

performance-aggregate

💎 Builder Performance Aggregate

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/builders/performance-aggregate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "hoodi",
  "builder": {
    "builder_index": 1889
  },
  "range": {
    "evaluation_window": "30d"
  }
}
'

import requests

url = "https://beaconcha.in/api/v2/ethereum/builders/performance-aggregate"

payload = {
    "chain": "hoodi",
    "builder": { "builder_index": 1889 },
    "range": { "evaluation_window": "30d" }
}
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',
    builder: {builder_index: 1889},
    range: {evaluation_window: '30d'}
  })
};

fetch('https://beaconcha.in/api/v2/ethereum/builders/performance-aggregate', 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/performance-aggregate",
  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',
    'builder' => [
        'builder_index' => 1889
    ],
    'range' => [
        'evaluation_window' => '30d'
    ]
  ]),
  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/performance-aggregate"

	payload := strings.NewReader("{\n  \"chain\": \"hoodi\",\n  \"builder\": {\n    \"builder_index\": 1889\n  },\n  \"range\": {\n    \"evaluation_window\": \"30d\"\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/performance-aggregate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"chain\": \"hoodi\",\n  \"builder\": {\n    \"builder_index\": 1889\n  },\n  \"range\": {\n    \"evaluation_window\": \"30d\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"builder\": {\n    \"builder_index\": 1889\n  },\n  \"range\": {\n    \"evaluation_window\": \"30d\"\n  }\n}"

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

{
  "data": {
    "evaluation_window": "30d",
    "builder_count": 123,
    "winning_builder_count": 123,
    "blocks_won": 123,
    "bid_value_total": "32000000000000000000",
    "bid_value_max": "32000000000000000000",
    "payload": {
      "full": 123,
      "empty": 123,
      "withheld": 123,
      "skipped": 123,
      "no_verdict": 123
    },
    "settlement": {
      "paid": 123,
      "paid_value": "32000000000000000000",
      "forfeited": 123,
      "forfeited_value": "32000000000000000000",
      "pending": 123,
      "pending_value": "32000000000000000000",
      "void_slashed": 123,
      "ambiguous": 123,
      "no_payment": 123
    },
    "trusted_payment": {
      "bid_count": 123,
      "promised": "32000000000000000000",
      "delivered": "32000000000000000000",
      "unchecked_count": 123
    }
  },
  "range": {
    "slot": {
      "start": 1,
      "end": 1
    },
    "epoch": {
      "start": 1,
      "end": 1
    },
    "timestamp": {
      "start": 1,
      "end": 1
    }
  }
}

{
  "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

builder

Builder Public Key · object

required

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.

Builder Public Key
Builder Index
💎 Builder Execution Address
💎 Builder Entity

Show child attributes

range

Fixed Window · object

required

Show child attributes

chain

enum<string>

default:mainnet

The Ethereum chain to query.

Available options:

mainnet,

hoodi

Response

Successful response.

Response containing the delivery and settlement record of the selected builders over the evaluation window.

data

object

required

Show child attributes

range

object

required

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.

Show child attributes

Introduction

V2 API Docs

V1 API Docs

💎 Builder Performance Aggregate

Authorizations

Body

Response