WebSockets

sdk.ws.orders(pairId, tradingMode, handler)                         // REQUIRES AUTH
sdk.ws.userOrders(handler)                                          // REQUIRES AUTH
sdk.ws.orderbook(pairId, tradingMode, magnitude, qMode, handler)    // PUBLIC
sdk.ws.ohlcv(pairId, tradingMode, interval, handler, priceType?)    // PUBLIC
sdk.ws.trades(pairId, handler)                                      // PUBLIC
sdk.ws.movements(handler)                                           // REQUIRES AUTH
sdk.ws.balances(handler)                                            // REQUIRES AUTH
sdk.ws.conditionalOrders(handler, pairId?)                          // REQUIRES AUTH
sdk.ws.positions(handler, pairId?)                                  // REQUIRES AUTH
sdk.ws.liquidations(handler, pairId?)                               // REQUIRES AUTH
sdk.ws.account(handler)                                             // REQUIRES AUTH
sdk.ws.marketStats(pairId, handler)                                 // PUBLIC
sdk.ws.marketStatsAll(handler)                                      // PUBLIC
sdk.ws.instruments(handler, pairId?)                                // PUBLIC
sdk.ws.twapOrders(handler, pairId?)                                 // REQUIRES AUTH

// Check connection status
const status = sdk.ws.getStatus(); // "connected", "connecting", "disconnected"

// Manual connect/disconnect
await sdk.ws.connect();
sdk.ws.disconnect();

const sdk = new MonacoSDK({
  walletClient,
  network: "staging",
  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com", // public testnet RPC — use a private provider in production
});

// WebSocket is already connecting in the background
// Connection errors are logged but don't block SDK initialization

const sdk = new MonacoSDK({
  walletClient,
  network: "staging",
  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com",
});

// Disconnect auto-connection
sdk.ws.disconnect();

// Connect later when needed
await sdk.ws.connect();

try {
  await sdk.ws.connect();
  console.log("WebSocket connected successfully");
} catch (error) {
  console.error("WebSocket connection failed:", error);
  // Implement retry logic or notify user
}

// When user navigates away or logs out
sdk.ws.disconnect();

// Reconnect when needed
await sdk.ws.connect();

const unsubscribe = sdk.ws.balances(
  (event) => applyBalanceUpdate(event.data),   // live diffs
  (balances) => setBalances(balances),         // complete current state, once
);

// All pairs, with a baseline
sdk.ws.positions(handler, undefined, (positions) => setPositions(positions));

// One pair, with a baseline
sdk.ws.positions(handler, pair.id, (positions) => setPositions(positions));

interface OrderSnapshotItem {
  orderId: string;
  userId: string;
  applicationId: string;
  tradingPairId: string;
  tradingPair: string;              // symbol, e.g. "BTC/USDC"
  tradingMode: string;              // "SPOT" | "MARGIN"
  side: string;                     // "BUY" | "SELL"
  orderType: string;                // "LIMIT" | "MARKET"
  price: string | null;             // null for a market order
  quantity: string;
  quantityRaw: string;
  filledQuantity: string;
  filledQuantityRaw: string;
  remainingQuantity: string | null;
  remainingQuantityRaw: string | null;
  status: string;                   // a resting status
  timeInForce: string | null;
  averageFillPrice: string | null;  // null before the first fill
  createdAt: string;                // ISO 8601 timestamp (UTC)
  updatedAt: string | null;
  marginAccountId: string | null;
  positionId: string | null;
  leverage: string | null;
  reduceOnly: boolean;
  clientOrderId?: string;           // omitted, not null, when the order carried none
  selfTradePreventionMode?: SelfTradePreventionMode | (string & {});  // the mode REQUESTED on the order; omitted when it carried none
  parentOrderId?: string;           // the TWAP parent of a child order, as `getOrder` returns it; omitted for any other order
  version?: number;                 // sequencer step that last wrote this order; omitted when unknown
}

