> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xmonaco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# useUserOrders

> Real-time order tracking and updates via WebSocket

<Note>
  **New in v0.5.5** - Real-time order tracking with WebSocket updates
</Note>

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

```tsx theme={null}
import { useUserOrders } from "@0xmonaco/react";

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

## Parameters

<ParamField path="maxOrders" type="number" default={50}>
  Maximum number of orders to keep in state (configurable history limit)
</ParamField>

## Return Values

<ResponseField name="orders" type="Order[]">
  Array of user orders, automatically updated in real-time. Merged from REST API initial data and WebSocket updates.

  A TWAP's slices — the child orders a TWAP parent places, which carry `parentOrderId` — are not in this list, from any source: the order listing leaves them to their parent, so the hook drops slice rows from the REST page, from the `orders` snapshot and from live frames alike. Read a TWAP's slices with [`sdk.trading.listTwapOrderSlices`](/sdk/typescript/trades#twap-orders).
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while fetching initial orders from REST API, `false` once loaded
</ResponseField>

<ResponseField name="subscribed" type="boolean">
  `true` when WebSocket subscription is active, `false` otherwise
</ResponseField>

<ResponseField name="error" type="Error | null">
  Error object if something went wrong during fetch or subscription, `null` otherwise
</ResponseField>

<ResponseField name="clearError" type="() => void">
  Function to clear the current error state
</ResponseField>

<ResponseField name="refresh" type="() => 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.
</ResponseField>

## 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

1. **Initial Load**: fetches recent orders via REST (`getPaginatedOrders`).
2. **WebSocket Subscription**: subscribes to the `orders` channel after the initial load.
3. **Race Condition Prevention**: the subscription only opens once the REST data is in, so an event cannot be overwritten by the response it raced.
4. **Subscribe-time Snapshot**: the channel's [snapshot](/sdk/typescript/websockets#subscribe-time-snapshots) 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.

<Warning>
  **`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.
</Warning>

* A snapshot row is **layered** over the order it supersedes, not substituted for it, so fields the hook does not take from the row — `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.

`origin` says what placed an order: `"USER"`, `"LIQUIDATION"`, `"ADL"`, `"COPY"` or `"SYSTEM"`. A liquidation is a reduce-only IOC limit order, so `orderType`, `timeInForce` and `reduceOnly` read the same as an order the user placed; render the row as a liquidation from `origin === "LIQUIDATION"`. The hook takes it from the `OrderPlaced` acknowledgement, from every later order frame (fills, cancels, expiry), from every subscribe-time snapshot row and from every REST row, so an order the user placed reads `"USER"` from whichever arrives first. A frame only fills in a missing origin; it never replaces one the row already has. Because it never changes for an order, whichever side knows it supplies it: a row from a server that does not report it gains it on the next REST read, and a row that learned it from the socket keeps it against a REST row that does not report one. If both report one and they differ, the REST row is the stored order and its value stands. Absent means not reported, never `"USER"`.

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.

<Note>
  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.
</Note>

### Real-time Updates

The hook listens to all order events:

* `OrderPlaced` - New orders added to state. A new row starts at `filledQuantity: "0"` with no `averageFillPrice`, except the replacement of a partly filled order (an edit): it starts from the fill and average its `OrderPlaced` carries over from the original, as `getOrder` reports it
* `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`](/sdk/react/hooks/use-auth) hook (or `sdk.login(...)`) before using it.

## Basic Usage

```tsx theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
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

```typescript theme={null}
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"; absent on MARKET orders, which have none
  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
  origin?: "USER" | "LIQUIDATION" | "SYSTEM" | "ADL" | "COPY" | (string & {});  // what placed the order; label a liquidation from this, not from orderType

  // 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
```

## See Also

* [useTrade](/sdk/react/hooks/use-trade) - Place, cancel, and manage orders
* [useOrderbook](/sdk/react/hooks/use-orderbook) - Real-time orderbook updates
* [WebSocket API](/websocket#subscribe-to-all-user-orders) - Low-level userOrders WebSocket channel
* [TypeScript SDK](/sdk/typescript/websockets#orders-channel) - Core SDK WebSocket methods


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.