Skip to main content

Besu API methods

caution
  • This reference contains API methods that apply to both public and private networks. For private-network-specific API methods, see the private network API reference.
  • All JSON-RPC HTTP examples use the default host and port endpoint http://127.0.0.1:8545. If using the --rpc-http-host or --rpc-http-port options, update the endpoint.
  • Most example requests are made against private networks. Depending on network configuration and activity, your example results might be different.
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.

Run in Postman.

Download collection​

Alternatively you can download the JSON collection file.

ADMIN methods​

The ADMIN API methods provide administrative functionality to manage your node.

note

The ADMIN API methods are not enabled by default for JSON-RPC. To enable the ADMIN API methods, use the --rpc-http-api or --rpc-ws-api options.

admin_addPeer​

Adds a static node.

caution

If connections are timing out, ensure the node ID in the enode URL is correct.

Parameters​

enode: string - enode URL of peer to add

Returns​

result: boolean - true if peer added or false if peer already a static node

curl -X POST --data '{"jsonrpc":"2.0","method":"admin_addPeer","params":["enode://f59c0ab603377b6ec88b89d5bb41b98fc385030ab1e4b03752db6f7dab364559d92c757c13116ae6408d2d33f0138e7812eb8b696b2a22fe3332c4b5127b22a3@127.0.0.1:30304"],"id":1}' http://127.0.0.1:8545

admin_changeLogLevel​

Changes the log level without restarting Besu. You can change the log level for all logs, or you can change the log level for specific packages or classes.

You can specify only one log level per RPC call.

Parameters​

  • level: string - log level

  • log_filter: array - (optional) packages or classes for which to change the log level

Returns​

result: string - Success if the log level has changed, otherwise error

The following example changes the debug level for specified classes to DEBUG.

curl -X POST --data '{"jsonrpc":"2.0", "method":"admin_changeLogLevel", "params":["DEBUG", ["org.hyperledger.besu.ethereum.eth.manager","org.hyperledger.besu.ethereum.p2p.rlpx.connections.netty.ApiHandler"]], "id":1}' http://127.0.0.1:8545

The following example changes the debug level of all logs to WARN.

curl -X POST --data '{"jsonrpc":"2.0","method":"admin_changeLogLevel","params":["WARN"], "id":1}' http://127.0.0.1:8545

admin_generateLogBloomCache​

Generates cached log bloom indexes for blocks. APIs such as eth_getLogs and eth_getFilterLogs use the cache for improved performance.

tip

Manually executing admin_generateLogBloomCache is not required unless the --auto-log-bloom-caching-enabled command line option is set to false.

note

Each index file contains 100000 blocks. The last fragment of blocks less than 100000 are not indexed.

Parameters​

  • startBlock: string - block to start generating indexes

  • endBlock: string - block to stop generating indexes

Returns​

result: object - log bloom index details:

  • startBlock: string - starting block for the last requested cache generation

  • endBlock: string - ending block for the last requested cache generation

  • currentBlock: string - most recent block added to the cache

  • indexing: boolean - indicates if indexing is in progress

  • boolean - indicates acceptance of the request from this call to generate the cache

curl -X POST --data '{jsonrpc":"2.0","method":"admin_generateLogBloomCache", "params":["0x0", "0x10000"], "id":1}' http://127.0.0.1:8545

admin_logsRemoveCache​

Removes cache files for the specified range of blocks.

Parameters​

  • fromBlock: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

  • toBlock: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

You can skip a parameter by using an empty string, "". If you specify:

  • No parameters, the call removes cache files for all blocks.

  • Only fromBlock, the call removes cache files for the specified block.

  • Only toBlock, the call removes cache files from the genesis block to the specified block.

Returns​

result: object - Cache Removed status or error.

curl -X POST --data '{"jsonrpc":"2.0","method":"admin_logsRemoveCache","params":["1", "100"], "id":1}' http://127.0.0.1:8545

admin_logsRepairCache​

Repairs cached logs by fixing all segments starting with the specified block number.

Parameters​

startBlock: string - decimal index of the starting block to fix; defaults to the head block

Returns​

result: object - status of the repair request; Started or Already running

curl -X POST --data '{"jsonrpc":"2.0","method":"admin_logsRepairCache","params":["1200"], "id":1}' http://127.0.0.1:8545

admin_nodeInfo​

Returns networking information about the node. The information includes general information about the node and specific information from each running Ethereum sub-protocol (for example, eth).

Parameters​

None

Returns​

result: object - node object with the following fields:

  • enode: string - enode URL of the node

  • listenAddr: string - host and port for the node

  • name: string - client name

  • id: string - node public key

  • ports: object - peer discovery and listening ports

  • protocols: object - list of objects containing information for each Ethereum sub-protocol

note

If the node is running locally, the host of the enode and listenAddr display as [::] in the result. When advertising externally, the external address displayed for the enode and listenAddr is defined by --nat-method.

curl -X POST --data '{"jsonrpc":"2.0","method":"admin_nodeInfo","params":[],"id":1}' http://127.0.0.1:8545

admin_peers​

Returns networking information about connected remote nodes.

Parameters​

None

Returns​

