Skip to main content

​
Overview

PrometheX uses Server-Sent Events (SSE) for real-time data. Connect once and receive push updates for prices, trades, position changes, and notifications.
SSE is a one-way channel (server → client). Use the REST API for sending data. SSE connections have a 10-minute timeout — reconnect when the connection drops.

​
Connect

POST /api/v1/sse/connect
Auth required: Yes Opens an SSE stream. The first event contains your connection_id: 
event: base:connected
data: {"connection_id": "conn-abc-123"}
Save the connection_id — you’ll need it to subscribe to market-specific topics.

​
Example

const eventSource = new EventSource('/api/v1/sse/connect', {
  headers: { 'Authorization': `Bearer ${privyJwt}` }
});

eventSource.addEventListener('base:connected', (e) => {
  const { connection_id } = JSON.parse(e.data);
  console.log('Connected:', connection_id);
  subscribeToMarkets(connection_id);
});

eventSource.addEventListener('market:price_change', (e) => {
  const data = JSON.parse(e.data);
  console.log('Price update:', data.market_address, data.option_address);
});

eventSource.addEventListener('user:position_changed', (e) => {
  const data = JSON.parse(e.data);
  console.log('Position changed:', data.market_address);
});

eventSource.onerror = () => {
  console.log('Connection lost, reconnecting...');
  // Implement reconnection logic
};

​
Subscribe to Markets

POST /api/v1/sse/subscribe
Auth required: Yes Subscribe to market-specific events (price changes, new trades, info updates).

​
Request Body

​
connection_id
string
required
The connection_id received from the base:connected event.
​
topics
string[]
required
Array of topic strings in the format market:{marketAddress}.

​
Example

curl -X POST "https://api-staging.promethex.market/api/v1/sse/subscribe" \
  -H "Authorization: Bearer $PRIVY_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn-abc-123",
    "topics": [
      "market:0x1234...abcd",
      "market:0x5678...efgh"
    ]
  }'

​
Unsubscribe

POST /api/v1/sse/unsubscribe
Auth required: Yes Remove subscriptions from specific market topics. Same request format as subscribe. 
curl -X POST "https://api-staging.promethex.market/api/v1/sse/unsubscribe" \
  -H "Authorization: Bearer $PRIVY_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn-abc-123",
    "topics": ["market:0x1234...abcd"]
  }'

​
Event Reference

​
Automatic Events

These events are sent without subscribing — you receive them as soon as you connect.
EventPayloadTrigger
base:connected{ connection_id }Connection established
base:ping{}Keepalive (every 30s)
user:position_changed{ uid, market_address, option_address }Your trade was executed
user:asset_changed{ uid, base_token_address }Your balance updated
user:new_notification{ uid }New notification available

​
Subscription Events

These events require subscribing to specific market topics.
EventPayloadTrigger
market:new_trades{ market_address, option_address }New trade on the market
market:price_change{ market_address, option_address }Price movement
market:info_update{ market_address, option_address }Market metadata change

​
Event Payload Examples

{
  "connection_id": "conn-abc-123"
}

​
Connection Management

​
Reconnection Strategy

Implement exponential backoff when reconnecting: 
let retryDelay = 1000; // Start at 1s

function connect() {
  const es = new EventSource('/api/v1/sse/connect', {
    headers: { 'Authorization': `Bearer ${privyJwt}` }
  });

  es.addEventListener('base:connected', () => {
    retryDelay = 1000; // Reset on successful connect
  });

  es.onerror = () => {
    es.close();
    setTimeout(() => {
      retryDelay = Math.min(retryDelay * 2, 30000); // Max 30s
      connect();
    }, retryDelay);
  };
}

​
Best Practices

PracticeDescription
Reconnect on dropSSE connections timeout after 10 minutes
Monitor base:pingIf no ping for 60s, consider reconnecting
ResubscribeAfter reconnecting, resubscribe to market topics
One connectionUse a single SSE connection per client session
Parse carefullyAlways validate event data before using it