Network Statistics

The /ws/stats endpoint streams a comprehensive snapshot of MultiversX network state every 250ms. It is a read-only, push-only stream — no subscribe action required. Connect and data arrives immediately.

---

Connection

const ws = new WebSocket('wss://relayer.xoxno.com/ws/stats');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // msg.type === 'networkStats'
  console.log(msg);
};

This endpoint operates independently of the main /ws endpoint. Connect to both simultaneously when your application needs subscription-based topics alongside the network stats stream.

---

Message Schema

{
  "type": "networkStats",
  "schemaVersion": "1.1.0",
  "sequence": 1,
  "ts": 1738800000000,
  "data": {
    "network": {
      "currentTps": 2500,
      "avgTps10s": 2400,
      "avgTps30s": 2350,
      "connectedPeers": 450,
      "activeValidators": 32,
      "wsLagMs": 25
    },
    "blocks": {
      "latestShard": {
        "shardId": 0,
        "nonce": 54321,
        "round": 12345,
        "epoch": 678,
        "txCount": 5000,
        "executedTxCount": 4950,
        "timestampMs": 1738800000000,
        "leaderSignatureHex": "0x...",
        "accumulatedFees": "1234567890000000000",
        "developerFees": "123456789000000000"
      },
      "latestMeta": {
        "nonce": 54321,
        "round": 12345,
        "epoch": 678,
        "txCount": 15000,
        "executedTxCount": 14850,
        "timestampMs": 1738800000000
      },
      "blockTimeMsP50ByShard": {
        "0": 6250,
        "1": 6200,
        "2": 6300
      },
      "nonceGapEvents1m": 0,
      "duplicateNonceEvents1m": 0
    },
    "mempool": {
      "estimatedQueue": 500,
      "ingressTps": 3000,
      "inclusionTps": 2500,
      "pressure": 0.167
    },
    "validators": {
      "onlineByShard": {
        "0": 11,
        "1": 11,
        "2": 10,
        "meta": 0
      },
      "totalOnline": 32,
      "heartbeatRatePerSec": 0.53
    },
    "health": {
      "p2pDedupRatio1m": 0.02,
      "streamSubscribers": 45,
      "dataCompleteness": 0.95
    }
  }
}

---

Field Descriptions

Top-Level Envelope

Field	Type	Description
type	string	Always "networkStats"
schemaVersion	string	Semantic version of the message schema. See Schema Versioning.
sequence	number	Monotonically increasing counter per connection. Use to detect missed messages.
ts	number	Server timestamp in milliseconds (Unix epoch) when the snapshot was assembled
data	object	Network state payload

data.network

Field	Type	Description
currentTps	number	Transactions per second executed in the most recent block across all shards
avgTps10s	number	Rolling average TPS over the last 10 seconds
avgTps30s	number	Rolling average TPS over the last 30 seconds
connectedPeers	number	Total P2P peers connected to the relayer node
activeValidators	number	Number of validators actively participating in consensus
wsLagMs	number	Internal propagation latency from block observation to WebSocket delivery, in milliseconds

data.blocks.latestShard

The most recent finalized shard block observed by the relayer.

Field	Type	Description
shardId	number	Shard identifier of the block
nonce	number	Block nonce (height)
round	number	Consensus round number
epoch	number	Epoch number
txCount	number	Total transactions included in the block
executedTxCount	number	Transactions successfully executed (excludes failed/invalid)
timestampMs	number	Block timestamp in milliseconds
leaderSignatureHex	string	Hex-encoded signature of the block proposer
accumulatedFees	string	Total transaction fees collected in atomic EGLD units
developerFees	string	Developer fee portion of accumulated fees in atomic EGLD units

data.blocks.latestMeta

The most recent finalized metachain block. Fields are the same as latestShard but without leaderSignatureHex, accumulatedFees, and developerFees.

data.blocks (additional)

Field	Type	Description
blockTimeMsP50ByShard	object	Median block time in milliseconds for each shard over the last 60 seconds. Keys are "0", "1", "2".
nonceGapEvents1m	number	Number of times a shard block nonce was skipped (missed block) in the last minute. Non-zero values indicate validator issues.
duplicateNonceEvents1m	number	Number of duplicate block nonce events in the last minute. Indicates a fork or consensus anomaly.

data.mempool

