useUserOrders

New in v0.5.5 - Real-time order tracking with WebSocket updates

Subscribe to real-time updates for all your orders. Automatically fetches initial orders via REST API and keeps them synchronized with WebSocket events.

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

const { 
  orders,
  loading,
  subscribed,
  error,
  clearError,
  refresh
} = useUserOrders(maxOrders);

Parameters

number

default:50

Maximum number of orders to keep in state (configurable history limit)

Return Values

Order[]

Array of user orders, automatically updated in real-time. Merged from REST API initial data and WebSocket updates.

boolean

true while fetching initial orders from REST API, false once loaded

boolean

true when WebSocket subscription is active, false otherwise

Error | null

Error object if something went wrong during fetch or subscription, null otherwise

() => void

Function to clear the current error state

() => Promise<void>

Reconcile a fresh REST read with live orders, preserving newer live data received while the request was in flight. When the incoming row carries version, the hook compares it first: it takes the REST row on incoming.version >= local.version and otherwise keeps local state. A versioned local row also wins over an unversioned response. Only when both sides lack version does the hook fall back to updatedAt; it retains live-only rows before applying the maxOrders limit.

Features

Automatic Deduplication

Orders are automatically deduplicated by order ID. If the same order appears in both REST API response and WebSocket updates, only one copy is kept with the most recent data.

Hybrid Data Loading

Initial Load: fetches recent orders via REST (getPaginatedOrders).
WebSocket Subscription: subscribes to the orders channel after the initial load.
Race Condition Prevention: the subscription only opens once the REST data is in, so an event cannot be overwritten by the response it raced.
Subscribe-time Snapshot: the channel’s snapshot carries every resting order, and the hook reconciles it into the list.

Applying the snapshot

The snapshot lists persisted resting orders only, so it is not the whole list this hook shows. It reconciles rows it carries directly, while an omitted locally resting row needs a point read:

A snapshot row is ranked against the row already held on version. It wins on snapshot.version >= local.version; a lower or absent snapshot version cannot overwrite versioned local state left by the previous connection. When both versions are absent, the snapshot keeps its pre-counter precedence without comparing incompatible timestamps.
A row still showing SUBMITTED or PARTIALLY_FILLED that the snapshot omits is retained while the hook calls sdk.trading.getOrder(orderId). Absence alone is ambiguous: the order may have filled or been cancelled during the outage, or persistence may lag a newer resting event the hook retained from the previous connection. Versioned results use the same ordering rule. When both rows are unversioned, the point result is accepted only if the held row did not change while the request was in flight; otherwise the hook preserves that intervening state and retries if it still needs resolution.
Terminal orders are untouched. The snapshot never carried them, so their absence says nothing.

selfTradePreventionMode is unreliable on this hook, as of v1.0.60. Rows seeded from REST carry it — the hook’s initial getPaginatedOrders load and its getOrder repairs both return it on Order. But orderFromEvent and orderFromSnapshotItem do not map it through, so a row that first appears from a live event or a subscribe-time snapshot omits it even though the underlying frame carries the value. Absence is therefore not evidence the order carried no override — unlike postOnly, where absence is meaningful. Where the requested mode matters, read it from sdk.trading.getOrder or the core sdk.ws.userOrders stream rather than from a row this hook built from stream data.

A snapshot row is layered over the order it supersedes, not substituted for it, so fields it does not carry — postOnly, expirationDate, positionSide, terminalReason, conditionalOrderId and the fee aggregates — survive.

conditionalOrderId — the take-profit or stop-loss conditional that placed a triggered close — is REST-only in the strictest sense: no order event and no snapshot row carries it, so a close this connection saw first over the socket carries no value for it. The hook does not schedule a read just because the field is missing — an order added from an OrderPlaced event is not enqueued for repair, and snapshot reconciliation leaves terminal rows alone — so the field appears only when some REST read of that order happens anyway: your own refetch, or one of the hook’s existing repair reads. Absent on orders the user placed, and on closes written before the field existed. The fee aggregates are the one thing that can go stale rather than missing, because they accumulate with fills. A snapshot reporting a fill this connection never saw schedules the same debounced REST re-read the hook already uses, which is their only source. If a snapshot row carries a future enum value this SDK cannot render, its validated orderId still marks that order present. The hook schedules a broad compatibility re-read for that row while continuing targeted resolution for distinct locally resting orders the snapshot omitted.

The broad REST repair is debounced and page-limited, but snapshot omissions use targeted reads because an older order may no longer fit on the newest list page. Those reads are deduplicated across repeated snapshots, limited to four in flight, and applied as each one succeeds, so a slow order does not delay its siblings. Each attempt releases its queue slot after ten seconds. If a point read fails or times out, the hook keeps the local row rather than treating that as proof the order is terminal; a later snapshot can retry it.

