Real-Time Events (SSE)

Overview

The SSE endpoint streams real-time updates without polling.

Endpoint: GET /api/v1/sse

Authentication modes:

Public mode (default): no auth, same behavior as before
Backend scoped mode: add apiKey=<raw_api_key> query param to scope position events to that API key

Optional query parameter: owner=<wallet_address> to further narrow position events to one wallet.

Connecting

Public mode (frontend/browser):

const es = new EventSource('https://api.lavarage.xyz/api/v1/sse?owner=YOUR_WALLET')

es.onopen = () => console.log('Connected')
es.onerror = () => {
  es.close()
  setTimeout(reconnect, 5_000)
}

Backend scoped mode (server-to-server):

Use this only from trusted backend services. Do not embed apiKey in browser/client code.

import EventSource from 'eventsource'

const apiKey = process.env.LAVARAGE_API_KEY!
const owner = 'YOUR_WALLET'
const url = 'https://api.lavarage.xyz/api/v1/sse?apiKey=' + encodeURIComponent(apiKey) + '&owner=' + owner

const es = new EventSource(url)

es.onopen = () => console.log('Connected')
es.onerror = () => {
  es.close()
  setTimeout(reconnect, 5_000)
}

Event Types

`prices`

Emitted every ~10 seconds with updated token prices.

Payload shape: Record<mintAddress, usdPriceString>

es.addEventListener('prices', (e) => {
  const prices: Record<string, string> = JSON.parse(e.data)
  // { "So111...": "152.40", "EPjFW...": "1.0001" }
  updatePriceStore(prices)
})

`positions`

Emitted when a monitored position changes status (e.g. SUBMITTED → ONCHAIN, or position closed/liquidated).

Payload shape: array of lightweight updates:

[
  {
    "address": "7xKX...",
    "owner": "Gsbw...",
    "status": "ONCHAIN",
    "event": "position_opened"
  }
]

Notes:

This is a change signal, not a full position object
Sometimes the server emits [] as a generic refresh signal (e.g. backfill pass)
Best practice: on any positions event, re-fetch GET /api/v1/positions

es.addEventListener('positions', (e) => {
  const updates = JSON.parse(e.data) // array, may be []
  invalidatePositionsCache()
})

`offers`

Emitted when offer/pool data changes (new offers, liquidity changes).

Payload shape is currently a small signal object (example: { "updated": 2839 }).

Important:

It does not include full offer rows
It does not include a specific changed-offer ID list
Client should treat it as an invalidation signal and re-fetch relevant offer endpoints

es.addEventListener('offers', (e) => {
  const signal = JSON.parse(e.data) // e.g. { updated: number }
  invalidateOffersCache()
})

`heartbeat`

Emitted every 30 seconds to keep the connection alive through proxies. No data payload — safe to ignore.

Reconnection

Implement a reconnect loop in your backend service:

function connect(walletAddress?: string) {
  const apiKey = process.env.LAVARAGE_API_KEY!
  const url = walletAddress
    ? `https://api.lavarage.xyz/api/v1/sse?apiKey=${encodeURIComponent(apiKey)}&owner=${walletAddress}`
    : `https://api.lavarage.xyz/api/v1/sse?apiKey=${encodeURIComponent(apiKey)}`

  const es = new EventSource(url)
  let reconnectTimer: ReturnType<typeof setTimeout>

  es.onopen = () => clearTimeout(reconnectTimer)
  es.onerror = () => {
    es.close()
    reconnectTimer = setTimeout(() => connect(walletAddress), 5_000)
  }

  es.addEventListener('prices', (e) => {
    const prices = JSON.parse(e.data)
    // handle price update
  })

  es.addEventListener('positions', (e) => {
    const updates = JSON.parse(e.data)
    // handle position update
  })

  es.addEventListener('offers', () => {
    // handle offer update
  })

  return () => {
    clearTimeout(reconnectTimer)
    es.close()
  }
}

const disconnect = connect('GsbwXfJraMomNxBcjK7xK2xQx5MQgQx4Ld8QkLeNmA3v')

Notes

Public mode (no apiKey) remains compatible with existing frontend EventSource usage
Price data arrives as a flat map of mintAddress → usdPrice (string decimals)
In scoped mode (apiKey provided), position events are filtered by API key; ?owner= adds wallet-level filtering
prices and offers are global signals in both modes (not API-key scoped)
Recommended client behavior: update local price store on prices, invalidate/refetch on offers and positions
If the connection drops, existing subscriptions do not need to be re-registered — just reconnect