Skip to main content
API docs by Redocly

Teku (v23.1.0+43-gca39f81fb4)

Download OpenAPI specification:Download

License: Apache 2.0

A minimal API specification for the beacon node, which enables a validator to connect and perform its obligations on the Ethereum beacon chain.

Beacon

Get chain genesis details

Retrieve details of the chain's genesis which can be used to identify chain.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get state root

Calculates HashTreeRoot for state with given 'state_id'. If stateId is root, same value will be returned.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": {
    }
}

Get state fork

Returns Fork object for state with given 'state_id'.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": {
    }
}

Get state finality checkpoints

Returns finality checkpoints for state with given 'state_id'. In case finality is not yet achieved, checkpoint should return epoch 0 and ZERO_HASH as root.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": {
    }
}

Get validators from state

Returns filterable list of validators with their balance, status and index.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

query Parameters
id
Array of strings >= 1 items
status
Array of strings <string> >= 1 items
Example: status=active_ongoing

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": [
    ]
}

Get validator from state

Retrieves data about the given peer.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

validator_id
required
string
Example: 1

Either hex encoded public key (with 0x prefix) or validator index

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": {
    }
}

Get validator balances from state

Returns filterable list of validator balances.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

query Parameters
id
Array of strings >= 1 items

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": [
    ]
}

Get committees at state

Retrieves the committees for the given state.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

query Parameters
epoch
string <uint64>
Example: epoch=1

uint64 Epoch number to query.

index
string <uint64>
Example: index=1

uint64 Committee index to query.

slot
string <uint64>
Example: slot=1

UInt64 Slot to query in the canonical chain.

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": [
    ]
}

Get sync committees

Retrieves the sync committees for the given state.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

query Parameters
epoch
string <uint64>
Example: epoch=1

uint64 Epoch number to query.

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": {
    }
}

Get chain genesis details

Fetch the RANDAO mix for the requested epoch from the state identified by state_id.

If an epoch is not specified then the RANDAO mix for the state's current epoch will be returned.

By adjusting the state_id parameter you can query for any historic value of the RANDAO mix. Ordinarily states from the same epoch will mutate the RANDAO mix for that epoch as blocks are applied.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

query Parameters
epoch
string <uint64>
Example: epoch=1

uint64 Epoch number to query.

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": {
    }
}

Get block headers

Retrieves block headers matching given query. By default it will fetch current head slot blocks.

query Parameters
slot
string <uint64>
Example: slot=1

UInt64 Slot to query in the canonical chain.

parent_root
string <byte>
Example: parent_root=0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2

Not currently supported.

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": [
    ]
}

Get block header

Retrieves block header for given block id.

path Parameters
block_id
required
string
Example: head

Block identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "execution_optimistic": true,
  • "finalized": true
}

Publish a signed block

Submit a signed beacon block to the beacon node to be imported. The beacon node performs the required validation.

Request Body schema:
string <binary>

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get block

Retrieves block details for given block id.

NOTE: only phase 0 blocks are returned, use /eth/v2/beacon/blocks/{block_id} for multiple milestone support.

path Parameters
block_id
required
string
Example: head

Block identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get block

Retrieves block details for given block id.

path Parameters
block_id
required
string
Example: head

Block identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.

Responses

Response samples

Content type
{
  • "version": "phase0",
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": {
    }
}

Get blinded block

Retrieves blinded block details for given block id. Depending on Accept header it can be returned either as JSON or as bytes serialized by SSZ

path Parameters
block_id
required
string
Example: head

Block identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.

Responses

Response samples

Content type
{
  • "version": "phase0",
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": {
    }
}

Get block root

Retrieves hashTreeRoot of BeaconBlock/BeaconBlockHeader

path Parameters
block_id
required
string
Example: head

Block identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "execution_optimistic": true,
  • "finalized": true
}

Get block attestations

Retrieves attestations included in requested block.

path Parameters
block_id
required
string
Example: head