result: array of objects - list of objects returned for each remote node, with the following fields.

  • version: string - P2P protocol version

  • name: string - client name

  • caps: array of strings - list of Ethereum sub-protocol capabilities

  • network: object - local and remote addresses established at time of bonding with the peer (the remote address might not match the hex value for port; it depends on which node initiated the connection.)

  • port: string - port on the remote node on which P2P discovery is listening

  • id: string - node public key (excluding the 0x prefix, the node public key is the ID in the enode URL enode://<id ex 0x>@<host>:<port>.)

  • protocols: object - current state of peer including difficulty and head (head is the hash of the highest known block for the peer.)

  • enode: string - enode URL of the remote node

curl -X POST --data '{"jsonrpc":"2.0","method":"admin_peers","params":[],"id":1}' http://127.0.0.1:8545

admin_removePeer​

Removes a static node.

Parameters​

enode: string - enode URL of peer to remove

Returns​

result: boolean - true if peer removed or false if peer not a static node

curl -X POST --data '{"jsonrpc":"2.0","method":"admin_removePeer","params":["enode://f59c0ab603377b6ec88b89d5bb41b98fc385030ab1e4b03752db6f7dab364559d92c757c13116ae6408d2d33f0138e7812eb8b696b2a22fe3332c4b5127b22a3@127.0.0.1:30304"],"id":1}' http://127.0.0.1:8545

DEBUG methods​

The DEBUG API methods allow you to inspect and debug the network. The DEBUG API is a more verbose alternative to the TRACE API, and its main purpose is compatibility with tools such as Remix. Where these APIs overlap, we recommend using the TRACE API for production use over the DEBUG API. Specifically, we recommend trace_block over debug_traceBlock, and trace_transaction over debug_traceTransaction.

note

The DEBUG API methods are not enabled by default for JSON-RPC. To enable the DEBUG API methods, use the --rpc-http-api or --rpc-ws-api options.

debug_accountAt​

Returns account information at the specified index of the specified block.

Parameters​

  • blockHashOrNumber: string - block hash or number at which to retrieve account information

  • txIndex: number - transaction index at which to retrieve account information

  • address: string - contract or account address for which to retrieve information

Returns​

result: object - account details object with the following fields:

  • code: data - code for the account. Displays 0x0 if the address is an externally owned account.

  • nonce: quantity - number of transactions made by the account before this one

  • balance: quantity - balance of the account in Wei

  • codehash: data - code hash for the account

This example uses an externally owned account address for the address parameter.

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_accountAt","params":["0xc8df1f061abb4d0c107b2b1a794ade8780b3120e681f723fe55a7be586d95ba6", 0, "0xbcde5374fce5edbc8e2a8697c15331677e6ebf0b"],"id":1}' http://127.0.0.1:8545

This example uses a contract address for the address parameter.

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_accountAt","params":["0x2b76b3a2fc44c0e21ea183d06c846353279a7acf12abcc6fb9d5e8fb14ae2f8c", 0, "0x0e0d2c8f7794e82164f11798276a188147fbd415"],"id":1}' http://127.0.0.1:8545

debug_accountRange​

Retesteth uses debug_accountRange to implement debugging.

Returns the accounts for a specified block.

Parameters​

  • blockHashOrNumber: string - block hash or number at which to retrieve account information

  • txIndex: number - transaction index at which to retrieve account information

  • address: string - address hash from which to start

  • limit: integer - maximum number of account entries to return

Returns​

result: object - account details object with the following fields:

  • addressMap: map of strings to strings - map of address hashes and account addresses

  • nextKey: string - hash of the next address if any addresses remain in the state, otherwise zero

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_accountRange","params":["12345", 0, "0", 5],"id":1}' http://127.0.0.1:8545

debug_batchSendRawTransaction​

Sends a list of signed transactions. This is used to quickly load a network with a lot of transactions. This does the same thing as calling eth_sendRawTransaction multiple times.

Parameters​

data: string - signed transaction data array

Returns​

result: array of objects - object returned for each transaction, with the following fields:

  • index: string - index of the transaction in the request parameters array

  • success: boolean - indicates whether or not the transaction has been added to the transaction pool

  • errorMessage: string - (optional) error message

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_batchSendRawTransaction","params":["0xf868808203e882520894627306090abab3a6e1400e9345bc60c78a8bef57872386f26fc10000801ba0ac74ecfa0e9b85785f042c143ead4780931234cc9a032fce99fab1f45e0d90faa02fd17e8eb433d4ca47727653232045d4f81322619c0852d3fe8ddcfcedb66a43","0x416","0xf868018203e882520894627306090abab3a6e1400e9345bc60c78a8bef57872386f26fc10000801ca0b24ea1bee8fe36984c36acbf80979a4509f23fc17141851e08d505c0df158aa0a00472a05903d4cd7a811bd4d5c59cc105d93f5943f3393f253e92e65fc36e7ce0","0xf868808203e882520894627306090abab3a6e1400e9345bc60c78a8bef5787470de4df820000801ca0f7936b4de04792e3c65095cfbfd1399d231368f5f05f877588c0c8509f6c98c9a01834004dead527c8da1396eede42e1c60e41f38a77c2fd13a6e495479c729b99"],"id":1}' http://127.0.0.1:8545

debug_getBadBlocks​

Returns a list of invalid blocks. This is used to detect and analyze consensus flaws.

Parameters​

None

Returns​

result: array of objects - list of block objects

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_getBadBlocks","params":[],"id":1}' http://127.0.0.1:8545

debug_getRawBlock​

Returns the RLP encoding of the specified block.

Parameters​

blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: object - RLP-encoded block object

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_getRawBlock","params":["0x32026E"],"id":1}' http://127.0.0.1:8545

debug_getRawHeader​

Returns the RLP encoding of the header of specified block.

Parameters​

blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: string - RLP-encoded block header or error

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_getRawHeader","params":["0x32026E"],"id":1}' http://127.0.0.1:8545

debug_getRawReceipts​

Returns the RLP encoding of the transaction receipts of the specified block.

Parameters​

blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: object - array of RLP-encoded transaction receipts

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_getRawReceipts","params":["0x32026E"],"id":1}' http://127.0.0.1:8545

debug_getRawTransaction​

Returns the RLP encoding of the specified transaction.

Parameters​

transaction: string - 32-byte transaction hash

Returns​

result: object - RLP-encoded transaction object

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_getRawTransaction","params":["0x3a2fd1a5ea9ffee477f449be53a49398533d2c006a5815023920d1c397298df3"],"id":1}' http://127.0.0.1:8545

debug_metrics​

Returns metrics providing information on the internal operation of Besu.

The available metrics might change over time. The JVM metrics might vary based on the JVM implementation used.

The metric types are:

  • Timer

  • Counter

  • Gauge

Parameters​

None

Returns​

result: object - metrics object

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_metrics","params":[],"id":1}' http://127.0.0.1:8545

debug_replayBlock​

Re-imports the block matching the specified block number, by rolling the head of the local chain back to the block right before the specified block, then importing the specified block.

Parameters​

blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: string - Success or error

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_replayBlock","params":["0x1"],"id":1}' http://127.0.0.1:8545

debug_resyncWorldstate​

Triggers a re-synchronization of the world state while retaining imported blocks. This is useful if there are world state database inconsistencies (for example, Bonsai database issues).

Parameters​

None

Returns​

result: string - Success or error

    curl -X POST --data '{"jsonrpc":"2.0","method":"debug_resyncWorldstate","params":[],"id":1}' http://127.0.0.1:8545

debug_setHead​

Sets the current head of the local chain to the block matching the specified block number.

Parameters​

blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: string - Success or error

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_setHead","params":["0x1"],"id":1}' http://127.0.0.1:8545

debug_standardTraceBlockToFile​

Generates files containing the block trace. A separate file is generated for each transaction in the block.

You can also specify a trace file for a specific transaction in a block.

Use debug_standardTraceBadBlockToFile to view the trace for an invalid block.

Parameters​

blockHash: string - block hash

txHash: string - (optional) transaction hash; if omitted, a trace file is generated for each transaction in the block.

disableMemory: boolean - (optional) specifies whether to capture EVM memory during the trace; defaults to true

Returns​

result: string - location of the generated trace files

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_standardTraceBlockToFile","params":["0x2dc0b6c43144e314a86777b4bd4f987c0790a6a0b21560671d221ed81a23f2dc", {
"txHash": "0x4ff04c4aec9517721179c8dd435f47fbbfc2ed26cd4926845ab687420d5580a6", "disableMemory": false}], "id":1}' http://127.0.0.1:8545

