Perp Events Stream

​

Endpoint

• URL: wss://stream-perps-prod-eu.mobula.io/
• Event type: stream (in the subscribe envelope)

​

Subscribe

{
  "type": "stream",
  "authorization": "<MOBULA_SERVER_SIDE_KEY>",
  "payload": {
    "name": "perp-events-<your-uuid>",
    "chainIds": ["evm:42161", "evm:421614", "evm:8453", "lighter:304"],
    "events": ["order"],
    "subscriptionTracking": "true"
  }
}

​

Parameters

• type (required) — must be "stream".
• authorization (required) — your Mobula server-side API key.
• payload.name (required) — client-provided subscription name. Echoed back on the ack frame and useful for log correlation.
• payload.chainIds (required) — array of chain ids to subscribe to. See Chain coverage below.
• payload.events (required) — array of event categories. "order" covers all perp trade-lifecycle events listed in Event types below.
• payload.subscriptionTracking (optional) — string "true" (not a boolean). When set, the ack frame includes a subscriptionId you can use to demux multiple subscriptions on a single socket.

​

Subscribe acknowledgement

{ "event": "subscribed", "subscriptionId": "sub_5cbd27158c9f0b7fb9bc66584d55d76a" }

​

Server push

{
  "data": { /* event-data — schema varies by event type, see below */ },
  "chainId": "evm:42161",
  "duplicateCount": 1,
  "subscriptionId": "sub_5cbd27158c9f0b7fb9bc66584d55d76a"
}

• data.traderAddress is lowercased on the wire — match accordingly when filtering by wallet.
• duplicateCount is informational; identical frames may still be delivered on reconnect or for Gains’ TRADE_STORED + MARKET_BUY pair on the same transaction. Deduplicate on the client with a key like (transactionHash, type, traderAddress, tradeId).

​

Event types

​

Gains “two frames per trade” caveat

• TRADE_STORED — { market, exchange, chainId, traderAddress, type, tradeId, transactionHash, extra: { tradeType, leverage, long, collateralAmount, index, openPrice, tp, sl }, date, ... }
• MARKET_BUY (or MARKET_SELL) — { market, exchange, chainId, type, priceQuote, priceUSD, blockNumber, baseAmountRaw, tradeId, collateralAmountRaw, collateralAsset, leverage, traderAddress, takeProfitUSD, stopLossUSD, extra: { open, amountSentToTrader, trade: { long, index, tradeType, openPrice, collateralIndex } }, transactionHash, date, ... }

​

Chain coverage

​

Envelope shape — events vs positions

​

Heartbeat & idle timeout

{ "event": "ping" }

​

Lighter “hawk” subscribers

​

Implementation example

const ws = new WebSocket('wss://stream-perps-prod-eu.mobula.io/');

ws.addEventListener('open', () => {
  ws.send(JSON.stringify({
    type: 'stream',
    authorization: process.env.MOBULA_API_KEY,
    payload: {
      name: `perp-events-${crypto.randomUUID()}`,
      chainIds: ['evm:42161', 'evm:8453', 'lighter:304'],
      events: ['order'],
      subscriptionTracking: 'true',     // STRING, not boolean
    },
  }));

  setInterval(() => ws.send(JSON.stringify({ event: 'ping' })), 30_000);
});

const seen = new Set<string>();

ws.addEventListener('message', (msg) => {
  const frame = JSON.parse(msg.data.toString());
  if (frame.event === 'pong') return;
  if (frame.event === 'subscribed') return;

  const e = frame.data;
  if (!e?.type) return;

  const dedupeKey = `${e.transactionHash}-${e.type}-${e.traderAddress}-${e.tradeId}`;
  if (seen.has(dedupeKey)) return;
  seen.add(dedupeKey);

  // Filter by your wallet — events are lowercased on the wire
  if (e.traderAddress !== WALLET_ADDRESS.toLowerCase()) return;

  handleEvent(e);
});

​

Related