Using Polygon blockchain nodes

This page describes how to call the Polygon node API. Before you can access the Polygon blockchain node, you will need to know the API key and node endpoint URL. Follow the using blockchain nodes guide to determine these, if you have not already done so.

JSON-RPC

This section describes querying a Polygon blockchain node's JSON-RPC API.

Example RPC

You can query the client via JSON-RPC. See Polygon RPC API Reference for documentation.

For example, to call the eth_getBlockByNumber() method:

curl -H POST \
  -H "X-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id":1,
    "jsonrpc":"2.0",
    "method": "eth_getBlockByNumber",
    "params": ["0x1", true]
  }' \
  http://YOUR_NODES_URL

Where:

  • id is an identifier set by the client--the originator of the request. For example, 1.
  • jsonrpc is the JSON-RPC version. For example, 2.0.
  • method is the name of the method. For example, eth_getBlockByNumber.
  • params are values to be used with method.
  • YOUR_NODES_URL is the address returned in Get the blockchain node URLs. For example, json-rpc.5baqy90l9xcxq6i262vch479a.d.blockchainnodeengine.com.
  • YOUR_API_KEY is the key you created in Create an API key.

See JSON-RPC2.0 Specification for more information on the format of the Request object.

Here's a sample response to the above command:

{
   "id" : 1,
   "jsonrpc" : "2.0",
   "result" : {
      "difficulty" : "0x3ff800000",
      "extraData" : "0x476574682f76312e302e302f6c696e75782f676f312e342e32",
      "gasLimit" : "0x1388",
      "gasUsed" : "0x0",
      "hash" : "0x88e96d4537bea4d9c05d12549907b32561d3bf31f45aae734cdc119f13406cb6",
      "logsBloom": "0x0000000000000000000000000000000000000",
      "miner" : "0x05a56e2d52c817161883f50c441c3228cfe54d9f",
      "mixHash" : "0x969b900de27b6ac6a67742365dd65f55a0526c41fd18e1b16f1a1215c2e66f59",
      "nonce" : "0x539bd4979fef1ec4",
      "number" : "0x1",
      "parentHash" : "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3",
      "receiptsRoot" : "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
      "sha3Uncles" : "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
      "size" : "0x219",
      "stateRoot" : "0xd67e4d450343046425ae4271474353857ab860dbc0a1dde64b41b5cd3a532bf3",
      "timestamp" : "0x55ba4224",
      "totalDifficulty" : "0x7ff800000",
      "transactions" : [],
      "transactionsRoot" : "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
      "uncles" : []
   }
}

WebSocket

To subscribe to data feeds rather than poll for data, you can use the WebSocket API of the blockchain node's execution client.

For example, to subscribe to new chain heads:

wscat -c wss://ws.YOUR_NODES_URL?key=YOUR_API_KEY
Connected (press CTRL+C to quit)
> {"jsonrpc":"2.0", "id": 1, "method": "eth_subscribe", "params": ["newHeads"]}

The execution client will respond with an identifier for the subscription, such as:

{"jsonrpc":"2.0","id":1,"result":"0xf47df962ae9ba250ba9e9fb239b6894f"}

Thereafter the client will send details of each new chain head block as it occurs. Here's a sample event from the above subscription:

{
   "jsonrpc" : "2.0",
   "method" : "eth_subscription",
   "params" : {
      "result" : {
         "baseFeePerGas" : "0x4bdc620b8",
         "difficulty" : "0x0",
         "extraData" : "0x496c6c756d696e61746520446d6f63726174697a6520447374726962757465",
         "gasLimit" : "0x1c9c380",
         "gasUsed" : "0xe24dae",
         "hash" : "0xbde840749c4d9086d17d66079d5f7d3d568ed4572329691e5b4a70f44a551816",
         "logsBloom": "0x0000000000000000000000000000000000000",
         "miner" : "0xb4c9e4617a16be36b92689b9e07e9f64757c1792",
         "mixHash" : "0xf68eb0b3ec50e1543de1cc7f09c7735ba20fa252124511756857078a3ff9a7cf",
         "nonce" : "0x0000000000000000",
         "number" : "0x109e280",
         "parentHash" : "0x54f78faba9fde0d15d7a9d6b80c4569435c7fdc5f1fef3255110373b66ce14de",
         "receiptsRoot" : "0x876bcb5772f8597fee4b063c57b7a51209eb428034efabf4cdf39a46901681b4",
         "sha3Uncles" : "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
         "stateRoot" : "0xfc5daf9608c8f2b9944bcfe0b9182148d85b1a6ad4dc52d3eb522dd02687c7e0",
         "timestamp" : "0x647fd287",
         "transactionsRoot" : "0x0acaef87e4609ea6075d88fdd404b3fbd25d796af9044522beefd3c708d37af8",
         "withdrawalsRoot" : "0x7adfc670253572678769e7d80db8c4c94b5d14d4e014274f39b679fdb5e72d98"
      },
      "subscription" : "0xf47df962ae9ba250ba9e9fb239b6894f"
   }
}

Metrics

Polygon nodes provide one metric on the operational state of the node. Typically this would be consumed by a tool such as Prometheus or Grafana.

To fetch the metrics exposed by a metrics endpoint you can use a command such as:

curl -H "X-goog-api-key: YOUR_API_KEY" https://YOUR_NODES_URL/debug/metrics/prometheus

Replace the following:

  • YOUR_API_KEY with the API key. For example, AIzaSyC8O2PS8hzUop1FxujvGw5x3eC6zuKbuDY.
  • YOUR_NODES_URL with the node's URL. For example, bp-mc.5baqy90l9xcxq6i262vch479a.d.blockchainnodeengine.com.

This produces an output similar to the following:

block_parallelizability {quantile="0.5"} 0
block_parallelizability {quantile="0.75"} 0
block_parallelizability {quantile="0.95"} 0
block_parallelizability {quantile="0.99"} 0
block_parallelizability {quantile="0.999"} 0
block_parallelizability {quantile="0.9999"} 0
block_parallelizability_sum 0.000000
block_parallelizability_count 6
...

Private Service Connect Port Reference Guide

Private Service Connect enabled nodes use a user generated static IP address along with the designated port to generate an endpoint. Use the appropriate mapping in the following table.

Port Type Port Number
JSON RPC API Endpoint 8545
Websocket API Endpoint 8546
Client Metrics API Endpoint 6060