debug_standardTraceBadBlockToFile​

Generates files containing the block trace of invalid blocks. A separate file is generated for each transaction in the block.

Use debug_standardTraceBlockToFile to view the trace for a valid block.

Parameters​

blockHash: string - block hash

Returns​

result: string - location of the generated trace files

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_standardTraceBadBlockToFile","params":["0x53741e9e94791466d117c5f9e41a2ed1de3f73d39920c621dfc2f294e7779baa"], "id":1}' http://127.0.0.1:8545

debug_storageRangeAt​

Remix uses debug_storageRangeAt to implement debugging. Use the Debugger tab in Remix instead of calling debug_storageRangeAt directly.

Returns the contract storage for the specified range.

Parameters​

  • blockHash: string - block hash

  • txIndex: number - transaction index from which to start

  • address: string - contract address

  • startKey: string - start key

  • limit: number - number of storage entries to return

Returns​

result: object - range object.

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_storageRangeAt","params":["0x2b76b3a2fc44c0e21ea183d06c846353279a7acf12abcc6fb9d5e8fb14ae2f8c",0,"0x0e0d2c8f7794e82164f11798276a188147fbd415","0x0000000000000000000000000000000000000000000000000000000000000000",1], "id":1}' http://127.0.0.1:8545

debug_traceBlock​

Returns full trace of all invoked opcodes of all transactions included in the block.

Parameters​

  • block: string - RLP of the block

  • options: object - request options object with the following fields (all optional and default to false):

    • disableStorage: boolean - true disables storage capture.

    • disableMemory: boolean - true disables memory capture.

    • disableStack : boolean - true disables stack capture.

Returns​

result: object - trace object

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_traceBlock","params":["0xf90277f90208a05a41d0e66b4120775176c09fcf39e7c0520517a13d2b57b18d33d342df038bfca01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d4934794e6a7a1d47ff21b6321162aea7c6cb457d5476bcaa00e0df2706b0a4fb8bd08c9246d472abbe850af446405d9eba1db41db18b4a169a04513310fcb9f6f616972a3b948dc5d547f280849a87ebb5af0191f98b87be598a0fe2bf2a941abf41d72637e5b91750332a30283efd40c424dc522b77e6f0ed8c4b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000860153886c1bbd82b44382520b8252088455c426598b657468706f6f6c2e6f7267a0b48c515a9dde8d346c3337ea520aa995a4738bb595495506125449c1149d6cf488ba4f8ecd18aab215f869f86780862d79883d2000825208945df9b87991262f6ba471f09758cde1c0fc1de734827a69801ca088ff6cf0fefd94db46111149ae4bfc179e9b94721fffd821d38d16464b3f71d0a045e0aff800961cfce805daef7016b9b675c137a6a41a548f7b60a3484c06a33ac0"],"id":1}' http://127.0.0.1:8545

debug_traceBlockByHash​

Returns full trace of all invoked opcodes of all transactions included in the block.

Parameters​

  • blockHash: string - block hash

  • options: object - request options object with the following fields (all optional and default to false):

    • disableStorage: boolean - true disables storage capture.

    • disableMemory: boolean - true disables memory capture.

    • disableStack : boolean - true disables stack capture.

Returns​

result: array of objects - list of trace objects

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_traceBlockByHash","params":["0xaceb3b2c9b25b0589230873921eb894b28722011b8df63977145517d754875a5"], "id":1}' http://127.0.0.1:8545

debug_traceBlockByNumber​

Returns full trace of all invoked opcodes of all transactions included in the block.

Parameters​

  • blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

  • options: object - request options object with the following fields (all optional and default to false):

    • disableStorage: boolean - true disables storage capture.

    • disableMemory: boolean - true disables memory capture.

    • disableStack : boolean - true disables stack capture.

Returns​

result: array of objects - list of trace objects

curl -X POST --data '{"jsonrpc":"2.0","method":"debug_traceBlockByNumber","params":["0x7224",{"disableStorage":true}], "id":1}' http://127.0.0.1:8545

ETH methods​

The ETH API methods allow you to interact with the blockchain.

note

Methods with an equivalent GraphQL query include a GraphQL request and result in the method example. The parameter and result descriptions apply to the JSON-RPC requests. The GraphQL specification is defined in the schema.

eth_accounts​

Returns a list of account addresses a client owns.

note

This method returns an empty object because Besu doesn't support key management inside the client.

To provide access to your key store and and then sign transactions, use Web3Signer with Besu.

Parameters​

None

Returns​

result: array of strings - list of 20-byte account addresses owned by the client

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":53}' http://127.0.0.1:8545

eth_blockNumber​

Returns the index corresponding to the block number of the current chain head.

Parameters​

None

Returns​

result: string - hexadecimal integer representing the index corresponding to the block number of the current chain head

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":51}' http://127.0.0.1:8545

eth_call​

Invokes a contract function locally and does not change the state of the blockchain.

You can interact with contracts using eth_sendRawTransaction or eth_call.

By default, the eth_call error response includes the revert reason.

Parameters​

call: object - transaction call object

blockNumber or blockHash: string - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

note

By default, eth_call does not fail if the sender account has an insufficient balance. This is done by setting the balance of the account to a large amount of ether. To enforce balance rules, set the strict parameter in the transaction call object to true.

Returns​

result: string - return value of the executed contract

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0x69498dd54bd25aa0c886cf1f8b8ae0856d55ff13","value":"0x1"}, "latest"],"id":53}' http://127.0.0.1:8545
Example of a simulated contract creation

The following example creates a simulated contract by not including the to parameter from the transaction call object in the call parameter. Besu simulates the data to create the contract.

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_call","params":[{"from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", "data":"0x6080604052336000806101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff16021790555034801561005057600080fd5b5061021e806100606000396000f3fe608060405234801561001057600080fd5b50600436106100415760003560e01c8063445df0ac146100465780638da5cb5b14610064578063fdacd576146100ae575b600080fd5b61004e6100dc565b6040518082815260200191505060405180910390f35b61006c6100e2565b604051808273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200191505060405180910390f35b6100da600480360360208110156100c457600080fd5b8101908080359060200190929190505050610107565b005b60015481565b6000809054906101000a900473ffffffffffffffffffffffffffffffffffffffff1681565b6000809054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff163373ffffffffffffffffffffffffffffffffffffffff16146101ac576040517f08c379a00000000000000000000000000000000000000000000000000000000081526004018080602001828103825260338152602001806101b76033913960400191505060405180910390fd5b806001819055505056fe546869732066756e6374696f6e206973207265737472696374656420746f2074686520636f6e74726163742773206f776e6572a265627a7a7231582007302f208a10686769509b529e1878bda1859883778d70dedd1844fe790c9bde64736f6c63430005100032","gas":"0x439cf","gasPrice":"0x0"},"latest"],"id":53}' http://127.0.0.1:8545

