Ethereum 2.0 REST API

Prysm supports the official Ethereum 2.0 REST API specification, the official API standard developed by the Ethereum R&D team. The specification describes a RESTful set of endpoints which should be implemented by an Eth2 client or a third-party service. This reduces the overhead of having to learn a new set of APIs when trying out a different client, and it allows network participants to reliably talk to each other over HTTP. As an example of an external service implementing the spec, Infura's beacon chain API is described here.

The official Ethereum 2.0 specification contains multiple definitions

As of the time of writing, there are two definitions: v1 and dev. The latter is an unstable version and supporting it is not to be expected.

Performing requests against a local Prysm node

The Eth2 JSON REST API is exposed by default on 127.0.0.1:3501. The host can be changed by manipulating the --grpc-gateway-host flag and the port can be modified with the --eth-api-port flag. Performing a request is straightforward - simply concatenate the Prysm's API endpoint with the API's URL, providing any required URL and query parameters. As an example, the finalized state's root can be obtained using:

http://127.0.0.1:3501/eth/v1/beacon/states/finalized/root

Notice that in this example the {state_id} URL parameter has been replaced with the literal value finalized. Please read the specification carefully to understand how each endpoint behaves.

Do not use the --grpc-gateway-port, use --eth-api-port instead

The existing Prysm API uses the port specified in the --grpc-gateway-port flag, and all request to this API should be done using that port. However, because of technical challenges of making the Ethereum 2.0 REST API conform to the official specification the --eth-api-port flag was introduced, and all request to the Ethereum 2.0 REST API should be done using the port specified in that flag. Although requests to --grpc-gateway-port are possible, results may be incorrectly encoded, malformed, simply wrong or even not possible to obtain due to server-side errors.

Supported endpoints

While Prysm would like to support all endpoints from the official specification, some of them have a higher priority for us than others, and there are other features that the development team might find more important. Therefore it is plausible that some endpoints will return a 404 Not Found response for the time being.

DefinitionGroupSupport
v1BeaconAll endpoints are supported
v1ConfigAll endpoints are supported
v1DebugAll endpoints are supported
v1EventsAll endpoints are supported
v1NodeAll endpoints are supported
v1ValidatorNo support
v1ValidatorRequiredApiPartial support. /eth/v1/validator endpoints not supported.