@0xmonaco/react 1.0.47 → 1.0.50-develop.9c1b239

package/dist/hooks/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./useAuth";
 export * from "./useFees";
+export * from "./useInstruments";
 export * from "./useMarket";
 export * from "./useMonaco";
 export * from "./useOHLCV";

package/dist/hooks/index.js

@@ -1,5 +1,6 @@
 export * from "./useAuth";
 export * from "./useFees";
+export * from "./useInstruments";
 export * from "./useMarket";
 export * from "./useMonaco";
 export * from "./useOHLCV";

package/dist/hooks/useInstruments/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export { useInstruments } from "./useInstruments";

package/dist/hooks/useInstruments/index.js

@@ -0,0 +1,2 @@
+export * from "./types";
+export { useInstruments } from "./useInstruments";

package/dist/hooks/useInstruments/types.d.ts

@@ -0,0 +1,34 @@
+import type { InstrumentEventData } from "@0xmonaco/types";
+/**
+ * Return type for the useInstruments hook
+ */
+export interface UseInstrumentsReturn {
+    /**
+     * Current configuration of every market seen on the channel, ordered by
+     * symbol and then trading pair id. Delisted markets stay in the list carrying
+     * `isActive: false` — filter on `isActive` for the tradable set.
+     */
+    instruments: InstrumentEventData[];
+    /** The same entries keyed by trading pair UUID, for direct lookup */
+    instrumentsByPair: Record<string, InstrumentEventData>;
+    /**
+     * Whether a subscription to the instrument channel is currently registered.
+     * This is not a connection indicator: the client accepts subscriptions while
+     * the socket is down and sends them on the next open, so `true` means
+     * "registered", not "receiving".
+     */
+    subscribed: boolean;
+    /**
+     * A rejected subscription request. The core helper validates its arguments
+     * synchronously — passing an empty `tradingPairId` is the reachable case — so
+     * treat this as a bad-usage signal.
+     *
+     * It is deliberately NOT a transport signal: the client registers handlers
+     * regardless of socket state, and logs malformed-frame failures internally,
+     * so connection loss and unparseable frames never appear here. Drive
+     * connection UI from the client's own status/resync callbacks instead.
+     */
+    error: Error | null;
+    /** Clear the current error state */
+    clearError: () => void;
+}

package/dist/hooks/useInstruments/useInstruments.d.ts

@@ -0,0 +1,27 @@
+import type { UseInstrumentsReturn } from "./types";
+/**
+ * Hook for subscribing to real-time instrument configuration via WebSocket (public)
+ *
+ * On subscribe the channel delivers a snapshot of the current active markets
+ * (one `listing` frame each), then live listing, delisting, halt/unhalt and
+ * config-change frames. Every frame carries a market's FULL current
+ * configuration rather than a delta, so state is kept as a terminal-state
+ * entry per trading pair: each event replaces that market's entry outright.
+ *
+ * A delisted market keeps its entry with `isActive: false` rather than
+ * disappearing, so a consumer can distinguish "no longer tradable" from "never
+ * seen"; read `instruments.filter((instrument) => instrument.isActive)` for the
+ * tradable set.
+ *
+ * Caveat on reconnect: the server's post-reconnect snapshot covers the markets
+ * active at that moment, and the core helper delivers it as ordinary per-market
+ * events. A market delisted while the socket was down is simply absent from
+ * that snapshot, so its entry here keeps its pre-outage state until the market
+ * next emits. Closing that needs a snapshot-boundary signal the channel's
+ * handler contract does not currently carry.
+ *
+ * @param tradingPairId - Optional trading pair UUID to filter on; omit to
+ *   receive every market. An empty string is rejected by the core helper and is
+ *   surfaced through `error`.
+ */
+export declare function useInstruments(tradingPairId?: string): UseInstrumentsReturn;

package/dist/hooks/useInstruments/useInstruments.js