Real-time Updates

The hook listens to all order events:

OrderPlaced - New orders added to state
OrderPartiallyFilled - Order updated with fill amount
OrderFilled - Order marked as fully filled
OrderCancelled - Order marked as cancelled
OrderRejected - Order marked as rejected
OrderExpired - Order marked as expired

Authentication Required

This hook requires an authenticated session. Log in with the useAuth hook (or sdk.login(...)) before using it.

Basic Usage

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

function OrdersList() {
  const { orders, loading, subscribed, error } = useUserOrders(50);

  if (loading) {
    return <div>Loading orders...</div>;
  }

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return (
    <div>
      <p>WebSocket: {subscribed ? "Connected" : "Disconnected"}</p>
      <h2>Your Orders ({orders.length})</h2>
      {orders.map(order => (
        <div key={order.id}>
          <strong>{order.side}</strong> {order.quantity} @ {order.price}
          <span>Status: {order.status}</span>
        </div>
      ))}
    </div>
  );
}

Filter Active Orders

function ActiveOrders() {
  const { orders } = useUserOrders(100);

  const activeOrders = orders.filter(
    order => order.status === "SUBMITTED" || order.status === "PARTIALLY_FILLED"
  );

  return (
    <div>
      <h2>Active Orders ({activeOrders.length})</h2>
      {activeOrders.map(order => (
        <div key={order.id}>
          {order.side} {order.quantity} @ {order.price}
          {order.filledQuantity && order.filledQuantity !== "0" && (
            <span>Filled: {order.filledQuantity}</span>
          )}
        </div>
      ))}
    </div>
  );
}

Group by Trading Pair

function OrdersByPair() {
  const { orders } = useUserOrders(100);

  // Group by trading pair ID. To display human-readable symbols, fetch
  // trading pairs once via sdk.market.getPaginatedTradingPairs and build
  // (or maintain) a local id → symbol map.
  const byPair = orders.reduce((acc, order) => {
    const pair = order.tradingPairId;
    if (!acc[pair]) acc[pair] = [];
    acc[pair].push(order);
    return acc;
  }, {} as Record<string, typeof orders>);

  return (
    <div>
      {Object.entries(byPair).map(([pair, pairOrders]) => (
        <div key={pair}>
          <h3>{pair}</h3>
          <p>{pairOrders.length} orders</p>
          <ul>
            {pairOrders.map(order => (
              <li key={order.id}>
                {order.side} {order.quantity} @ {order.price} - {order.status}
              </li>
            ))}
          </ul>
        </div>
      ))}
    </div>
  );
}

Order History with Filters