Block identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": [
    ]
}

Get attestations

Retrieves attestations known by the node but not necessarily incorporated into any block.

query Parameters
slot
string <uint64>
Example: slot=1

UInt64 Slot to query in the canonical chain.

committee_index
string <uint64>
Example: committee_index=1

uint64 Committee index to query.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Submit signed attestations

Submit signed attestations to the beacon node to be validated and submitted if valid.

This endpoint does not protected against slashing.

Request Body schema: application/json
Array
aggregation_bits
required
string <bytes> ^0x[a-fA-F0-9]{2,}$

SSZ hexadecimal

required
object (AttestationData)
signature
required
string <bytes> ^0x[a-fA-F0-9]{2,}$

SSZ hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "failures": [
    ]
}

Get Attester Slashings

Retrieves attester slashings known by the node but not necessarily incorporated into any block.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Submit attester slashing object

Submits attester slashing object to node's pool and if passes validation node MUST broadcast it to network.

Request Body schema: application/json
required
object (IndexedAttestation)
required
object (IndexedAttestation)

Responses

Request samples

Content type
application/json
{
  • "attestation_1": {
    },
  • "attestation_2": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get proposer slashings

Retrieves proposer slashings known by the node but not necessarily incorporated into any block.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Submit proposer slashing object

Submits proposer slashing object to node's pool and, if it passes validation, the node MUST broadcast it to network.

Request Body schema: application/json
required
object (SignedBeaconBlockHeader)
required
object (SignedBeaconBlockHeader)

Responses

Request samples

Content type
application/json
{
  • "signed_header_1": {
    },
  • "signed_header_2": {
    }
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get signed voluntary exits

Retrieves voluntary exits known by the node but not necessarily incorporated into any block.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Submit signed voluntary exit

Submits signed voluntary exit object to node's pool and if it passes validation node MUST broadcast it to network.

Request Body schema: application/json
required
object (VoluntaryExit)
signature
required
string <bytes> ^0x[a-fA-F0-9]{2,}$

SSZ hexadecimal

Responses

Request samples

Content type
application/json
{
  • "message": {
    },
  • "signature": "string"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Submit sync committee messages to node

Submits sync committee message objects to the node.

Sync committee messages are not present in phase0, but are required for Altair networks.

If a sync committee message is validated successfully the node MUST publish that sync committee message on all applicable subnets.

If one or more sync committee messages fail validation the node MUST return a 400 error with details of which sync committee messages have failed, and why.

Request Body schema: application/json
Array
slot
required
string <uint64>

unsigned 64 bit integer

beacon_block_root
required
string <byte>

Bytes32 hexadecimal

validator_index
required
string <uint64>

unsigned 64 bit integer

signature
required
string <bytes> ^0x[a-fA-F0-9]{2,}$

SSZ hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "message": "string",
  • "failures": [
    ]
}

Submit SignedBLSToExecutionChange object to node's pool

Submits SignedBLSToExecutionChange object to node's pool and if passes validation node MUST broadcast it to network.

Request Body schema: application/json
Array
required
object (BLSToExecutionChange)
signature
required
string <bytes> ^0x[a-fA-F0-9]{2,}$

SSZ hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "failures": [
    ]
}

Get SignedBLSToExecutionChange from operations pool

Retrieves BLS to execution changes known by the node but not necessarily incorporated into any block

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Validator Required Api

Get chain genesis details

Retrieve details of the chain's genesis which can be used to identify chain.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get state fork

Returns Fork object for state with given 'state_id'.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": {
    }
}

Get validator from state

Retrieves data about the given peer.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

validator_id
required
string
Example: 1

Either hex encoded public key (with 0x prefix) or validator index

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": {
    }
}

Get sync committees

Retrieves the sync committees for the given state.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

query Parameters
epoch
string <uint64>
Example: epoch=1

uint64 Epoch number to query.

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": {
    }
}

Publish a signed block

