@totemsdk/realtime

Live balance streaming with graceful HTTP fallback.

Maintains a persistent WebSocket connection to the Axia balance streaming endpoint with auto-reconnect, exponential backoff, and a TTL cache so your UI always has something to show even while reconnecting.

Install

npm install @totemsdk/realtime

What's inside

| Export | What it does | |--------|-------------| | MegBalanceStreamManager | WebSocket client with auto-reconnect and connection state tracking | | BalanceCache | TTL-based persistent balance cache with configurable storage adapters | | BalanceUpdateEvent | Typed event payload for live balance changes | | TxConfirmationEvent | Typed event payload for transaction confirmations |

HTTP fallback: a balance/snapshot JSON-RPC endpoint (total, confirmed, unconfirmed) is available for environments where WebSocket is restricted.

Usage

Subscribe to live balance updates

import { MegBalanceStreamManager } from '@totemsdk/realtime';

const manager = new MegBalanceStreamManager({
  wsUrl: 'wss://api.axia.to/v1/wallet/balance/ws',
  address: 'Mx...',
  projectId: 'your-project-id',
});

manager.on('balance', (event: BalanceUpdateEvent) => {
  console.log('Confirmed:', event.confirmed);
  console.log('Unconfirmed:', event.unconfirmed);
});

manager.on('tx', (event: TxConfirmationEvent) => {
  console.log('New tx confirmed:', event.txpowid);
});

manager.on('state', (state) => {
  console.log('Connection state:', state); // 'connecting' | 'connected' | 'reconnecting' | 'closed'
});

manager.start();

// Later
manager.stop();

Cache with fallback

import { BalanceCache, MegBalanceStreamManager } from '@totemsdk/realtime';

const cache = new BalanceCache(storageAdapter, { ttlMs: 30_000 });
const manager = new MegBalanceStreamManager({ ..., cache });

// Cache is populated automatically; read from it directly
const cached = await cache.get('Mx...');
if (cached) {
  renderBalance(cached);
}

See also

• @totemsdk/core — base adapters used by the cache
• @totemsdk/connect — the extension's built-in balance stream for dApps
• @totemsdk/lookup-client — alternative balance source via personal lookup node