eth_chainId​

Returns the chain ID.

Parameters​

None

Returns​

result: string - chain ID in hexadecimal

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":51}' http://127.0.0.1:8545

eth_coinbase​

Returns the client coinbase address. The coinbase address is the account to pay mining rewards to.

To set a coinbase address, start Besu with the --miner-coinbase option set to a valid Ethereum account address. You can get the Ethereum account address from a client such as MetaMask or Etherscan. For example:

Example
besu --miner-coinbase="0xfe3b557e8fb62b89f4916b721be55ceb828dbd73" --rpc-http-enabled

Parameters​

None

Returns​

result: string - coinbase address

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_coinbase","params":[],"id":53}' http://127.0.0.1:8545

eth_createAccessList​

Creates an EIP-2930 access list that you can include in a transaction.

Parameters​

transaction: object - transaction call object

blockNumber or blockHash: string - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

Returns​

result: object - access list object with the following fields:

  • accessList: array of objects - list of objects with the following fields:
    • address: string - addresses to be accessed by the transaction
    • storageKeys: array - storage keys to be accessed by the transaction
  • gasUsed: string - approximate gas cost for the transaction if the access list is included
curl -X POST --data '{"method":"eth_createAccessList","params":[{"from": "0xaeA8F8f781326bfE6A7683C2BD48Dd6AA4d3Ba63", "data": "0x608060806080608155"}, "pending"],"id":1,"jsonrpc":"2.0"}' http://127.0.0.1:8545

eth_estimateGas​

Returns an estimate of the gas required for a transaction to complete. The estimation process does not use gas and the transaction is not added to the blockchain. The resulting estimate can be greater than the amount of gas the transaction ends up using, for reasons including EVM mechanics and node performance.

The eth_estimateGas call does not send a transaction. You must call eth_sendRawTransaction to execute the transaction.

By default, the eth_estimateGas error response includes the revert reason.

Parameters​

For eth_estimateGas, all fields are optional because setting a gas limit is irrelevant to the estimation process (unlike transactions, in which gas limits apply).

call: object - transaction call object

Returns​

result: string - amount of gas used

The following example returns an estimate of 21000 wei (0x5208) for the transaction.

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from":"0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73","to":"0x44Aa93095D6749A706051658B970b941c72c1D53","value":"0x1"}],"id":53}' http://127.0.0.1:8545

The following example request estimates the cost of deploying a simple storage smart contract to the network. The data field contains the hash of the compiled contract you want to deploy. (You can get the compiled contract hash from your IDE, for example, Remix > Compile tab > details > WEB3DEPLOY.) The result is 113355 wei.

curl -X POST \
http://127.0.0.1:8545 \
-H 'Content-Type: application/json' \
-d '{
  "jsonrpc": "2.0",
  "method": "eth_estimateGas",
  "params": [{
    "from": "0x8bad598904ec5d93d07e204a366d084a80c7694e",
    "data": "0x608060405234801561001057600080fd5b5060e38061001f6000396000f3fe6080604052600436106043576000357c0100000000000000000000000000000000000000000000000000000000900480633fa4f24514604857806355241077146070575b600080fd5b348015605357600080fd5b50605a60a7565b6040518082815260200191505060405180910390f35b348015607b57600080fd5b5060a560048036036020811015609057600080fd5b810190808035906020019092919050505060ad565b005b60005481565b806000819055505056fea165627a7a7230582020d7ad478b98b85ca751c924ef66bcebbbd8072b93031073ef35270a4c42f0080029"
  }],
  "id": 1
}'

eth_feeHistory​

Returns base fee per gas and transaction effective priority fee per gas history for the requested block range, allowing you to track trends over time.

Parameters​

  • blockCount: integer or string - Number of blocks in the requested range. Between 1 and 1024 blocks can be requested in a single query. If blocks in the specified block range are not available, then only the fee history for available blocks is returned. Accepts hexadecimal or integer values.

  • newestBlock: string - hexadecimal or decimal integer representing the highest number block of the requested range or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

  • array of integers - (optional) A monotonically increasing list of percentile values to sample from each block's effective priority fees per gas in ascending order, weighted by gas used.

Returns​

result: object - Fee history results object.

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_feeHistory","params": ["0x5", "latest", [20,30]],"id":1}' http://127.0.0.1:8545

eth_gasPrice​

Returns a percentile gas unit price for the most recent blocks, in Wei. By default, the last 100 blocks are examined and the 50th percentile gas unit price (that is, the median value) is returned.

If there are no blocks, the value for --min-gas-price is returned. The value returned is restricted to values between --min-gas-price and --api-gas-price-max. By default, 1000 Wei and 500GWei.

Use the --api-gas-price-blocks, --api-gas-price-percentile , and --api-gas-price-max command line options to configure the eth_gasPrice default values.

Parameters​

None

Returns​

result: string - percentile gas unit price for the most recent blocks, in Wei, as a hexadecimal value

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":53}' http://127.0.0.1:8545

eth_getBalance​

Returns the account balance of the specified address.

Parameters​

  • address: string - 20-byte account address from which to retrieve the balance

  • blockNumber or blockHash: string - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: string - current balance, in Wei, as a hexadecimal value

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", "latest"],"id":53}' http://127.0.0.1:8545

eth_getBlockByHash​

Returns information about the block matching the specified block hash.

Parameters​

  • hash: string - 32-byte hash of a block

  • verbose: boolean - if true, returns the full transaction objects; if false, returns the transaction hashes

Returns​

result: object - block object, or null when there is no block

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockByHash","params":["0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c", false],"id":53}' http://127.0.0.1:8545

eth_getBlockByNumber​

Returns information about the block matching the specified block number.

Parameters​

  • blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

  • verbose: boolean - if true, returns the full transaction objects; if false, returns only the hashes of the transactions.

Returns​

result: object - block object, or null when there is no block.

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["0x68B3", true],"id":1}' http://127.0.0.1:8545

eth_getBlockReceipts​

Returns all transaction receipts for a given block. Transaction receipts provide a way to track the success or failure of a transaction (1 if successful and 0 if failed), as well as the amount of gas used and any event logs that might have been produced by a smart contract during the transaction.

Parameters​

  • blockNumber or blockHash: string - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: object - block object, or null when there is no block.

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockReceipts","params":["latest"],"id":1}' http://127.0.0.1:8545

eth_getBlockTransactionCountByHash​

Returns the number of transactions in the block matching the specified block hash.

Parameters​

hash: string - 32-byte block hash

Returns​

result: number - integer representing the number of transactions in the specified block, or null if no matching block hash is found

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockTransactionCountByHash","params":["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],"id":53}' http://127.0.0.1:8545

eth_getBlockTransactionCountByNumber​

Returns the number of transactions in a block matching the specified block number.

Parameters​

blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: string - integer representing the number of transactions in the specified block, or null if no matching block number is found

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getBlockTransactionCountByNumber","params":["0xe8"],"id":51}' http://127.0.0.1:8545

eth_getCode​

Returns the code of the smart contract at the specified address. Besu stores compiled smart contract code as a hexadecimal value.

Parameters​

address: string - 20-byte contract address

blockNumber or blockHash: string - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: data - code stored at the specified address

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getCode","params":["0xa50a51c09a5c451c52bb714527e1974b686d8e77", "latest"],"id":53}' http://127.0.0.1:8545

eth_getFilterChanges​

Polls the specified filter and returns an array of changes that have occurred since the last poll.

Parameters​

filterId: string - filter ID

Returns​

result: array of strings or objects - if nothing changed since the last poll, an empty list; otherwise:

  • For filters created with eth_newBlockFilter, returns block hashes.

  • For filters created with eth_newPendingTransactionFilter, returns transaction hashes.

  • For filters created with eth_newFilter, returns log objects.

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0xf8bf5598d9e04fbe84523d42640b9b0e"],"id":1}' http://127.0.0.1:8545

eth_getFilterLogs​

Returns an array of logs for the specified filter.

Leave the --auto-log-bloom-caching-enabled command line option at the default value of true to improve log retrieval performance.

note

eth_getFilterLogs is only used for filters created with eth_newFilter. To specify a filter object and get logs without creating a filter, use eth_getLogs.

Parameters​

filterId: string - filter ID

Returns​

result: array of objects - list of log objects

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x5ace5de3985749b6a1b2b0d3f3e1fb69"],"id":1}' http://127.0.0.1:8545

eth_getLogs​

Returns an array of logs matching a specified filter object.

Leave the --auto-log-bloom-caching-enabled command line option at the default value of true to improve log retrieval performance.

caution

Using eth_getLogs to get logs from a large range of blocks, especially an entire chain from its genesis block, might cause Besu to hang for an indeterminable amount of time while generating the response. We recommend setting a range limit using the --rpc-max-logs-range option (or leaving it at its default value of 1000).

Parameters​

filterOptions: object - filter options object

Returns​

result: array of objects - list of log objects

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"earliest", "toBlock":"latest", "address": "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", "topics":[]}], "id":1}' http://127.0.0.1:8545

eth_getMinerDataByBlockHash​

Returns miner data for the specified block.

Parameters​

hash: string - 32-byte block hash

Returns​

result: object - miner data object

curl -X POST --data '{"jsonrpc":"2.0","method": "eth_getMinerDataByBlockHash","params": ["0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7"],"id": 1}' http://127.0.0.1:8545

eth_getMinerDataByBlockNumber​

Returns miner data for the specified block.

Parameters​

blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: object - miner data object

curl -X POST --data '{"jsonrpc":"2.0","method": "eth_getMinerDataByBlockNumber","params": ["0x7689D2"],"id": 1}' http://127.0.0.1:8545

eth_getProof​

Returns the account and storage values of the specified account, including the Merkle proof.

The API allows IoT devices or mobile apps which are unable to run light clients to verify responses from untrusted sources, by using a trusted block hash.

Parameters​

address: string - 20-byte address of the account or contract

keys: array of strings - list of 32-byte storage keys to generate proofs for

blockNumber or blockHash: string - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: object - account details object with the following fields:

  • balance: string - account balance

  • codeHash: string - 32-byte hash of the account code

  • nonce: string - number of transactions sent from the account

  • storageHash: string - 32-byte SHA3 of the storageRoot

  • accountProof: array of strings - list of RLP-encoded Merkle tree nodes, starting with the stateRoot

  • storageProof: array of objects - list of storage entry objects with the following fields:

    • key: string - storage key

    • value: string - storage value

    • proof: array of strings - list of RLP-encoded Merkle tree nodes, starting with the storageHash

curl -X POST --data '{"jsonrpc":"2.0","method": "eth_getProof","params": [
"0a8156e7ee392d885d10eaa86afd0e323afdcd95", ["0x0000000000000000000000000000000000000000000000000000000000000347"], "latest"],"id": 1}' http://127.0.0.1:8545

eth_getStorageAt​

Returns the value of a storage position at a specified address.

Parameters​

address: string - 20-byte storage address

index: string - integer index of the storage position

blockNumber or blockHash: string - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result : string - value at the specified storage position

Calculating the correct position depends on the storage you want to retrieve.

curl -X POST --data '{"jsonrpc":"2.0","method": "eth_getStorageAt","params": ["0x‭3B3F3E‬","0x0","latest"],"id": 53}' http://127.0.0.1:8545

eth_getTransactionByBlockHashAndIndex​

Returns transaction information for the specified block hash and transaction index position.

Parameters​

block: string - 32-byte hash of a block

index: string - integer representing the transaction index position

Returns​

result: object - transaction object, or null when there is no transaction

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByBlockHashAndIndex","params":["0xbf137c3a7a1ebdfac21252765e5d7f40d115c2757e4a4abee929be88c624fdb7", "0x2"], "id":1}' http://127.0.0.1:8545

eth_getTransactionByBlockNumberAndIndex​

Returns transaction information for the specified block number and transaction index position.

Parameters​

blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

index: string - transaction index position

Returns​

result: object - transaction object, or null when there is no transaction

This request returns the third transaction in the 82990 block on the Ropsten testnet. You can also view this block and transaction on Etherscan.

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByBlockNumberAndIndex","params":["82990", "0x2"], "id":1}' http://127.0.0.1:8545

eth_getTransactionByHash​

Returns transaction information for the specified transaction hash.

Parameters​

transaction: string - 32-byte transaction hash

Returns​

result: object - transaction object, or null when there is no transaction

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0xa52be92809541220ee0aaaede6047d9a6c5d0cd96a517c854d944ee70a0ebb44"],"id":53}' http://127.0.0.1:8545

eth_getTransactionCount​

Returns the number of transactions sent from a specified address. Use the pending tag to get the next account nonce not used by any pending transactions.

Parameters​

address: string - 20-byte account address

blockNumber or blockHash: string - hexadecimal or decimal integer representing a block number, block hash, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: string - integer representing the number of transactions sent from the specified address

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0xc94770007dda54cF92009BFF0dE90c06F603a09f","latest"],"id":1}' http://127.0.0.1:8545

eth_getTransactionReceipt​

Returns the receipt of a transaction by transaction hash. Receipts for pending transactions are not available.

If you enabled revert reason, the receipt includes available revert reasons in the response.

Parameters​

transaction: string - 32-byte hash of a transaction

Returns​

result: object - transaction receipt object, or null when there is no receipt

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x504ce587a65bdbdb6414a0c6c16d86a04dd79bfcc4f2950eec9634b30ce5370f"],"id":53}' http://127.0.0.1:8545

eth_getUncleByBlockHashAndIndex​