Submit a signed beacon block to the beacon node to be imported. The beacon node performs the required validation.

Request Body schema:
string <binary>

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Publish a signed blinded block

Submit a signed blinded beacon block to the beacon node to be imported. The beacon node performs the required validation.

Request Body schema:
string <binary>

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Submit signed attestations

Submit signed attestations to the beacon node to be validated and submitted if valid.

This endpoint does not protected against slashing.

Request Body schema: application/json
Array
aggregation_bits
required
string <bytes> ^0x[a-fA-F0-9]{2,}$

SSZ hexadecimal

required
object (AttestationData)
signature
required
string <bytes> ^0x[a-fA-F0-9]{2,}$

SSZ hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string",
  • "failures": [
    ]
}

Submit sync committee messages to node

Submits sync committee message objects to the node.

Sync committee messages are not present in phase0, but are required for Altair networks.

If a sync committee message is validated successfully the node MUST publish that sync committee message on all applicable subnets.

If one or more sync committee messages fail validation the node MUST return a 400 error with details of which sync committee messages have failed, and why.

Request Body schema: application/json
Array
slot
required
string <uint64>

unsigned 64 bit integer

beacon_block_root
required
string <byte>

Bytes32 hexadecimal

validator_index
required
string <uint64>

unsigned 64 bit integer

signature
required
string <bytes> ^0x[a-fA-F0-9]{2,}$

SSZ hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
Example
{
  • "code": 0,
  • "message": "string",
  • "failures": [
    ]
}

Subscribe to node events

Provides endpoint to subscribe to beacon node Server-Sent-Events stream. Consumers should use eventsource implementation to listen on those events.

Servers may send SSE comments beginning with : for any purpose, including to keep the event stream connection alive in the presence of proxy servers.

query Parameters
topics
string
Example: topics=head

Event types to subscribe to. Available values include: [head, finalized_checkpoint, chain_reorg, block, attestation, voluntary_exit, contribution_and_proof]

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get node syncing status

Requests the beacon node to describe if it's currently syncing or not, and if it is, what block it is up to.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get attester duties

Requests the beacon node to provide a set of attestation duties, which should be performed by validators, for a particular epoch. Duties should only need to be checked once per epoch, however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety, you should monitor head events and confirm the dependent root in this response matches:

  • event.previous_duty_dependent_root when compute_epoch_at_slot(event.slot) == epoch
  • event.current_duty_dependent_root when compute_epoch_at_slot(event.slot) + 1 == epoch
  • event.block otherwise

The dependent_root value is get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1) or the genesis block root in the case of underflow.

path Parameters
epoch
required
string <uint64>
Example: 1

uint64 Epoch number to query.

Request Body schema: application/json
Array
string <integer>

integer string

Responses

Request samples

Content type
application/json
[
  • "1"
]

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "dependent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
  • "data": [
    ]
}

Get proposer duties

Request beacon node to provide all validators that are scheduled to propose a block in the given epoch.

Duties should only need to be checked once per epoch, however a chain reorganization could occur that results in a change of duties. For full safety, you should monitor head events and confirm the dependent root in this response matches:

  • event.current_duty_dependent_root when compute_epoch_at_slot(event.slot) == epoch
  • event.block otherwise

The dependent_root value is get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1) or the genesis block root in the case of underflow.

path Parameters
epoch
required
string <uint64>
Example: 1

uint64 Epoch number to query.

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "dependent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
  • "data": [
    ]
}

Produce unsigned block

Requests a beacon node to produce a valid block, which can then be signed by a validator.

NOTE: deprecated, switch to using /eth/v2/validator/blocks/{slot} for multiple milestone support.

path Parameters
slot
required
string <uint64>
Example: 1

The slot for which the block should be proposed.

query Parameters
randao_reveal
required
string <byte>
Example: randao_reveal=0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505

BLSSignature Hex BLS12-381 signature for the current epoch.

graffiti
string <byte>
Example: graffiti=0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2

