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
View the Besu JSON-RPC APIs documentation in the Postman format and obtain example requests in multiple coding languages.
Run in Postman
Click the following button to fork the collection and run requests directly on your local network.
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:
- 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
Besu disables Authentication by default.
HTTP and WebSocket requests
HTTP
To make RPC requests over HTTP, you can use curl
.
Example
curl -X POST --data '{"jsonrpc":"2.0","id":<request-ID>,"method":"<method-name>","params":[<method-parameters>]}' <JSON-RPC-http-endpoint:port>
curl -X POST --data '{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}' http://127.0.0.1:8555
{
"jsonrpc":"2.0",
"id":"1",
"result":"0x60e"
}
You can use curl
to make multiple RPC requests over HTTP at the same time.
Send the requests as an array, and receive an array of responses.
Example
curl -X POST --data '[{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}, {"jsonrpc":"2.0","id":"2","method":"admin_peers","params":[]}]' http://127.0.0.1:8555
[{
"jsonrpc":"2.0",
"id":"1",
"result":"0x60e"
},{
"jsonrpc":"2.0",
"id":"2",
"result":[]
}]
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 you establish a connection, the terminal displays a ‘>’ prompt. Send individual requests as a JSON data package at each prompt.
Example
{"jsonrpc":"2.0","id":<request-ID>,"method":"<method-name>","params":[<method-parameters>]}
{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}
{
"jsonrpc":"2.0",
"id":"1",
"result":"0x23"
}
You can use wscat
to make multiple RPC requests over WebSockets at the same time.
Send the requests as an array, and receive an array of responses.
Example
[{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}, {"jsonrpc":"2.0","id":"2","method":"admin_peers","params":[]}]
[{
"jsonrpc":"2.0",
"id":"1",
"result":"0x23"
},{
"jsonrpc":"2.0",
"id":"2",
"result":[]
}]
Note
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.
Readiness
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.
http://<JSON-RPC-HTTP-endpoint:port>/readiness
curl -v 'http://localhost:8545/readiness'
curl -v 'http://localhost:8545/readiness?minPeers=0&maxBlocksBehind=10'
Liveness
The liveness check requires the JSON-RPC server to be up.
http://<JSON-RPC-HTTP-endpoint:port>/liveness
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 witheth_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
.