const sdk = new MonacoSDK({
  ...,
  ws: {
    onReauthenticationRequired: ({ code }) => {
      // SESSION_INVALID: revoked/expired session. AUTH_FAILED: handshake rejected.
      console.warn("WebSocket session lost:", code);
      void sdk.login(clientId);
    },
    onResync: ({ code }) => {
      void reconcileFromRest(code);
    },
  },
});

// Declared before the SDK so `onError` can close over it, and reassigned
// whenever the subscription is (re-)created. The subscribe call itself has to
// come after `sdk` exists, which is why the handle starts undefined.
let unsubscribeOrders: (() => void) | undefined;

const sdk = new MonacoSDK({
  ...,
  ws: {
    onError: ({ code, message, channel }) => {
      switch (code) {
        case "SNAPSHOT_UNAVAILABLE":
          // The subscription is live and diffs flow, but this channel's
          // subscribe-time baseline is missing — refetch just that one from
          // REST.
          if (channel) void refetchSnapshot(channel);
          break;
        case "SESSION_INVALID":
          // The connection is closing and will not reconnect on its own;
          // onReauthenticationRequired follows. Recover there.
          break;
        case "AUTH_REQUIRED":
          // The channel was subscribed before authenticating, so the server
          // rejected it WITHOUT registering it. Re-authenticating is not
          // enough on its own: the client still holds your handler, so it
          // treats the channel as already subscribed and sends no new
          // Subscribe. Drop the subscription and re-create it after
          // authenticating — releasing the last handler for a channel is what
          // lets the next subscribe re-send Subscribe.
          void reauthenticate().then(() => {
            unsubscribeOrders?.();
            unsubscribeOrders = sdk.ws.orders(pairId, "SPOT", onOrder);
          });
          break;
        default:
          console.error("ws error", code, message, channel);
      }
    },
  },
});

unsubscribeOrders = sdk.ws.orders(pairId, "SPOT", onOrder);

// Auto-connect errors are logged but don't throw
const sdk = new MonacoSDK({ ... });
// Even if WebSocket fails, SDK methods work normally

// Manual connect errors can be caught
try {
  await sdk.ws.connect();
} catch (error) {
  if (error.message.includes("connection refused")) {
    console.error("WebSocket server unavailable");
  } else if (error.message.includes("timeout")) {
    console.error("Connection timeout - check network");
  } else {
    console.error("WebSocket error:", error);
  }
}

// ✅ Simple and works in most cases
const sdk = new MonacoSDK({ ... });
sdk.ws.orders(pairId, "SPOT", handler);

// ✅ Useful for apps with conditional real-time features
const sdk = new MonacoSDK({ ... });
sdk.ws.disconnect();  // Disable auto-connect

if (userWantsRealtime) {
  await sdk.ws.connect();
  sdk.ws.orders(pairId, "SPOT", handler);
}

// ✅ React example
useEffect(() => {
  sdk.ws.connect();
  return () => sdk.ws.disconnect();
}, []);

// ✅ Wait for connection before subscribing
if (sdk.ws.getStatus() !== "connected") {
  await sdk.ws.connect();
}
sdk.ws.orders(pairId, "SPOT", handler);

/** Connection status */
type WebSocketStatus = "connected" | "connecting" | "disconnected" | "reconnecting";

/** Orderbook price quotation mode */
type OrderbookQuotationMode = "BASE" | "QUOTE";
// BASE:  Prices in quote currency per base (e.g., USD per BTC for BTC/USD)
// QUOTE: Prices in base currency per quote (e.g., BTC per USD for BTC/USD)

/** Valid magnitude values for orderbook grouping */
const ALL_MAGNITUDES = [0.0001, 0.001, 0.01, 0.1, 1, 10, 100, 1000, 10000];

// Authenticate first
await sdk.login(clientId);

// Get trading pair
const pair = await sdk.market.getTradingPairBySymbol("BTC/USDC");

// Subscribe to order events
const unsubscribe = sdk.ws.orders(
  pair.id,       // Trading pair ID (UUID)
  "SPOT",        // Trading mode
  (event) => {
    console.log("Event type:", event.eventType);
    console.log("Order ID:", event.orderId);
  }
);

// Later, to unsubscribe:
unsubscribe();

