Using the JSON-RPC API

!!!attention "Breaking Change in v0.8.3"

From v0.8.3, incoming HTTP requests are only accepted from hostnames specified using the [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) option.
If not specified, the default value for [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) is `localhost`. 

If using the URL `http://127.0.0.1` to make JSON-RPC calls, use [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) to specify the hostname `127.0.0.1` or update the hostname to `localhost`. 

If your application publishes RPC ports, specify the hostnames when starting Pantheon. For example:  
```bash
pantheon --host-whitelist=foo.com
```

Specify `*` or `all` for [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) to effectively disable host protection and replicate pre-v0.8.3 behavior.

**This is not recommended for production code.**

Using the Pantheon JSON-RPC API

Postman

Use the button to import our collection of examples to Postman.

Endpoint Address and Port

In this reference, the placeholder <JSON-RPC-http-endpoint:port> and <JSON-RPC-ws-endpoint:port> means an endpoint (IP address and port) of the JSON-RPC service of a Pantheon node respectively for http endpoint and for WebSocket endpoint.

To activate JSON-RPC using http or WebSocket, see --rpc-listen and --ws-listen options in the CLI documentation.

The transport attributes are:

HTTP: Listens by default on port 8545
WebSockets: Listens by default on port 8546

HTTP and WebSocket Requests

HTTP

To make RPC over HTTP requests, you can use the curl tool, available in many systems using curl source code or pre-compiled packages.

$ curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53}' <JSON-RPC-http-endpoint:port>

WebSockets

To make requests over WebSockets, this reference uses wscat, a Node.js based command-line tool.

First connect to the WebSockets server using wscat (you only need to connect once per session):

$ wscat -c ws://<JSON-RPC-ws-endpoint:port>

After the connection is established, the terminal will display a '>' prompt. Send individual requests as a JSON data package at each prompt:

> {"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53}

The RPC Pub/Sub methods can also be used over WebSockets.

Block Parameter

When you make requests that might have different results depending on the block accessed, the block parameter specifies the block. Several methods, such as eth_getTransactionByBlockNumberAndIndex, have a block parameter.

The block parameter can have the following values:

blockNumber : quantity - Block number. Can be specified in hexadecimal or decimal. 0 represents the genesis block.
earliest : tag - Earliest (genesis) block.
latest : tag - Last block mined.
pending : tag - Last block mined plus pending transactions. Use only with eth_getTransactionCount.

Not Supported by Pantheon

Account Management

Account management relies on private key management in the client which is not implemented by Pantheon.

Use eth_sendRawTransaction to send signed transactions; eth_sendTransaction is not implemented.

Use third-party wallets for account management.

Protocols

Pantheon does not implement the Whisper and Swarm protocols.

4.0 KiB Raw Blame History