JSON is a lightweight data-interchange format. It can represent numbers, strings, ordered sequences of values, and collections of name/value pairs.
JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification 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.
Geth has pub/sub support since version 1.4. See this page for more information.
OpenEthereum (f.k.a. Parity) experimental pub/sub support since version 1.6. See this for more information.
Hyperledger Besu has pub/sub support since version 1.3. See this for more information.
Nethermind has pub/sub support. See this for more information.
Default JSON-RPC endpoints:
You can start the HTTP JSON-RPC with the
change the default port (8545) and listing address (localhost) with:
geth --rpc --rpcaddr <ip> --rpcport <portnumber>
geth --rpc --rpccorsdomain "http://localhost:3000"
The JSON RPC can also be started from the geth console using the
admin.startRPC(addr, port) command.
You can start it by running
eth application with
You can also specify JSON-RPC port (default is 8545):
./eth -j --json-rpc-port 8079
In python the JSONRPC server is currently started by default and listens on
You can change the port and listen address by giving a config option.
pyethapp -c jsonrpc.listen_port=4002 -c jsonrpc.listen_host=127.0.0.2 run
Run a Besu node on mainnet with the HTTP JSON-RPC service enabled:
More details can be found in the documentation.
At present there are two key datatypes that are passed over JSON: unformatted byte arrays and quantities. Both are passed with a hex encoding, however with different requirements to formatting:
When encoding QUANTITIES (integers, numbers): encode as hex, prefix with “0x”, the most compact representation (slight exception: zero should be represented as “0x0”). Examples:
When encoding UNFORMATTED DATA (byte arrays, account addresses, hashes, bytecode arrays): encode as hex, prefix with “0x”, two hex digits per byte. Examples:
Currently cpp-ethereum,go-ethereum, and parity provide JSON-RPC communication over http and IPC (unix socket Linux and OSX/named pipes on Windows). Version 1.4 of go-ethereum, version 1.6 of Parity and version 1.3 of Hyperledger Besu onwards have websocket support.
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 number
String "earliest"for the earliest/genesis block
String "latest"- for the latest mined block
String "pending"- for the pending state/transactions
The curl options might return a response where the node complains about the content type, this is because the --data option sets the content type to application/x-www-form-urlencoded . If your node does complain, 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.x. 127.0.0.1:8545
The full list of JSON-RPC methods is now maintained in the eth1.0-apis repository.