Skip to main content

Flux Streams

Surflux Flux Streams deliver real-time blockchain events directly to your application via Server-Sent Events (SSE). Monitor any on-chain activity as it happens—no polling, no delays, no complex infrastructure.

Surflux is the first native infrastructure platform on Sui that delivers real-time streaming of events, fully configurable for your exact use case. Whether you're tracking wallet activity, monitoring smart contract events, or building live trading dashboards, Flux Streams keeps your application instantly synchronized with the Sui blockchain.

Why Flux Streams?​

Traditional blockchain monitoring requires constant polling of RPC nodes or running custom indexers. Flux Streams eliminates this complexity:

  • Instant Updates — Receive events as they're finalized on-chain, typically within 1-2 seconds
  • Zero Infrastructure — No indexers to maintain, no databases to sync, no WebSocket management
  • Flexible Filtering — Subscribe to exactly what you need: specific addresses, packages, objects, or trading pools
  • Guaranteed Delivery — Events are persisted and can be resumed from any point using the last-id parameter
  • Simple Integration — Standard HTTP/SSE protocol works with any programming language

What You Can Build​

Flux Streams powers real-time applications across DeFi, gaming, NFTs, and more:

  • Live Trading Dashboards — Stream Deepbook trades and order book updates for instant market data
  • Wallet Notifications — Alert users immediately when they receive assets or their balances change
  • DeFi Protocol Monitoring — Track liquidations, swaps, and pool activities in real-time
  • NFT Activity Feeds — Show live minting, sales, and transfers as they happen
  • Gaming State Sync — Keep game clients synchronized with on-chain state changes
  • Automated Trading Bots — React to market events and execute strategies with minimal latency
  • Analytics & Indexing — Build custom indexers that stay perfectly in sync with the blockchain

Stream Types​

Surflux offers two categories of Flux Streams:

Custom Flux Streams​

Monitor general blockchain activity with flexible filtering:

  • Package Events — Subscribe to events emitted by specific Move packages
  • Address Events — Track all activity for specific wallet addresses
  • Object Changes — Monitor state changes to specific on-chain objects

Deepbook Flux Stream​

Specialized streams for DeepBook trading pools:

  • Live Trades — Real-time order fills with price, quantity, and fee data
  • Order Book Depth — Live updates to bid/ask levels and liquidity

How It Works​

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

Connection Flow​

  1. Connect — Open an SSE connection to the /events endpoint with your API key
  2. Filter — Events stream continuously based on your configuration (address, package, object filters)
  3. Process — Your application receives events as they occur on-chain
  4. Resume — If disconnected, resume from the last event ID to avoid missing data

Event Structure​

All events follow a consistent structure:

{
  "type": "package_event",
  "timestamp_ms": 1730565189365,
  "checkpoint_id": 75542359,
  "tx_hash": "Fw7Hk5bjtiYLVeZc6N5ZAeHur9tvfgNN6KQThD2AwFUg",
  "data": {
    "event_type": "0x2::display::VersionUpdated",
    "sender": "0x443f35e4d8e7f0f9e590e92569cf08b49bc24b63a92dc80b5d5510e753aad2e8",
    "contents": {
      "field": "value"
    }
  }
}

Every event includes:

  • type — Event category (package_event, address_update, object_change)
  • timestamp_ms — Unix timestamp in milliseconds
  • checkpoint_id — Sui checkpoint number for ordering
  • tx_hash — Transaction hash that generated the event
  • data — Event-specific payload with full details

Getting Started​

1. Choose Your Stream Type​

Decide what blockchain activity you need to monitor:

2. Connect to the Stream​

All streams connect to the same endpoint with different filters:

curl -N "https://flux.surflux.dev/events?api-key=YOUR_API_KEY"

3. Configure Your Filters​

Configure which events you receive through your Surflux dashboard:

  • Address filters — Monitor specific wallet addresses
  • Package filters — Track events from Move packages
  • Object filters — Watch changes to specific objects

4. Handle Events​

Process incoming events in your application:

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 event:', data);

  // Handle event based on type
  switch (data.type) {
    case 'package_event':
      handlePackageEvent(data);
      break;
    case 'address_update':
      handleAddressUpdate(data);
      break;
    case 'object_change':
      handleObjectChange(data);
      break;
  }
};

Key Features​

Event Persistence & Resumption​

Flux Streams persist events so you never miss critical data. Use the last-id parameter to resume from where you left off:

# Resume from specific event ID
curl -N "https://flux.surflux.dev/events?api-key=YOUR_API_KEY&last-id=1755091934020-0"

# Start from real-time only
curl -N "https://flux.surflux.dev/events?api-key=YOUR_API_KEY&last-id=$"

# Replay from beginning
curl -N "https://flux.surflux.dev/events?api-key=YOUR_API_KEY&last-id=0"

Flexible Filtering​

Configure multiple filters to receive only relevant events:

  • Monitor up to 100,000 addresses per stream
  • Track unlimited package types
  • Watch specific object IDs

Guaranteed Ordering​

Events are delivered in checkpoint order, ensuring your application processes blockchain state changes in the correct sequence.

One Client Per API Key​

Each API key supports one active SSE connection at a time. This ensures consistent event delivery and simplifies connection management.

Best Practices​

  • Persist Event IDs — Always save the lastEventId from received events to resume streams after disconnections
  • Handle Reconnections — Implement automatic reconnection logic with exponential backoff
  • Filter Client-Side — The stream includes all configured events; filter in your application for specific use cases
  • Process Asynchronously — Don't block the event stream; process events in background workers
  • Monitor Connection Health — SSE includes periodic heartbeat comments to detect stale connections
  • Use Specific Filters — Configure precise filters in the dashboard to reduce bandwidth and processing overhead

Authentication​

All Flux Streams require authentication via API key. Include your API 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​

All Flux Streams connect to the Flux API:

Mainnet:

https://flux.surflux.dev/

Testnet:

https://testnet-flux.surflux.dev/

Next Steps​

Ready to start streaming blockchain events? Choose your stream type:

Additional Resources​