WebSocket Alerts

Production: wss://alerts.hyperquote.xyz
Local:      ws://127.0.0.1:8090

{
  "type": "AUTHENTICATE",
  "data": {
    "token": "hq_live_abc123..."
  }
}

{
  "type": "AUTHENTICATED",
  "data": {
    "agentId": "clx1abc2d0001...",
    "wallet": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
    "roles": ["maker", "monitor"],
    "subscription": {
      "tokens": [],
      "minNotionalUsd": 0,
      "visibility": "all",
      "side": "all",
      "eventTypes": ["rfq.created", "rfq.filled"]
    }
  }
}

interface Message {
  type: string;
  data: unknown;
}

{
  "type": "SUBSCRIBE",
  "data": {
    "tokens": ["0xb88339cb7199b77e23db6e890353e22632ba630f"],
    "visibility": "public",
    "eventTypes": ["rfq.created"],
    "side": "buy"
  }
}

{
  "type": "SUBSCRIBED",
  "data": {
    "tokens": ["0xb88339cb7199b77e23db6e890353e22632ba630f"],
    "minNotionalUsd": 0,
    "visibility": "public",
    "side": "buy",
    "eventTypes": ["rfq.created"]
  }
}

tokens: ["0xUSDC"]

RFQ: tokenIn=USDC, tokenOut=HYPE  →  Delivered (tokenIn match)
RFQ: tokenIn=HYPE, tokenOut=USDC  →  Delivered (tokenOut match)
RFQ: tokenIn=PURR, tokenOut=HYPE  →  Filtered (no match)

tokens: ["0xHYPE"], side: "buy"

RFQ: tokenIn=USDC, tokenOut=HYPE  →  Delivered (tokenOut=HYPE, buying HYPE)
RFQ: tokenIn=HYPE, tokenOut=USDC  →  Filtered (tokenIn match only, not tokenOut)

{ "type": "UNSUBSCRIBE", "data": {} }

{
  "type": "ALERT",
  "data": {
    "eventType": "rfq.created",
    "sequence": 42,
    "eventId": "rfq.created:f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "rfqId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "timestamp": 1710200000,
    "visibility": "public",
    "rfq": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "taker": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
      "tokenIn": {
        "address": "0xb88339cb7199b77e23db6e890353e22632ba630f",
        "symbol": "USDC",
        "decimals": 6
      },
      "tokenOut": {
        "address": "0x5555555555555555555555555555555555555555",
        "symbol": "HYPE",
        "decimals": 18
      },
      "kind": 0,
      "amountIn": "1000000000",
      "amountOut": null,
      "expiry": 1710203600,
      "createdAt": 1710200000
    },
    "quoteCount": 0
  }
}

{
  "type": "ALERT",
  "data": {
    "eventType": "rfq.filled",
    "sequence": 43,
    "eventId": "rfq.filled:f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "rfqId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "timestamp": 1710200120,
    "visibility": "public",
    "rfq": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "taker": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
      "tokenIn": {
        "address": "0xb88339cb7199b77e23db6e890353e22632ba630f",
        "symbol": "USDC",
        "decimals": 6
      },
      "tokenOut": {
        "address": "0x5555555555555555555555555555555555555555",
        "symbol": "HYPE",
        "decimals": 18
      },
      "kind": 0,
      "amountIn": "1000000000",
      "amountOut": "50000000000000000000",
      "expiry": 1710203600,
      "createdAt": 1710200000
    },
    "fill": {
      "txHash": "0x8a3c2f1e4b5d6c7a8e9f0123456789abcdef0123456789abcdef0123456789ab",
      "filledAt": 1710200120
    }
  }
}

let lastSequence = 0;
 
function onAlert(alert) {
  if (alert.sequence > lastSequence + 1) {
    console.warn(`Gap detected: expected ${lastSequence + 1}, got ${alert.sequence}`);
    // Consider refreshing state from the REST API
  }
  lastSequence = alert.sequence;
  processAlert(alert);
}

const processed = new Set<string>();
 
function onAlert(alert) {
  if (processed.has(alert.eventId)) {
    return; // Already handled
  }
  processed.add(alert.eventId);
  processAlert(alert);
}

const MAX_RECONNECT_ATTEMPTS = 10;
const BASE_DELAY_MS = 1000;
const MAX_DELAY_MS = 30000;
 
let attempt = 0;
let lastSequence = 0;
const processedEvents = new Set<string>();
 
