system_health | Acala RPC Docs

Check node health status on Acala. Returns peer count, sync status, and connectivity — essential for monitoring, load balancing, and infrastructure management on Polkadot's DeFi and liquidity hub with aUSD stablecoin and liquid staking (LDOT).

Returns the health status of the Acala node, including peer count, sync state, and whether the node expects to have peers.

Why Acala? Build on Polkadot's DeFi and liquidity hub with aUSD stablecoin and liquid staking (LDOT) with $250M aUSD ecosystem fund, 150%+ LDOT TVL growth, micro gas fees payable in any token, and Coinbase Cloud partnership.

When to Use This Method

system_health is essential for DeFi developers, stablecoin builders, and teams requiring cross-chain liquidity:

Health Checks — Monitor node availability and readiness before routing traffic on Acala
Load Balancing — Route requests only to healthy, fully synced nodes for decentralized stablecoin (aUSD), liquid DOT staking (LDOT), and cross-chain AMM DEX
Sync Status — Verify a node is caught up before trusting its state queries
Infrastructure Alerts — Trigger alerts when peers drop or sync stalls

Code Examples

Common Use Cases

1. Readiness Probe for Kubernetes

Use as a health check endpoint for container orchestration on Acala:

JavaScript

import express from 'express';
import { ApiPromise, WsProvider } from '@polkadot/api';

const app = express();
const provider = new WsProvider('wss://api-acala.n.dwellir.com/YOUR_API_KEY');
const api = await ApiPromise.create({ provider });

app.get('/healthz', async (req, res) => {
  try {
    const health = await api.rpc.system.health();
    const isReady = !health.isSyncing.isTrue && health.peers.toNumber() > 0;

    if (isReady) {
      res.status(200).json({ status: 'healthy', peers: health.peers.toNumber() });
    } else {
      res.status(503).json({
        status: 'not ready',
        syncing: health.isSyncing.isTrue,
        peers: health.peers.toNumber()
      });
    }
  } catch (error) {
    res.status(503).json({ status: 'unreachable', error: error.message });
  }
});

2. Multi-Node Load Balancer

Route traffic only to healthy Acala nodes:

JavaScript

async function selectHealthyNode(endpoints) {
  const results = await Promise.allSettled(
    endpoints.map(async (endpoint) => {
      const response = await fetch(endpoint, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          jsonrpc: '2.0',
          method: 'system_health',
          params: [],
          id: 1
        })
      });

      const { result } = await response.json();
      return { endpoint, ...result };
    })
  );

  const healthy = results
    .filter(r => r.status === 'fulfilled' && !r.value.isSyncing)
    .map(r => r.value)
    .sort((a, b) => b.peers - a.peers);

  return healthy.length > 0 ? healthy[0].endpoint : null;
}

3. Continuous Health Monitor

Periodically check node health and alert on degradation:

Python

import requests
import time

def monitor_health(endpoint, interval=30, min_peers=5):
    while True:
        try:
            payload = {
                'jsonrpc': '2.0',
                'method': 'system_health',
                'params': [],
                'id': 1
            }

            response = requests.post(endpoint, json=payload, timeout=5)
            health = response.json()['result']

            peers = health['peers']
            syncing = health['isSyncing']

            if syncing:
                print(f'WARNING: Node is syncing (peers: {peers})')
            elif peers < min_peers:
                print(f'WARNING: Low peer count: {peers}')
            else:
                print(f'OK: peers={peers}, syncing={syncing}')

        except Exception as e:
            print(f'ERROR: Node unreachable — {e}')

        time.sleep(interval)

monitor_health('https://api-acala.n.dwellir.com/YOUR_API_KEY')

Error Handling

Error Code	Description	Solution
-32603	Internal error	Node may be starting up — retry after delay
-32601	Method not found	Verify the node exposes the `system` RPC module
HTTP 429 / -32029	Rate limit exceeded	Reduce polling frequency and retry with backoff
Connection refused	Node is down	Check node process and network connectivity

system_version — Get node software version
system_chain — Get chain name
system_syncState — Get detailed sync progress
system_peers — Get detailed peer information

system_health - Acala RPC Method