WebSocket events

Use WebSocket events to refresh an interface when the node processes a block. Use RPC to recover state after a disconnect and to check an operation's outcome. The event stream has no replay or delivery guarantee.

Connect and subscribe

Enable the listener with --websocket. Its default address is ws://127.0.0.1:7078/ws. For a browser served over HTTPS, expose it through a properly secured wss:// endpoint.

This browser example logs confirmations for all accounts:

const socket = new WebSocket('ws://127.0.0.1:7078/ws');
socket.addEventListener('open', () => {
  socket.send(JSON.stringify({ action: 'subscribe', topic: 'confirmation' }));
});
socket.addEventListener('message', ({ data }) => {
  const message = JSON.parse(data);
  if (message.topic === 'confirmation') {
    console.log(message.data.block_hash, message.data.account);
  } else if (message.type === 'error') {
    console.error(message.message);
  }
});

The server acknowledges the subscription:

{"type":"ack","action":"subscribe","topic":"confirmation"}

To restrict it to an account, add a filter containing real BURST addresses:

{"action":"subscribe","topic":"confirmation","filter":{"accounts":["YOUR_ACCOUNT_ADDRESS"]}}

The filter matches the block's data.account. It does not match every participant in a payment: filtering for a recipient will not capture a sender's block merely because it pays that recipient. Omit accounts for all accounts; an empty array matches none. Subscribing again replaces the existing filter for that topic. Block-type and minimum-amount filters are not supported.

Event fields

Events have topic, data and timestamp at the top level. They do not have the type field used by acknowledgments. This is an illustrative confirmation event; the address and hash are placeholders:

{
  "topic": "confirmation",
  "data": {
    "account": "ACCOUNT_ADDRESS",
    "block_hash": "BLOCK_HASH",
    "amount": "2000000000000000000"
  },
  "timestamp": 1700000000
}

amount is the block's TRST balance, not the amount transferred. Preserve it as an integer string. timestamp is the publisher's Unix time in seconds, not the signed block timestamp.

Topic	When it is sent	Data fields
confirmation	The node cements a block as confirmed.	account, block_hash, amount
account_update	The node accepts a block, before confirmation.	account, balance, change_type
governance	No node lifecycle publisher is connected yet.	Do not rely on it.
verification	No node lifecycle publisher is connected yet.	Do not rely on it.

Treat account_update as provisional. For a payment notification, confirm the specific block and inspect its operation; do not infer a payment from a changed balance alone.

Reconnect and reconcile

On each new connection, subscribe again and query account state through RPC. Also refresh periodically while connected: a slow consumer can miss messages without receiving a gap notification. Track submitted actions by their block hashes, not by whether an event arrived.

To unsubscribe or check that the connection responds:

{"action":"unsubscribe","topic":"confirmation"}

{"action":"ping"}

A ping returns {"type":"pong"}. Listener limits and deployment settings are documented under RPC and networking.

Source: subscription messages and filters, event payloads, node publishers.