Skip to main content

JSON-RPC methods

This section lists the Ethereum JSON-RPC API endpoints. You can call these APIs using a variety of tools.

These APIs (or a subset of them) are also used by some Ethereum-compatible networks such as:

Error codes

The following list contains all possible error codes and associated messages:

CodeMessageMeaningCategory
-32700Parse errorInvalid JSONstandard
-32600Invalid requestJSON is not a valid request objectstandard
-32601Method not foundMethod does not existstandard
-32602Invalid paramsInvalid method parametersstandard
-32603Internal errorInternal JSON-RPC errorstandard
-32000Invalid inputMissing or invalid parametersnon-standard
-32001Resource not foundRequested resource not foundnon-standard
-32002Resource unavailableRequested resource not availablenon-standard
-32003Transaction rejectedTransaction creation failednon-standard
-32004Method not supportedMethod is not implementednon-standard
-32005Limit exceededRequest exceeds defined limitnon-standard
-32006JSON-RPC version not supportedVersion of JSON-RPC protocol is not supportednon-standard

Example error response:

{
"id": 1337
"jsonrpc": "2.0",
"error": {
"code": -32003,
"message": "Transaction rejected"
}
}

Value encoding

Specific types of values passed to and returned from Ethereum RPC methods require special encoding:

Quantity

A Quantity (integer, number) must:

  • Be hex-encoded.
  • Be "0x"-prefixed.
  • Be expressed using the fewest possible hex digits per byte.
  • Express zero as "0x0".

Examples Quantity values:

ValueValidityReason
0xinvalidempty not a valid quantity
0x0validinterpreted as a quantity of zero
0x00invalidleading zeroes not allowed
0x41validinterpreted as a quantity of 65
0x400validinterpreted as a quantity of 1024
0x0400invalidleading zeroes not allowed
ffinvalidvalues must be prefixed

Block identifier

The RPC methods below take a default block identifier as a parameter.

  • eth_getBalance
  • eth_getStorageAt
  • eth_getTransactionCount
  • eth_getCode
  • eth_call
  • eth_getProof

Since there is no way to clearly distinguish between a Data parameter and a Quantity parameter, EIP-1898 provides a format to specify a block either using the block hash or block number. The block identifier is a JSON object with the following fields:

PropertyTypeDescription
[blockNumber]{Quantity}The block in the canonical chain with this number
OR [blockHash]{Data}The block uniquely identified by this hash. The blockNumber and blockHash properties are mutually exclusive; exactly one of them must be set.
requireCanonical{boolean}(optional) Whether or not to throw an error if the block is not in the canonical chain as described below. Only allowed in conjunction with the blockHash tag. Defaults to false.

Data

A Data value (for example, byte arrays, account addresses, hashes, and bytecode arrays) must:

  • Be hex-encoded.
  • Be "0x"-prefixed.
  • Be expressed using two hex digits per byte.

Examples Data values:

ValueValidReason
0xvalidinterpreted as empty data
0x0invalideach byte must be represented using two hex digits
0x00validinterpreted as a single zero byte
0x41trueinterpreted as a data value of 65
0x004200trueinterpreted as a data value of 16896
0xf0f0ffalsebytes require two hex digits
004200falsevalues must be prefixed