API Method
The API Method allows you to interact with the Bitrock Blockchain.
ADMIN
methodsβ
ADMIN
methodsβadmin_addPeer
β
admin_addPeer
βIf connections are timing out, ensure the node ID in the enode URL is correct.
Parametersβ
enode
: - String = enode://1fd6bfa1ac606ab3cdbbbacef1b27a1e38b0ac54d5c1a361d07a27211b54b4817aa9b14e596f23c7020d246998f5224ae18882b181dad2ee940d774a085eb7bd@206.81.20.253:30303
Returnsβ
result
: boolean - true
if peer added or false
if peer already a static node
curl HTTP request
wscat WS request
JSON result
admin_changeLogLevel
β
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 levellog_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 HTTP request
wscat WS request
JSON result
The following example changes the debug level of all logs to WARN
.
curl HTTP request
wscat WS request
JSON result
admin_generateLogBloomCache
β
admin_generateLogBloomCache
βGenerates cached log bloom indexes for blocks. APIs such as eth_getLogs
and eth_getFilterLogs
use the cache for improved performance.
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 indexesendBlock
: string - block to stop generating indexes
Returnsβ
result
: object - log bloom index details:
startBlock
: string - starting block for the last requested cache generationendBlock
: string - ending block for the last requested cache generationcurrentBlock
: string - most recent block added to the cacheindexing
: boolean - indicates if indexing is in progressboolean - indicates acceptance of the request from this call to generate the cache
curl HTTP request
wscat WS request
JSON result
admin_logsRemoveCache
β
admin_logsRemoveCache
βRemoves cache files for the specified range of blocks.
Parametersβ
fromBlock
: string - integer representing a block number or one of the string tagslatest
,earliest
, orpending
, as described in block parametertoBlock
: string - integer representing a block number or one of the string tagslatest
,earliest
, orpending
, 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 HTTP request
wscat WS request
JSON result
admin_logsRepairCache
β
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 HTTP request
wscat WS request
JSON result
admin_nodeInfo
β
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 nodelistenAddr
: string - host and port for the nodename
: string - client nameid
: string - node public keyports
: object - peer discovery and listening portsprotocols
: 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 HTTP request
wscat WS request
JSON result
admin_peers
β
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 versionname
: string - client namecaps
: array of strings - list of Ethereum sub-protocol capabilitiesnetwork
: object - local and remote addresses established at time of bonding with the peer (the remote address might not match the hex value forport
; it depends on which node initiated the connection.)port
: string - port on the remote node on which P2P discovery is listeningid
: string - node public key (excluding the0x
prefix, the node public key is the ID in the enode URLenode://<id ex 0x>@<host>:<port>
.)protocols
: object - current state of peer includingdifficulty
andhead
(head
is the hash of the highest known block for the peer.)enode
: string - enode URL of the remote nodecurl HTTP request
wscat WS request
JSON result
admin_removePeer
β
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 HTTP request
wscat WS request
JSON result
DEBUG
methodsβ
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
β
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 informationtxIndex
: number - transaction index at which to retrieve account informationaddress
: 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. Displays0x0
if the address is an externally owned account.nonce
: quantity - number of transactions made by the account before this onebalance
: quantity - balance of the account in Weicodehash
: data - code hash for the account
This example uses an externally owned account address for the address
parameter.
curl HTTP request
wscat WS request
JSON result
This example uses a contract address for the address
parameter.
curl HTTP request
wscat WS request
JSON result
debug_accountRange
β
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 informationtxIndex
: number - transaction index at which to retrieve account informationaddress
: string - address hash from which to startlimit
: 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 addressesnextKey
: string - hash of the next address if any addresses remain in the state, otherwise zerocurl HTTP request
wscat WS request
JSON result
debug_batchSendRawTransaction
β
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 arraysuccess
: boolean - indicates whether or not the transaction has been added to the transaction poolerrorMessage
: string - (optional) error messagecurl HTTP
wscat WS
JSON result
debug_getBadBlocks
β
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 HTTP
wscat WS
JSON result
debug_getRawBlock
β
debug_getRawBlock
βReturns the RLP encoding of the specified block.
Parametersβ
blockNumber
: string - integer representing a block number or one of the string tags latest
, earliest
, or pending
, as described in block parameter
Returnsβ
result
: object - RLP-encoded block object
curl HTTP request
wscat WS request
JSON result
Returns the RLP encoding of the header of specified block.
Parametersβ
blockNumber
: string - integer representing a block number or one of the string tags latest
, earliest
, or pending
, as described in block parameter
Returnsβ
result
: string - RLP-encoded block header or error
curl HTTP request
wscat WS request
JSON result
debug_metrics
β
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 HTTP request
wscat WS request
JSON result
debug_replayBlock
β
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 - integer representing a block number or one of the string tags latest
, earliest
, or pending
, as described in block parameter
Returnsβ
result
: string - Success
or error
curl HTTP request
wscat WS request
JSON result
debug_resyncWorldstate
β
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 HTTP request
wscat WS request
JSON result
debug_setHead
β
debug_setHead
βSets the current head of the local chain to the block matching the specified block number.
Parametersβ
blockNumber
: string - integer representing a block number or one of the string tags latest
, earliest
, or pending
, as described in block parameter
Returnsβ
result
: string - Success
or error
curl HTTP request
wscat WS request
JSON result
debug_standardTraceBlockToFile
β
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 HTTP request
wscat WS request
JSON result
debug_standardTraceBadBlockToFile
β
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 HTTP request
wscat WS request
JSON result
debug_storageRangeAt
β
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 hashtxIndex
: number - transaction index from which to startaddress
: string - contract addressstartKey
: string - start keylimit
: number - number of storage entries to return
Returnsβ
result
: object - range object.
curl HTTP request
wscat WS request
JSON result
curl HTTP request
wscat WS request
JSON result
debug_traceBlock
β
debug_traceBlock
βReturns full trace of all invoked opcodes of all transactions included in the block.
Parametersβ
block
: string - RLP of the blockoptions
: object - request options object with the following fields (all optional and default tofalse
):disableStorage
: boolean -true
disables storage capture.disableMemory
: boolean -true
disables memory capture.disableStack
: boolean -true
disables stack capture.
Returnsβ
result
: object - trace object
curl HTTP request
wscat WS request
JSON result
debug_traceBlockByHash
β
debug_traceBlockByHash
βReturns full trace of all invoked opcodes of all transactions included in the block.
Parametersβ
blockHash
: string - block hashoptions
: object - request options object with the following fields (all optional and default tofalse
):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 HTTP request
wscat WS request
JSON result
debug_traceBlockByNumber
β
debug_traceBlockByNumber
βReturns full trace of all invoked opcodes of all transactions included in the block.
Parametersβ
blockNumber
: string - integer representing a block number or one of the string tagslatest
,earliest
, orpending
, as described in block parameteroptions
: object - request options object with the following fields (all optional and default tofalse
):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 HTTP request
wscat WS request
JSON result
ETH
methodsβ
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
β
eth_accounts
βReturns a list of account addresses a client owns.
Parametersβ
None
Returnsβ
result
: array of strings - list of 20-byte account addresses owned by the client
curl HTTP request
wscat WS request
JSON result
eth_blockNumber
β
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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_call
β
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
.
If revert reason is enabled with --revert-reason-enabled
, the eth_call
error response includes the revert reason.
Parametersβ
call
: object - transaction call object
blockNumber
or blockHash
: string - integer representing a block number, block hash, or one of the string tags latest
, earliest
, or pending
, 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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
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 HTTP
JSON result
eth_chainId
β
eth_chainId
βReturns the chain ID.
Parametersβ
None
Returnsβ
result
: string - chain ID in hexadecimal
curl HTTP request
wscat WS request
JSON result
eth_coinbase
β
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 Bitrock Scan. For example:
Example
Parametersβ
None
Returnsβ
result
: string - coinbase address
curl HTTP request
wscat WS request
JSON result
eth_createAccessList
β
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 - integer representing a block number, block hash, or one of the string tags latest
, earliest
, or pending
, 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 transactionstorageKeys
: array - storage keys to be accessed by the transaction
gasUsed
: string - approximate gas cost for the transaction if the access list is includedcurl HTTP
wscat WS
JSON result
eth_estimateGas
β
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.
If revert reason is enabled with --revert-reason-enabled
, 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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
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 HTTP request
JSON result
eth_feeHistory
β
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 - Integer representing the highest number block of the requested range or one of the string tagslatest
,earliest
, orpending
, as described in block parameter.array
ofintegers
- (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 HTTP
wscat WS
JSON result
eth_gasPrice
β
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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getBalance
β
eth_getBalance
βReturns the account balance of the specified address.
Parametersβ
address
: string - 20-byte account address from which to retrieve the balanceblockNumber
orblockHash
: string - integer representing a block number, block hash, or one of the string tagslatest
,earliest
, orpending
, as described in block parameter
Returnsβ
result
: string - current balance, in Wei, as a hexadecimal value
curl HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getBlockByHash
β
eth_getBlockByHash
βReturns information about the block matching the specified block hash.
Parametersβ
hash
: string - 32-byte hash of a blockverbose
: boolean - iftrue
, returns the full transaction objects; iffalse
, returns the transaction hashes
Returnsβ
result
: object - block object, or null
when there is no block
curl HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getBlockByNumber
β
eth_getBlockByNumber
βReturns information about the block matching the specified block number.
Parametersβ
blockNumber
: string - integer representing a block number or one of the string tagslatest
,earliest
,pending
,finalized
, orsafe
as described in block parameterverbose
: boolean - iftrue
, returns the full transaction objects; iffalse
, returns only the hashes of the transactions.
Returnsβ
result
: object - block object, or null
when there is no block.
curl HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getBlockTransactionCountByHash
β
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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getBlockTransactionCountByNumber
β
eth_getBlockTransactionCountByNumber
βReturns the number of transactions in a block matching the specified block number.
Parametersβ
blockNumber
: string - integer representing a block number or one of the string tags latest
, earliest
, or pending
, 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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getCode
β
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 - integer representing a block number, block hash, or one of the string tags latest
, earliest
, or pending
, as described in block parameter
Returnsβ
result
: data - code stored at the specified address
curl HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getFilterChanges
β
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 HTTP request
wscat WS request
JSON result
eth_getFilterLogs
β
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 HTTP request
wscat WS request
JSON result
eth_getLogs
β
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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getMinerDataByBlockHash
β
eth_getMinerDataByBlockHash
βReturns miner data for the specified block.
Parametersβ
hash
: string - 32-byte block hash
Returnsβ
result
: object - miner data object
curl HTTP
wscat WS
JSON result
eth_getMinerDataByBlockNumber
β
eth_getMinerDataByBlockNumber
βReturns miner data for the specified block.
Parametersβ
blockNumber
: string - integer representing a block number or one of the string tags latest
, earliest
, or pending
, as described in block parameter
Returnsβ
result
: object - miner data object
curl HTTP
wscat WS
JSON result
eth_getProof
β
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 - integer representing a block number, block hash, or one of the string tags latest
, earliest
, or pending
, as described in block parameter
Returnsβ
result
: object - account details object with the following fields:
balance
: string - account balancecodeHash
: string - 32-byte hash of the account codenonce
: string - number of transactions sent from the accountstorageHash
: string - 32-byte SHA3 of thestorageRoot
accountProof
: array of strings - list of RLP-encoded Merkle tree nodes, starting with thestateRoot
storageProof
: array of objects - list of storage entry objects with the following fields:key
: string - storage keyvalue
: string - storage valueproof
: array of strings - list of RLP-encoded Merkle tree nodes, starting with thestorageHash
curl HTTP
wscat WS
JSON result
eth_getStorageAt
β
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 - integer representing a block number, block hash, or one of the string tags latest
, earliest
, or pending
, 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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getTransactionByBlockHashAndIndex
β
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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getTransactionByBlockNumberAndIndex
β
eth_getTransactionByBlockNumberAndIndex
βReturns transaction information for the specified block number and transaction index position.
Parametersβ
blockNumber
: string - integer representing a block number or one of the string tags latest
, earliest
, or pending
, 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 Bitrock Chain. You can also view this block and transaction on Bitrock Scan.
curl HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getTransactionByHash
β
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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getTransactionCount
β
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 - integer representing a block number, block hash, or one of the string tags latest
, earliest
, or pending
, as described in block parameter
Returnsβ
result
: string - integer representing the number of transactions sent from the specified address
curl HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getTransactionReceipt
β
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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getUncleByBlockHashAndIndex
β
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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getUncleByBlockNumberAndIndex
β
eth_getUncleByBlockNumberAndIndex
βReturns uncle specified by block number and index.
Parametersβ
blockNumber
: string - integer representing a block number or one of the string tagslatest
,earliest
, orpending
, as described in block parameteruncleIndex
: string - index of the uncle
Returnsβ
result
: object - block object
note
Uncles do not contain individual transactions.
curl HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getUncleCountByBlockHash
β
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 HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getUncleCountByBlockNumber
β
eth_getUncleCountByBlockNumber
βReturns the number of uncles in a block matching the specified block number.
Parametersβ
blockNumber
: string - integer representing a block number or one of the string tags latest
, earliest
, or pending
, as described in block parameter
Returnsβ
result
: string - integer representing the number of uncles in the specified block
curl HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_getWork
β
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 DAGtarget
: string - 32-byte required target boundary condition: 2^256 / difficultyblockNumber
: string - hexadecimal integer representing the current block numbercurl HTTP request
wscat WS request
JSON result
eth_hashrate
β
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 HTTP request
wscat WS request
JSON result
eth_mining
β
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 HTTP request
wscat WS request
JSON result
eth_newBlockFilter
β
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 HTTP request
wscat WS request
JSON result
eth_newFilter
β
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 HTTP request
wscat WS request
JSON result
eth_newPendingTransactionFilter
β
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 HTTP request
wscat WS request
JSON result
eth_protocolVersion
β
eth_protocolVersion
βReturns current Ethereum protocol version.
Parametersβ
None
Returnsβ
result
: string - Ethereum protocol version
curl HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_sendRawTransaction
β
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
.
Parametersβ
transaction
: string - signed transaction serialized to hexadecimal format
Returnsβ
result
: string - 32-byte transaction hash
curl HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_submitHashrate
β
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 hashrateid
: string - 32-byte random hexadecimal ID identifying the client
Returnsβ
result
: boolean - indicates if submission is successful
curl HTTP request
wscat WS request
JSON result
eth_submitWork
β
eth_submitWork
βSubmits a proof of work (Ethash) solution. This is used by mining software such as Ethminer.
Parametersβ
nonce
: string - retrieved 8-byte nonceheader
: 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 HTTP request
wscat WS request
JSON result
eth_syncing
β
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 startscurrentBlock
: string - index of the latest block (also known as the best block) for the current node (this is the same index thateth_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 ascurrentBlock
if the current node has no peers.)pulledStates
: string - if fast synchronizing, the number of state entries fetched so far, ornull
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, ornull
if this is not known or not relevant (if full synchronizing or fully synchronized, this field is not returned.)curl HTTP
wscat WS
JSON result
curl GraphQL
GraphQL
GraphQL result
eth_uninstallFilter
β
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 HTTP request
wscat WS request
JSON result
MINER
methodsβ
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
β
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 HTTP request
wscat WS request
JSON result
miner_setCoinbase
β
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 HTTP request
wscat WS request
JSON result
miner_start
β
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 HTTP request
wscat WS request
JSON result
miner_stop
β
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 HTTP request
wscat WS request
JSON result
NET
methodsβ
NET
methodsβThe NET
API methods provide network-related information.
net_enode
β
net_enode
βReturns the enode URL.
Parametersβ
None
Returnsβ
result
: string - enode URL of the node
curl HTTP request
wscat WS request
JSON result
net_listening
β
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 HTTP request
wscat WS request
JSON result
net_peerCount
β
net_peerCount
βReturns the number of peers currently connected to the client.
Parametersβ
None
Returnsβ
result
: string - number of connected peers in hexadecimal
curl HTTP request
wscat WS request
JSON result
TXPOOL
methodsβ
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
β
txpool_besuPendingTransactions
βLists pending transactions that match the supplied filter conditions.
Parametersβ
numResults
: number - integer representing the maximum number of results to returnfields
: 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 name | Value | Value type | Supported operators |
---|---|---|---|
| Address of the sender. | Data, 20 bytes |
|
| Address of the receiver, or | Data, 20 bytes |
|
| Gas provided by the sender. | Quantity |
|
| Gas price, in wei, provided by the sender. | Quantity |
|
| Value transferred, in wei. | Quantity |
|
| Number of transactions made by the sender. | Quantity |
|
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 HTTP request
wscat WS request
JSON result
txpool_besuStatistics
β
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 noderemoteCount
: number - number of transactions received from remote nodescurl HTTP request
wscat WS request
JSON result
txpool_besuTransactions
β
txpool_besuTransactions
βLists transactions in the node transaction pool.
Parametersβ
None
Returnsβ
result
: array of objects - list of transactions
curl HTTP request
wscat WS request
JSON result
WEB3
methodsβ
WEB3
methodsβThe WEB3
API methods provide functionality for the Ethereum ecosystem.
web3_clientVersion
β
web3_clientVersion
βReturns the current client version.
Parametersβ
None
Returnsβ
result
: string - current client version
curl HTTP request
wscat WS request
JSON result
web3_sha3
β
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 HTTP request
wscat WS request
JSON result
Miscellaneous methodsβ
rpc_modules
β
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 HTTP request
wscat WS request
JSON result
Last updated