Bytes32 Hex Graffiti.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Produce unsigned block

Requests a beacon node to produce a valid block, which can then be signed by a validator. Metadata in the response indicates the type of block produced, and the supported types of block will be added to as forks progress.

path Parameters
slot
required
string <uint64>
Example: 1

The slot for which the block should be proposed.

query Parameters
randao_reveal
required
string <byte>
Example: randao_reveal=0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505

BLSSignature Hex BLS12-381 signature for the current epoch.

graffiti
string <byte>
Example: graffiti=0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2

Bytes32 Hex Graffiti.

Responses

Response samples

Content type
{
  • "data": {
    },
  • "version": "phase0"
}

Produce unsigned blinded block

Requests a beacon node to produce a valid blinded block, which can then be signed by a validator. A blinded block is a block with only a transactions root, rather than a full transactions list.

Metadata in the response indicates the type of block produced, and the supported types of block will be added to as forks progress.

Pre-Bellatrix, this endpoint will return a BeaconBlock.

path Parameters
slot
required
string <uint64>
Example: 1

The slot for which the block should be proposed.

query Parameters
randao_reveal
required
string <byte>
Example: randao_reveal=0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505

BLSSignature Hex BLS12-381 signature for the current epoch.

graffiti
string <byte>
Example: graffiti=0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2

Bytes32 Hex Graffiti.

Responses

Response samples

Content type
{
  • "data": {
    },
  • "version": "phase0"
}

Produce an AttestationData

Requests that the beacon node produce an AttestationData.

query Parameters
slot
string <uint64>
Example: slot=1

uint64 The slot for which an attestation data should be created.

committee_index
string <uint64>
Example: committee_index=1

UInt64 The committee index for which an attestation data should be created.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get aggregated attestations

Aggregates all attestations matching given attestation data root and slot.

query Parameters
attestation_data_root
required
string <byte>
Example: attestation_data_root=0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2

String HashTreeRoot of AttestationData that validator wants aggregated.

slot
required
string <uint64>
Example: slot=1

uint64 Non-finalized slot for which to create the aggregation.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Publish aggregate and proofs

Verifies given aggregate and proofs and publishes it on appropriate gossipsub topic.

Request Body schema: application/json
Array
required
object (AggregateAndProof)
signature
required
string <bytes> ^0x[a-fA-F0-9]{2,}$

SSZ hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Subscribe to a committee subnet

After Beacon node receives this request, search using discv5 for peers related to this subnet and replace current peers with those ones if necessary If validator is_aggregator, beacon node must:

  • announce subnet topic subscription on gossipsub
  • aggregate attestations received on that subnet
Request Body schema: application/json
Array
validator_index
required
string <integer>

integer string

committee_index
required
string <integer>

integer string

committees_at_slot
required
string <uint64>

unsigned 64 bit integer

slot
required
string <uint64>

unsigned 64 bit integer

is_aggregator
required
boolean

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get sync committee duties

Requests the beacon node to provide a set of sync committee duties

path Parameters
epoch
required
string <uint64>
Example: 1

uint64 Epoch number to query.

Request Body schema: application/json
Array
string <integer>

integer string

Responses

Request samples

Content type
application/json
[
  • "1"
]

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "data": [
    ]
}

Produce a sync committee contribution

Returns a SyncCommitteeContribution that is the aggregate of SyncCommitteeMessage values known to this node matching the specified slot, subcommittee index and beacon block root.

query Parameters
slot
required
string <uint64>
Example: slot=1

UInt64 Slot to query in the canonical chain.

subcommittee_index
required
number

Integer The subcommittee index for which to produce the contribution.

beacon_block_root
required
string <byte>
Example: beacon_block_root=0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2

bytes32 The block root for which to produce the contribution.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Subscribe to a Sync committee subnet

Subscribe to a number of sync committee subnets

Sync committees are not present in phase0, but are required for Altair networks.