import type {
  OrderRole,
  OrderSide,
  OrderStatus,
  OrderTerminalReason,
  OrderType,
  SelfTradePreventionMode,
  TimeInForce,
  TradingMode,
} from "@0xmonaco/types";

const pair = await sdk.market.getTradingPairBySymbol("BTC/USDC");

const unsubscribe = sdk.ws.orderbook(
  pair.id,       // Trading pair ID
  "SPOT",        // Trading mode
  1,             // Magnitude (price grouping)
  "BASE",        // Quotation mode: "BASE" or "QUOTE"
  (event) => {
    console.log("Best bid:", event.bestBid);
    console.log("Best ask:", event.bestAsk);
    console.log("Bids:", event.bids);
    console.log("Asks:", event.asks);
  }
);

// Cleanup
unsubscribe();

const pair = await sdk.market.getTradingPairBySymbol("BTC/USDC");

const unsubscribe = sdk.ws.ohlcv(
  pair.id,    // Trading pair ID
  "SPOT",     // Trading mode
  "1m",       // Interval: "1m", "5m", "15m", "1h", "4h", "1d"
  (event) => {
    const candle = event.candlestick;
    console.log("Open:", candle.o);
    console.log("High:", candle.h);
    console.log("Low:", candle.l);
    console.log("Close:", candle.c);
    console.log("Volume:", candle.v);
  }
);

// Cleanup
unsubscribe();

// Mark-price candles for a margin pair
const unsubMark = sdk.ws.ohlcv(pair.id, "MARGIN", "1m", (event) => {
  console.log("mark close:", event.candlestick.c);
}, "mark");

import type { Interval, TradingMode } from "@0xmonaco/types";

interface OHLCVEvent {
  tradingPairId: string;
  interval: Interval | (string & {});
  tradingMode: TradingMode | (string & {});
  priceType?: "trade" | "mark" | (string & {});
  candlestick: Candlestick;
}

interface Candlestick {
  T: number;  // Period start timestamp (ms, UTC)
  t: number;  // Period end timestamp (ms, UTC)
  o: string;  // Open price
  h: string;  // High price
  l: string;  // Low price
  c: string;  // Close price
  v: string;  // Volume
  s: string;  // Symbol
  i: string;  // Interval
  n: number;  // Number of trades
}

const pair = await sdk.market.getTradingPairBySymbol("BTC/USDC");

const unsubscribe = sdk.ws.trades(
  pair.id,    // Trading pair ID
  (event) => {
    console.log("Trade ID:", event.data.tradeId);
    console.log("Price:", event.data.price);
    console.log("Quantity:", event.data.quantity);
    console.log("Maker side:", event.data.makerSide);
  }
);

// Cleanup
unsubscribe();

import type { OrderSide, TradingMode } from "@0xmonaco/types";

interface TradeEvent {
  eventType: "trade";
  tradingPairId: string;
  tradingMode: TradingMode | (string & {});
  data: {
    tradeId: string;
    price: string;
    quantity: string;
    makerSide: OrderSide | (string & {});
    executedAt: string;
  };
}

// Authenticate first
await sdk.login("your-client-id");

// Subscribe to movements
const unsubscribe = sdk.ws.movements((event) => {
  console.log("Movement ID:", event.data.id);
  // Live types: "deposit", "withdrawal", "funding" (lowercase) and the order
  // unlocks "OrderCancelled", "OrderPartiallyCancelled", "OrderExpired", whose
  // entryType is uppercase "CREDIT". Fills and fees never arrive here — read
  // them from movement history, and take a fill's live signal off `balances`.
  console.log("Transaction:", event.data.transactionType);
  console.log("Entry:", event.data.entryType);
  console.log("Token:", event.data.tokenAddress);
  console.log("Amount:", event.data.amount);
  console.log("Balance:", event.data.balanceBefore, "→", event.data.balanceAfter);
  
  // Check if related to an order
  if (event.data.referenceType === "order") {
    console.log("Order ID:", event.data.referenceId);
  }
  
  // Check for on-chain transaction
  if (event.data.txHash) {
    console.log("TX Hash:", event.data.txHash);
  }
});