@@ -0,0 +1,94 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useMonacoSDK } from "../useMonaco";
+const IDLE = {
+    source: undefined,
+    tradingPairId: undefined,
+    byPair: {},
+    subscribed: false,
+    error: null,
+};
+/** Shared empty map, so an out-of-scope render keeps a stable identity. */
+const NO_INSTRUMENTS = {};
+/**
+ * Hook for subscribing to real-time instrument configuration via WebSocket (public)
+ *
+ * On subscribe the channel delivers a snapshot of the current active markets
+ * (one `listing` frame each), then live listing, delisting, halt/unhalt and
+ * config-change frames. Every frame carries a market's FULL current
+ * configuration rather than a delta, so state is kept as a terminal-state
+ * entry per trading pair: each event replaces that market's entry outright.
+ *
+ * A delisted market keeps its entry with `isActive: false` rather than
+ * disappearing, so a consumer can distinguish "no longer tradable" from "never
+ * seen"; read `instruments.filter((instrument) => instrument.isActive)` for the
+ * tradable set.
+ *
+ * Caveat on reconnect: the server's post-reconnect snapshot covers the markets
+ * active at that moment, and the core helper delivers it as ordinary per-market
+ * events. A market delisted while the socket was down is simply absent from
+ * that snapshot, so its entry here keeps its pre-outage state until the market
+ * next emits. Closing that needs a snapshot-boundary signal the channel's
+ * handler contract does not currently carry.
+ *
+ * @param tradingPairId - Optional trading pair UUID to filter on; omit to
+ *   receive every market. An empty string is rejected by the core helper and is
+ *   surfaced through `error`.
+ */
+export function useInstruments(tradingPairId) {
+    const { sdk } = useMonacoSDK();
+    const ws = sdk?.ws;
+    const [subscription, setSubscription] = useState(IDLE);
+    // Entries only count while they belong to the subscription the caller is
+    // asking for right now; the effect below realigns them a tick later.
+    const inScope = subscription.source === ws && subscription.tradingPairId === tradingPairId;
+    const clearError = useCallback(() => {
+        setSubscription((prev) => (prev.error === null ? prev : { ...prev, error: null }));
+    }, []);
+    useEffect(() => {
+        if (!ws) {
+            setSubscription({ ...IDLE, tradingPairId });
+            return;
+        }
+        // Only a frame that belongs to *this* subscription may touch state — a
+        // late arrival from a torn-down one must not resurrect old markets.
+        const belongsToThisSubscription = (prev) => prev.source === ws && prev.tradingPairId === tradingPairId;
+        // Claim the scope before subscribing so the first frame, whenever it lands,
+        // already has somewhere in-scope to go.
+        setSubscription({ source: ws, tradingPairId, byPair: {}, subscribed: false, error: null });
+        // `instruments` throws synchronously on a missing handler or an empty pair
+        // id — surface that through `error` instead of letting it escape the effect.
+        let unsubscribe;
+        try {
+            unsubscribe = ws.instruments((event) => {
+                setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, byPair: { ...prev.byPair, [event.tradingPairId]: event.data } } : prev));
+            }, tradingPairId);
+            setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, subscribed: true } : prev));
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, subscribed: false, error } : prev));
+        }
+        return () => {
+            unsubscribe?.();
+            setSubscription((prev) => (belongsToThisSubscription(prev) ? { ...prev, subscribed: false } : prev));
+        };
+    }, [ws, tradingPairId]);
+    const instrumentsByPair = inScope ? subscription.byPair : NO_INSTRUMENTS;
+    // Sorted with plain codepoint comparison rather than `localeCompare`, so the
+    // order does not shift with the runtime locale, and tie-broken on the pair id
+    // because a spot and a perp market can carry the same symbol.
+    const instruments = useMemo(() => Object.values(instrumentsByPair).sort((left, right) => {
+        if (left.symbol !== right.symbol)
+            return left.symbol < right.symbol ? -1 : 1;
+        if (left.tradingPairId === right.tradingPairId)
+            return 0;
+        return left.tradingPairId < right.tradingPairId ? -1 : 1;
+    }), [instrumentsByPair]);
+    return {
+        instruments,
+        instrumentsByPair,
+        subscribed: inScope && subscription.subscribed,
+        error: inScope ? subscription.error : null,
+        clearError,
+    };
+}

package/dist/hooks/useUserOrders/useUserOrders.d.ts

@@ -1,11 +1,31 @@
+import type { Order, OrderEvent } from "@0xmonaco/types";
 import type { UseUserOrdersReturn } from "./types";
