💎 Builder Proposal Slots

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/builders/proposal-slots \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "hoodi",
  "builder": {
    "builder_pubkey": "0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3"
  },
  "page_size": 10
}
'

import requests

url = "https://beaconcha.in/api/v2/ethereum/builders/proposal-slots"

payload = {
    "chain": "hoodi",
    "builder": { "builder_pubkey": "0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3" },
    "page_size": 10
}
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_pubkey: '0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3'
    },
    page_size: 10
  })
};

fetch('https://beaconcha.in/api/v2/ethereum/builders/proposal-slots', 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/proposal-slots",
  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_pubkey' => '0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3'
    ],
    'page_size' => 10
  ]),
  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/proposal-slots"

	payload := strings.NewReader("{\n  \"chain\": \"hoodi\",\n  \"builder\": {\n    \"builder_pubkey\": \"0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3\"\n  },\n  \"page_size\": 10\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/proposal-slots")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"chain\": \"hoodi\",\n  \"builder\": {\n    \"builder_pubkey\": \"0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3\"\n  },\n  \"page_size\": 10\n}")
  .asString();

require 'uri'
require 'net/http'

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

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_pubkey\": \"0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3\"\n  },\n  \"page_size\": 10\n}"

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

{
  "data": [
    {
      "validator": {
        "index": 1,
        "public_key": "0xab6b6d826c14b6141e3406c5227ead15b133993195e96edc05fdeba998d0e0fd96e4ec5f47f6c9eec1558a59042c03d1"
      },
      "slot": 1,
      "finality": "finalized",
      "block": 1,
      "execution_payload": {
        "payload_status": "full",
        "self_built": true,
        "empty_reason": "withheld",
        "builder_index": 1,
        "builder_pubkey": "0xab6b6d826c14b6141e3406c5227ead15b133993195e96edc05fdeba998d0e0fd96e4ec5f47f6c9eec1558a59042c03d1",
        "builder_execution_address": "0x388C818CA8B9251b393131C08a736A67ccB19297",
        "bid_value": "32000000000000000000",
        "bid_fee_recipient": "0x388C818CA8B9251b393131C08a736A67ccB19297",
        "fee_recipient": "0x388C818CA8B9251b393131C08a736A67ccB19297",
        "extra_data": "0x546974616e",
        "settlement": "paid",
        "settled_slot": 1,
        "payment_quorum": "reached",
        "trusted_payment": "32000000000000000000",
        "trusted_payment_paid": "32000000000000000000",
        "proposer_reward": "32000000000000000000"
      },
      "publish_time": {
        "observation": "seen_on_gossip",
        "attestation_deadline_ms": 123,
        "block_included": true,
        "slot_offset_ms": 123,
        "seen_after_attestation_deadline": true
      }
    }
  ],
  "range": {
    "slot": {
      "start": 1,
      "end": 1
    },
    "epoch": {
      "start": 1,
      "end": 1
    },
    "timestamp": {
      "start": 1,
      "end": 1
    }
  },
  "paging": {
    "next_cursor": "eyJfc2FtcGxlX2N1cnNvciI6MTIzNDU2Nzg5MH0"
  }
}

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

Returns the proposals a builder won, newest first, whichever validator proposed them. From the Glamsterdam hard fork on, builders register on the beacon chain and bid to build a slot’s execution payload, the part of the block that carries its transactions. The proposer accepts one bid or builds the payload itself. A proposal is the builder’s when the proposer accepted its bid.

The rows have the same format as v2/ethereum/validators/proposal-slots. Each row’s validator is the proposer, and its execution_payload.builder_pubkey and execution_payload.builder_execution_address name the builder that won it.

A proposal matches whatever execution_payload.payload_status is. The builder won the slot even when the chain did not include its payload (empty); block is then null.
Self-built payloads (execution_payload.self_built is true), missed slots and orphaned blocks never match.
builder_index selects the builder that holds the index now, with every proposal of its public key. builder_entity selects every builder whose execution address beaconcha.in curated under that name, so one request lists an entity’s proposals.
A selector that matches no builder on the selected chain returns 404. A registered builder without won proposals in the range returns an empty list, also when the range ends before the fork.
A chain that has not reached the fork returns 404, so mainnet returns 404 until it forks.

You can combine this endpoint with:

Reward: v2/ethereum/block/rewards
Consensus slot information: v2/ethereum/slot
Execution block information: v2/ethereum/block
The builder registry: v2/ethereum/builders
The delivery and settlement record of the builder over a window: v2/ethereum/builders/performance-aggregate

Results can be filtered by a time range.

Note: This endpoint supports only finalized data at this time.

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

POST

api

ethereum

builders

proposal-slots

💎 Builder Proposal Slots

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/builders/proposal-slots \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "hoodi",
  "builder": {
    "builder_pubkey": "0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3"
  },
  "page_size": 10
}
'

import requests

url = "https://beaconcha.in/api/v2/ethereum/builders/proposal-slots"

payload = {
    "chain": "hoodi",
    "builder": { "builder_pubkey": "0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3" },
    "page_size": 10
}
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_pubkey: '0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3'
    },
    page_size: 10
  })
};

fetch('https://beaconcha.in/api/v2/ethereum/builders/proposal-slots', 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/proposal-slots",
  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_pubkey' => '0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3'
    ],
    'page_size' => 10
  ]),
  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/proposal-slots"

	payload := strings.NewReader("{\n  \"chain\": \"hoodi\",\n  \"builder\": {\n    \"builder_pubkey\": \"0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3\"\n  },\n  \"page_size\": 10\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/proposal-slots")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"chain\": \"hoodi\",\n  \"builder\": {\n    \"builder_pubkey\": \"0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3\"\n  },\n  \"page_size\": 10\n}")
  .asString();

require 'uri'
require 'net/http'

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

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_pubkey\": \"0xa0df2d753f8a123bb822a90e421a552c28008778920345a0510a22a346c25fc7c60bfc8c1f9cfd9b7ecd945fdcef68d3\"\n  },\n  \"page_size\": 10\n}"

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

{
  "data": [
    {
      "validator": {
        "index": 1,
        "public_key": "0xab6b6d826c14b6141e3406c5227ead15b133993195e96edc05fdeba998d0e0fd96e4ec5f47f6c9eec1558a59042c03d1"
      },
      "slot": 1,
      "finality": "finalized",
      "block": 1,
      "execution_payload": {
        "payload_status": "full",
        "self_built": true,
        "empty_reason": "withheld",
        "builder_index": 1,
        "builder_pubkey": "0xab6b6d826c14b6141e3406c5227ead15b133993195e96edc05fdeba998d0e0fd96e4ec5f47f6c9eec1558a59042c03d1",
        "builder_execution_address": "0x388C818CA8B9251b393131C08a736A67ccB19297",
        "bid_value": "32000000000000000000",
        "bid_fee_recipient": "0x388C818CA8B9251b393131C08a736A67ccB19297",
        "fee_recipient": "0x388C818CA8B9251b393131C08a736A67ccB19297",
        "extra_data": "0x546974616e",
        "settlement": "paid",
        "settled_slot": 1,
        "payment_quorum": "reached",
        "trusted_payment": "32000000000000000000",
        "trusted_payment_paid": "32000000000000000000",
        "proposer_reward": "32000000000000000000"
      },
      "publish_time": {
        "observation": "seen_on_gossip",
        "attestation_deadline_ms": 123,
        "block_included": true,
        "slot_offset_ms": 123,
        "seen_after_attestation_deadline": true
      }
    }
  ],
  "range": {
    "slot": {
      "start": 1,
      "end": 1
    },
    "epoch": {
      "start": 1,
      "end": 1
    },
    "timestamp": {
      "start": 1,
      "end": 1
    }
  },
  "paging": {
    "next_cursor": "eyJfc2FtcGxlX2N1cnNvciI6MTIzNDU2Nzg5MH0"
  }
}

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

chain

enum<string>

default:mainnet

The Ethereum chain to query.

Available options:

mainnet,

hoodi

range

Unix Timestamp · object

Specify a time range using either Unix timestamps or epoch numbers. If left null, the API will query the entire available history of the selected validators.

Unix Timestamp
Epoch
Slot

Show child attributes

cursor

string

default:""

Cursor value for pagination. See our pagination guide for more details.

page_size

integer

default:10

The number of items to return per page.

Required range: 1 <= x <= 10

Response

Successful response.

Response containing detailed proposal information of the validators.

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

paging

object

Show child attributes

Introduction

V2 API Docs

V1 API Docs

💎 Builder Proposal Slots

Authorizations

Body

Response