Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Ethereum APIs

Build status Discord PyPI

This repository hosts a mirror of Prysm's service interface definitions for the Ethereum. These protocol buffer service definitions support gRPC as well as JSON over HTTP.

Mirror details

This repository is a mirror of This means changes and contributions to protobufs ARE NOT accepted in this repository and must instead be made in the source repository instead. This project is updated on every new release of Prysm.

Need assistance?

For general information on the functionality of gRPC and protocol buffers, see the gRPC guide. If you still have questions, feel free to stop by either our Discord and a member of the team or our community will be happy to assist you.

Service definitions

Package Service Version Description
eth BeaconChain v1alpha1 This service is used to retrieve critical data relevant to the Ethereum proof-of-stake beacon chain, including the most recent head block, current pending deposits, the chain state and more.
eth Node v1alpha1 The Node service returns information about the Ethereum beacon node itself, including versioning and general information as well as network sync status and a list of services currently implemented on the beacon node.
eth Validator v1alpha1 This API provides the information a validator needs to retrieve throughout its life cycle, including assignments from the network, its current index in the state as well as the rewards and penalties that have been applied to it.



Here's what you need to get started:

  • A modern, UNIX operating system
  • Go installed
  • The latest release of protocol buffers installed (the protoc compiler)
  • The cmake package installed

Installing and Building Go Stubs

To install the required dependencies for compiling the protocol buffers, run

make install

Next, to generate the Go stubs for the protocol buffers, run

make generate

Building Python stubs

Python libraries can be generated using scripts/

Making API Schema Changes

Say you want to add a new endpoint to the BeaconChain gRPC service in our API schema to retrieve orphaned blocks. Keep in mind making strict changes to the API schema can often times be difficult without a significant reason as this API is used by many different developers building on eth2. If you are confident in your desired changes, you can proceed by modifying the protobuf schema:

service BeaconChain {
    // Retrieve orphaned blocks from the eth2 chain.
    rpc GetOrphanedBlocks(OrphanedBlocksRequest) returns (OrphanedBlocksResponse) {
        option (google.api.http) = {
            get: "/eth/v1alpha1/beacon/blocks/orphaned"

message OrphanedBlocksRequest {
    uint64 slot = 1;

message OrphanedBlocksResponse {
    repeated BeaconBlock blocks = 1;

After making your changes, you can regenerate the Go libraries from the schema by running:

make generate

RESTful endpoints (gRPC Transcoding)

All of the gRPC services should define JSON over HTTP endpoints by specifying HTTPRules. Developers may choose to bundle a REST service of gRPC with their client implementation binaries, or alternatively, they may use a JSON encoding proxy such as Envoy Proxy, grpc-gateway, etc.

For more information on gRPC transcoding, see the examples found here.

Code sample:

service Messaging {
    rpc GetMessage(GetMessageRequest) returns (Message) {
        option (google.api.http) = {
            get: "/v1/{name=messages/*}"
message GetMessageRequest {
    string name = 1; // Mapped to URL Path.
message Message {
    string text = 1; // The resource content.

This enables an HTTP REST to gRPC mapping, as shown below:

GET /v1/messages/123456 GetMessage(name: "messages/123456")

gRPC tooling and resources


Apache 2.0