Subscribing to sync committee subnets is an action performed by VC to enable network participation in Altair networks, and only required if the VC has an active validator in an active sync committee.

Request Body schema: application/json
Array
validator_index
required
string <integer>

integer string

sync_committee_indices
required
Array of strings <integer>
until_epoch
required
string <uint64>

unsigned 64 bit integer

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Publish contribution and proofs

Verifies given sync committee contribution and proofs and publishes on appropriate gossipsub topics.

Request Body schema: application/json
Array
required
object (ContributionAndProof)
signature
required
string <bytes> ^0x[a-fA-F0-9]{2,}$

SSZ hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Prepare Beacon Proposers

Prepares the beacon node for potential proposers by supplying information required when proposing blocks for the given validators. The information supplied for each validator index is considered persistent until overwritten by new information for the given validator index, or until the beacon node restarts.

Note that because the information is not persistent across beacon node restarts it is recommended that either the beacon node is monitored for restarts or this information is refreshed by resending this request periodically (for example, each epoch).

Also note that requests containing currently inactive or unknown validator indices will be accepted, as they may become active at a later epoch.

Request Body schema: application/json
Array
validator_index
required
string <uint64>

unsigned 64 bit integer

fee_recipient
required
string <byte>

Hex encoded deposit contract address with 0x prefix

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Register validators with builder

Prepares the beacon node for engaging with external builders. The information must be sent by the beacon node to the builder network. It is expected that the validator client will send this information periodically to ensure the beacon node has correct and timely registration information to provide to builders. The validator client should not sign blinded beacon blocks that do not adhere to their latest fee recipient and gas limit preferences.

Request Body schema:
string <binary>

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get spec params

Retrieve specification configuration used on this node.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Validator

Publish a signed blinded block

Submit a signed blinded beacon block to the beacon node to be imported. The beacon node performs the required validation.

Request Body schema:
string <binary>

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get attester duties

Requests the beacon node to provide a set of attestation duties, which should be performed by validators, for a particular epoch. Duties should only need to be checked once per epoch, however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety, you should monitor head events and confirm the dependent root in this response matches:

  • event.previous_duty_dependent_root when compute_epoch_at_slot(event.slot) == epoch
  • event.current_duty_dependent_root when compute_epoch_at_slot(event.slot) + 1 == epoch
  • event.block otherwise

The dependent_root value is get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1) or the genesis block root in the case of underflow.

path Parameters
epoch
required
string <uint64>
Example: 1

uint64 Epoch number to query.

Request Body schema: application/json
Array
string <integer>

integer string

Responses

Request samples

Content type
application/json
[
  • "1"
]

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "finalized": true,
  • "dependent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
  • "data": [
    ]
}

Get proposer duties

Request beacon node to provide all validators that are scheduled to propose a block in the given epoch.

Duties should only need to be checked once per epoch, however a chain reorganization could occur that results in a change of duties. For full safety, you should monitor head events and confirm the dependent root in this response matches:

  • event.current_duty_dependent_root when compute_epoch_at_slot(event.slot) == epoch
  • event.block otherwise

The dependent_root value is get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1) or the genesis block root in the case of underflow.

path Parameters
epoch
required
string <uint64>
Example: 1

uint64 Epoch number to query.

Responses

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "dependent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
  • "data": [
    ]
}

Produce unsigned block

Requests a beacon node to produce a valid block, which can then be signed by a validator.

NOTE: deprecated, switch to using /eth/v2/validator/blocks/{slot} for multiple milestone support.

path Parameters
slot
required
string <uint64>
Example: 1

The slot for which the block should be proposed.

query Parameters
randao_reveal
required
string <byte>
Example: randao_reveal=0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505

BLSSignature Hex BLS12-381 signature for the current epoch.

graffiti
string <byte>
Example: graffiti=0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2

Bytes32 Hex Graffiti.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Produce unsigned block

Requests a beacon node to produce a valid block, which can then be signed by a validator. Metadata in the response indicates the type of block produced, and the supported types of block will be added to as forks progress.