+export declare function useUserOrders(maxOrders?: number): UseUserOrdersReturn;
 /**
- * Hook for subscribing to real-time user order events via WebSocket (authenticated)
+ * Reconcile a REST read against live state, last-writer-wins by `updatedAt`.
+ *
+ * The resync runs with the subscription open, so `fetched` may already be stale
+ * by the time it lands. Three cases:
  *
- * Fetches initial orders from the REST API, then subscribes to real-time updates.
- * Requires authentication - the user must be logged in with a session key.
- * User is identified on the backend from the signed session-key handshake.
+ * - In both: keep whichever `updatedAt` is later, so a fill that arrived over
+ *   the socket mid-request is not rolled back by an older REST row. Ties keep
+ *   the live row, which cannot be older than the response.
+ * - Live only: keep it. Either it was placed over the socket after the read
+ *   started, or it is an older row the page no longer reaches — the two are
+ *   indistinguishable here, which is why the cap is applied by age below
+ *   rather than by which side a row came from.
+ * - REST only: take it. This is the order the resync exists to recover.
  *
- * @param maxOrders - Maximum number of orders to keep in state (default: 50)
+ * The union is then sorted newest-first by `createdAt` and truncated to
+ * `limit`, so the row dropped at the cap is the genuinely oldest one. A missing
+ * or unparseable `createdAt` sorts last rather than to the top.
  */
-export declare function useUserOrders(maxOrders?: number): UseUserOrdersReturn;
+export declare function mergeOrders(current: Order[], fetched: Order[], limit: number): Order[];
+/**
+ * Create an Order object from an OrderPlaced event
+ */
+export declare function orderFromEvent(event: OrderEvent): Order | null;
+/**
+ * Update an existing Order with data from a WebSocket event
+ */
+export declare function updateOrderFromEvent(order: Order, event: OrderEvent): Order;

package/dist/hooks/useUserOrders/useUserOrders.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { useMonacoSDK } from "../useMonaco";
 /**
  * Hook for subscribing to real-time user order events via WebSocket (authenticated)
@@ -9,6 +9,8 @@ import { useMonacoSDK } from "../useMonaco";
  *
  * @param maxOrders - Maximum number of orders to keep in state (default: 50)
  */