// Cleanup
unsubscribe();

interface UserMovementEvent {
  eventType: "movement";
  userId: string;
  data: {
    id: string;                    // Movement ID (UUID)
    entryType: string;             // free-form; "credit" | "debit" | "CREDIT" (order unlocks) — compare case-insensitively
    transactionType: string;       // free-form; live: "deposit" | "withdrawal" | "funding" | "OrderCancelled" | "OrderPartiallyCancelled" | "OrderExpired". History adds fill/fee types this channel never emits
    status?: string;               // Movement status: "completed" | "pending" | "failed" (wire `status`)
    token?: string;                // Token contract address (wire `token`; older payloads use the `token_address` alias)
    tokenAddress: string;          // Populated legacy alias of `token` (always set, for back-compat)
    assetId?: string;              // Asset registry ID, UUID (wire `asset_id`)
    symbol?: string;               // Token symbol (e.g., "USDC")
    decimals: number;              // Token decimals (e.g., 6 for USDC)
    amount: string;                // Movement amount (decimal string, normalized)
    amountRaw?: string;            // Raw amount (integer string, no decimals)
    balanceBefore?: string;        // Balance before movement (normalized)
    balanceBeforeRaw?: string;     // Balance before in raw format (wei)
    balanceAfter?: string;         // Balance after movement (normalized)
    balanceAfterRaw?: string;      // Balance after in raw format (wei)
    lockedBefore?: string;         // Locked balance before (normalized)
    lockedBeforeRaw?: string;      // Locked balance before in raw format (wei)
    lockedAfter?: string;          // Locked balance after (normalized)
    lockedAfterRaw?: string;       // Locked balance after in raw format (wei)
    referenceId?: string;          // Related entity ID (e.g., order UUID)
    referenceType?: string;        // Reference type ("order", "deposit", etc.)
    description?: string;          // Human-readable description
    txHash?: string;               // On-chain transaction hash (if applicable)
    blockNumber?: number;          // Block number, if on-chain (wire `block_number`)
    createdAt?: string;            // ISO 8601 timestamp (UTC)
  };
}

sdk.ws.movements((event) => {
  if (event.data.transactionType === "deposit" && event.data.txHash) {
    console.log(`✅ Deposit confirmed: ${event.data.amount}`);
    console.log(`New balance: ${event.data.balanceAfter}`);
    console.log(`TX: ${event.data.txHash}`);
  }
});

sdk.ws.movements((event) => {
  // A cancelled, partially cancelled, or expired order releases its lock.
  if (event.data.transactionType.toLowerCase().startsWith("order")) {
    console.log(`Order ${event.data.referenceId}: ${event.data.amount} unlocked`);
  }
});

import { useUserMovements } from "@0xmonaco/react";

function MovementsFeed() {
  const { movements, loading, subscribed } = useUserMovements(50);
  
  return (
    <div>
      {movements.map(m => (
        <div key={m.data.id}>
          {m.data.transactionType}: {m.data.amount}
        </div>
      ))}
    </div>
  );
}

// All conditional-order events for the authenticated user
const unsubscribe = sdk.ws.conditionalOrders((event) => {
  const { conditionalOrderId, state, reason, triggerPrice, triggeredOrderId } = event.data;
  console.log(`${conditionalOrderId} → ${state} (${reason})`);
});

// Scope to a single trading pair (optional second arg)
const unsubscribePair = sdk.ws.conditionalOrders(
  (event) => { /* ... */ },
  tradingPairId,
);

// Cleanup
unsubscribe();

import type {
  ConditionalOrderConditionType,
  ConditionalOrderState,
  ConditionalOrderTriggerSource,
  OrderSide,
  OrderType,
  PositionSide,
  TimeInForce,
} from "@0xmonaco/types";

