WebSocket Private API Documentation

hub.on("LR", () => {
    hub.invoke("WebSocketLogin", jwtToken);
});

hub.on("LS", () => console.log("Authenticated"));  // Success
hub.on("LF", () => console.log("Auth failed"));    // Failure

const crypto = require("crypto");

hub.on("LR", () => {
    const timestamp = Date.now();
    const signature = crypto
        .createHmac("sha256", API_SECRET)
        .update(timestamp.toString())
        .digest("hex");

    hub.invoke("WebSocketLoginWithApiKey", API_KEY, signature, timestamp);
});

{
  "positions": [
    {
      "positionId": 12345,
      "symbol": "BTCUSDT",
      "baseAsset": "BTC",
      "quoteAsset": "USDT",
      "size": 0.5,
      "orderSide": "Buy",
      "marginMode": "Isolated",
      "entryPrice": 65230.50,
      "quantity": 0.5,
      "leverage": 10,
      "initialMargin": 3261.525,
      "marginBalance": 3350.00,
      "maintenanceMargin": 163.08,
      "liquidationPrice": 58700.00,
      "unrealizedPnL": 125.75,
      "realizedPnL": 0,
      "markPrice": 65482.00,
      "fundingFee": -1.23,
      "adl": 2,
      "openedAt": "2025-03-15T10:30:00Z"
    }
  ],
  "symbol": "BTCUSDT",
  "availableBalance": 15000.00,
  "maintenanceMargin": 163.08,
  "marginBalance": 3350.00,
  "balance": 18350.00,
  "accountequity": 18475.75,
  "unrealizedPnL": 125.75,
  "walletMode": "OneWay",
  "marginCallRate": 20,
  "marginRatio": 0.048
}

{
  "orderId": 98765,
  "clientOrderId": "my-order-001",
  "symbol": "BTCUSDT",
  "orderBookType": "Futures",
  "side": "Buy",
  "type": "Limit",
  "orderDirection": "Open",
  "baseAsset": "BTC",
  "quoteAsset": "USDT",
  "price": 65000.00,
  "quantity": 0.5,
  "executedQuantity": 0.3,
  "averagePrice": 65010.25,
  "cost": 19503.075,
  "status": "PartiallyFilled",
  "created": "2025-03-15T10:30:00Z",
  "updated": "2025-03-15T10:30:05Z",
  "stopTriggered": false,
  "stopPrice": 0,
  "stopLossTriggerPrice": 60000.00,
  "takeProfitTriggerPrice": 70000.00,
  "source": "Api"
}

{
  "id": 456789,
  "symbol": "BTCUSDT",
  "price": 65010.25,
  "quantity": 0.3,
  "quoteQuantity": 19503.075,
  "orderSide": "Buy",
  "isBuyerMaker": false,
  "isBestMatch": true,
  "time": "2025-03-15T10:30:05Z"
}

hub.on("TradeUpdate", (trade) => {
    const isMaker = (trade.orderSide === "Buy" && trade.isBuyerMaker) ||
                    (trade.orderSide === "Sell" && !trade.isBuyerMaker);

    console.log(`Trade ${trade.id}: ${trade.quantity} @ ${trade.price}`);
    console.log(`Liquidity: ${isMaker ? "MAKER" : "TAKER"}`);
});

{
  "userId": 12345,
  "type": "Futures",
  "currencyId": 1,
  "symbol": "USDT",
  "currencyName": "Tether",
  "free": 15000.00,
  "locked": 3261.525,
  "total": 18261.525,
  "block": 0
}

// Subscribe
await marketHub.invoke("Subscribe", "domain.com", "BTCUSDT", "Spot", 500);

// Snapshot (immediate, on subscribe)
marketHub.on("OrderBookSnapshot", (msg) => {
    // msg.s = sequence ID, msg.b = bids, msg.a = asks, msg.tr = recent trades
    initOrderBook(msg);
    lastSeqId = msg.s;
});

// Delta updates (every 250ms)
marketHub.on("OrderBookUpdate", (msg) => {
    if (msg.s !== lastSeqId + 1) {
        // Gap detected - request replay
        marketHub.invoke("RequestReplay", "domain.com", "BTCUSDT", "Spot", lastSeqId);
        return;
    }
    applyDelta(msg);  // qty "0" = remove level, non-zero = replace
    lastSeqId = msg.s;
});

{
  "c": "snapshot",
  "s": 42,
  "t": 1709500000000,
  "p": "BTCUSDT",
  "o": "spot",
  "d": 500,
  "b": [["65230.50", "1.234"], ["65230.00", "0.567"]],
  "a": [["65231.00", "0.890"], ["65231.50", "2.345"]],
  "tr": [{"i": 1001, "p": "65230.75", "q": "0.100", "m": true, "t": 1709499999500}]
}

