API Reference

Complete reference for the pRPC API and XandScan data structures

pNode Endpoints

XandScan uses these verified pRPC endpoints:

// Active pNode endpoints (port 6000)
178.18.243.183:6000
158.220.126.109:6000
62.171.147.216:6000
152.53.45.250:6000
192.99.8.88:6000
192.99.9.233:6000
167.235.193.133:6000
147.45.231.139:6000

Data Structures

PNode Type

interface PNode {
  publicKey: string;
  moniker: string;
  ipAddress: string;
  version: string;
  status: 'active' | 'inactive' | 'syncing';
  uptime: number; // percentage (0-100)
  storage: {
    used: number; // bytes
    total: number; // bytes
    available: number; // bytes
    usagePercentage: number; // percentage (0-100)
  };
  performance: {
    avgLatency: number; // milliseconds
    successRate: number; // percentage (0-100)
    bandwidthMbps: number;
    responseTime: number; // milliseconds
    requestsPerSecond: number;
  };
  location: {
    country: string;
    countryCode: string; // ISO 3166-1 alpha-2
    city: string;
    region: string;
    lat: number;
    lng: number;
    timezone: string;
  };
  lastSeen: Date;
  stakingInfo?: {
    staked: number;
    weight: number;
    rewards: number;
    delegators: number;
  };
  healthScore: number; // calculated score (0-100)
}

NetworkStats Type

interface NetworkStats {
  totalNodes: number;
  activeNodes: number;
  inactiveNodes: number;
  syncingNodes: number;
  totalStorage: number; // bytes
  usedStorage: number; // bytes
  availableStorage: number; // bytes
  avgUptime: number; // percentage
  decentralizationScore: number; // 0-100
  networkVersion: string;
  avgLatency: number; // milliseconds
  totalBandwidth: number; // Mbps
}

NetworkHealthBreakdown Type

interface NetworkHealthBreakdown {
  availability: number; // 0-100
  versionHealth: number; // 0-100
  distribution: number; // 0-100
  storageHealth: number; // 0-100
  totalScore: number; // weighted average
}

React Query Hooks

useAllPNodes

Fetch all pNodes from the network

import { useAllPNodes } from '@/lib/hooks';

function MyComponent() {
  const {
    data: nodes,
    isLoading,
    error,
    refetch
  } = useAllPNodes();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {nodes?.map(node => (
        <div key={node.publicKey}>{node.moniker}</div>
      ))}
    </div>
  );
}

useNetworkStats

Fetch network-wide statistics

import { useNetworkStats } from '@/lib/hooks';

function Dashboard() {
  const { data: stats, isLoading } = useNetworkStats();

  return (
    <div>
      <h2>Total Nodes: {stats?.totalNodes}</h2>
      <h2>Active: {stats?.activeNodes}</h2>
      <h2>Avg Uptime: {stats?.avgUptime.toFixed(2)}%</h2>
    </div>
  );
}

usePNodeDetails

Fetch specific pNode details by public key

import { usePNodeDetails } from '@/lib/hooks';

function NodePage({ publicKey }: { publicKey: string }) {
  const { data: node, isLoading } = usePNodeDetails(publicKey);

  if (!node) return null;

  return (
    <div>
      <h1>{node.moniker}</h1>
      <p>Uptime: {node.uptime}%</p>
      <p>Location: {node.location.city}, {node.location.country}</p>
    </div>
  );
}

Direct PNodeClient Usage

For advanced use cases, use PNodeClient directly:

import { getPNodeClient } from '@/lib/pnode-client';

async function fetchCustomData() {
  const client = getPNodeClient();

  // Get all nodes
  const nodes = await client.getAllPNodes();

  // Get network stats
  const stats = await client.getNetworkStats();

  // Get specific node
  const node = await client.getPNodeDetails('publicKey123');

  return { nodes, stats, node };
}

Health Score Calculation

Calculate network health breakdown:

import { calculateNetworkHealth } from '@/lib/intelligence';

const healthBreakdown = calculateNetworkHealth(stats, nodes);

// Returns:
// {
//   availability: 95.2,
//   versionHealth: 87.5,
//   distribution: 78.3,
//   storageHealth: 82.1,
//   totalScore: 87
// }

Data Export Functions

import {
  exportNodesCSV,
  exportNodesJSON,
  exportNetworkStatsCSV,
  exportNetworkStatsJSON
} from '@/lib/export';

// Export nodes to CSV
exportNodesCSV(nodes, 'xandscan-nodes.csv');

// Export nodes to JSON
exportNodesJSON(nodes, 'xandscan-nodes.json');

// Export network stats
exportNetworkStatsCSV(stats, nodes, 'network-stats.csv');
exportNetworkStatsJSON(stats, nodes, 'network-stats.json');

Error Handling

React Query provides built-in error handling:

const { data, error, isError, isLoading } = useAllPNodes();

if (isError) {
  console.error('Failed to fetch nodes:', error);

  // Error types:
  // - Network errors (timeout, connection refused)
  // - pRPC errors (invalid response, parse errors)
  // - Circuit breaker (all endpoints failed)
}

Next Steps

• • Review Integration Guide for practical examples
• • Check Architecture for system design
• • See Metrics Guide for scoring formulas