path Parameters
slot
required
string <uint64>
Example: 1

The slot for which the block should be proposed.

query Parameters
randao_reveal
required
string <byte>
Example: randao_reveal=0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505

BLSSignature Hex BLS12-381 signature for the current epoch.

graffiti
string <byte>
Example: graffiti=0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2

Bytes32 Hex Graffiti.

Responses

Response samples

Content type
{
  • "data": {
    },
  • "version": "phase0"
}

Produce unsigned blinded block

Requests a beacon node to produce a valid blinded block, which can then be signed by a validator. A blinded block is a block with only a transactions root, rather than a full transactions list.

Metadata in the response indicates the type of block produced, and the supported types of block will be added to as forks progress.

Pre-Bellatrix, this endpoint will return a BeaconBlock.

path Parameters
slot
required
string <uint64>
Example: 1

The slot for which the block should be proposed.

query Parameters
randao_reveal
required
string <byte>
Example: randao_reveal=0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505

BLSSignature Hex BLS12-381 signature for the current epoch.

graffiti
string <byte>
Example: graffiti=0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2

Bytes32 Hex Graffiti.

Responses

Response samples

Content type
{
  • "data": {
    },
  • "version": "phase0"
}

Produce an AttestationData

Requests that the beacon node produce an AttestationData.

query Parameters
slot
string <uint64>
Example: slot=1

uint64 The slot for which an attestation data should be created.

committee_index
string <uint64>
Example: committee_index=1

UInt64 The committee index for which an attestation data should be created.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get aggregated attestations

Aggregates all attestations matching given attestation data root and slot.

query Parameters
attestation_data_root
required
string <byte>
Example: attestation_data_root=0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2

String HashTreeRoot of AttestationData that validator wants aggregated.

slot
required
string <uint64>
Example: slot=1

uint64 Non-finalized slot for which to create the aggregation.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Publish aggregate and proofs

Verifies given aggregate and proofs and publishes it on appropriate gossipsub topic.

Request Body schema: application/json
Array
required
object (AggregateAndProof)
signature
required
string <bytes> ^0x[a-fA-F0-9]{2,}$

SSZ hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Subscribe to a committee subnet

After Beacon node receives this request, search using discv5 for peers related to this subnet and replace current peers with those ones if necessary If validator is_aggregator, beacon node must:

  • announce subnet topic subscription on gossipsub
  • aggregate attestations received on that subnet
Request Body schema: application/json
Array
validator_index
required
string <integer>

integer string

committee_index
required
string <integer>

integer string

committees_at_slot
required
string <uint64>

unsigned 64 bit integer

slot
required
string <uint64>

unsigned 64 bit integer

is_aggregator
required
boolean

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get sync committee duties

Requests the beacon node to provide a set of sync committee duties

path Parameters
epoch
required
string <uint64>
Example: 1

uint64 Epoch number to query.

Request Body schema: application/json
Array
string <integer>

integer string

Responses

Request samples

Content type
application/json
[
  • "1"
]

Response samples

Content type
application/json
{
  • "execution_optimistic": true,
  • "data": [
    ]
}

Produce a sync committee contribution

Returns a SyncCommitteeContribution that is the aggregate of SyncCommitteeMessage values known to this node matching the specified slot, subcommittee index and beacon block root.

query Parameters
slot
required
string <uint64>
Example: slot=1

UInt64 Slot to query in the canonical chain.

subcommittee_index
required
number

Integer The subcommittee index for which to produce the contribution.

beacon_block_root
required
string <byte>
Example: beacon_block_root=0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2

bytes32 The block root for which to produce the contribution.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Subscribe to a Sync committee subnet

Subscribe to a number of sync committee subnets

Sync committees are not present in phase0, but are required for Altair networks.

Subscribing to sync committee subnets is an action performed by VC to enable network participation in Altair networks, and only required if the VC has an active validator in an active sync committee.

