getClusterNodes

Learn getClusterNodes use cases, code examples, request parameters, response structure, and tips.

The getClusterNodes RPC method returns a list of all known nodes currently participating in the Solana cluster, as seen from the perspective of the RPC node you’re querying. This is a valuable tool for network discovery, cluster diagnostics, and understanding node connectivity.

---

✅ Common Use Cases

• Network Topology Mapping Get a real-time view of the nodes active in the cluster, including their identity keys and network endpoints.

• Discover RPC Endpoints Identify nodes that advertise public RPC interfaces, which may be used as alternative access points (availability and rate limits may vary).

• Monitor Node Versions Observe software version distribution across cluster participants for insights into network upgrade progress or compatibility.

---

🛠 Request Parameters

This method does not accept any parameters.

---

📦 Response Structure

The result will be an array of objects, each representing a node and containing the following fields:

Field	Type	Description
pubkey	string	Base58-encoded public key (identity) of the node.
gossip	string | null	Gossip address used for cluster communication.
tpu	string | null	TPU (Transaction Processing Unit) address used for submitting transactions.
rpc	string | null	JSON-RPC endpoint address if advertised.
version	string | null	Software version reported by the node.
featureSet	u32 | null	Identifier of the node’s current feature set.
shredVersion	u16 | null	Shred version used by the node (affects data encoding).

Code Examples

Nodejs

const fetch = require('node-fetch');

async function getClusterNodes(rpcUrl) {
  try {
    const response = await fetch(rpcUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: 1,
        method: 'getClusterNodes'
      }),
    });

    const data = await response.json();
    
    // Print the exact full response
    console.log('Full RPC Response:');
    console.log(JSON.stringify(data, null, 2));
    
    return data;
  } catch (error) {
    console.error('Error getting health:', error.message);
    return null;
  }
}

// Example usage
const RPC_URL = 'https://rpc.coinvera.io/?x-api-key=your-coinvera-x-api-key';

getClusterNodes(RPC_URL);

Python

import requests
import json

def get_cluster_nodes(rpc_url):
    try:
        response = requests.post(
            rpc_url,
            headers={
                'Content-Type': 'application/json',
            },
            json={
                'jsonrpc': '2.0',
                'id': 1,
                'method': 'getClusterNodes'
            }
        )
        
        data = response.json()
        
        # Print the exact full response
        print('Full RPC Response:')
        print(json.dumps(data, indent=2))
        
        return data
        
    except Exception as error:
        print(f'Error getting health: {error}')
        return None

# Example usage
RPC_URL = 'https://rpc.coinvera.io/?x-api-key=your-coinvera-x-api-key'
get_cluster_nodes(RPC_URL)

Example Response

    {
      "featureSet": 3073396398,
      "gossip": "5.199.165.12:8000",
      "pubkey": "GK1dUWJJhk62z7ZKQFuLq4xuNvKJoJW7GvijsdWQLxw6",
      "pubsub": null,
      "rpc": null,
      "serveRepair": "5.199.165.12:8012",
      "shredVersion": 50093,
      "tpu": "5.199.165.12:8003",
      "tpuForwards": "5.199.165.12:8004",
      "tpuForwardsQuic": "5.199.165.12:8010",
      "tpuQuic": "5.199.165.12:8009",
      "tpuVote": "5.199.165.12:8005",
      "tvu": "5.199.165.12:8001",
      "version": "2.2.19"
    },
    {
      "featureSet": 3073396398,
      "gossip": "185.209.178.131:8001",
      "pubkey": "EmhoLGAXDEguKMqAGxNzgy6LGXe5jvmD1az7whhDKnB7",
      "pubsub": null,
      "rpc": null,
      "serveRepair": "185.209.178.131:8013",
      "shredVersion": 50093,
      "tpu": "185.209.178.131:8004",
      "tpuForwards": "185.209.178.131:8005",
      "tpuForwardsQuic": "185.209.178.131:8011",
      "tpuQuic": "185.209.178.131:8010",
      "tpuVote": "185.209.178.131:8006",
      "tvu": "185.209.178.131:8002",
      "version": "2.2.20"
    }

🧠 Developer Tips

• Results Depend on Node Perspective The node list reflects what the queried RPC node sees. Different RPC providers (e.g., CoinVera) may have slightly different views of the cluster due to synchronization state or network partitions.

• RPC Field Is Optional Not all nodes expose their RPC endpoint. Even if the rpc field is present, the endpoint may be unavailable or restricted.

• Expect Dynamic Results The cluster is constantly changing—nodes join, leave, or restart frequently. Always treat this list as real-time and transient.

• Large Output on Mainnet On Solana Mainnet Beta, the response can include hundreds or even thousands of nodes. Be prepared to paginate, filter, or cache results for performance.