Skip to main content

Consuming SSE Events

This guide shows you how to connect to Surflux Server-Sent Events streams and handle incoming events in your application.

Browser​

The EventSource API is built into all modern browsers:

const eventSource = new EventSource(
  'https://flux.surflux.dev/events?api-key=YOUR_API_KEY'
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

eventSource.onerror = (error) => {
  console.error('Connection error:', error);
};

Node.js​

Install the eventsource package:

npm install eventsource

Use it in your application:

import EventSource from 'eventsource';

const eventSource = new EventSource(
  'https://flux.surflux.dev/events?api-key=YOUR_API_KEY'
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

eventSource.onerror = (error) => {
  console.error('Connection error:', error);
};

Filtering Events​

The SSE stream includes all events. Filter for the ones you need on the client side:

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  // Filter for specific package events
  if (data.type === 'package_event' &&
      data.data.event_type.includes('0x123abc::nft::MintEvent')) {
    console.log('NFT minted:', data.data.contents);
  }

  // Filter for specific address activity
  if (data.type === 'address_update' &&
      data.data.address === '0x456def...') {
    console.log('Address activity:', data.data);
  }

  // Filter for DeepBook trades
  if (data.type === 'deepbook_live_trades') {
    console.log('Trade executed:', data.data);
  }
};

Resuming from Last Event​

Use the last-id parameter to resume from where you left off:

let lastEventId: string | null = null;

const url = new URL('https://flux.surflux.dev/events');
url.searchParams.set('api-key', 'YOUR_API_KEY');

if (lastEventId) {
  url.searchParams.set('last-id', lastEventId);
}

const eventSource = new EventSource(url.toString());

eventSource.onmessage = (event) => {
  lastEventId = event.lastEventId;
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

Handling Different Event Types​

Process events based on their type:

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'package_event':
      console.log('Package event:', data.data.event_type);
      console.log('Contents:', data.data.contents);
      break;
    case 'address_update':
      console.log('Address update:', data.data.address);
      console.log('New object:', data.data.new_object);
      break;
    case 'object_change':
      console.log('Object changed:', data.data.object_id);
      break;
    case 'deepbook_live_trades':
      console.log('Trade:', data.data.price, data.data.base_quantity);
      break;
    case 'deepbook_order_book_depth':
      console.log('Order book update:', data.data.pool_id);
      break;
  }
};

Connection Management​

Handle reconnections and cleanup:

let eventSource: EventSource | null = null;

function connect() {
  eventSource = new EventSource(
    'https://flux.surflux.dev/events?api-key=YOUR_API_KEY'
  );

  eventSource.onopen = () => {
    console.log('Connected');
  };

  eventSource.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Received:', data);
  };

  eventSource.onerror = (error) => {
    console.error('Connection error:', error);
    eventSource?.close();

    // Reconnect after 5 seconds
    setTimeout(connect, 5000);
  };
}

function disconnect() {
  eventSource?.close();
  eventSource = null;
}

// Start connection
connect();

// Clean up on exit
process.on('SIGINT', disconnect);

Next Steps​