Updated 2020-02-21

JSON-RPC over HTTP and WebSockets

To enable JSON-RPC over HTTP or WebSockets, use the --rpc-http-enabled and --rpc-ws-enabled options.

Click the button to import our collection of API examples to Postman.

or download the raw JSON collection file.

Geth Console

The geth console is a REPL (Read, Evaluate, & Print Loop) Javascript console. Use JSON-RPC APIs supported by geth and Hyperledger Besu directly in the console.

To use the geth console with Besu:

Start Besu with the --rpc-http-enabled option.
Specify which APIs to enable using the --rpc-http-api option.
Start the geth console specifying the JSON-RPC endpoint:
```
 geth attach http://localhost:8545
```

Use the geth console to call JSON-RPC API methods that geth and Besu share.

Example

eth.syncing

JSON-RPC Authentication

Authentication is disabled by default.

HTTP and WebSocket Requests

HTTP

To make RPC requests over HTTP, you can use curl.

curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53}' <JSON-RPC-http-endpoint:port>

WebSockets

To make RPC requests over WebSockets, you can use wscat, a Node.js based command-line tool.

First connect to the WebSockets server using wscat (you only need to connect once per session):

wscat -c ws://<JSON-RPC-ws-endpoint:port>

After the connection is established, the terminal displays a ‘>’ prompt. Send individual requests as a JSON data package at each prompt:

{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53}

Note

wscat does not support headers. Authentication requires an authentication token to be passed in the request header. To use authentication with WebSockets, an app that supports headers is required.

Readiness and Liveness Endpoints

Besu provides readiness and liveness endpoints to confirm the Besu node status. Both return a 200 OK status when ready or live and a 503 Service Unavailable status if not ready or live.

By default, the readiness check requires a peer to be connected and the node to be within 2 blocks of the best known block. If p2p communication is disabled, no peers are required. A live node with p2p disabled is always ready.

Use the query parameters minPeers and maxBlocksBehind to adjust the number of peers required and number of blocks tolerance.

Readiness Endpoint

http://<JSON-RPC-HTTP-endpoint:port>/readiness

curl Request Example

curl -v 'http://localhost:8545/readiness'

Query Parameters Example

curl -v 'http://localhost:8545/readiness?minPeers=0&maxBlocksBehind=10'

The liveness check requires the JSON RPC server to be up.

Liveness Endpoint

http://<JSON-RPC-HTTP-endpoint:port>/liveness

curl Request Example

curl -v 'http://localhost:8545/liveness'

API Methods Enabled by Default

The ETH, NET, and WEB3 API methods are enabled by default.

Use the --rpc-http-api or --rpc-ws-api options to enable the ADMIN, CLIQUE, DEBUG, EEA, IBFT, MINER, PERM, PLUGINS, PRIV, and TXPOOL API methods.

Block Parameter

When you make requests that might have different results depending on the block accessed, the block parameter specifies the block. Several methods, such as eth_getTransactionByBlockNumberAndIndex, have a block parameter.

The block parameter can have the following values:

blockNumber : quantity - Block number. Can be specified in hexadecimal or decimal. 0 represents the genesis block.
earliest : tag - Earliest (genesis) block.
latest : tag - Last block mined.
pending : tag - Last block mined plus pending transactions. Use only with eth_getTransactionCount.

Note

If synchronizing in FAST mode, most historical world state data is unavailable. Any methods attempting to access unavailable world state data return null.