WebSockets

sdk.ws.orders(pairId, tradingMode, handler)                         // REQUIRES AUTH
sdk.ws.userOrders(handler)                                          // REQUIRES AUTH
sdk.ws.orderbook(pairId, tradingMode, magnitude, qMode, handler, onSnapshot?) // PUBLIC
sdk.ws.ohlcv(pairId, tradingMode, interval, handler, priceType?, onSnapshot?) // PUBLIC
sdk.ws.trades(pairId, handler, onSnapshot?)                         // PUBLIC
sdk.ws.marketLiquidations(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.rfq(handler)                                                 // REQUIRES AUTH (RFQ pushes, see RFQ)
sdk.ws.rfqTrades(pairId, handler, onSnapshot?)                      // PUBLIC (RFQ block prints)

// 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: "mainnet",
  seiRpcUrl: "https://evm-rpc.sei-apis.com", // public 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: "mainnet",
  seiRpcUrl: "https://evm-rpc.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: "mainnet",
  seiRpcUrl: "https://evm-rpc.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;       // null on a MARKET order, which has none
  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
  origin?: OrderOrigin | (string & {});  // what placed the order: "USER", "LIQUIDATION", "ADL" or "SYSTEM"
  placementTakerFeeBps?: string;    // Monaco taker fee rate fixed at placement, in bps; omitted for orders placed before rates were stored
  placementMakerFeeBps?: string;    // Monaco maker fee rate fixed at placement, in bps (negative = rebate); omitted likewise
}

const sdk = new MonacoSDK({
  ...,
  ws: {
    onReauthenticationRequired: ({ code }) => {
      // SESSION_INVALID: revoked/expired session. AUTH_FAILED: handshake rejected.
      // ACCOUNT_DEACTIVATED: the account is deactivated; a new login is refused too.
      console.warn("WebSocket session lost:", code);
      // ACCOUNT_RESTRICTED: the wallet is on the OFAC sanctions list.
      if (code === "ACCOUNT_DEACTIVATED" || code === "ACCOUNT_RESTRICTED") return; // terminal: surface it, do not sign in again
      void sdk.login(clientId);
    },
    onResync: ({ code }) => {
      void reconcileFromRest(code);
    },
  },
});

sdk.ws.getSubscriptionState(`trades:${pairId}`);
// "pending" until the Subscribed ack names it, then "subscribed"

const stop = sdk.ws.onSubscriptionChange(({ channel, state }) => {
  // "subscribed": the server confirmed a channel you still want.
  // "unsubscribed": the server confirmed an unsubscribe.
  console.log(channel, state);
});

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. The SDK keeps your handler
          // and re-sends the Subscribe once the connection authenticates, so
          // authenticate and leave the subscription alone.
          void reauthenticate();
          break;
        default:
          console.error("ws error", code, message, channel);
      }
    },
  },
});

const 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.000001, 0.00001, 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();

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

interface OrderbookLevel {
  price: string;
  quantity: string;
  orderCount: number;   // Orders at this price level
}

interface PriceChange {
  side: OrderSide | (string & {});
  oldPrice?: string;
  newPrice?: string;
  levelRemoved: boolean;
  levelAdded: boolean;
}

interface OrderbookEvent {
  tradingPairId: string;
  tradingMode: TradingMode | (string & {});
  bids: OrderbookLevel[];
  asks: OrderbookLevel[];
  bestBid?: string;
  bestAsk?: string;
  bidVolume?: string;
  askVolume?: string;
  priceChange?: PriceChange;
  baseDecimals: number;
  quoteDecimals: number;
  timestamp: string;    // UTC
  sequence: number;     // never compare across a snapshot or reconnect; see Book sequence
  bookSeq?: string;     // market-data source only: u64 as a decimal string; levels exact as of this sequence
  prevBookSeq?: string; // market-data source only: bookSeq of this server's previous event for the book; "0" before the first
}

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

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

const unsubscribe = sdk.ws.depth(
  pair.id,   // Trading pair ID
  "SPOT",    // Trading mode: "SPOT" or "MARGIN"
  (book: DepthBook) => {
    console.log("bookSeq", book.bookSeq, "stale", book.stale);
    console.log("best bid", book.bids[0], "best ask", book.asks[0]);
  },
  {
    onResync: (reason) => console.warn("depth rebuilding:", reason),
    onError: ({ code, message }) => console.error("depth refused:", code, message),
  },
);

// Cleanup
unsubscribe();

interface DepthLevel {
  price: string;       // decimal string
  quantity: string;    // absolute quantity resting at the price
  orderCount: number;
}

