Skip to main content

DeepBook Margin Flux Stream

The DeepBook Margin Flux Stream delivers real-time margin trading events directly from DeepBook Margin on Sui. Stream loan updates, manager events, deposits, withdrawals, and liquidations as they occur on-chain with sub-second latency.

Unlike the DeepBook Margin Indexing API which provides historical snapshots, Flux Streams push live events as they occur—no polling, no delays.

What You Can Build​

DeepBook Margin Flux Streams power real-time DeFi applications:

  • Risk Monitoring Dashboards — Track position health and liquidation risk in real-time
  • Liquidation Bots — Detect at-risk positions instantly for liquidation opportunities
  • Portfolio Trackers — Monitor deposits, withdrawals, and loan changes live
  • Lending Analytics — Stream borrow and repay events for real-time metrics
  • Alert Systems — Trigger notifications on position changes, liquidations, or large loans

Stream Types​

Loan Updates​

Real-time stream of loan events for a specific margin pool. Includes:

  • Loan Borrowed — New loans taken out
  • Loan Repaid — Partial or full repayments
  • Liquidations — Position liquidations

View Loan Updates Documentation →

Manager Updates​

Real-time stream of margin manager lifecycle events. Includes:

  • Manager Created — New margin managers created
  • Deposit Collateral — Collateral deposits
  • Withdraw Collateral — Collateral withdrawals
  • Liquidations — Position liquidations

View Manager Updates Documentation →

How It Works​

DeepBook Margin Flux Streams use Server-Sent Events (SSE), a standard HTTP-based protocol for real-time push notifications.

Connection Flow​

  1. Connect — Open SSE connection to the stream endpoint with your API key
  2. Stream — Receive events as margin activities occur on-chain
  3. Process — Handle events in your application to update UI or trigger logic

Event Resumption​

Both streams support resumption from a specific point using the last-id parameter:

  • last-id — Resume from events after this ID (client persists the event ID)
  • last-id=0 — Consume from the beginning (limited by server retention)
  • last-id=$ — Consume only real-time events (skip historical)

Quick Start​

Connect to Loan Updates​

const marginPoolId = '0x4405b50d791fd3346754e8171aaab6bc2ed26c2c46efdd033c14b30ae507ac33';
const apiKey = 'YOUR_API_KEY';

const eventSource = new EventSource(
  `https://flux.surflux.dev/deepbook-margin/${marginPoolId}/loan-updates?api-key=${apiKey}`
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  switch (data.type) {
    case 'deepbook_margin_loan_updates_loan_borrowed':
      console.log('New loan:', data.data.loan_amount);
      break;
    case 'deepbook_margin_loan_updates_loan_repaid':
      console.log('Loan repaid:', data.data.repay_amount);
      break;
    case 'deepbook_margin_loan_updates_liquidation':
      console.log('Liquidation!', data.data.liquidation_amount);
      break;
  }
};

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

Connect to Manager Updates​

const apiKey = 'YOUR_API_KEY';

const eventSource = new EventSource(
  `https://flux.surflux.dev/deepbook-margin/manager-updates?api-key=${apiKey}`
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  switch (data.type) {
    case 'deepbook_margin_manager_updates_manager_created':
      console.log('New manager:', data.data.margin_manager_id);
      break;
    case 'deepbook_margin_manager_updates_deposit':
      console.log('Deposit:', data.data);
      break;
    case 'deepbook_margin_manager_updates_withdraw':
      console.log('Withdrawal:', data.data);
      break;
    case 'deepbook_margin_manager_updates_liquidation':
      console.log('Liquidation:', data.data);
      break;
  }
};

Authentication​

All DeepBook Margin Flux Streams require authentication via API key. Include your key as a query parameter:

?api-key=YOUR_API_KEY

Don't have an API key yet? Create your Surflux account to get started.

Base URL​

https://flux.surflux.dev/

Event ID Persistence​

Each SSE event includes an id field. To resume streaming from where you left off:

  1. Store the event ID after processing each event
  2. Reconnect with last-id=<stored-id> to resume
let lastEventId = localStorage.getItem('lastMarginEventId') || '0';

const eventSource = new EventSource(
  `https://flux.surflux.dev/deepbook-margin/${poolId}/loan-updates?api-key=${apiKey}&last-id=${lastEventId}`
);

eventSource.onmessage = (event) => {
  // Store the event ID for resumption
  localStorage.setItem('lastMarginEventId', event.lastEventId);
  
  // Process the event
  const data = JSON.parse(event.data);
  handleEvent(data);
};

Best Practices​

  • Persist Event IDs — Store the last processed event ID to resume after disconnections
  • Implement Reconnection — SSE connections can drop; use exponential backoff to reconnect
  • Filter by Type — Each stream includes multiple event types; route by the type field
  • Combine with Indexing API — Use DeepBook Margin Indexing API for historical data, streams for live updates
  • Monitor Multiple Pools — Open separate connections for each margin pool you want to monitor

Next Steps​

Choose the event stream you need:

Additional Resources​