Skip to content
You are reading Hyperledger Besu development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.
Last update: December 14, 2020

JSON-RPC over HTTP and WebSockets

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

Besu JSON-RPC APIs documentation in Postman format

Postman documentation

View the Besu JSON-RPC APIs documentation in the Postman format and obtain example requests in multiple coding languages. You can also run requests directly in Postman.

Run requests

Click the Run in Postman button on the top right hand corned on the Postman API documentation to run the requests of the collection.

Download collection

Alternatively you can download the 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:

  1. Start Besu with the --rpc-http-enabled option.
  2. Specify which APIs to enable using the --rpc-http-api option.
  3. 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.



JSON-RPC authentication

Besu disables Authentication by default.

HTTP and WebSocket requests


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>


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 you establish a connection, the terminal displays a ‘>’ prompt. Send individual requests as a JSON data package at each prompt:



wscat does not support headers. Authentication requires you to pass an authentication token in the request header. To use authentication with WebSockets, you require an app that supports headers.

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 connected peer and the node to be within two blocks of the best known block. If you have disabled P2P communication, you do not need peers. A live node with P2P disabled is always ready.

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

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


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

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

API methods enabled by default

Besu enables the ETH, NET, and WEB3 API methods by default.

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

Block parameter

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

The block parameter can have the following values:

  • blockNumber : quantity - The block number, specified in hexadecimal or decimal. 0 represents the genesis block.
  • earliest : tag - The earliest (genesis) block.
  • latest : tag - The last block mined.
  • pending : tag - The last block mined plus pending transactions. Use only with eth_getTransactionCount.


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

Questions or feedback? You can discuss issues and obtain free support on Hyperledger Besu chat channel.
For Hyperledger Besu community support, contact the mailing list