net_listening | IoTeX RPC Docs

Check the legacy net_listening compatibility method on IoTeX. Public endpoints may return a boolean or an unsupported-method response depending on the client.

Checks whether the connected IoTeX client reports that its P2P networking layer is listening for peers. Depending on the client behind the endpoint, this call may return true, false, or an unsupported-method error.

Why IoTeX? Build on the leading DePIN infrastructure blockchain powering 130+ applications in the $27B+ DePIN ecosystem with W3bstream offchain compute, Quicksilver AI data verification, Vodafone partnership for 5M+ cell tower integration, and ioID device identity.

When to Use This Method

net_listening is useful for DePIN builders, IoT device manufacturers, and real-world AI application developers:

P2P Diagnostics — Check whether the connected client exposes peer-listening state at all
Client Capability Checks — Distinguish between boolean responses and unsupported-method errors across different node clients
Peer-Network Troubleshooting — Combine with net_peerCount and eth_syncing when investigating peer discovery or sync issues
Operational Audits — Confirm what the endpoint reports before wiring it into monitoring or dashboards

Code Examples

Common Use Cases

1. Capability-Aware Peer Diagnostic

Combine net_listening with other status methods, but treat unsupported responses as normal:

JavaScript

async function getPeerDiagnostic(provider) {
  const [peerCountHex, syncing] = await Promise.all([
    provider.send('net_peerCount', []),
    provider.send('eth_syncing', [])
  ]);

  let listening = { supported: false };
  try {
    listening = { supported: true, value: await provider.send('net_listening', []) };
  } catch (error) {
    listening = { supported: false, message: error.message };
  }

  const peerCount = parseInt(peerCountHex, 16);
  return {
    listening,
    peerCount,
    synced: syncing === false
  };
}

2. Fallback-Friendly Check

JavaScript

async function readListeningStatus(provider) {
  try {
    return { supported: true, value: await provider.send('net_listening', []) };
  } catch (error) {
    return { supported: false, message: error.message };
  }
}

3. Multi-Node Fleet Monitor

Check which endpoints expose net_listening and what they report:

Python

import requests
from concurrent.futures import ThreadPoolExecutor

def check_fleet_listening(endpoints):
    def check_node(endpoint):
        try:
            response = requests.post(
                endpoint,
                json={'jsonrpc': '2.0', 'method': 'net_listening', 'params': [], 'id': 1},
                timeout=5
            )
            payload = response.json()
            if 'error' in payload:
                return {'endpoint': endpoint, 'supported': False, 'error': payload['error']['message']}
            return {'endpoint': endpoint, 'supported': True, 'listening': payload.get('result', False)}
        except Exception as e:
            return {'endpoint': endpoint, 'supported': False, 'error': str(e)}

    with ThreadPoolExecutor(max_workers=10) as executor:
        results = list(executor.map(check_node, endpoints))

    supported = [r for r in results if r.get('supported')]
    unsupported = [r for r in results if not r.get('supported')]

    print(f'{len(supported)}/{len(results)} endpoints expose net_listening')
    for node in unsupported:
        print(f'  UNSUPPORTED: {node["endpoint"]} — {node.get("error", "not available")}')

    return results

Error Handling

Error Code	Description	Solution
-32601	Method not found	The connected client may not expose this legacy method
-32603	Internal error	Some clients surface unsupported compatibility methods through a generic internal-error path
-32005	Rate limit exceeded	Reduce polling frequency or implement backoff
Connection refused	Cannot connect	The RPC endpoint may be unavailable — check endpoint health separately

net_peerCount — Get number of connected peers
net_version — Get the network ID
eth_syncing — Check node sync progress
web3_clientVersion — Get node client info

net_listening - IoTeX RPC Method