Field	Type	Description
estimatedQueue	number	Estimated number of transactions currently waiting for inclusion across all shards
ingressTps	number	Rate at which new transactions are arriving at the relayer (transactions per second)
inclusionTps	number	Rate at which transactions are being included in blocks (transactions per second)
pressure	number	Ratio of queue growth to inclusion rate: (ingressTps - inclusionTps) / ingressTps. Values approaching 1.0 indicate the network is falling behind.

data.validators

Field	Type	Description
onlineByShard	object	Count of online validators per shard. Keys: "0", "1", "2", "meta".
totalOnline	number	Sum of all online validators across shards
heartbeatRatePerSec	number	Average rate of validator heartbeat messages received per second

data.health

Field	Type	Description
p2pDedupRatio1m	number	Fraction of P2P gossip messages that were duplicates in the last minute. High values indicate gossip amplification or topology issues.
streamSubscribers	number	Current number of clients connected to the /ws/stats stream
dataCompleteness	number	Fraction of expected data fields populated in this snapshot (0.0–1.0). Values below 1.0 indicate partial data due to a slow upstream source.

---

Schema Versioning

The schemaVersion field uses semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR increments on breaking changes (field removals, type changes, structural reorganization).

• MINOR increments when new fields are added in a backward-compatible way.

• PATCH increments for documentation or metadata corrections.

Check schemaVersion on connection and log a warning if the major version exceeds what your client expects. New minor-version fields appear as null or are absent on older relayer deployments.

The current schema version is 1.1.0. Check schemaVersion in your client and alert when it changes to avoid silent breakage.

---

Example: Network Dashboard

class NetworkDashboard {
  constructor() {
    this.latest = null;
    this.sequence = 0;
    this.connect();
  }

  connect() {
    this.ws = new WebSocket('wss://relayer.xoxno.com/ws/stats');

    this.ws.onmessage = (event) => {
      const msg = JSON.parse(event.data);
      if (msg.type !== 'networkStats') return;

      // Detect missed messages
      if (this.sequence > 0 && msg.sequence !== this.sequence + 1) {
        console.warn(`Sequence gap: expected ${this.sequence + 1}, got ${msg.sequence}`);
      }
      this.sequence = msg.sequence;
      this.latest = msg;
      this.render(msg);
    };

    this.ws.onclose = () => {
      console.log('Stats stream closed, reconnecting in 2s');
      setTimeout(() => this.connect(), 2000);
    };
  }

  render(msg) {
    const { network, blocks, mempool, validators, health } = msg.data;

    console.log('--- Network Stats ---');
    console.log(`TPS: ${network.currentTps} (10s avg: ${network.avgTps10s})`);
    console.log(`Peers: ${network.connectedPeers} | Validators: ${validators.totalOnline}`);
    console.log(`Mempool queue: ${mempool.estimatedQueue} | Pressure: ${(mempool.pressure * 100).toFixed(1)}%`);
    console.log(`Latest shard block: #${blocks.latestShard.nonce} (shard ${blocks.latestShard.shardId})`);
    console.log(`Data completeness: ${(health.dataCompleteness * 100).toFixed(0)}%`);
    console.log(`WS lag: ${network.wsLagMs}ms`);
  }

  isHealthy() {
    if (!this.latest) return false;
    const { health, blocks } = this.latest.data;
    return (
      health.dataCompleteness >= 0.95 &&
      blocks.nonceGapEvents1m === 0 &&
      blocks.duplicateNonceEvents1m === 0
    );
  }

  getMempoolPressure() {
    return this.latest?.data.mempool.pressure ?? 0;
  }
}

const dashboard = new NetworkDashboard();

---

Use Cases

• Real-time dashboards — Display TPS, validator count, block times, and mempool depth.

• Mempool monitoring — Track mempool.pressure to detect backlog buildup and delay non-urgent transactions.

• Validator health alerting — Alert when nonceGapEvents1m > 0 or duplicateNonceEvents1m > 0.

• Transaction timing — Submit transactions when mempool.pressure is low for faster inclusion.

• Relayer health monitoring — Use health.dataCompleteness and health.p2pDedupRatio1m to verify data feed quality.

• Block time SLAs — Use blockTimeMsP50ByShard to confirm shards are producing blocks within expected intervals.

---

Related Pages

• Gas Statistics — Per-shard gas price and PPU

• Account Subscriptions — Address-level balance and nonce updates

• Error Reference — WebSocket error codes