title | sidebar_position | description | tags | ||
---|---|---|---|---|---|
Use JSON-RPC over HTTP, WS, and IPC |
1 |
How to access the Besu API using JSON-RPC |
|
import Postman from '../../../global/postman.md'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
JSON-RPC APIs allow you to interact with your node. JSON-RPC endpoints are not enabled by default.
:::caution
You should secure access to your node's JSON-RPC endpoints. Users with access to your node via JSON-RPC can make calls directly to your node, causing your node to consume resources.
:::
To enable JSON-RPC over HTTP or WebSocket, use the --rpc-http-enabled
and --rpc-ws-enabled
options.
To enable JSON-RPC over an IPC socket, use the --Xrpc-ipc-enabled
option.
:::caution
--Xrpc-ipc-enabled
is an early access option.
:::
The geth console is a REPL (Read, Evaluate, & Print Loop) JavaScript console. Use JSON-RPC APIs supported by geth and Besu directly in the console.
To use the geth console with Besu:
-
Start Besu with the
--rpc-http-enabled
or--Xrpc-ipc-enabled
option. -
Specify which APIs to enable using the
--rpc-http-api
or--Xrpc-ipc-api
option. -
Start the geth console specifying the JSON-RPC endpoint:
geth attach http://localhost:8545
geth attach /path/to/besu.ipc
-
Use the geth console to call JSON-RPC API methods that geth and Besu share.
eth.syncing
Besu disables Authentication by default.
To make RPC requests over HTTP, you can use curl
.
curl -X POST --data '{"jsonrpc":"2.0","id":<request-ID>,"method":"<method-name>","params":[<method-parameters>]}' <JSON-RPC-http-endpoint:port> -H "Content-Type: application/json"
curl -X POST --data '{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}' http://127.0.0.1:8555/ -H "Content-Type: application/json"
{
"jsonrpc": "2.0",
"id": "1",
"result": "0x60e"
}
You can use curl
to make multiple RPC requests (batch requests) over HTTP at the same time. Send the requests as an array, and receive an array of responses. The default number of allowed requests in a RPC batch request is 1024
. Use the --rpc-http-max-batch-size
command line option to update the default value.
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/ -H "Content-Type: application/json"
[
{
"jsonrpc": "2.0",
"id": "1",
"result": "0x60e"
},
{
"jsonrpc": "2.0",
"id": "2",
"result": []
}
]
To make RPC requests over WebSocket, you can use wscat
, a Node.js based command-line tool.
First connect to the WebSocket 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.
{"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 WebSocket at the same time. Send the requests as an array, and receive an array of responses.
[{"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 WebSocket, you need an app that supports headers.
:::
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.
http://<JSON-RPC-HTTP-endpoint:port>/readiness
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. You can use the endpoint to verify that the node can respond to RPC calls. The status in the response will always be UP
.
http://<JSON-RPC-HTTP-endpoint:port>/liveness
curl -v 'http://localhost:8545/liveness'
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
, --rpc-ws-api
, or --Xrpc-ipc-api
options.
:::caution
--Xrpc-ipc-api
is an early access option.
:::
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 one of the following values:
-
blockNumber
: quantity - The block number, specified in hexadecimal or decimal.0
represents the genesis block. -
blockHash
: string or object - 32-byte block hash or JSON object specifying the block hash. If using a JSON object, you can specifyrequireCanonical
to indicate whether the block must be a canonical block. See this example.:::note
Only the following methods support the
blockHash
parameter::::
-
earliest
: tag - The earliest (genesis) block. -
latest
: tag - The last block mined. -
pending
: tag - When used witheth_getTransactionCount
, refers to the last block mined plus pending transactions. When used withqbft_getValidatorsByBlockNumber
, returns a list of validators that will be used to produce the next block. -
finalized
: tag - The most recent crypto-economically secure block. It cannot be reorganized outside manual intervention driven by community coordination. -
safe
: tag - The most recent block that is safe from reorganization under honest majority and certain synchronicity assumptions.