Request Body schema: application/json
Array
validator_index
required
string <integer>

integer string

sync_committee_indices
required
Array of strings <integer>
until_epoch
required
string <uint64>

unsigned 64 bit integer

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Publish contribution and proofs

Verifies given sync committee contribution and proofs and publishes on appropriate gossipsub topics.

Request Body schema: application/json
Array
required
object (ContributionAndProof)
signature
required
string <bytes> ^0x[a-fA-F0-9]{2,}$

SSZ hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Prepare Beacon Proposers

Prepares the beacon node for potential proposers by supplying information required when proposing blocks for the given validators. The information supplied for each validator index is considered persistent until overwritten by new information for the given validator index, or until the beacon node restarts.

Note that because the information is not persistent across beacon node restarts it is recommended that either the beacon node is monitored for restarts or this information is refreshed by resending this request periodically (for example, each epoch).

Also note that requests containing currently inactive or unknown validator indices will be accepted, as they may become active at a later epoch.

Request Body schema: application/json
Array
validator_index
required
string <uint64>

unsigned 64 bit integer

fee_recipient
required
string <byte>

Hex encoded deposit contract address with 0x prefix

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Register validators with builder

Prepares the beacon node for engaging with external builders. The information must be sent by the beacon node to the builder network. It is expected that the validator client will send this information periodically to ensure the beacon node has correct and timely registration information to provide to builders. The validator client should not sign blinded beacon blocks that do not adhere to their latest fee recipient and gas limit preferences.

Request Body schema:
string <binary>

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Experimental

Get full BeaconState object for finalized checkpoint state

Returns full BeaconState object for a finalized checkpoint state from the Weak Subjectivity period.

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get finalized block root

Retrieves hashTreeRoot of finalized Beacon Block.

Responds with 404 if block at a slot is either unavailable or not yet finalized.

path Parameters
slot
required
string <uint64>
Example: 1

uint64 value representing slot

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Validator Liveness

Requests the beacon node to indicate if a validator has been observed to be live in a given epoch. The beacon node might detect liveness by observing messages from the validator on the network, in the beacon chain, from its API or from any other source. It is important to note that the values returned by the beacon node are not canonical; they are best-effort and based upon a subjective view of the network.

path Parameters
epoch
required
string <uint64>
Example: 1

uint64 Epoch number to query.

Request Body schema: application/json
indices
required
Array of strings <uint64>

Responses

Request samples