Returns uncle specified by block hash and index.

Parameters​

block: string - 32-byte block hash

uncleIndex: string - index of the uncle

Returns​

result: object - block object

note

Uncles don't contain individual transactions.

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleByBlockHashAndIndex","params":["0xc48fb64230a82f65a08e7280bd8745e7fea87bc7c206309dee32209fe9a985f7", "0x0"],"id":1}' http://127.0.0.1:8545

eth_getUncleByBlockNumberAndIndex​

Returns uncle specified by block number and index.

Parameters​

  • blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

  • uncleIndex: string - index of the uncle

Returns​

result: object - block object

note

Uncles do not contain individual transactions.

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleByBlockNumberAndIndex","params":["0x7689D2", "0x0"],"id":1}' http://127.0.0.1:8545

eth_getUncleCountByBlockHash​

Returns the number of uncles in a block from a block matching the given block hash.

Parameters​

block: string - 32-byte block hash

Returns​

result: string - integer representing the number of uncles in the specified block

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleCountByBlockHash","params":["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"],"id":1}' http://127.0.0.1:8545

eth_getUncleCountByBlockNumber​

Returns the number of uncles in a block matching the specified block number.

Parameters​

blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: string - integer representing the number of uncles in the specified block

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getUncleCountByBlockNumber","params":["0xe8"],"id":1}' http://127.0.0.1:8545

eth_getWork​

Returns the hash of the current block, the seed hash, and the required target boundary condition.

Parameters​

None

Returns​

result: array of strings - array with the following items:

  • header: string - 32-byte hash of the current block header (PoW-hash)

  • seed: string - 32-byte seed hash used for the DAG

  • target: string - 32-byte required target boundary condition: 2^256 / difficulty

  • blockNumber: string - hexadecimal integer representing the current block number

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getWork","params":[],"id":1}' http://127.0.0.1:8545

eth_hashrate​

Returns the number of hashes per second with which the node is mining.

When the stratum server is enabled, this method returns the cumulative hashrate of all sealers reporting their hashrate.

Parameters​

None

Returns​

result: string - number of hashes per second

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_hashrate","params":[],"id":1}' http://127.0.0.1:8545

eth_mining​

Whether the client is actively mining new blocks. Besu pauses mining while the client synchronizes with the network regardless of command settings or methods called.

Parameters​

None

Returns​

result: boolean - indicates if the client is actively mining new blocks

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_mining","params":[],"id":53}' http://127.0.0.1:8545

eth_newBlockFilter​

Creates a filter to retrieve new block hashes. To poll for new blocks, use eth_getFilterChanges.

Parameters​

None

Returns​

result: string - filter ID

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":1}' http://127.0.0.1:8545

eth_newFilter​

Creates a log filter. To poll for logs associated with the created filter, use eth_getFilterChanges. To get all logs associated with the filter, use eth_getFilterLogs.

Parameters​

filterOptions: object - filter options object

note

fromBlock and toBlock in the filter options object default to latest.

Returns​

result: string - filter ID

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newFilter","params":[{"fromBlock":"earliest", "toBlock":"latest", "topics":[]}],"id":1}' http://127.0.0.1:8545

eth_newPendingTransactionFilter​

Creates a filter to retrieve new pending transactions hashes. To poll for new pending transactions, use eth_getFilterChanges.

Parameters​

None

Returns​

result: string - filter ID

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":1}' http://127.0.0.1:8545

eth_protocolVersion​

Returns current Ethereum protocol version.

Parameters​

None

Returns​

result: string - Ethereum protocol version

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_protocolVersion","params":[],"id":1}' http://127.0.0.1:8545

eth_sendRawTransaction​

Sends a signed transaction. A transaction can send ether, deploy a contract, or interact with a contract. Set the maximum transaction fee for transactions using the --rpc-tx-feecap CLI option.

You can interact with contracts using eth_sendRawTransaction or eth_call.

To avoid exposing your private key, create signed transactions offline and send the signed transaction data using eth_sendRawTransaction.

info

Besu doesn't implement eth_sendTransaction.

Web3Signer provides transaction signing and implements eth_sendTransaction.

Parameters​

transaction: string - signed transaction serialized to hexadecimal format

note

Creating and sending transactions includes examples of creating signed transactions using the web3.js library.

Returns​

result: string - 32-byte transaction hash

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xf869018203e882520894f17f52151ebef6c7334fad080c5704d77216b732881bc16d674ec80000801ba02da1c48b670996dcb1f447ef9ef00b33033c48a4fe938f420bec3e56bfd24071a062e0aa78a81bf0290afbc3a9d8e9a068e6d74caa66c5e0fa8a46deaae96b0833"],"id":1}' http://127.0.0.1:8545

eth_submitHashrate​

Submits the mining hashrate. This is used by mining software such as Ethminer.

Parameters​

  • hashrate: string - 32-byte hexadecimal string representation of the hashrate

  • id: string - 32-byte random hexadecimal ID identifying the client

Returns​

result: boolean - indicates if submission is successful

curl -X POST --data '{"jsonrpc":"2.0", "method":"eth_submitHashrate", "params":["0x0000000000000000000000000000000000000000000000000000000000500000", "0x59daa26581d0acd1fce254fb7e85952f4c09d0915afd33d3886cd914bc7d283c"],"id":1}' http://127.0.0.1:8545

eth_submitWork​

Submits a proof of work (Ethash) solution. This is used by mining software such as Ethminer.

Parameters​

  • nonce: string - retrieved 8-byte nonce

  • header: string - 32-byte hash of the block header (PoW-hash)

  • digest: string - 32-bytes mix digest

Returns​

result: boolean - indicates if the provided solution is valid

curl -X POST --data '{"jsonrpc":"2.0", "method":"eth_submitWork", "params":["0x0000000000000001", "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "0xD1GE5700000000000000000000000000D1GE5700000000000000000000000000"],"id":1}' http://127.0.0.1:8545

eth_syncing​

Returns an object with data about the synchronization status, or false if not synchronizing.

note

Once the node reaches the head of the chain, eth_syncing returns false, indicating that there is no active syncing target.

Parameters​

None

Returns​

result: object or boolean - synchronization status data object with the following fields, or false if not synchronizing:

  • startingBlock: string - index of the highest block on the blockchain when the network synchronization starts

  • currentBlock: string - index of the latest block (also known as the best block) for the current node (this is the same index that eth_blockNumber returns.)

  • highestBlock: string - index of the highest known block in the peer network (that is, the highest block so far discovered among peer nodes. This is the same value as currentBlock if the current node has no peers.)

  • pulledStates: string - if fast synchronizing, the number of state entries fetched so far, or null if this is not known or not relevant (if full synchronizing or fully synchronized, this field is not returned.)

  • knownStates: string - if fast synchronizing, the number of states the node knows of so far, or null if this is not known or not relevant (if full synchronizing or fully synchronized, this field is not returned.)

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":51}' http://127.0.0.1:8545