{
  eventType: "conditional_order_update";
  userId: string;
  data: {
    conditionalOrderId: string;
    version?: number;             // REST/subscription snapshots only; never live events
    tradingPairId: string;
    marginAccountId: string;
    positionId?: string;
    parentOrderId?: string;
    associationType?: "POSITION" | "PARENT_ORDER" | (string & {});
    linkedGroupId?: string;              // populated for OCO TP/SL pairs
    conditionType: ConditionalOrderConditionType | (string & {});
    triggerSource: ConditionalOrderTriggerSource | (string & {});
    triggerPrice: string;
    side: OrderSide | (string & {});
    positionSide: PositionSide | (string & {});
    orderType: OrderType | (string & {});
    limitPrice?: string;
    quantity?: string;
    slippageToleranceBps?: number;
    reduceOnly: boolean;
    timeInForce?: TimeInForce | (string & {});           // full enum, not just GTC/IOC — narrow before use
    state: ConditionalOrderState | (string & {});
    triggeredOrderId?: string;           // declared, but no frame on this channel carries it — read it from REST
    triggeredAt?: string;
    activatedAt?: string;                // populated when parent-attached TP/SL becomes active
    cancelledAt?: string;
    expiresAt?: string;
    failureReason?: string;              // populated on FAILED
    trailBps?: number;                   // TRAILING_STOP only: retracement behind the watermark, in bps
    activationPrice?: string;            // TRAILING_STOP only: level that starts tracking; absent when armed immediately
    watermarkPrice?: string;             // TRAILING_STOP only: best mark since arming; triggerPrice trails it
    trailArmedAt?: string;               // TRAILING_STOP only: when tracking began; absent while awaiting activationPrice
    reason: string;                      // free-form; canonical values listed below
    createdAt?: string;                  // same string REST returns; always sent by current servers, absent only from an older deployment
    updatedAt: string;
  }
}

// All position updates for the authenticated user
const unsubscribe = sdk.ws.positions((event) => {
  const { positionId, side, status, size, markPrice, unrealizedPnl, liquidationPrice } = event.data;
  console.log(`${positionId} ${side} ${status} size=${size} mark=${markPrice} uPnL=${unrealizedPnl}`);
});

// Scope to a single trading pair (optional second arg)
const unsubscribePair = sdk.ws.positions((event) => { /* ... */ }, tradingPairId);

// Cleanup
unsubscribe();

import type { MarginMode, PositionEventSide, PositionEventStatus } from "@0xmonaco/types";

{
  eventType: "position_update";
  userId: string;
  data: {
    positionId: string;
    marginAccountId: string;
    tradingPairId: string;
    side: PositionEventSide | (string & {});
    status: PositionEventStatus | (string & {});  // SCREAMING_SNAKE_CASE, same casing as REST
    size: string;                 // absolute size (decimal string)
    entryPrice: string;           // decimal string
    markPrice?: string;           // decimal string
    unrealizedPnl?: string;       // decimal string
    liquidationPrice?: string;    // decimal string
    isolatedMargin: string;       // the position's backing (decimal string) — the same value the REST position's isolatedMargin serves
    leverage: string;             // decimal string
    riskBucketId?: string;        // risk bucket scoping the position — the same value REST's riskBucketId serves
    marginMode?: MarginMode | (string & {});  // "CROSS" | "ISOLATED"; never infer it from riskBucketId
    maintenanceMarginRequired?: string;  // required at markPrice (decimal string); "0" with no open exposure
    initialMarginRequired?: string;      // required at markPrice (decimal string); "0" with no open exposure
    tradeId?: string;             // trade that caused the update, present when a fill drove it
    orderId?: string;             // order that caused the update (falls back to the position's opening order)
    reason: string;               // "trade" | "close" | "liquidation" | "adl" | "funding" | "margin_added" | "margin_reduced" | "margin_collateral_transfer"
    updatedAt: string;            // ISO 8601 (UTC) — when the position was last MUTATED, not when the frame was built
    version?: number;             // opaque durable row revision; absent means unranked
  }
}

// All liquidation alerts for the authenticated user
const unsubscribe = sdk.ws.liquidations((event) => {
  const { liquidationId, status, accountState, estimatedShortfall, message } = event.data;
  console.warn(`liquidation ${liquidationId} ${status}/${accountState} shortfall=${estimatedShortfall}: ${message}`);
});