Content type
application/json
{
  • "indices": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get current prepared beacon proposers and registered validators

Get the current proposers information held by beacon node as result of prepare_beacon_proposer and register_validator validator API calls. This API is considered unstable and the returned data format may change in the future.

Responses

Response samples

Content type
application/json
{
  • "prepared_proposers": [
    ],
  • "registered_validators": [
    ]
}

Get Global Validator Inclusion

Returns a global count of votes for a given epoch.

path Parameters
epoch
required
string <uint64>
Example: 1

uint64 Epoch number to query.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Validator Inclusion

Returns a per-validator summary of how that validator performed during the current epoch.

path Parameters
epoch
required
string <uint64>
Example: 1

uint64 Epoch number to query.

validator_id
required
string <uint64>
Example: 1

unsigned 64 bit integer

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Events

Subscribe to node events

Provides endpoint to subscribe to beacon node Server-Sent-Events stream. Consumers should use eventsource implementation to listen on those events.

Servers may send SSE comments beginning with : for any purpose, including to keep the event stream connection alive in the presence of proxy servers.

query Parameters
topics
string
Example: topics=head

Event types to subscribe to. Available values include: [head, finalized_checkpoint, chain_reorg, block, attestation, voluntary_exit, contribution_and_proof]

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Node

Get node health

Returns node health status in http status codes. Useful for load balancers.

query Parameters
syncing_status
number

Customize syncing status instead of default status code (206)

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get node network identity

Retrieves data about the node's network presence

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get node peers

Retrieves data about the node's network peers.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get peer count

Retrieves number of known peers.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get node peer

Retrieves data about the given peer.

path Parameters
peer_id
required
string
Example: QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N

Cryptographic hash of a peer’s public key. Read more

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get node syncing status

Requests the beacon node to describe if it's currently syncing or not, and if it is, what block it is up to.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get node version

similar to HTTP User-Agent.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Config

Get deposit contract address

Retrieve deposit contract address and genesis fork version.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get scheduled forks

Retrieve all scheduled upcoming forks this node is aware of.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get spec params

Retrieve specification configuration used on this node.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Debug

Get fork choice leaves Deprecated

Retrieves all possible chain heads (leaves of fork choice tree).

Deprecated - use `/eth/v2/debug/beacon/heads

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get fork choice leaves

Retrieves all possible chain heads (leaves of fork choice tree).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get state

Returns full BeaconState object for given state_id.

Use Accept header to select application/octet-stream if SSZ response type is required.

NOTE: Only phase0 beacon state will be returned in JSON, use /eth/v2/beacon/states/{state_id} for altair.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

Responses

Response samples

Content type
{
  • "data": {
    }
}

Get full BeaconState object

Returns full BeaconState object for given state_id.

Use Accept header to select application/octet-stream if SSZ response type is required.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

Responses

Response samples

Content type
{
  • "version": "phase0",
  • "execution_optimistic": true,
  • "finalized": true,
  • "data": {
    }
}

Get fork choice array

Retrieves all current fork choice context.

Responses

Response samples

Content type
application/json
{
  • "justified_checkpoint": {
    },
  • "finalized_checkpoint": {
    },
  • "fork_choice_nodes": [
    ],
  • "extra_data": {
    }
}

Teku

Changes the log level without restarting.

Changes the log level without restarting. You can change the log level for all logs, or the log level for specific packages or classes.

Request Body schema: application/json
level
required
string <string> (Level)

Level string

log_filter
Array of strings

Responses

Request samples

Content type
application/json
{
  • "level": "ERROR",
  • "log_filter": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get SSZ State By Block id

Download the state SSZ object for given identifier - by block root, keyword, or slot.

path Parameters
block_id
required
string
Example: head

Block identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get node liveness

Returns 200 if the node is up even if it is syncing.

query Parameters
failOnRejectedCount
boolean

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get node readiness

Returns 200 if the node is ready to accept traffic

query Parameters
target_peer_count
string <integer>
Example: target_peer_count=1

Returns 503 status code when current peer count is below than target

Responses

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Get blocks at slot

Get all blocks (canonical and non-canonical) by slot.

path Parameters
slot
required
string <uint64>
Example: 1

slot of the blocks to retrieve.

Responses

Response samples

Content type
application/json
{
  • "version": "phase0",
  • "data": [
    ]
}

Get peer scores

Retrieves data about the node's network peers.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get deposits

Get all deposits currently held for inclusion in future blocks.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get new Eth1Data

Eth1Data that would be used in a new block created based on the current head.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get cached eth1 blocks

Get all of the eth1 blocks currently cached by the beacon node, that could be considered for inclusion during block production.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get Eth1 voting summary

Returns information about the current state of voting for Eth1Data from the specified state.

path Parameters
state_id
required
string
Example: head

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get finalized DepositTreeSnapshot

Latest finalized DepositTreeSnapshot that could be used to reconstruct Deposit merkle tree. See EIP-4881 for details.

Responses

Response samples

Content type
{
  • "data": {
    }
}

Get Global Validator Inclusion

Returns a global count of votes for a given epoch.

path Parameters
epoch
required
string <uint64>
Example: 1

uint64 Epoch number to query.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Validator Inclusion

Returns a per-validator summary of how that validator performed during the current epoch.

path Parameters
epoch
required
string <uint64>
Example: 1

uint64 Epoch number to query.

validator_id
required
string <uint64>
Example: 1

unsigned 64 bit integer

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}