interface DepthBook {
  tradingPairId: string;
  tradingMode: TradingMode | (string & {});
  bookSeq: string;          // u64 as a decimal string; compare with BigInt
  bids: DepthLevel[];       // best (highest) first
  asks: DepthLevel[];       // best (lowest) first
  bidsComplete: boolean;    // false: levels beyond the last one held are unknown
  asksComplete: boolean;
  stale: boolean;           // the latest frame was published while the service lagged
  timestampMs?: number;     // exchange time of the latest frame; absent right after a snapshot
}

const unsubscribe = sdk.ws.bbo(pair.id, "SPOT", (bbo) => {
  console.log(bbo.bestBid, bbo.bidQty, bbo.bestAsk, bbo.askQty, bbo.stale);
});

interface Bbo {
  tradingPairId: string;
  tradingMode: TradingMode | (string & {});
  bookSeq: string;
  bestBid: string | null;   // null when the side is empty
  bidQty: string | null;
  bestAsk: string | null;
  askQty: string | null;
  stale: boolean;
  timestampMs?: number;
}

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 { OHLCVSnapshotCandle } from "@0xmonaco/types";

const candles = new Map<number, OHLCVSnapshotCandle>();

const unsubscribe = sdk.ws.ohlcv(
  pair.id,
  "SPOT",
  "1m",
  (event) => {
    // Upsert by period start: a live candle replaces the one with the same `T`.
    candles.set(event.candlestick.T, event.candlestick);
  },
  undefined,
  (snapshot) => {
    for (const candle of snapshot) candles.set(candle.T, candle);
  }
);

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

interface OHLCVEvent {
  tradingPairId: string;
  interval: Interval | (string & {});
  tradingMode: TradingMode | (string & {});
  priceType?: "trade" | "mark" | "reference" | (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
  openInterestBase?: string | null;      // One-sided LONG open interest in base-asset units, sampled at or before the candle end
  openInterestNotional?: string | null;  // One-sided LONG quote notional, valued at that same sample's paired price (not the close)
}

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);
  },
  (trades) => {
    // Optional: the market's newest 50 trades, newest first
    console.log("Recent trades:", trades.length);
  }
);

// 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;
  };
  // Present when trades are served from the market-data service:
  seq?: number;                    // durable-log sequence of the step that executed the trade
  matchIndex?: number;             // the trade's index among that step's fills
  prevSeq?: number;                // the market's previous trade
  prevMatchIndex?: number | null;  // null when no previous trade is known (prevSeq need not be 0)
}

const unsubscribe = sdk.ws.trades(
  pair.id,
  (event) => record(event),
  (trades, meta) => {
    seedRecentTrades(trades);
    console.log("continues from", meta?.cursor);  // { seq, matchIndex } | null | undefined
  },
  {
    onGap: ({ expected, received }) =>
      console.warn("trade gap: expected link to", expected, "got", received),
  },
);

const unsubscribe = sdk.ws.marketLiquidations(tradingPairId, (event) => {
  console.log(event.data.wallet, event.data.side, event.data.markNotional, event.data.quoteAssetSymbol);
});

interface MarketLiquidationEvent {
  eventType: "liquidation_event";
  tradingPairId: string;
  data: {
    eventId: string;
    timestamp: number;       // Unix milliseconds
    wallet: string;
    side: "LONG" | "SHORT";
    positionSize: string;    // base-asset units
    markPrice: string;       // quote units per base unit, captured at event time
    markNotional: string;    // positionSize × markPrice, in quote units
    quoteAssetSymbol: string;
  };
}

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

const unsubscribe = sdk.ws.balances((event) => {
  const { tokenSymbol, available, locked, total, reason, version } = event.data;
  console.log(reason, tokenSymbol, available, locked, total, version);
});

// Cleanup
unsubscribe();

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

interface UserBalanceEvent {
  eventType: "balance_update";
  userId: string;
  data: {
    tokenAddress: string;           // Token contract address
    tokenSymbol: string | null;     // e.g. "USDC"; null only when the token is not a configured asset
    available: string;              // Available balance (normalized)
    availableRaw: string;           // Available balance (raw)
    locked: string;                 // Locked in orders or pending operations (normalized)
    lockedRaw: string;              // Locked (raw)
    total: string;                  // Total balance (normalized)
    totalRaw: string;               // Total balance (raw)
    version?: number;               // Durable spot-row revision; absent on legacy frames
    reason: BalanceUpdateReason | (string & {});
    referenceId: string | null;     // Related entity, e.g. an order or deposit
    updatedAt: string;              // Display only; never use it to order balance state
  };
}

// 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
  // unlock, entryType "UNLOCK" with transactionType "TRADE" (uppercase). 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?.toLowerCase() === "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" | "UNLOCK" (order unlocks) — compare case-insensitively
    transactionType: string;       // free-form; live: "deposit" | "withdrawal" | "funding" | "TRADE" (order unlocks; the reason starts `description`). History adds fill and fee rows 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 (e.g. "Order" on an order unlock)
    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.entryType.toUpperCase() === "UNLOCK") {
    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;
  }
}