// Scope to a single trading pair (optional second arg)
const unsubscribePair = sdk.ws.liquidations((event) => { /* ... */ }, tradingPairId);

// Cleanup
unsubscribe();

{
  eventType: "liquidation_alert";
  userId: string;
  data: {
    liquidationId: string;
    marginAccountId: string;
    positionId?: string;          // present when the alert is position-scoped
    tradingPairId?: string;       // present when the alert is position-scoped
    status: string;               // liquidation record status (e.g. "UNRESOLVED", or "COMPLETED" on a terminal alert)
    accountState: string;         // margin-account risk state (e.g. "Liquidating", or "Normal" on a recovery)
    liquidationPrice?: string;    // decimal string
    markPrice?: string;           // decimal string
    estimatedShortfall: string;   // decimal string
    message: string;              // human-readable alert message
    triggeredAt: string;          // ISO 8601 timestamp (UTC)
  }
}

const unsubscribe = sdk.ws.account(
  (event) => {
    const { marginAccountId, sequence, equity, freeCollateral, marginRatio, maintenanceRequirement } = event.data;
    console.log(`${marginAccountId} seq=${sequence} equity=${equity} free=${freeCollateral} ratio=${marginRatio} mmr=${maintenanceRequirement}`);
  },
  // Subscribe-time snapshot: one row per margin account you own in THIS
  // application, ahead of the live frames (live delivery is per user and
  // wider, so do not treat an absent account as deleted). `sequence` is absent
  // on these rows, and any live frame supersedes one.
  (accounts) => {
    for (const account of accounts) {
      console.log(`baseline ${account.marginAccountId} equity=${account.equity} ratio=${account.marginRatio}`);
    }
  },
);

// Cleanup
unsubscribe();

{
  eventType: "account_update";
  userId: string;
  data: {
    marginAccountId: string;          // margin account this update describes
    equity: string;                   // collateral + unrealized PnL + funding (decimal string)
    collateral: string;               // raw deposited collateral in USD (decimal string)
    freeCollateral: string;           // equity headroom for existing cross exposure (decimal string); NOT the withdrawal bound — read withdrawableCollateral from the margin-accounts or portfolio-margin API
    marginRatio: string;              // maintenance requirement / equity (decimal string). "0" for an account with no open positions. Saturates to a maximum-distress sentinel (Decimal::MAX, ~7.9e28) whenever the ratio cannot be computed or represented — a maintenance requirement at zero/negative equity, or near-zero positive (dust) equity where the true ratio exceeds the decimal range — treat a value at/above the liquidation threshold as maximal distress and clamp it for display
    maintenanceRequirement: string;   // maintenance margin required to stay solvent (decimal string)
    sequence?: number;                // per-account counter within one producer run, LIVE frames only: dedupe live frames by updatedAt (newest wins), sequence tie-breaks same-updatedAt frames. Resets to 0 on producer restart (socket may stay connected), MAY skip values — never a gap detector or cross-restart order. ABSENT on a subscribe-time snapshot row, which any live frame supersedes regardless of timestamps; treat absent as unknown, never as zero
    updatedAt: string;                // ISO 8601 timestamp (UTC)
  }
}

const unsubscribe = sdk.ws.twapOrders((event) => {
  const t = event.data;
  console.log(
    `${t.twapOrderId} ${t.state} ` +
    `executed=${t.executedQuantity}/${t.totalQuantity} ` +
    `slices=${t.slicesPlaced}/${t.plannedSlices} (${t.reason})`
  );
});

// Or scope to one market
const unsubPair = sdk.ws.twapOrders(handler, pair.id);

// Cleanup
unsubscribe();

import type {
  OrderSide,
  TradingMode,
  TwapExecutionStyle,
  TwapOrderEventReason,
  TwapOrderState,
} from "@0xmonaco/types";