{
  "c": "update",
  "s": 43,
  "t": 1709500000250,
  "p": "BTCUSDT",
  "o": "spot",
  "b": [["65230.50", "1.500"], ["65229.00", "0"]],
  "a": [["65231.00", "0.500"]],
  "tr": [{"i": 1002, "p": "65230.50", "q": "0.050", "m": false, "t": 1709500000100}]
}

await marketHub.invoke("SubscribeMiniTickers", "domain.com");

// Full snapshot (immediate)
marketHub.on("TickerSnapshot", (msg) => {
    // msg.d = array of all tickers
    msg.d.forEach(t => tickers.set(t.s, t));
});

// Delta updates (every 500ms, changed tickers only)
marketHub.on("TickerUpdate", (msg) => {
    msg.d.forEach(t => tickers.set(t.s, { ...tickers.get(t.s), ...t }));
});

{
  "c": "markprice_update",
  "t": 1709500000000,
  "d": [
    { "s": "BTCUSDT", "m": "65235.50", "i": "65234.80", "f": "0.00010", "t": 1709503600000 }
  ]
}

import * as signalR from "@microsoft/signalr";
const crypto = require("crypto");

const API_KEY = "your-api-key";
const API_SECRET = "your-api-secret";
const DOMAIN = "domain.com";

// === State ===
const positions = new Map();
const openOrders = new Map();
const balances = new Map();

// === GlobalHub (Private Data) ===
const globalHub = new signalR.HubConnectionBuilder()
    .withUrl("wss://your-domain.com/GlobalHub", {
        transport: signalR.HttpTransportType.WebSockets,
        skipNegotiation: true
    })
    .withAutomaticReconnect([0, 1000, 5000, 10000])
    .build();

// === PublicMarketData Hub ===
const marketHub = new signalR.HubConnectionBuilder()
    .withUrl("wss://your-domain.com/PublicMarketData", {
        transport: signalR.HttpTransportType.WebSockets,
        skipNegotiation: true
    })
    .withAutomaticReconnect([0, 1000, 5000, 10000])
    .build();

// --- Private Event Handlers ---
globalHub.on("FuturesAccountUpdate", (account) => {
    account.positions.forEach(pos => {
        pos.quantity > 0
            ? positions.set(pos.positionId, pos)
            : positions.delete(pos.positionId);
    });
});

globalHub.on("OrderUpdate", (order) => {
    if (order.status === "New" || order.status === "PartiallyFilled") {
        openOrders.set(order.orderId, order);
    } else {
        openOrders.delete(order.orderId);
    }
});

globalHub.on("TradeUpdate", (trade) => {
    const isMaker = (trade.orderSide === "Buy" && trade.isBuyerMaker) ||
                    (trade.orderSide === "Sell" && !trade.isBuyerMaker);
    console.log(`Trade: ${trade.symbol} ${trade.quantity} @ ${trade.price} [${isMaker ? "MAKER" : "TAKER"}]`);
});

globalHub.on("BalanceUpdate", (wallet) => {
    balances.set(`${wallet.type}:${wallet.symbol}`, wallet);
});

// --- Authentication ---
globalHub.on("LR", () => {
    const timestamp = Date.now();
    const signature = crypto
        .createHmac("sha256", API_SECRET)
        .update(timestamp.toString())
        .digest("hex");
    globalHub.invoke("WebSocketLoginWithApiKey", API_KEY, signature, timestamp);
});

globalHub.on("LS", async () => {
    console.log("Authenticated");

    // Fetch initial state via REST
    const [pos, ord, bal] = await Promise.all([
        fetch("/fapi/v1/positionRisk", { headers: authHeaders }).then(r => r.json()),
        fetch("/fapi/v1/openOrders", { headers: authHeaders }).then(r => r.json()),
        fetch("/fapi/v1/balance", { headers: authHeaders }).then(r => r.json())
    ]);

    pos.forEach(p => positions.set(p.positionId, p));
    ord.forEach(o => openOrders.set(o.orderId, o));
    bal.forEach(b => balances.set(`${b.type}:${b.symbol}`, b));
    console.log("State initialized");
});

// --- Market Data Handlers ---
let lastSeqId = 0;
marketHub.on("OrderBookSnapshot", (msg) => {
    initOrderBook(msg);
    lastSeqId = msg.s;
});

marketHub.on("OrderBookUpdate", (msg) => {
    if (msg.s !== lastSeqId + 1) {
        marketHub.invoke("RequestReplay", DOMAIN, "BTCUSDT", "Spot", lastSeqId);
        return;
    }
    applyDelta(msg);
    lastSeqId = msg.s;
});

// --- Start ---
await Promise.all([globalHub.start(), marketHub.start()]);

// Subscribe to market data (snapshot is pushed automatically)
await marketHub.invoke("Subscribe", DOMAIN, "BTCUSDT", "Spot", 500);
await marketHub.invoke("SubscribeMiniTickers", DOMAIN);