+/** Debounce for the REST re-read after an undescribable event, in milliseconds. */
+const RESYNC_DEBOUNCE_MS = 1000;
 export function useUserOrders(maxOrders = 50) {
     const { sdk } = useMonacoSDK();
     const [orders, setOrders] = useState([]);
@@ -16,42 +18,131 @@ export function useUserOrders(maxOrders = 50) {
     const [error, setError] = useState(null);
     const [subscribed, setSubscribed] = useState(false);
     const clearError = useCallback(() => setError(null), []);
-    const fetchOrders = useCallback(async () => {
+    const resyncTimer = useRef(null);
+    /**
+     * Bumped by effect cleanup. Every REST read — the initial load and the resync
+     * alike — captures this when it starts and drops its result if it no longer
+     * matches, so a response still in flight when the SDK changed or the
+     * component unmounted cannot write rows belonging to the previous client.
+     */
+    const readGeneration = useRef(0);
+    /** Read the newest page of orders. Shared by the initial load and the resync. */
+    const readOrders = useCallback(async () => {
+        if (!sdk?.trading)
+            return null;
+        // Cursor mode (pageToken "") reads the newest rows first, which is all
+        // this hook needs; legacy page-number mode is deprecated.
+        const response = await sdk.trading.getPaginatedOrders({
+            pageSize: maxOrders,
+            pageToken: "",
+        });
+        // Deduplicate the paginated orders by id, keeping the first occurrence.
+        const seenIds = new Set();
+        const dedupedOrders = [];
+        for (const order of response.orders) {
+            if (!seenIds.has(order.id)) {
+                seenIds.add(order.id);
+                dedupedOrders.push(order);
+            }
+        }
+        return dedupedOrders.slice(0, maxOrders);
+    }, [sdk?.trading, maxOrders]);
+    /**
+     * Read the list and apply it, either owning it outright or reconciling.
+     *
+     * `replace` is only correct BEFORE the subscription opens: the initial load
+     * runs first by design, so nothing newer can exist to lose. Every other
+     * caller runs with the socket live and must `reconcile`, or an event arriving
+     * while the request is in flight is overwritten by an older snapshot.
+     */
+    const load = useCallback(async (mode) => {
         if (!sdk?.trading)
             return;
+        const generation = readGeneration.current;
+        // A read belonging to a previous client must not write ANY of this state:
+        // not the rows, not the error, and not the loading flag. Clearing
+        // `loading` from a stale request would mark the hook loaded while the new
+        // client's read is still running — showing an empty list as though it
+        // were the answer — and a stale rejection would leave `error` set after
+        // the new load had already succeeded.
+        const current = () => generation === readGeneration.current;
         setLoading(true);
         try {
-            // Cursor mode (pageToken "") reads the newest rows first, which is all
-            // this hook needs; legacy page-number mode is deprecated.
-            const response = await sdk.trading.getPaginatedOrders({
-                pageSize: maxOrders,
-                pageToken: "",
-            });
-            // Deduplicate the paginated orders by id, keeping the first occurrence.
-            const seenIds = new Set();
-            const dedupedOrders = [];
-            for (const order of response.orders) {
-                if (!seenIds.has(order.id)) {
-                    seenIds.add(order.id);
-                    dedupedOrders.push(order);
-                }
+            const rows = await readOrders();
+            if (rows && current()) {
+                setOrders((prev) => (mode === "replace" ? rows : mergeOrders(prev, rows, maxOrders)));
             }
-            setOrders(dedupedOrders.slice(0, maxOrders));
         }
         catch (err) {
-            setError(err instanceof Error ? err : new Error(String(err)));
+            if (current())
+                setError(err instanceof Error ? err : new Error(String(err)));
         }
         finally {
-            setLoading(false);
+            if (current())
+                setLoading(false);
         }
-    }, [sdk?.trading, maxOrders]);
-    // Manual refresh function
+    }, [sdk?.trading, readOrders, maxOrders]);
+    const fetchOrders = useCallback(() => load("replace"), [load]);
+    /**
+     * Manual refresh. Reconciles rather than replaces: unlike the initial load
+     * this is public and can be called at any time, including with the
+     * subscription open, so a fill arriving mid-request must not be rolled back
+     * by the older snapshot the request returns.
+     */
     const refresh = useCallback(async () => {
-        await fetchOrders();
-    }, [fetchOrders]);
+        await load("reconcile");
+    }, [load]);
+    /**
+     * Re-read the list from REST after an event this SDK version cannot describe.
+     *
+     * `orderFromEvent` declines an `OrderPlaced` whose `orderType`, `side` or
+     * `tradingMode` is a value this version does not know, rather than
+     * relabelling it. Without this the order would then be missing from the list
+     * indefinitely — it exists on the server, and no later event adds it, because
+     * every subsequent event for it takes the "update an existing order" path and
+     * finds nothing to update.
+     *
+     * Deliberately NOT `fetchOrders`. This runs while the subscription is live,
+     * so unlike the initial load it cannot own the list: it must not raise
+     * `loading` (consumers read that as the initial load and would flash a
+     * spinner), and it must not replace the list wholesale (an event landing
+     * while the request is in flight would be overwritten by an older snapshot —
+     * the very race the initial load avoids by subscribing only after it
+     * completes). It merges instead, last-writer-wins by `updatedAt`, the same
+     * reconciliation the SDK documents for `onResync`.
+     *
+     * Debounced and coalesced: a deploy that adds an order type produces a burst
+     * of declines, and one REST read repairs the whole burst. A failure is
+     * swallowed rather than surfaced through `error`, which describes the load.
+     */
+    const scheduleResync = useCallback(() => {
+        if (resyncTimer.current)
+            return;
+        const generation = readGeneration.current;
+        resyncTimer.current = setTimeout(() => {
+            resyncTimer.current = null;
+            void readOrders()
+                .then((rows) => {
+                // Clearing the timer cannot cancel a read that already started, so
+                // the generation is what invalidates it.
+                if (rows && generation === readGeneration.current) {
+                    setOrders((prev) => mergeOrders(prev, rows, maxOrders));
+                }
+            })
+                .catch(() => {
+                // A repair that fails leaves the list exactly as it was.
+            });
+        }, RESYNC_DEBOUNCE_MS);
+    }, [readOrders, maxOrders]);
     useEffect(() => {
         if (!sdk?.ws || !sdk?.trading) {
             setSubscribed(false);
+            // The previous effect's cleanup has already bumped `readGeneration`, so
+            // any read still in flight will now decline to write — including its
+            // `setLoading(false)`. With no client left to start a replacement read,
+            // nothing would ever clear the flag, and the hook would report loading
+            // forever. Clear it here instead.
+            setLoading(false);
             return;
         }
         setOrders([]);
@@ -60,12 +151,27 @@ export function useUserOrders(maxOrders = 50) {
         const limit = Number.isFinite(maxOrders) ? maxOrders : 50;
         // Fetch initial orders via REST API, then subscribe to WebSocket updates
         let unsubscribe;
+        // Cleanup cannot cancel a fetch already in flight. Without this, a slow
+        // initial read could resolve after the SDK changed or the component
+        // unmounted and then install a subscription on the OLD client — after
+        // cleanup had already run with `unsubscribe` still unset, so that handler
+        // would never be removed.
+        let cancelled = false;
+        const generation = readGeneration.current;
         fetchOrders()
             .then(() => {
+            if (cancelled || generation !== readGeneration.current)
+                return;
             // Subscribe to WebSocket order updates after initial data is loaded
             // This prevents race conditions where WS events could be overwritten by REST response
             try {
                 unsubscribe = sdk.ws.userOrders((event) => {
+                    // Built OUTSIDE the state updater: an updater must stay pure, and
+                    // React may invoke it more than once. `null` here means the event
+                    // is an `OrderPlaced` this version cannot describe.
+                    const placed = event.eventType === "OrderPlaced" ? orderFromEvent(event) : null;
+                    if (event.eventType === "OrderPlaced" && !placed)
+                        scheduleResync();
                     setOrders((prev) => {
                         const orderId = event.orderId;
                         // Check if this order already exists
@@ -80,11 +186,8 @@ export function useUserOrders(maxOrders = 50) {
                             return newOrders;
                         }
                         // New order - add to the beginning if it's an OrderPlaced event
-                        if (event.eventType === "OrderPlaced") {
-                            const newOrder = orderFromEvent(event);
-                            if (newOrder) {
-                                return [newOrder, ...prev].slice(0, limit);
-                            }
+                        if (placed) {
+                            return [placed, ...prev].slice(0, limit);
                         }
                         return prev;
                     });
@@ -102,34 +205,172 @@ export function useUserOrders(maxOrders = 50) {
             setLoading(false);
         });
         return () => {
+            cancelled = true;
             unsubscribe?.();
+            if (resyncTimer.current) {
+                clearTimeout(resyncTimer.current);
+                resyncTimer.current = null;
+            }
+            // Invalidates any read already in flight; see `readGeneration`.
+            readGeneration.current += 1;
             setSubscribed(false);
         };
-    }, [sdk?.ws, sdk?.trading, maxOrders, fetchOrders]);
+    }, [sdk?.ws, sdk?.trading, maxOrders, fetchOrders, scheduleResync]);
     return { orders, loading, subscribed, error, clearError, refresh };
 }
+/**
+ * Runtime membership test for the closed `OrderStatus` union.
+ *
+ * `@0xmonaco/core` never validates the order-event `status` against a value
+ * list — it hands the wire string through, so an unfamiliar value cannot drop
+ * the whole frame (0XM-2627/0XM-2628). The REST `Order` model this hook builds
+ * has a closed `OrderStatus`, so an unrecognized value has to be recognized as
+ * such here rather than cast in, where it would corrupt the model for every
+ * consumer that branches on `order.status`.
+ *
+ * A `Record<OrderStatus, true>` rather than an array: adding a variant to
+ * `OrderStatus` is a compile error here until it is listed, so this cannot
+ * fall behind the union it mirrors.
+ */
+const ORDER_STATUSES = {
+    SUBMITTED: true,
+    PARTIALLY_FILLED: true,
+    FILLED: true,
+    SETTLED_ON_CHAIN: true,
+    SETTLED: true,
+    CANCELLED: true,
+    REJECTED: true,
+    EXPIRED: true,
+};
+/**
+ * The other closed unions this hook converts into the REST `Order`. Same
+ * contract as `ORDER_STATUSES`: every one of these arrives on the same
+ * unvalidated WebSocket payload, so an unrecognized value in any of them would
+ * corrupt the model just as an unknown status would. `Record<T, true>` again,
+ * so adding a variant to any union is a compile error here until it is listed.
+ */
+const ORDER_TYPES = { LIMIT: true, MARKET: true };
+const ORDER_SIDES = { BUY: true, SELL: true };
+const TRADING_MODES = { SPOT: true, MARGIN: true };
+const TIMES_IN_FORCE = { GTC: true, IOC: true, FOK: true, GTD: true };
+/**
+ * Narrow a widened WebSocket value back to its closed union, or `undefined`.
+ *
+ * `Object.hasOwn`, not `in`: `in` walks the prototype chain, so a wire value of
+ * "toString" / "constructor" / "valueOf" would test true and be cast into the
+ * closed union — the corruption these helpers exist to prevent.
+ */
+function asKnown(known, value) {
+    return typeof value === "string" && Object.hasOwn(known, value) ? value : undefined;
+}
+function asOrderStatus(value) {
+    return asKnown(ORDER_STATUSES, value);
+}
+/** Milliseconds since epoch for an order's `updatedAt`, or `NaN` if unparseable. */
+function updatedAtMs(order) {
+    return Date.parse(order.updatedAt ?? "");
+}
+/**
+ * Sort key for the list's newest-first order. An unparseable or absent
+ * `createdAt` sorts oldest rather than jumping to the top.
+ */
+function createdAtMs(order) {
+    const parsed = Date.parse(order.createdAt ?? "");
+    return Number.isNaN(parsed) ? Number.NEGATIVE_INFINITY : parsed;
+}
+/**
+ * Reconcile a REST read against live state, last-writer-wins by `updatedAt`.
+ *
+ * The resync runs with the subscription open, so `fetched` may already be stale
+ * by the time it lands. Three cases:
+ *
+ * - In both: keep whichever `updatedAt` is later, so a fill that arrived over
+ *   the socket mid-request is not rolled back by an older REST row. Ties keep
+ *   the live row, which cannot be older than the response.
+ * - Live only: keep it. Either it was placed over the socket after the read
+ *   started, or it is an older row the page no longer reaches — the two are
+ *   indistinguishable here, which is why the cap is applied by age below
+ *   rather than by which side a row came from.
+ * - REST only: take it. This is the order the resync exists to recover.
+ *
+ * The union is then sorted newest-first by `createdAt` and truncated to
+ * `limit`, so the row dropped at the cap is the genuinely oldest one. A missing
+ * or unparseable `createdAt` sorts last rather than to the top.
+ */
+export function mergeOrders(current, fetched, limit) {
+    const fetchedIds = new Set(fetched.map((order) => order.id));
+    const currentById = new Map(current.map((order) => [order.id, order]));
+    const reconciled = fetched.map((incoming) => {
+        const live = currentById.get(incoming.id);
+        if (!live)
+            return incoming;
+        const liveAt = updatedAtMs(live);
+        const incomingAt = updatedAtMs(incoming);
+        // An unparseable timestamp on either side is not evidence of staleness, so
+        // prefer the live row rather than silently rolling it back.
+        if (Number.isNaN(liveAt) || Number.isNaN(incomingAt))
+            return live;
+        return liveAt >= incomingAt ? live : incoming;
+    });
+    const liveOnly = current.filter((order) => !fetchedIds.has(order.id));
+    // Cap by RECENCY, not by side. Prepending every live-only row and slicing
+    // evicted the tail of the REST page, and a live-only row is not always the
+    // newer one: once the list is at `limit`, a row REST no longer returns is the
+    // OLDEST held, so the recovered order this resync exists to insert was
+    // precisely the row being dropped — at `limit` 1 it never landed at all.
+    // Sorting newest-first keeps a genuinely new socket row ahead of the page and
+    // lets a genuinely old one fall off, which is what the cap means.
+    return [...liveOnly, ...reconciled].sort((a, b) => createdAtMs(b) - createdAtMs(a)).slice(0, limit);
+}
 /**
  * Create an Order object from an OrderPlaced event
  */
-function orderFromEvent(event) {
+export function orderFromEvent(event) {
     if (event.eventType !== "OrderPlaced")
         return null;
     const { data } = event;
     const tradingPairId = data.tradingPairId || data.tradingPair;
     if (!tradingPairId)
         return null;
+    // The closed REST unions this event must supply for the order to be
+    // describable at all. `@0xmonaco/core` passes an unrecognized value straight
+    // through during version skew, and there is no honest default for any of
+    // these: defaulting a future `STOP` to `LIMIT`, or an unknown side to `BUY`,
+    // renders an order as something it is not — the worst outcome in a trading
+    // UI, and worse than not rendering it. So the order is declined here the same
+    // way one with no trading pair is. Declining alone would leave the order
+    // missing indefinitely, so `useUserOrders` schedules a debounced REST re-read
+    // when this happens and picks the order up from there.
+    const orderType = asKnown(ORDER_TYPES, data.orderType);
+    const side = asKnown(ORDER_SIDES, data.side);
+    const tradingMode = asKnown(TRADING_MODES, data.tradingMode);
+    if (!orderType || !side || !tradingMode)
+        return null;
     return {
         id: event.orderId,
         tradingPairId: tradingPairId,
-        orderType: (data.orderType || "LIMIT"),
-        side: (data.side || "BUY"),
+        orderType,
+        side,
         price: data.price,
         quantity: data.quantity || "0",
         filledQuantity: "0",
         averageFillPrice: undefined,
-        status: data.status,
-        tradingMode: (data.tradingMode || "SPOT"),
-        timeInForce: data.timeInForce,
+        // Not an invented value: an `OrderPlaced` event IS a submitted order by
+        // construction, whatever status string it carries.
+        status: asOrderStatus(data.status) ?? "SUBMITTED",
+        tradingMode,
+        // Optional on the model, so an unrecognized value is simply absent —
+        // there is no honest default to invent for it.
+        timeInForce: asKnown(TIMES_IN_FORCE, data.timeInForce),
+        // Read from the ACKNOWLEDGEMENT only, and then left alone:
+        // `updateOrderFromEvent` spreads the existing order and never rewrites this
+        // field, so the value learned here survives every later event. That is
+        // load-bearing rather than incidental — the maker fill does not carry
+        // `postOnly`, and a post-only order rests and therefore fills as a maker,
+        // so re-deriving the field per event would clear it on the one event a
+        // post-only order most often produces and disagree with REST. Only a real
+        // boolean is taken: anything else is not evidence the order was post-only.
+        postOnly: typeof data.postOnly === "boolean" ? data.postOnly : undefined,
         createdAt: event.timestamp,
         updatedAt: event.timestamp,
     };
@@ -137,12 +378,16 @@ function orderFromEvent(event) {
 /**
  * Update an existing Order with data from a WebSocket event
  */
-function updateOrderFromEvent(order, event) {
+export function updateOrderFromEvent(order, event) {
     const data = event.data;
-    // Prefer status from event data when available, fall back to event-type-based mapping
+    // Prefer a RECOGNIZED status from the event data, else fall back to the
+    // event-type mapping. An unrecognized status falls through rather than being
+    // cast in: the event type still says what happened, which is a better answer
+    // for the UI than a string no consumer can branch on.
     let newStatus = order.status;
-    if ("status" in data && data.status) {
-        newStatus = data.status;
+    const reportedStatus = "status" in data ? asOrderStatus(data.status) : undefined;
+    if (reportedStatus) {
+        newStatus = reportedStatus;
     }
     else {
         switch (event.eventType) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/react",
-	"version": "1.0.47",
+	"version": "1.0.50-develop.9c1b239",
 	"type": "module",
 	"homepage": "https://docs.0xmonaco.com/sdk/typescript",
 	"main": "./dist/index.js",
@@ -16,8 +16,8 @@
 		"lint": "biome lint ."
 	},
 	"dependencies": {
-		"@0xmonaco/core": "1.0.47",
-		"@0xmonaco/types": "1.0.47"
+		"@0xmonaco/core": "1.0.50-develop.9c1b239",
+		"@0xmonaco/types": "1.0.50-develop.9c1b239"
 	},
 	"devDependencies": {
 		"@types/react": "^19.1.12",
@@ -25,8 +25,8 @@
 	},
 	"peerDependencies": {
 		"react": "^17.0.0 || ^18.0.0 || ^19.0.0",
-		"wagmi": "^2.0.0 || ^3.0.0",
-		"viem": "^2.45.2"
+		"viem": "^2.45.2",
+		"wagmi": "^2.0.0 || ^3.0.0"
 	},
 	"exports": {
 		".": {