{
  eventType: "twap_order_update";
  userId: string;
  data: {
    twapOrderId: string;
    tradingPairId: string;
    side: OrderSide | (string & {});
    tradingMode: TradingMode | (string & {});
    totalQuantity: string;
    executedQuantity: string;
    executedNotional: string;
    averageFillPrice?: string;     // absent until the first fill
    plannedSlices: number;
    slicesPlaced: number;
    slicesSkipped: number;         // refusals, not slots — a PASSIVE slot can increment this AND slicesPlaced; skips never terminate the parent
    nextSliceAt?: string;
    state: TwapOrderState | (string & {});
    terminalReason?: string;       // e.g. end-of-window shortfall, or "trigger expired" (human-readable, not a parsing contract)
    executionStyle: TwapExecutionStyle | (string & {});
    triggerPrice?: string;         // conditional parents only
    triggerDirection?: "ABOVE" | "BELOW" | (string & {});
    conditionalExpiry?: string;    // deadline for the trigger to fire
    triggeredAt?: string;          // when the trigger fired
    reason: TwapOrderEventReason | (string & {});  // what triggered this frame — see Reasons below
    // plus config echoes (limitPrice, slippageToleranceBps, reduceOnly, margin context,
    // clientTwapId, randomize, startAt/endAt) and created/updated/cancelled/completed timestamps
  }
}

sdk.ws.twapOrders(
  (event) => applyTwapUpdate(event.data),   // live diffs
  undefined,                                // all pairs (or pass a tradingPairId)
  (parents) => setTwapParents(parents),     // complete current state, once
);

// Per-market: full stats for one trading pair
const unsubscribe = sdk.ws.marketStats(tradingPairId, (event) => {
  const { markPrice, openInterest, currentFundingRate, dailyPriceChangePercent } = event.data;
  console.log(`${event.tradingPairId} mark=${markPrice} OI=${openInterest} funding=${currentFundingRate} 24h%=${dailyPriceChangePercent}`);
});

// All markets: one summary row per market, per frame
const unsubscribeAll = sdk.ws.marketStatsAll((event) => {
  for (const m of event.markets) {
    console.log(`${m.symbol} ${m.marketStatus} last=${m.lastTradePrice} 24h%=${m.dailyPriceChangePercent}`);
  }
});

// Cleanup
unsubscribe();
unsubscribeAll();

import type { MarketStatus } from "@0xmonaco/types";

// Per-market (market_stats:<tradingPairId>)
{
  tradingPairId: string;
  data: {
    symbol: string;
    tradingPairId: string;
    indexPrice?: string;              // perp-only; omitted for spot
    markPrice?: string;               // perp-only; omitted for spot
    midPrice?: string;
    bestBidPrice?: string;
    bestAskPrice?: string;
    openInterest?: string;            // perp-only; omitted for spot
    openInterestLimit?: string;       // perp-only; omitted for spot
    lastTradePrice?: string;
    dailyBaseTokenVolume?: string;
    dailyQuoteTokenVolume?: string;
    dailyPriceLow?: string;
    dailyPriceHigh?: string;
    dailyPriceChange?: string;
    dailyPriceChangePercent?: string;
    currentFundingRate?: string;      // perp-only; omitted for spot
    fundingRate?: string;             // perp-only; omitted for spot
    fundingTimestamp?: number;        // ms epoch; perp-only; omitted for spot
    premium?: string;                 // perp-only; omitted for spot
    baseInterestRate?: string;        // perp-only; omitted for spot
    fundingClampSmall?: string;       // perp-only; omitted for spot
    fundingClampBig?: string;         // perp-only; omitted for spot
  }
}

// All markets (market_stats)
{
  markets: Array<{
    tradingPairId: string;
    symbol: string;
    lastTradePrice?: string;
    markPrice?: string;               // perp-only; omitted for spot
    dailyPriceChange?: string;
    dailyPriceChangePercent?: string;
    dailyBaseTokenVolume?: string;
    dailyQuoteTokenVolume?: string;
    dailyPriceHigh?: string;
    dailyPriceLow?: string;
    openInterest?: string;            // perp-only; omitted for spot
    currentFundingRate?: string;      // perp-only; omitted for spot
    fundingTimestamp?: number;        // ms epoch; perp-only; omitted for spot
    marketStatus: MarketStatus | (string & {});
  }>;
}