eth_uninstallFilter​

Uninstalls a filter with the specified ID. When a filter is no longer required, call this method.

Filters time out when not requested by eth_getFilterChanges or eth_getFilterLogs for 10 minutes.

Parameters​

filterId: string - filter ID

Returns​

result: boolean - indicates if the filter is successfully uninstalled

curl -X POST --data '{"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0x70355a0b574b437eaa19fe95adfedc0a"],"id":1}' http://127.0.0.1:8545

MINER methods​

The MINER API methods allow you to control the node’s mining operation.

note

The MINER API methods are not enabled by default for JSON-RPC. To enable the MINER API methods, use the --rpc-http-api or --rpc-ws-api options.

miner_changeTargetGasLimit​

Updates the target gas limit set using the --target-gas-limit command line option.

Parameters​

gasPrice: number - target gas price in Wei

Returns​

result: string - Success or error

curl -X POST --data '{"jsonrpc":"2.0","method":"miner_changeTargetGasLimit","params":[800000], "id":1}' http://127.0.0.1:8545

miner_setCoinbase​

Sets the coinbase, the address for the mining rewards.

note

You can also use miner_setEtherbase as an alternative method. They both work the same way. Etherbase is a historic name for coinbase.

Parameters​

coinbase: string - Account address you pay mining rewards to

Returns​

result: boolean - true when address is set

curl -X POST --data '{"jsonrpc":"2.0","method":"miner_setCoinbase","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"],"id":1}' http://127.0.0.1:8545

miner_start​

Starts the mining process. To start mining, you must first specify a miner coinbase using the --miner-coinbase command line option or using miner_setCoinbase.

Parameters​

None

Returns​

result: boolean - true if mining starts, or if the node is already mining

curl -X POST --data '{"jsonrpc":"2.0","method":"miner_start","params":[],"id":1}' http://127.0.0.1:8545

miner_stop​

Stops the mining process on the client.

Parameters​

None

Returns​

result: boolean - true if mining stops, or if the node is not mining

curl -X POST --data '{"jsonrpc":"2.0","method":"miner_stop","params":[],"id":1}' http://127.0.0.1:8545

NET methods​

The NET API methods provide network-related information.

net_enode​

Returns the enode URL.

Parameters​

None

Returns​

result: string - enode URL of the node

curl -X POST --data '{"jsonrpc":"2.0","method":"net_enode","params":[],"id":1}' http://127.0.0.1:8545

net_listening​

Whether the client is actively listening for network connections.

Parameters​

None

Returns​

result: boolean - indicates if the client is actively listening for network connections

curl -X POST --data '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":53}' http://127.0.0.1:8545

net_peerCount​

Returns the number of peers currently connected to the client.

Parameters​

None

Returns​

result: string - number of connected peers in hexadecimal

curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":53}' http://127.0.0.1:8545

net_services​

Returns enabled services (for example, jsonrpc) and the host and port for each service.

note

The --nat-method setting affects the JSON-RPC and P2P host and port values, but not the metrics host and port values.

Parameters​

None

Returns​

result: object - enabled services

curl -X POST --data '{"jsonrpc":"2.0","method":"net_services","params":[],"id":1}' http://127.0.0.1:8545

net_version​

Returns the network ID.

Parameters​

None

Returns​

result: string - current network ID

Network IDChainNetworkDescription
1ETHMainnetMain Ethereum network
5ETHGoerliPoS test network
11155111ETHSepoliaPoS test network
2018ETHDevPoW development network
1ETCClassicMain Ethereum Classic network
7ETCMordorPoW test network
note

For almost all networks, network ID and chain ID are the same.

The only networks in the table above with different network and chain IDs are Classic with a chain ID of 61 and Mordor with a chain ID of 63.

curl -X POST --data '{"jsonrpc":"2.0","method":"net_version","params":[],"id":53}' http://127.0.0.1:8545

PLUGINS methods​

The PLUGINS API methods provide plugin-related functionality.

note

The PLUGINS API methods are not enabled by default for JSON-RPC. To enable the PLUGINS API methods, use the --rpc-http-api or --rpc-ws-api options.

plugins_reloadPluginConfig​

Reloads specified plugin configuration.

Parameters​

plugin: string - plugin

Returns​

result: string - Success

curl -X POST --data '{"jsonrpc":"2.0","method":"plugins_reloadPluginConfig","params":["tech.pegasys.plus.plugin.kafka.KafkaPlugin"],"id":1}' http://127.0.0.1:8545

TRACE methods​

The TRACE API is a more concise alternative to the DEBUG API.

note

The TRACE API methods are not enabled by default for JSON-RPC. To enable the TRACE API methods, use the --rpc-http-api or --rpc-ws-api options.

trace_block​

Provides transaction processing of type trace for the specified block.

tip

Your node must be an archive node (that is, synchronized without pruning or fast sync) or the requested block must be within the number of blocks retained with pruning enabled (by default, 1024).

Parameters​

blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: array of objects - list of calls to other contracts containing one object per call, in transaction execution order; if revert reason is enabled with --revert-reason-enabled, the returned list items include the revert reason.

curl -X POST --data '{"jsonrpc":"2.0","method":"trace_block","params":["0x6"],"id":1}' http://127.0.0.1:8545

trace_call​

Executes the given call and returns a number of possible traces for it.

info

The requested transaction must be contained in a block within the number of blocks retained with pruning enabled (by default, 1024).

Parameters​

  • call: object - transaction call object

  • blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

  • options: array of strings - list of tracing options; tracing options are trace, vmTrace, and stateDiff. Specify any combination of the three options including none of them.

Returns​

result: array of objects - list of calls to other contracts containing one object per call, in transaction execution order

curl -X POST --data '{"jsonrpc":"2.0","method":"trace_call","params":[{"from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73","to":"0x0010000000000000000000000000000000000000","gas":"0xfffff2","gasPrice":"0xef","value":"0x0","data":"0x0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000002","nonce":"0x0"},["trace"],"latest"],"id":1}' http://127.0.0.1:8545

trace_callMany​

Performs multiple call traces on top of the same block. You can trace dependent transactions.

info

The requested block must be within the number of blocks retained with pruning enabled (by default, 1024).

Parameters​

  • options: array of strings - list of tracing options; tracing options are trace, vmTrace, and stateDiff. Specify any combination of the three options including none of them.

  • blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: array of objects - list of calls to other contracts containing one object per call, in transaction execution order

curl -X POST --data '{"jsonrpc":"2.0","method":"trace_callMany","params":[[[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]],[{"from":"0x407d73d8a49eeb85d32cf465507dd71d507100c1","to":"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b","value":"0x186a0"},["trace"]]],"latest"],"id":1}' http://127.0.0.1:8545

trace_filter​

Returns traces matching the specified filter.

info

