JSON-RPC API
கடைசியாகத் திருத்தப்பட்டது: , Invalid DateTime
In order for a software application to interact with the Ethereum blockchain - either by reading blockchain data or sending transactions to the network - it must connect to an Ethereum node.
For this purpose, every Ethereum client implements a JSON-RPC specification(opens in a new tab), so there is a uniform set of methods that applications can rely on regardless of the specific node or client implementation.
JSON-RPC(opens in a new tab) is a stateless, light-weight remote procedure call (RPC) protocol. It defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over HTTP, or in many various message passing environments. It uses JSON (RFC 4627) as data format.
Client implementations
Ethereum clients each may utilize different programming languages when implementing the JSON-RPC specification. See individual client documentation for further details related to specific programming languages. We recommend checking the documentation of each client for the latest API support information.
Convenience Libraries
While you may choose to interact directly with Ethereum clients via the JSON-RPC API, there are often easier options for dapp developers. Many JavaScript and backend API libraries exist to provide wrappers on top of the JSON-RPC API. With these libraries, developers can write intuitive, one-line methods in the programming language of their choice to initialize JSON-RPC requests (under the hood) that interact with Ethereum.
Consensus client APIs
This page deals mainly with the JSON-RPC API used by Ethereum execution clients. However, consensus clients also have an RPC API that allows users to query information about the node, request Beacon blocks, Beacon state, and other consensus-related information directly from a node. This API is documented on the Beacon API webpage(opens in a new tab).
An internal API is also used for inter-client communication within a node - that is, it enables the consensus client and execution client to swap data. This is called the 'Engine API' and the specs are available on GitHub(opens in a new tab).
Execution client spec
Read the full JSON-RPC API spec on GitHub(opens in a new tab).
Conventions
Hex value encoding
Two key data types get passed over JSON: unformatted byte arrays and quantities. Both are passed with a hex encoding but with different requirements for formatting.
Quantities
When encoding quantities (integers, numbers): encode as hex, prefix with "0x", the most compact representation (slight exception: zero should be represented as "0x0").
Here are some examples:
- 0x41 (65 in decimal)
- 0x400 (1024 in decimal)
- WRONG: 0x (should always have at least one digit - zero is "0x0")
- WRONG: 0x0400 (no leading zeroes allowed)
- WRONG: ff (must be prefixed 0x)
Unformatted data
When encoding unformatted data (byte arrays, account addresses, hashes, bytecode arrays): encode as hex, prefix with "0x", two hex digits per byte.
Here are some examples:
- 0x41 (size 1, "A")
- 0x004200 (size 3, "\0B\0")
- 0x (size 0, "")
- WRONG: 0xf0f0f (must be even number of digits)
- WRONG: 004200 (must be prefixed 0x)
The default block parameter
The following methods have an extra default block parameter:
When requests are made that act on the state of Ethereum, the last default block parameter determines the height of the block.
The following options are possible for the defaultBlock parameter:
HEX String
- an integer block numberString "earliest"
for the earliest/genesis blockString "latest"
- for the latest mined blockString "safe"
- for the latest safe head blockString "finalized"
- for the latest finalized blockString "pending"
- for the pending state/transactions
Examples
On this page we provide examples of how to use individual JSON_RPC API endpoints using the command line tool, curl(opens in a new tab). These individual endpoint examples are found below in the Curl examples section. Further down the page, we also provide an end-to-end example for compiling and deploying a smart contract using a Geth node, the JSON_RPC API and curl.
Curl examples
Examples of using the JSON_RPC API by making curl(opens in a new tab) requests to an Ethereum node are provided below. Each example includes a description of the specific endpoint, its parameters, return type, and a worked example of how it should be used.
The curl requests might return an error message relating to the content type. This is because the --data
option sets the content type to application/x-www-form-urlencoded
. If your node does complain about this, manually set the header by placing -H "Content-Type: application/json"
at the start of the call. The examples also do not include the URL/IP & port combination which must be the last argument given to curl (e.g. 127.0.0.1:8545
). A complete curl request including these additional data takes the following form:
1curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":67}' 127.0.0.1:85452
Gossip, State, History
A handful of core JSON-RPC methods require data from the Ethereum network, and fall neatly into three main categories: Gossip, State, and History. Use the links in these sections to jump to each method, or use the table of contents to explore the whole list of methods.
Gossip Methods
These methods track the head of the chain. This is how transactions make their way around the network, find their way into blocks, and how clients find out about new blocks.
State Methods
Methods that report the current state of all the data stored. The "state" is like one big shared piece of RAM, and includes account balances, contract data, and gas estimations.
History Methods
Fetches historical records of every block back to genesis. This is like one large append-only file, and includes all block headers, block bodies, uncle blocks, and transaction receipts.
- eth_getBlockTransactionCountByHash
- eth_getBlockTransactionCountByNumber
- eth_getUncleCountByBlockHash
- eth_getUncleCountByBlockNumber
- eth_getBlockByHash
- eth_getBlockByNumber
- eth_getTransactionByHash
- eth_getTransactionByBlockHashAndIndex
- eth_getTransactionByBlockNumberAndIndex
- eth_getTransactionReceipt
- eth_getUncleByBlockHashAndIndex
- eth_getUncleByBlockNumberAndIndex
JSON-RPC API Methods
web3_clientVersion
Returns the current client version.
Parameters
None
Returns
String
- The current client version
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":67}'3// Result4{5 "id":67,6 "jsonrpc":"2.0",7 "result": "Geth/v1.12.1-stable/linux-amd64/go1.19.1"8}9நகலெடு
web3_sha3
Returns Keccak-256 (not the standardized SHA3-256) of the given data.
Parameters
DATA
- the data to convert into a SHA3 hash
1params: ["0x68656c6c6f20776f726c64"]2நகலெடு
Returns
DATA
- The SHA3 result of the given string.
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"web3_sha3","params":["0x68656c6c6f20776f726c64"],"id":64}'3// Result4{5 "id":64,6 "jsonrpc": "2.0",7 "result": "0x47173285a8d7341e5e972fc677286384f802f8ef42a5ec5f03bbfa254cb01fad"8}9நகலெடு
net_version
Returns the current network id.
Parameters
None
Returns
String
- The current network id.
The full list of current network IDs is available at chainlist.org(opens in a new tab). Some common ones are:
1
: Ethereum Mainnet5
: Goerli testnet11155111
: Sepolia testnet
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"net_version","params":[],"id":67}'3// Result4{5 "id":67,6 "jsonrpc": "2.0",7 "result": "3"8}9நகலெடு
net_listening
Returns true
if client is actively listening for network connections.
Parameters
None
Returns
Boolean
- true
when listening, otherwise false
.
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":67}'3// Result4{5 "id":67,6 "jsonrpc":"2.0",7 "result":true8}9நகலெடு
net_peerCount
Returns number of peers currently connected to the client.
Parameters
None
Returns
QUANTITY
- integer of the number of connected peers.
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":74}'3// Result4{5 "id":74,6 "jsonrpc": "2.0",7 "result": "0x2" // 28}9நகலெடு
eth_protocolVersion
Returns the current Ethereum protocol version. Note that this method is not available in Geth(opens in a new tab).
Parameters
None
Returns
String
- The current Ethereum protocol version
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"eth_protocolVersion","params":[],"id":67}'3// Result4{5 "id":67,6 "jsonrpc": "2.0",7 "result": "54"8}9நகலெடு
eth_syncing
Returns an object with data about the sync status or false
.
Parameters
None
Returns
The precise return data varies between client implementations. All clients return False
when the node is not syncing, and all clients return the following fields.
Object|Boolean
, An object with sync status data or FALSE
, when not syncing:
startingBlock
:QUANTITY
- The block at which the import started (will only be reset, after the sync reached his head)currentBlock
:QUANTITY
- The current block, same as eth_blockNumberhighestBlock
:QUANTITY
- The estimated highest block
However, the individual clients may also provide additional data. For example Geth returns the following:
1{2 "jsonrpc": "2.0",3 "id": 1,4 "result": {5 "currentBlock": "0x3cf522",6 "healedBytecodeBytes": "0x0",7 "healedBytecodes": "0x0",8 "healedTrienodes": "0x0",9 "healingBytecode": "0x0",10 "healingTrienodes": "0x0",11 "highestBlock": "0x3e0e41",12 "startingBlock": "0x3cbed5",13 "syncedAccountBytes": "0x0",14 "syncedAccounts": "0x0",15 "syncedBytecodeBytes": "0x0",16 "syncedBytecodes": "0x0",17 "syncedStorage": "0x0",18 "syncedStorageBytes": "0x0"19 }20}21அனைத்தையும் காட்டுநகலெடு
Whereas Besu returns:
1{2 "jsonrpc": "2.0",3 "id": 51,4 "result": {5 "startingBlock": "0x0",6 "currentBlock": "0x1518",7 "highestBlock": "0x9567a3",8 "pulledStates": "0x203ca",9 "knownStates": "0x200636"10 }11}12அனைத்தையும் காட்டுநகலெடு
Refer to the documentation for your specific client for more details.
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}'3// Result4{5 "id":1,6 "jsonrpc": "2.0",7 "result": {8 startingBlock: '0x384',9 currentBlock: '0x386',10 highestBlock: '0x454'11 }12}13// Or when not syncing14{15 "id":1,16 "jsonrpc": "2.0",17 "result": false18}19அனைத்தையும் காட்டுநகலெடு
eth_coinbase
Returns the client coinbase address.
Parameters
None
Returns
DATA
, 20 bytes - the current coinbase address.
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"eth_coinbase","params":[],"id":64}'3// Result4{5 "id":64,6 "jsonrpc": "2.0",7 "result": "0x407d73d8a49eeb85d32cf465507dd71d507100c1"8}9நகலெடு
eth_chainId
Returns the chain ID used for signing replay-protected transactions.
Parameters
None
Returns
chainId
, hexadecimal value as a string representing the integer of the current chain id.
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":67}'3// Result4{5 "id":67,6 "jsonrpc": "2.0",7 "result": "0x1"8}9நகலெடு
eth_mining
Returns true
if client is actively mining new blocks. This can only return true
for proof-of-work networks and may not be available in some clients since The Merge.
Parameters
None
Returns
Boolean
- returns true
of the client is mining, otherwise false
.
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"eth_mining","params":[],"id":71}'3//4{5 "id":71,6 "jsonrpc": "2.0",7 "result": true8}9நகலெடு
eth_hashrate
Returns the number of hashes per second that the node is mining with. This can only return true
for proof-of-work networks and may not be available in some clients since The Merge.
Parameters
None
Returns
QUANTITY
- number of hashes per second.
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"eth_hashrate","params":[],"id":71}'3// Result4{5 "id":71,6 "jsonrpc": "2.0",7 "result": "0x38a"8}9நகலெடு
eth_gasPrice
Returns an estimate of the current price per gas in wei. For example, the Besu client examines the last 100 blocks and returns the median gas unit price by default.
Parameters
None
Returns
QUANTITY
- integer of the current gas price in wei.
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":73}'3// Result4{5 "id":73,6 "jsonrpc": "2.0",7 "result": "0x1dfd14000" // 8049999872 Wei8}9நகலெடு
eth_accounts
Returns a list of addresses owned by client.
Parameters
None
Returns
Array of DATA
, 20 Bytes - addresses owned by the client.
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"eth_accounts","params":[],"id":1}'3// Result4{5 "id":1,6 "jsonrpc": "2.0",7 "result": ["0x407d73d8a49eeb85d32cf465507dd71d507100c1"]8}9நகலெடு
eth_blockNumber
Returns the number of most recent block.
Parameters
None
Returns
QUANTITY
- integer of the current block number the client is on.
Example
1// Request2curl -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":83}'3// Result4{5 "id":83,6 "jsonrpc": "2.0",7 "result": "0x4b7" // 12078}9![]()