Private WebSocket

Client                                Server
  |                                      |
  |--- WebSocket connect --------------->|
  |<-- connection open ------------------|
  |                                      |
  |--- AUTH { bearer token } ----------->|
  |<-- { status: "authenticated" } ------|
  |                                      |
  |--- SUBSCRIBE { channels } ---------->|
  |<-- ack ------------------------------|
  |<-- initial snapshots (per channel) --|
  |<-- live updates ---------------------|
  |                                      |
  |--- UNSUBSCRIBE { channels } -------->|
  |<-- ack ------------------------------|

{
  "method": "METHOD_NAME",
  "params": [],
  "id": 1
}

{
  "method": "AUTH",
  "authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
  "id": 1
}

{
  "method": "SUBSCRIBE",
  "params": ["position", "order", "fill"],
  "id": 2
}

{
  "method": "UNSUBSCRIBE",
  "params": ["position"],
  "id": 3
}

{
  "method": "LIST_SUBSCRIPTIONS",
  "id": 4
}

{
  "result": null,
  "id": 2
}

{
  "result": {
    "status": "authenticated",
    "walletAddress": "0x1234...abcd",
    "scopes": ["read", "trade"]
  },
  "id": 1
}

{
  "result": ["position", "order", "fill"],
  "id": 4
}

{
  "error": {
    "code": 4001,
    "msg": "Authentication required"
  },
  "id": 2
}

{
  "stream": "position",
  "data": { ... }
}

{
  "data": {
    "type": "heartbeat",
    "timestamp": 1711612800000
  }
}

{
  "stream": "position",
  "data": {
    "portfolioId": 1,
    "seriesId": "0xabc123...def",
    "symbol": "BTC-80000-C-1711612800",
    "optionBalance": "1000000000000000000",
    "premiumBalance": "-250000000000000000",
    "markPrice": "3200000000000000000000",
    "unrealizedPnl": "150000000000000000"
  }
}

{
  "stream": "order",
  "data": {
    "orderId": "0x789...abc",
    "status": "partially_filled",
    "filled": "500000000000000000",
    "remaining": "500000000000000000"
  }
}

{
  "stream": "fill",
  "data": {
    "tradeId": "trade-001",
    "seriesId": "0xabc123...def",
    "symbol": "ETH-2500-P-1711612800",
    "portfolioId": 1,
    "side": "buy",
    "price": "120000000000000000000",
    "size": "1000000000000000000",
    "fee": "500000000000000000",
    "timestamp": 1711612800000
  }
}

{
  "stream": "collateral",
  "data": {
    "portfolioId": 1,
    "deposit": "10000000000000000000000",
    "equity": "9850000000000000000000",
    "initialMargin": "3200000000000000000000",
    "maintenanceMargin": "1600000000000000000000",
    "maxWithdraw": "8250000000000000000000",
    "isHealthy": true
  }
}

{
  "stream": "rfq",
  "data": {
    "quoteId": "quote-abc-123",
    "seriesId": "0xabc123...def",
    "side": "sell",
    "price": "3100000000000000000000",
    "size": "2000000000000000000",
    "status": "filled",
    "timestamp": 1711612830000
  }
}

{
  "stream": "liquidation",
  "data": {
    "walletAddress": "0x1234...abcd",
    "level": "warning",
    "marginRatio": "1250000000000000000",
    "liquidationDistance": "500000000000000000000",
    "maintenanceMargin": "1600000000000000000000",
    "equity": "2100000000000000000000",
    "timestamp": 1711612850000
  }
}

{
  "stream": "portfolio",
  "data": {
    "portfolioId": 3,
    "user": "0x1234...abcd",
    "action": "created"
  }
}

{
  "method": "SUBSCRIBE",
  "params": ["rfq.quotes.abc123-def456"],
  "id": 5
}

{
  "stream": "rfq.quotes.abc123-def456",
  "data": {
    "type": "quote_arrived",
    "requestId": "abc123-def456",
    "timestamp": 1711612810000,
    "mmAddress": "0x9876...fedc",
    "price": "3150000000000000000000",
    "size": "1000000000000000000",
    "isBest": true
  }
}

{
  "stream": "rfq.quotes.abc123-def456",
  "data": {
    "type": "auction_resolved",
    "requestId": "abc123-def456",
    "timestamp": 1711612830000,
    "winnerMmAddress": "0x9876...fedc",
    "winnerPrice": "3150000000000000000000",
    "totalQuotes": 3
  }
}

SUBSCRIBE ["position", "collateral"]
    |
    +-- snapshot: position (msg 1 of N)
    +-- snapshot: position (msg 2 of N)
    +-- ...
    +-- snapshot: collateral (current state)
    |
    +-- live: position update (on trade)
    +-- live: collateral update (on margin change)
    +-- live: position update (on settlement)
    |
UNSUBSCRIBE ["position"]
    |
    +-- live: collateral update (still subscribed)

const ws = new WebSocket("wss://api.testnet.diffusal.xyz/ws/private");

ws.addEventListener("open", () => {
  // Step 1: Authenticate
  ws.send(
    JSON.stringify({
      method: "AUTH",
      authorization: "Bearer eyJhbGciOiJIUzI1NiIs...",
      id: 1,
    }),
  );
});

ws.addEventListener("message", (event) => {
  const msg = JSON.parse(event.data);

  // Handle auth response
  if (msg.id === 1 && msg.result?.status === "authenticated") {
    console.log("Authenticated as", msg.result.walletAddress);

    // Step 2: Subscribe to channels
    ws.send(
      JSON.stringify({
        method: "SUBSCRIBE",
        params: ["position", "collateral", "fill", "liquidation"],
        id: 2,
      }),
    );
    return;
  }

  // Handle subscription ack
  if (msg.id === 2 && msg.result === null) {
    console.log("Subscribed successfully");
    return;
  }

  // Handle errors
  if (msg.error) {
    console.error(`Error ${msg.error.code}: ${msg.error.msg}`);
    return;
  }

  // Handle heartbeats
  if (msg.data?.type === "heartbeat") {
    return;
  }

  // Handle channel data
  if (msg.stream) {
    switch (msg.stream) {
      case "position":
        console.log("Position update:", msg.data.symbol, msg.data.optionBalance);
        break;
      case "collateral":
        console.log("Collateral:", msg.data.equity, "healthy:", msg.data.isHealthy);
        break;
      case "fill":
        console.log("Fill:", msg.data.side, msg.data.size, "@", msg.data.price);
        break;
      case "liquidation":
        console.log("Liquidation alert:", msg.data.level);
        break;
    }
  }
});

ws.addEventListener("close", (event) => {
  console.log("Connection closed:", event.code, event.reason);
});