function OrderHistory() {
  const { orders, loading } = useUserOrders(200);
  const [filter, setFilter] = useState<"all" | "active" | "filled" | "cancelled">("all");

  const filteredOrders = orders.filter(order => {
    switch (filter) {
      case "active":
        return order.status === "SUBMITTED" || order.status === "PARTIALLY_FILLED";
      case "filled":
        return order.status === "FILLED" || order.status === "SETTLED" || order.status === "SETTLED_ON_CHAIN";
      case "cancelled":
        return order.status === "CANCELLED";
      default:
        return true;
    }
  });

  return (
    <div>
      <div>
        <button onClick={() => setFilter("all")}>All ({orders.length})</button>
        <button onClick={() => setFilter("active")}>Active</button>
        <button onClick={() => setFilter("filled")}>Filled</button>
        <button onClick={() => setFilter("cancelled")}>Cancelled</button>
      </div>
      
      {loading ? (
        <div>Loading...</div>
      ) : (
        <div>
          {filteredOrders.map(order => (
            <div key={order.id}>
              <strong>{order.tradingPairId}</strong>
              <span>{order.side} {order.quantity}</span>
              {order.price && <span>@ {order.price}</span>}
              <span>{order.status}</span>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

Real-time Order Updates

function LiveOrderTracker({ orderId }: { orderId: string }) {
  const { orders, subscribed } = useUserOrders(50);

  const order = orders.find(o => o.id === orderId);

  if (!order) {
    return <div>Order not found</div>;
  }

  const fillPercentage = order.filledQuantity && order.quantity
    ? (parseFloat(order.filledQuantity) / parseFloat(order.quantity)) * 100
    : 0;

  return (
    <div>
      <div>
        <span>Live: {subscribed ? "Connected" : "Disconnected"}</span>
      </div>
      
      <h3>Order {order.id.slice(0, 8)}...</h3>
      <p>Status: {order.status}</p>
      <p>Side: {order.side}</p>
      <p>Quantity: {order.quantity}</p>
      {order.price && <p>Price: {order.price}</p>}
      
      {order.filledQuantity && order.filledQuantity !== "0" && (
        <div>
          <p>Filled: {order.filledQuantity} ({fillPercentage.toFixed(2)}%)</p>
          <div style={{ width: "100%", backgroundColor: "#e0e0e0", borderRadius: "4px" }}>
            <div 
              style={{ 
                width: `${fillPercentage}%`, 
                backgroundColor: "#4caf50", 
                height: "8px",
                borderRadius: "4px",
                transition: "width 0.3s ease"
              }} 
            />
          </div>
        </div>
      )}
      
      {order.averageFillPrice && (
        <p>Average Fill Price: {order.averageFillPrice}</p>
      )}
    </div>
  );
}

Error Handling with Retry

function OrdersWithRetry() {
  const { orders, loading, error, clearError, refresh } = useUserOrders(50);

  if (error) {
    return (
      <div>
        <p>Failed to load orders</p>
        <p>{error.message}</p>
        <button onClick={() => {
          clearError();
          refresh();
        }}>
          Retry
        </button>
      </div>
    );
  }

  if (loading) {
    return <div>Loading orders...</div>;
  }

  return (
    <div>
      <button onClick={refresh}>Refresh Orders</button>
      <div>
        {orders.map(order => (
          <div key={order.id}>
            {order.tradingPairId}: {order.side} {order.quantity}
          </div>
        ))}
      </div>
    </div>
  );
}

Complete Dashboard Example

import { useUserOrders } from "@0xmonaco/react";
import { formatDistanceToNow } from "date-fns";

function OrdersDashboard() {
  const { orders, loading, subscribed, error } = useUserOrders(100);

  const stats = {
    total: orders.length,
    active: orders.filter(o => o.status === "SUBMITTED" || o.status === "PARTIALLY_FILLED").length,
    filled: orders.filter(o => o.status === "FILLED" || o.status === "SETTLED" || o.status === "SETTLED_ON_CHAIN").length,
    cancelled: orders.filter(o => o.status === "CANCELLED").length,
  };

  const getStatusColor = (status: string) => {
    switch (status) {
      case "SUBMITTED":
      case "PARTIALLY_FILLED":
        return "text-blue-600";
      case "FILLED":
      case "SETTLED":
      case "SETTLED_ON_CHAIN":
        return "text-green-600";
      case "CANCELLED":
        return "text-gray-600";
      case "REJECTED":
        return "text-red-600";
      default:
        return "text-gray-600";
    }
  };

  if (loading) {
    return (
      <div className="animate-pulse">
        <div className="h-4 bg-gray-200 rounded w-3/4 mb-2"></div>
        <div className="h-4 bg-gray-200 rounded w-1/2"></div>
      </div>
    );
  }

  if (error) {
    return (
      <div className="bg-red-50 border border-red-200 rounded p-4">
        <p className="text-red-800">Failed to load orders</p>
        <p className="text-sm text-red-600">{error.message}</p>
      </div>
    );
  }

  return (
    <div className="space-y-4">
      {/* Connection Status */}
      <div className="flex items-center gap-2">
        <div className={`w-2 h-2 rounded-full ${subscribed ? "bg-green-500" : "bg-gray-400"}`} />
        <span className="text-sm text-gray-600">
          {subscribed ? "Real-time updates active" : "Disconnected"}
        </span>
      </div>

      {/* Stats */}
      <div className="grid grid-cols-4 gap-4">
        <div className="bg-white border border-gray-200 rounded-lg p-4">
          <p className="text-sm text-gray-600">Total Orders</p>
          <p className="text-2xl font-bold">{stats.total}</p>
        </div>
        <div className="bg-white border border-gray-200 rounded-lg p-4">
          <p className="text-sm text-gray-600">Active</p>
          <p className="text-2xl font-bold text-blue-600">{stats.active}</p>
        </div>
        <div className="bg-white border border-gray-200 rounded-lg p-4">
          <p className="text-sm text-gray-600">Filled</p>
          <p className="text-2xl font-bold text-green-600">{stats.filled}</p>
        </div>
        <div className="bg-white border border-gray-200 rounded-lg p-4">
          <p className="text-sm text-gray-600">Cancelled</p>
          <p className="text-2xl font-bold text-gray-600">{stats.cancelled}</p>
        </div>
      </div>

      {/* Orders List */}
      <div className="space-y-2">
        {orders.length === 0 ? (
          <p className="text-gray-500 text-center py-8">No orders yet</p>
        ) : (
          orders.map(order => (
            <div 
              key={order.id}
              className="bg-white border border-gray-200 rounded-lg p-4 hover:shadow-md transition-shadow"
            >
              <div className="flex items-start justify-between">
                <div className="flex-1">
                  <div className="flex items-center gap-2">
                    <span className="font-medium">{order.tradingPairId}</span>
                    <span className={`px-2 py-1 text-xs rounded ${
                      order.side === "BUY" ? "bg-green-100 text-green-800" : "bg-red-100 text-red-800"
                    }`}>
                      {order.side}
                    </span>
                    <span className={`text-sm ${getStatusColor(order.status)}`}>
                      {order.status}
                    </span>
                  </div>
                  
                  <div className="mt-2 text-sm text-gray-600">
                    <span>Quantity: {order.quantity}</span>
                    {order.price && <span className="ml-4">Price: {order.price}</span>}
                    {order.filledQuantity && order.filledQuantity !== "0" && (
                      <span className="ml-4">Filled: {order.filledQuantity}</span>
                    )}
                  </div>
                  
                  {order.averageFillPrice && (
                    <div className="mt-1 text-sm text-gray-500">
                      Avg Fill Price: {order.averageFillPrice}
                    </div>
                  )}
                </div>
                
                <div className="text-right text-sm text-gray-500">
                  {order.createdAt && (
                    <p>{formatDistanceToNow(new Date(order.createdAt), { addSuffix: true })}</p>
                  )}
                </div>
              </div>
            </div>
          ))
        )}
      </div>
    </div>
  );
}

export default OrdersDashboard;

Order Type Structure

interface Order {
  id: string;                           // Order UUID
  tradingPairId: string;              // Trading pair UUID
  orderType: OrderType;                // "LIMIT" | "MARKET"
  side: OrderSide;                      // "BUY" | "SELL"
  price?: string;                       // Order price (undefined for MARKET orders)
  quantity: string;                     // Order quantity
  filledQuantity: string;              // Amount filled so far
  averageFillPrice?: string;          // Average price of fills
  status: OrderStatus;                  // Order status
  tradingMode: TradingMode;            // "SPOT" | "MARGIN"
  timeInForce?: TimeInForce;          // "GTC" | "IOC" | "FOK"
  clientOrderId?: string;              // correlation handle echoed back as supplied; absent when the order carried none
  selfTradePreventionMode?: "CANCEL_MAKER" | "CANCEL_TAKER" | "CANCEL_BOTH" | "SKIP";  // the per-order override REQUESTED at placement — present on REST-seeded rows, absent on event/snapshot-derived ones (see the limitation below)
  createdAt: string;                   // ISO 8601 timestamp (UTC)
  updatedAt?: string;                  // ISO 8601 timestamp (UTC)
  version?: number;                    // opaque same-order revision; absent means unknown
  expirationDate?: string;             // expiry for a GTC order
  conditionalOrderId?: string;         // REST-only: the TP/SL conditional that placed this order

  // Perp-only fields (populated when this is a margin order)
  marginAccountId?: string;
  positionSide?: "LONG" | "SHORT" | "NONE";
  leverage?: string;
  reduceOnly?: boolean;
  postOnly?: boolean;                   // maker-only; absent for orders placed before the flag was persisted
  positionId?: string;
}

type OrderStatus =
  | "SUBMITTED"
  | "PARTIALLY_FILLED"
  | "FILLED"
  | "CANCELLED"
  | "REJECTED"
  | "EXPIRED"
  | "SETTLED"
  | "SETTLED_ON_CHAIN"; // terminal state — fully settled on-chain

Learn

Build

Libraries

APIs

Resources

Parameters

Return Values

Features

Automatic Deduplication

Hybrid Data Loading

Applying the snapshot

Real-time Updates

Authentication Required

Basic Usage

Filter Active Orders

Group by Trading Pair

Order History with Filters

Real-time Order Updates

Error Handling with Retry

Complete Dashboard Example

Order Type Structure

See Also

​Parameters

​Return Values

​Features

​Automatic Deduplication

​Hybrid Data Loading

​Applying the snapshot

​Real-time Updates

​Authentication Required

​Basic Usage

​Filter Active Orders

​Group by Trading Pair

​Order History with Filters

​Real-time Order Updates

​Error Handling with Retry

​Complete Dashboard Example

​Order Type Structure

​See Also

Parameters

Return Values

Features

Automatic Deduplication

Hybrid Data Loading

Applying the snapshot

Real-time Updates

Authentication Required

Basic Usage

Filter Active Orders

Group by Trading Pair

Order History with Filters

Real-time Order Updates

Error Handling with Retry

Complete Dashboard Example

Order Type Structure

See Also