Account Subscriptions

Subscribe to real-time updates for specific blockchain addresses. Receive notifications when account balances change or nonces are updated.

Subscribe

ws.send(JSON.stringify({
  action: 'subscribe',
  topic: 'address/erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th'
}));

Topic Format

address/{bech32_address}

The address must be a valid MultiversX bech32 address starting with erd1.

Subscription Confirmation

{
  "action": "subscribe",
  "status": "ok",
  "topic": "address/erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th"
}

Account Update Events

When an account's state changes, you receive an update:

{
  "topic": "address/erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th",
  "type": "accountDelta",
  "data": {
    "address": "erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th",
    "nonce": 42,
    "shardId": 1,
    "balances": [
      {
        "token": "EGLD",
        "balance": "5000000000000000000"
      },
      {
        "token": "USDC-c76f1f",
        "balance": "150000000"
      }
    ]
  }
}

Response Fields

Field	Type	Description
topic	string	The subscribed topic
type	string	Event type (accountDelta)
data.address	string	The account address
data.nonce	number	Current account nonce
data.shardId	number	Shard where account resides
data.balances	array	Changed token balances

Balance Object

Field	Type	Description
token	string	Token identifier or "EGLD"
balance	string	Current balance in atomic units

Use Cases

Wallet Balance Monitoring

class WalletMonitor {
  constructor(wsUrl) {
    this.ws = new WebSocket(wsUrl);
    this.balances = new Map();
    this.nonce = 0;
    
    this.ws.onmessage = (event) => {
      const msg = JSON.parse(event.data);
      if (msg.type === 'accountDelta') {
        this.handleUpdate(msg.data);
      }
    };
  }

  subscribe(address) {
    this.ws.send(JSON.stringify({
      action: 'subscribe',
      topic: `address/${address}`
    }));
  }

  handleUpdate(data) {
    // Update nonce
    this.nonce = data.nonce;
    
    // Update balances
    for (const balance of data.balances) {
      const previous = this.balances.get(balance.token) || '0';
      this.balances.set(balance.token, balance.balance);
      
      // Emit change event
      this.onBalanceChange?.(balance.token, previous, balance.balance);
    }
    
    // Emit nonce update
    this.onNonceChange?.(data.nonce);
  }

  getBalance(token) {
    return this.balances.get(token) || '0';
  }

  getNonce() {
    return this.nonce;
  }
}

// Usage
const monitor = new WalletMonitor('wss://relayer.xoxno.com/ws');

monitor.onBalanceChange = (token, previous, current) => {
  const diff = BigInt(current) - BigInt(previous);
  console.log(`${token}: ${diff > 0 ? '+' : ''}${diff}`);
};

monitor.ws.onopen = () => {
  monitor.subscribe('erd1...');
};

Transaction Confirmation Detection

class TxConfirmationWatcher {
  constructor(wsUrl, address) {
    this.ws = new WebSocket(wsUrl);
    this.address = address;
    this.expectedNonce = null;
    this.resolvers = new Map();
    
    this.ws.onopen = () => {
      this.ws.send(JSON.stringify({
        action: 'subscribe',
        topic: `address/${address}`
      }));
    };
    
    this.ws.onmessage = (event) => {
      const msg = JSON.parse(event.data);
      if (msg.type === 'accountDelta') {
        this.checkConfirmations(msg.data.nonce);
      }
    };
  }

  waitForNonce(nonce, timeout = 60000) {
    return new Promise((resolve, reject) => {
      const timer = setTimeout(() => {
        this.resolvers.delete(nonce);
        reject(new Error('Transaction confirmation timeout'));
      }, timeout);
      
      this.resolvers.set(nonce, { resolve, timer });
    });
  }

  checkConfirmations(currentNonce) {
    // Resolve all waiters for nonces that have been confirmed
    for (const [nonce, { resolve, timer }] of this.resolvers) {
      if (currentNonce >= nonce) {
        clearTimeout(timer);
        resolve(currentNonce);
        this.resolvers.delete(nonce);
      }
    }
  }

  async waitForTransaction(txNonce) {
    return this.waitForNonce(txNonce + 1);
  }
}

// Usage
const watcher = new TxConfirmationWatcher('wss://relayer.xoxno.com/ws', userAddress);

// Submit transaction with nonce 42
const tx = await submitTransaction(signedTx);

// Wait for confirmation
await watcher.waitForTransaction(42);
console.log('Transaction confirmed!');

Portfolio Tracker

class PortfolioTracker {
  constructor(wsUrl, addresses) {
    this.ws = new WebSocket(wsUrl);
    this.portfolios = new Map();
    
    this.ws.onopen = () => {
      // Subscribe to all addresses
      for (const address of addresses) {
        this.portfolios.set(address, new Map());
        this.ws.send(JSON.stringify({
          action: 'subscribe',
          topic: `address/${address}`
        }));
      }
    };
    
    this.ws.onmessage = (event) => {
      const msg = JSON.parse(event.data);
      if (msg.type === 'accountDelta') {
        this.updatePortfolio(msg.data);
      }
    };
  }

  updatePortfolio(data) {
    const portfolio = this.portfolios.get(data.address);
    if (!portfolio) return;
    
    for (const balance of data.balances) {
      portfolio.set(balance.token, balance.balance);
    }
    
    this.onUpdate?.(data.address, portfolio);
  }

  getTotalValue(address) {
    const portfolio = this.portfolios.get(address);
    if (!portfolio) return {};
    
    return Object.fromEntries(portfolio);
  }
}

Multiple Subscriptions

You can subscribe to multiple addresses on the same connection:

const addresses = [
  'erd1abc...',
  'erd1def...',
  'erd1ghi...'
];

ws.onopen = () => {
  for (const address of addresses) {
    ws.send(JSON.stringify({
      action: 'subscribe',
      topic: `address/${address}`
    }));
  }
};

Unsubscribe

ws.send(JSON.stringify({
  action: 'unsubscribe',
  topic: 'address/erd1qyu5wthldzr8wx5c9ucg8kjagg0jfs53s8nr3zpz3hypefsdd8ssycr6th'
}));

Error Handling

Invalid Address

{
  "action": "subscribe",
  "status": "fail",
  "reason": "invalid bech32 address in topic"
}

Topic Limit Reached

{
  "action": "subscribe",
  "status": "fail",
  "reason": "topic limit reached"
}

Each connection can subscribe to a maximum of 100 topics. Unsubscribe from unused addresses to stay within limits.

Best Practices

1. Reuse connections - Subscribe to multiple addresses on one WebSocket

2. Handle reconnection - Re-subscribe to all topics after reconnecting

3. Validate addresses - Verify bech32 format before subscribing

4. Clean up - Unsubscribe when addresses are no longer needed