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?, onSnapshot?, onValuation?)      // 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
sdk.ws.copy(handler, onSnapshot?)                                   // REQUIRES AUTH

// Check connection status
const status = sdk.ws.getStatus(); // "connecting", "connected", "reconnecting" or "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 sdk = new MonacoSDK({
  walletClient,
  network: "staging",
  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com",
  ws: {
    onStatusChange: (status, { attempt, hasConnected, nextRetryDelayMs }) => {
      if (status === "reconnecting" && !hasConnected) {
        showBanner(`Can't reach Monaco (attempt ${attempt}), retrying in ${Math.round((nextRetryDelayMs ?? 0) / 1000)}s`);
      } else if (status === "reconnecting") {
        showBanner(`Connection lost, reconnecting (attempt ${attempt})`);
      } else if (status === "connected") {
        hideBanner();
      }
    },
  },
});

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;
  postOnly?: boolean;               // `true` when resting post-only; omitted, never `false`, otherwise
  expirationDate?: string;          // custom GTC expiry (RFC 3339), as `getOrder` returns it; omitted when none
  triggerPrice?: string;            // trigger price of an order a conditional placed; omitted otherwise
  positionSide?: string;            // deprecated derived label, as `getOrder` returns it; `side` is authoritative
  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({ maxMovements: 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;             // revision of this row, on every update; compare with >=
    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;           // the close the trigger placed; set from the "triggered" update on
    triggeredAt?: string;
    activatedAt?: string;                // populated when parent-attached TP/SL becomes active
    cancelledAt?: string;
    expiresAt?: string;
    failureReason?: string;              // populated on FAILED and EXPIRED, and on a refused trailing stop
    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);

// Periodic valuations (optional fourth arg): apply them only to positions you hold as OPEN
const unsubscribeWithValuations = sdk.ws.positions(
  (event) => { /* lifecycle frames */ },
  undefined,
  undefined,
  (valuation) => {
    const held = positions.get(valuation.data.positionId);
    if (held?.status !== "OPEN") return; // unknown or terminal: ignore
    // read before the held state's last mutation: stale, ignore
    if (Date.parse(valuation.data.valuedAt) <= Date.parse(held.updatedAt)) return;
    Object.assign(held, {
      markPrice: valuation.data.markPrice,
      unrealizedPnl: valuation.data.unrealizedPnl,
      liquidationPrice: valuation.data.liquidationPrice ?? undefined,
      initialMarginRequired: valuation.data.initialMarginRequired,
      maintenanceMarginRequired: valuation.data.maintenanceMarginRequired,
    });
  },
);

// 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"
    updatedAt: string;            // ISO 8601 (UTC) — when the position was last MUTATED, not when the frame was built
    openedAt?: string;            // ISO 8601 (UTC) — when the position OPENED; never moves; absent when unknown
    version?: number;             // opaque durable row revision; absent means unranked
  }
}

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

{
  eventType: "position_valuation";
  userId: string;
  data: {
    positionId: string;
    marginAccountId: string;
    tradingPairId: string;
    markPrice: string;                  // decimal string
    unrealizedPnl: string;              // decimal string
    liquidationPrice: string | null;    // null when no liquidation price can be derived
    initialMarginRequired: string;      // required at markPrice (decimal string)
    maintenanceMarginRequired: string;  // required at markPrice (decimal string)
    valuedAt: string;                   // ISO 8601 (UTC) — when the server read the position
  }
}

// All liquidation alerts for the authenticated user
const unsubscribe = sdk.ws.liquidations((event) => {
  const { liquidationId, status, riskBucketState, estimatedShortfall, message } = event.data;
  console.warn(`liquidation ${liquidationId} ${status}/${riskBucketState} 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)
    riskBucketState: string;      // liquidated risk bucket's state (e.g. "PENDING_LIQUIDATION")
    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.copy(
  (event) => {
    switch (event.eventType) {
      case "copy_relationship_update": {
        const { relationshipId, status, change, allocation, consecutiveSkips, version } = event.data;
        console.log(`follow ${relationshipId} ${status} (${change}) allocation=${allocation} skips=${consecutiveSkips} v=${version}`);
        break;
      }
      case "copy_skip": {
        const { relationshipId, tradingPairId, reason, requestedQuantity } = event.data;
        console.warn(`follow ${relationshipId} skipped ${requestedQuantity} on ${tradingPairId}: ${reason}`);
        break;
      }
    }
  },
  // Subscribe-time snapshot: every live follow, with change "snapshot".
  (follows) => setFollows(follows),
);

unsubscribe();

type CopyEvent =
  | {
      eventType: "copy_relationship_update";
      userId: string;                // the follower (you)
      data: {
        relationshipId: string;      // the follow id (Follow.followId over REST)
        leaderWallet: string;
        status: CopyRelationshipStatus | (string & {});
        marginModePolicy: CopyMarginModePolicy | (string & {});
        copyRiskBucketId: string;    // the copy account's cross risk bucket
        sizingMode: CopySizingMode | (string & {});
        sizingParam?: string;
        leverageMode: CopyLeverageMode | (string & {});
        fixedLeverage?: string;
        allocation: string;
        slPct?: string;
        copyExisting: boolean;
        tradingPairIds: string[];    // empty: every market the leader trades
        cumNetRealized: string;      // profit-share basis, not a balance
        hwm: string;
        consecutiveSkips: number;
        startedAt: string;
        stoppedAt?: string;
        stopReason?: CopyStopReason | (string & {});
        change: CopyRelationshipChange | (string & {});
        version?: number;
      };
    }
  | {
      eventType: "copy_skip";
      userId: string;
      data: {
        relationshipId: string;
        leaderWallet: string;
        leaderTradeId: string;
        leaderOrderId: string;
        tradingPairId: string;
        reason: CopySkipReason | (string & {});
        requestedQuantity: string;   // base units
        consecutiveSkips: number;
        detail?: string;
        version?: number;
      };
    };