function connect() {
  const ws = new WebSocket("wss://alerts.hyperquote.xyz");
 
  ws.on("open", () => {
    attempt = 0;
 
    // Re-authenticate
    ws.send(JSON.stringify({
      type: "AUTHENTICATE",
      data: { token: process.env.HQ_API_KEY }
    }));
  });
 
  ws.on("message", (raw) => {
    const msg = JSON.parse(raw.toString());
 
    if (msg.type === "AUTHENTICATED") {
      // Reset sequence tracking on reconnect
      lastSequence = 0;
 
      // Re-subscribe with your filters
      ws.send(JSON.stringify({
        type: "SUBSCRIBE",
        data: { eventTypes: ["rfq.created"], visibility: "public" }
      }));
    }
 
    if (msg.type === "ALERT") {
      const { eventId, sequence } = msg.data;
 
      // Deduplicate
      if (processedEvents.has(eventId)) return;
      processedEvents.add(eventId);
 
      // Gap detection
      if (sequence > lastSequence + 1 && lastSequence > 0) {
        console.warn(`Missed ${sequence - lastSequence - 1} alerts`);
      }
      lastSequence = sequence;
 
      processAlert(msg.data);
    }
  });
 
  ws.on("close", (code) => {
    if (attempt >= MAX_RECONNECT_ATTEMPTS) {
      console.error("Max reconnect attempts reached");
      process.exit(1);
    }
 
    const delay = Math.min(BASE_DELAY_MS * Math.pow(2, attempt), MAX_DELAY_MS);
    attempt++;
    console.log(`Reconnecting in ${delay}ms (attempt ${attempt})...`);
    setTimeout(connect, delay);
  });
 
  ws.on("error", (err) => {
    console.error("WebSocket error:", err.message);
  });
}
 
connect();

const pingInterval = setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: "PING", data: {} }));
  }
}, 30_000);
 
ws.on("close", () => clearInterval(pingInterval));

curl https://hyperquote.xyz/api/v1/agent/alerts/preferences \
  -H "Authorization: Bearer hq_live_abc123..."

{
  "agentId": "clx1abc2d0001...",
  "enabled": true,
  "tokens": [],
  "minNotionalUsd": 0,
  "visibility": "all",
  "side": "all",
  "eventTypes": ["rfq.created", "rfq.filled"],
  "createdAt": "2025-03-10T12:00:00.000Z",
  "updatedAt": "2025-03-10T12:00:00.000Z"
}

curl -X PUT https://hyperquote.xyz/api/v1/agent/alerts/preferences \
  -H "Authorization: Bearer hq_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "tokens": ["0xb88339cb7199b77e23db6e890353e22632ba630f"],
    "visibility": "public",
    "eventTypes": ["rfq.created"],
    "side": "buy"
  }'

import WebSocket from "ws";
 
const API_KEY = process.env.HQ_API_KEY!;
const WS_URL = process.env.HQ_ALERTS_URL ?? "wss://alerts.hyperquote.xyz";
 
const MAX_RECONNECT = 10;
const BASE_DELAY = 1000;
let attempt = 0;
let lastSeq = 0;
const seen = new Set<string>();
 
function connect() {
  const ws = new WebSocket(WS_URL);
 
  ws.on("open", () => {
    attempt = 0;
    ws.send(JSON.stringify({
      type: "AUTHENTICATE",
      data: { token: API_KEY }
    }));
  });
 
  ws.on("message", (raw) => {
    const msg = JSON.parse(raw.toString());
 
    switch (msg.type) {
      case "AUTHENTICATED":
        console.log("Authenticated as agent:", msg.data.agentId);
        lastSeq = 0;
 
        ws.send(JSON.stringify({
          type: "SUBSCRIBE",
          data: {
            eventTypes: ["rfq.created"],
            visibility: "public"
          }
        }));
        break;
 
      case "SUBSCRIBED":
        console.log("Subscription active:", msg.data);
        break;
 
      case "ALERT": {
        const { eventId, sequence, eventType, rfqId, rfq } = msg.data;
 
        // Deduplicate
        if (seen.has(eventId)) break;
        seen.add(eventId);
 
        // Gap detection
        if (lastSeq > 0 && sequence > lastSeq + 1) {
          console.warn(`Sequence gap: ${lastSeq} → ${sequence}`);
        }
        lastSeq = sequence;
 
        // Process the alert
        console.log(
          `[${sequence}] ${eventType} | ${rfqId.slice(0, 8)}...` +
          ` | ${rfq.tokenIn.symbol} → ${rfq.tokenOut.symbol}` +
          ` | ${rfq.amountIn ?? rfq.amountOut}`
        );
        break;
      }
 
      case "ERROR":
        console.error("Server error:", msg.data.code, msg.data.message);
        break;
    }
  });
 
  // Keepalive
  const ping = setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) {
      ws.send(JSON.stringify({ type: "PING", data: {} }));
    }
  }, 30_000);
 
  ws.on("close", (code) => {
    clearInterval(ping);
    console.log(`Disconnected (code ${code})`);
 
    if (attempt >= MAX_RECONNECT) {
      console.error("Max reconnect attempts reached");
      process.exit(1);
    }
    const delay = Math.min(BASE_DELAY * Math.pow(2, attempt), 30_000);
    attempt++;
    console.log(`Reconnecting in ${delay}ms...`);
    setTimeout(connect, delay);
  });
 
  ws.on("error", (err) => console.error("WS error:", err.message));
}
 
connect();

HQ_API_KEY=hq_live_abc123... npx tsx alert-bot.ts

curl https://alerts.hyperquote.xyz/health

{
  "status": "ok",
  "eventSourceConnected": true,
  "connectedClients": 12,
  "authenticatedClients": 10,
  "uniqueAgents": 7,
  "uptime": 86400
}