Your node must be an archive node (that is, synchronized without pruning or fast sync) or the requested block must be within the number of blocks retained with pruning enabled (by default, 1024).

Parameters​

traceFilterOptions: object - trace filter options object

Returns​

result: array of objects - list of calls to other contracts containing one object per call, in transaction execution order

curl -X POST --data '{"jsonrpc":"2.0","method":"trace_filter","params":[{"fromBlock":"0x1","toBlock":"0x21","after":2,"count":2,"fromAddress":["0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"]}],"id":415}' http://127.0.0.1:8545

trace_get​

Returns trace at given position.

info

Your node must be an archive node (that is, synchronized without pruning or fast sync) or the requested transaction must be contained in a block within the number of blocks retained with pruning enabled (by default, 1024).

Parameters​

  • transaction: string - transaction hash

  • indexPositions: array - Index positions of the traces

Returns​

result: array of objects - list of calls to other contracts containing one object per call, in the order called by the transaction

curl -X POST --data '{"jsonrpc":"2.0","method":"trace_get","params":["0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",["0x0"]],"id":1}' http://127.0.0.1:8545

trace_rawTransaction​

Traces a call to eth_sendRawTransaction without making the call, returning the traces.

info

The requested transaction must be contained in a block within the number of blocks retained with pruning enabled (by default, 1024).

Parameters​

  • data - string - Raw transaction data

  • options: array of strings - list of tracing options; tracing options are trace, vmTrace, and stateDiff. Specify any combination of the three options including none of them.

Returns​

result: array of objects - list of calls to other contracts containing one object per call, in the order called by the transaction

curl -X POST --data '{"jsonrpc":"2.0","method":"trace_rawTransaction","params":["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",["trace"]],"id":1}' http://127.0.0.1:8545

trace_replayBlockTransactions​

Provides transaction processing tracing per block.

info

When using Bonsai, the requested block must be within the number of blocks retained (by default, 512 from the head of the chain).

When using Forest, the requested block must be within the number of blocks retained with pruning enabled (by default, 1024 from head of the chain).

Parameters​

  • blockNumber: string - hexadecimal or decimal integer representing a block number or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

  • options: array of strings - list of tracing options; tracing options are trace, vmTrace, and stateDiff. Specify any combination of the three options including none of them.

Returns​

result: array of objects - list of transaction trace objects containing one object per transaction, in transaction execution order; if revert reason is enabled with --revert-reason-enabled, the trace list items in the returned transaction trace object include the revert reason.

curl -X POST --data '{"jsonrpc": "2.0", "method": "trace_replayBlockTransactions","params": ["0x12",["trace","vmTrace","stateDiff"]],"id": 1}' http://127.0.0.1:8545

trace_transaction​

Provides transaction processing of type trace for the specified transaction.

info

Your node must be an archive node (that is, synchronized without pruning or fast sync) or the requested transaction must be contained in a block within the number of blocks retained with pruning enabled (by default, 1024).

Parameters​

transaction: string - transaction hash

Returns​

result: array of objects - list of calls to other contracts containing one object per call, in the order called by the transaction; if revert reason is enabled with --revert-reason-enabled, the returned list items include the revert reason.

curl -X POST --data '{"jsonrpc": "2.0", "method": "trace_transaction","params": ["0x4c253746668dca6ac3f7b9bc18248b558a95b5fc881d140872c2dff984d344a7"],"id": 1}' http://127.0.0.1:8545

TXPOOL methods​

The TXPOOL API methods allow you to inspect the contents of the transaction pool.

note

The TXPOOL API methods are not enabled by default for JSON-RPC. To enable the TXPOOL API methods, use the --rpc-http-api or --rpc-ws-api options.

txpool_besuPendingTransactions​

Lists pending transactions that match the supplied filter conditions.

Parameters​

  • numResults: number - integer representing the maximum number of results to return

  • fields: object - object of fields used to create the filter condition

Each field in the object corresponds to a field name containing an operator, and a value for the operator. A field name can only be specified once, and can only contain one operator. For example, you cannot query transactions with a gas price between 8 and 9 Gwei by using both the gt and lt operator in the same field name instance.

All filters must be satisfied for a transaction to be returned.

Field nameValueValue typeSupported operators
fromAddress of the sender.Data, 20 byteseq
toAddress of the receiver, or "contract_creation".Data, 20 byteseq, action
gasGas provided by the sender.Quantityeq, gt, lt
gasPriceGas price, in wei, provided by the sender.Quantityeq, gt, lt
valueValue transferred, in wei.Quantityeq, gt, lt
nonceNumber of transactions made by the sender.Quantityeq, gt, lt

Supported operators:

  • eq (equal to)

  • lt (less than)

  • gt (greater than)

  • action

note

The only supported action is "contract_creation".

Returns​

result: array of objects - list of objects with details of the pending transaction

curl -X POST --data '{"jsonrpc":"2.0","method":"txpool_besuPendingTransactions","params":[2,{"from":{"eq":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73"},"gas":{"lt":"0x5209"},"nonce":{"gt":"0x1"}}],"id":1}' http://127.0.0.1:8545

txpool_besuStatistics​

Lists statistics about the node transaction pool.

Parameters​

None

Returns​

result: object - transaction pool statistics object with the following fields:

  • maxSize: number - maximum number of transactions kept in the transaction pool; use the --tx-pool-max-size option to configure the maximum size.

  • localCount: number - number of transactions submitted directly to this node

  • remoteCount: number - number of transactions received from remote nodes

curl -X POST --data '{"jsonrpc":"2.0","method":"txpool_besuStatistics","params":[],"id":1}' http://127.0.0.1:8545

txpool_besuTransactions​

Lists transactions in the node transaction pool.

Parameters​

None

Returns​

result: array of objects - list of transactions

curl -X POST --data '{"jsonrpc":"2.0","method":"txpool_besuTransactions","params":[],"id":1}' http://127.0.0.1:8545

WEB3 methods​

The WEB3 API methods provide functionality for the Ethereum ecosystem.

web3_clientVersion​

Returns the current client version.

Parameters​

None

Returns​

result: string - current client version

curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}' http://127.0.0.1:8545

web3_sha3​

Returns a SHA3 hash of the specified data. The result value is a Keccak-256 hash, not the standardized SHA3-256.

Parameters​

data: string - data to convert to a SHA3 hash

Returns​

result: string - SHA3 result of the input data

curl -X POST --data '{"jsonrpc":"2.0","method":"web3_sha3","params":["0x68656c6c6f20776f726c00"],"id":53}' http://127.0.0.1:8545

Miscellaneous methods​

rpc_modules​

Lists enabled APIs and the version of each.

Parameters​

None

Returns​

result: map of strings to strings - enabled APIs and their versions

curl -X POST --data '{"jsonrpc":"2.0","method":"rpc_modules","params":[],"id":1}' http://127.0.0.1:8545