@agg-build/hooks 1.0.2 → 1.2.11

package/dist/index.d.ts

@@ -2,12 +2,12 @@ import * as _tanstack_react_query from '@tanstack/react-query';
 import { QueryClient } from '@tanstack/react-query';
 export { QueryClient, QueryClientProvider, useQueryClient } from '@tanstack/react-query';
 import * as _agg_build_sdk from '@agg-build/sdk';
-import { CandleBuilder, AggAuthStartBody, AggAuthStartResult, AggClientSessionInput, AggClient, RampQuote, RampQuoteRequest, RampWidgetSession, RampSessionRequest, QuoteManagedResponse, QuoteManagedParams, ExecuteManagedResponse, ExecuteManagedParams, GetPositionsParams, WsOrderSubmitted, WsBalanceUpdate, RedeemResponse, RedeemRequest, WsRedeemEvent, AggWebSocket, WsWithdrawalLifecycleEvent, WsCandleInterval, WsTrade, AggregatedOrderbookResponse, AggLinkAccountBody, AggLinkAccountResult, AggLinkAccountConfirmResult, UserActivityQuery, UserActivityItem, CandleInterval, OrderbookState, OrderbookQuoteResponse, OrderListQuery, TradeExecutorOrder, SmartRouteSide, SmartRouteResponse, MidpointRow, BatchMidpointsResponse, AppClientConfigResponse } from '@agg-build/sdk';
+import { CandleBuilder, AggAuthStartBody, AggAuthStartResult, AggClientSessionInput, AggClient, RampQuote, RampQuoteRequest, RampWidgetSession, RampSessionRequest, QuoteManagedResponse, QuoteManagedParams, ExecuteManagedResponse, ExecuteManagedParams, GetPositionsParams, WsOrderSubmitted, WsBalanceUpdate, RedeemResponse, RedeemRequest, WsRedeemEvent, AggWebSocket, WsWithdrawalLifecycleEvent, WsCandleInterval, WsTrade, AggregatedOrderbookResponse, AggLinkAccountBody, AggLinkAccountResult, AggLinkAccountConfirmResult, UserActivityQuery, UserActivityItem, PaginatedResponse, CandleInterval, OrderbookState, OrderbookQuoteResponse, OrderListQuery, TradeExecutorOrder, SmartRouteSide, SmartRouteResponse, MidpointRow, BatchMidpointsResponse, AppClientConfigResponse } from '@agg-build/sdk';
 export { TurnstileChallengeError } from '@agg-build/sdk';
 import React, { ReactNode } from 'react';
-export { UseManagedBalancesOptions, UseWithdrawFlowOptions, UseWithdrawFlowResult, UseWithdrawManagedOptions, UseWithdrawalLifecycleResult, WithdrawalLifecycleState, useManagedBalances, useWithdrawFlow, useWithdrawManaged, useWithdrawalLifecycle } from './withdraw.js';
+export { UseManagedBalancesOptions, UseWithdrawEstimateParams, UseWithdrawFlowOptions, UseWithdrawFlowResult, UseWithdrawManagedOptions, UseWithdrawalLifecycleResult, WithdrawFeeEstimate, WithdrawalLifecycleState, useManagedBalances, useWithdrawEstimate, useWithdrawFlow, useWithdrawManaged, useWithdrawalLifecycle } from './withdraw.js';
 export { U as UseDepositAddressesOptions, g as getDepositAddress, u as useDepositAddresses } from './use-deposit-addresses-B9ICS-3U.js';
-export { U as UseSyncBalancesOptions, u as useSyncBalances } from './use-sync-balances-B1_8tBKw.js';
+export { U as UseSyncBalancesOptions, u as useSyncBalances } from './use-sync-balances-CeD8qZWP.js';
 
 /** Use these constants instead of hardcoding "kalshi" or "polymarket". */
 declare enum Venue {
@@ -101,6 +101,7 @@ type UserProfile = {
         kycStatus: string;
     }[] | null;
 };
+type PriceSource = "orderbook" | "cached" | "entry" | "settled";
 type UnifiedBalanceResponse = {
     cash: {
         tokenSymbol: string;
@@ -125,6 +126,8 @@ type UnifiedBalanceResponse = {
 type GetOrdersQuery = {
     status?: OrderStatus | undefined;
     orderId?: string | undefined;
+    /** Filter to all legs of one quote (multi-venue split routes). */
+    quoteId?: string | undefined;
     cursor?: string | undefined;
     limit?: number | undefined;
 };
@@ -136,6 +139,12 @@ type GetPositionsQuery = {
 type OrderListItem = {
     status: string;
     id: string;
+    /**
+     * Parent quote — lets the frontend correlate legs of a multi-venue
+     * split route without a second request. Nullable for sell-side /
+     * standalone orders without a Quote row.
+     */
+    quoteId: string | null;
     createdAt: Date;
     updatedAt: Date;
     venue: Venue;
@@ -144,8 +153,28 @@ type OrderListItem = {
     slippageBps: number | null;
     quotedPriceRaw: string | null;
     quotedCostRaw: string | null;
+    /**
+     * Quote-time shares + payout, 6-decimal atomic. Lets the UI render
+     * "Quoted X shares / $Y to win" without re-deriving from cost ÷
+     * price (precision drift on fractional fills; divide-by-zero before
+     * `executionPrice` exists).
+     */
+    quotedSharesRaw: string | null;
+    quotedToWinRaw: string | null;
     filledAmountRaw: string | null;
     executionPrice: string | null;
+    /**
+     * Actual shares + payout, populated by the venue's finalize handler.
+     * Pair with the quoted-side fields above to render the diff inline.
+     */
+    actualSharesRaw: string | null;
+    actualToWinRaw: string | null;
+    /**
+     * Set only on `partial_fill`. One of `"venue_capacity"`,
+     * `"price_slipped"`, `"user_cancelled"`, `"timeout"`, `"bridge_short"`,
+     * or a venue-specific tag.
+     */
+    partialFillReason: string | null;
     txHash: string | null;
     errorMessage: string | null;
     dagRunId: string | null;
@@ -175,13 +204,14 @@ type PositionGroup = {
                 venue: Venue;
                 size: number;
                 venueMarketId: string;
-                venueMarketOutcomeId?: string | null;
+                venueMarketOutcomeId: string;
             }[];
             totalSize: number;
             avgEntryPrice: number;
             currentPrice: number;
             totalValue: number;
             unrealizedPnlPercent: number;
+            priceSource: PriceSource;
         }[];
     };
     targetMarketId: string;
@@ -202,6 +232,14 @@ type VenueMarket = {
         title?: string | null | undefined;
         externalIdentifier?: string | null | undefined;
         winner?: boolean | null | undefined;
+        /** Counterpart outcomes on matched sibling markets — only populated
+         *  on the parent (queried) market's outcomes. Each entry is a
+         *  `{ venueMarketId, venueMarketOutcomeId }` ref into the same
+         *  response's `matchedVenueMarkets[].venueMarketOutcomes[]`. */
+        matchedVenueMarketOutcomes?: {
+            venueMarketId: string;
+            venueMarketOutcomeId: string;
+        }[];
     }[];
     externalIdentifier: string;
     status?: MarketStatus | undefined;
@@ -274,6 +312,13 @@ type VenueEvent = {
     venues?: Venue[];
     venueCount?: number | undefined;
     marketCount?: number | undefined;
+    /**
+     * ISO-8601 duration denormalized from Series.recurrence. `null` means
+     * the event has no recurring schedule (one-off). Use this value with
+     * the `?recurrence=` filter on /venue-events; discover all available
+     * values via GET /recurrences.
+     */
+    recurrence?: string | null | undefined;
 };
 type Orderbook = {
     bids: {
@@ -286,6 +331,14 @@ type Orderbook = {
     }[];
     negRisk?: boolean | undefined;
 };
+/** Reference to a counterpart outcome on a matched sibling market.
+ *  Resolves into the same response's `matchedVenueMarkets[].venueMarketOutcomes[]`
+ *  by id. Sourced from `MatchedVenueMarketOutcome` so the alignment is
+ *  robust to inversely-framed binary markets and multi-outcome markets. */
+type MatchedVenueMarketOutcomeRef = {
+    venueMarketId: string;
+    venueMarketOutcomeId: string;
+};
 type VenueMarketOutcome = {
     id: string;
     price: number;
@@ -294,6 +347,9 @@ type VenueMarketOutcome = {
     title?: string | null | undefined;
     externalIdentifier?: string | null | undefined;
     winner?: boolean | null | undefined;
+    /** Counterpart outcomes on matched sibling markets — only populated on
+     *  the parent (queried) market's outcomes. */
+    matchedVenueMarketOutcomes?: MatchedVenueMarketOutcomeRef[];
 };
 type VenueEventWithMarkets = VenueEvent & {
     venueMarkets: VenueMarket[];
@@ -506,6 +562,12 @@ interface AggUiLabels {
             max: string;
             tokenLabel: string;
             networkLabel: string;
+            estimatedFees: string;
+            networkReserve: string;
+            networkReserveTooltipAria: string;
+            networkReserveTooltipLineOne: string;
+            networkReserveTooltipLineTwo: string;
+            youReceive: string;
             confirm: string;
             successTitle: string;
             successDescription: (tokenSymbol: string) => string;
@@ -515,7 +577,11 @@ interface AggUiLabels {
             successDescriptionPartial: (tokenSymbol: string) => string;
             successTitleFailed: string;
             successDescriptionFailed: (tokenSymbol: string) => string;
+            retry: string;
+            close: string;
+            loadingDescription: string;
             summary: {
+                requestedWithdrawal: string;
                 amountReceived: string;
                 network: string;
                 toWallet: string;
@@ -533,6 +599,12 @@ interface AggUiLabels {
                 completed: string;
                 partial: string;
                 failed: string;
+                loadingSteps: {
+                    preparing: string;
+                    bridging: string;
+                    sending: string;
+                    confirming: string;
+                };
                 /**
                  * Per-leg step labels rendered in the success step's execution
                  * timeline. `bridge` covers cross-chain hops, `transfer` covers
@@ -590,20 +662,69 @@ interface AggUiLabels {
                 externalWallet: string;
                 card: string;
             };
+            /**
+             * Status-aware titles per activity status. The activity row reads
+             * the appropriate variant based on the normalized status
+             * ("completed" | "pending" | "failed" | "canceled") so the cell
+             * matches the icon and tone — e.g. a pending withdrawal reads
+             * "Processing withdrawal", a failed card deposit reads
+             * "Failed deposit with card".
+             */
+            depositStatusTitles: {
+                connectedWallet: {
+                    pending: string;
+                    completed: string;
+                    failed: string;
+                    canceled: string;
+                };
+                externalWallet: {
+                    pending: string;
+                    completed: string;
+                    failed: string;
+                    canceled: string;
+                };
+                card: {
+                    pending: string;
+                    completed: string;
+                    failed: string;
+                    canceled: string;
+                };
+            };
+            withdrawalStatusTitles: {
+                pending: string;
+                completed: string;
+                failed: string;
+                canceled: string;
+            };
             withdrawalTitle: (tokenSymbol: string) => string;
         };
         positions: {
+            activeFilter: string;
+            closedFilter: string;
+            marketHeader: string;
             totalTradedHeader: string;
+            currentValueHeader: string;
+            statusHeader: string;
+            resolutionHeader: string;
+            payoutHeader: string;
+            resultHeader: string;
             amountWonHeader: string;
             claimHeader: string;
             claim: string;
             claimed: string;
             pending: string;
+            open: string;
             won: string;
             lost: string;
+            sold: string;
             resolved: string;
             marketClosed: string;
             closed: string;
+            searchPlaceholder: string;
+            noResults: string;
+            avgPrefix: string;
+            nowPrefix: string;
+            finalPrefix: string;
         };
     };
     eventList: {
@@ -789,6 +910,7 @@ interface AggUiLabels {
         noMarketSelected: string;
         noOrderbooks: string;
         quoteUnavailable: string;
+        quoteBalanceMismatch: string;
         selectedVenueUnavailable: string;
         engineUnavailable: string;
         insufficientInputAmount: string;
@@ -815,10 +937,18 @@ interface AggUiLabels {
         splitOrderDescription: string;
         viewAllRoutes: (count: number) => string;
         venueUnavailableInRegion: string;
+        platformFee: string;
+        estimatedFees: string;
+        estimatedFeesTooltipAria: string;
+        feeBreakdownVenueFees: string;
+        feeBreakdownBridgeFees: string;
+        feeBreakdownExecutionGas: string;
+        feeBreakdownTotalFees: string;
         toWin: (tab: "buy" | "sell") => string;
         buyingOutcome: (label: string) => string;
         sellingOutcome: (label: string) => string;
         findingBestRoute: string;
+        checkingBalance: string;
         submittingOrderProgress: string;
         orderSubmittedProgress: (orderId: string) => string;
         executingOnVenue: (venueLabel: string) => string;
@@ -1013,6 +1143,8 @@ interface AggUiFeatureFlagsConfig {
     enableAnimations: boolean;
     /** Enable live updates */
     enableLiveUpdates: boolean;
+    /** Enable fee UI in trading flows */
+    showFeesBreakdown: boolean;
     /** Enable gradients */
     enableGradients: boolean;
 }
@@ -1067,6 +1199,12 @@ interface AggUiConfig {
     enableLogs: boolean;
     /** Enable AGG websocket pipeline logs */
     enableWebsocketsLogs: boolean;
+    /**
+     * Enable developer-only debug instrumentation
+     * (e.g. the Place Order execution-debug collector)
+     * Off by default
+     */
+    enableDebug: boolean;
     /** General UI settings */
     general: AggUiGeneralConfig;
     /** UI feature flags */
@@ -1098,6 +1236,8 @@ interface AggUiConfigInput {
     enableLogs?: boolean;
     /** Enable AGG websocket pipeline logs */
     enableWebsocketsLogs?: boolean;
+    /** Enable developer-only debug instrumentation (Place Order debug, etc.). */
+    enableDebug?: boolean;
     /** General UI overrides */
     general?: AggUiGeneralConfigInput;
     /** Feature flag overrides */
@@ -1300,10 +1440,27 @@ declare const resolveOrderEligibility: (params: {
 }) => OrderEligibility;
 declare function resolveDefaultMarket(event: VenueEventWithMarkets | null): VenueMarket | null;
 
+/**
+ * Active trade side. Modeled as a frozen const-object so callers can use
+ * enum-style access (`TradeSide.Buy`, `TradeSide.Sell`) while the resulting
+ * type is still the plain `"buy" | "sell"` string union — interoperable
+ * everywhere a literal is expected (URL params, JSON payloads, helper
+ * function signatures).
+ */
+declare const TradeSide: {
+    readonly Buy: "buy";
+    readonly Sell: "sell";
+};
+type TradeSide = (typeof TradeSide)[keyof typeof TradeSide];
 interface TradingState {
     event: VenueEventWithMarkets | null;
     market: VenueMarket | null;
     outcome: VenueMarketOutcome | null;
+    /**
+     * Currently selected buy/sell side. Optional in shape (older fixtures and
+     * snapshots may omit it) — readers should treat `undefined` as `Buy`.
+     */
+    tradeSide?: TradeSide;
 }
 type TradingAction = {
     type: "INITIALIZE_EVENT";
@@ -1322,6 +1479,9 @@ type TradingAction = {
     type: "SELECT_MARKET_AND_OUTCOME";
     marketId: string;
     outcomeId: string;
+} | {
+    type: "SET_TRADE_SIDE";
+    tradeSide: TradeSide;
 };
 declare function tradingReducer(state: TradingState, action: TradingAction): TradingState;
 interface EventTradingContextValue {
@@ -1332,6 +1492,14 @@ interface EventTradingContextValue {
     selectedMarketId: string | null;
     selectedOutcomeId: string | null;
     selectedVenue: string | null;
+    /**
+     * Currently selected trade side. Drives `bestAsk` vs `bestBid` selection
+     * across all price-display surfaces (home tile, event details, market
+     * details, place-order outcome buttons) so flipping Buy/Sell in PlaceOrder
+     * is reflected everywhere. Defaults to `"buy"`.
+     */
+    tradeSide: TradeSide;
+    setTradeSide: (tradeSide: TradeSide) => void;
     initializeFromEvent: (event: VenueEventWithMarkets | null) => void;
     syncEvent: (event: VenueEventWithMarkets) => void;
     selectMarket: (marketId: string, market?: VenueMarket) => void;
@@ -1355,6 +1523,49 @@ declare const invalidateBalanceQueries: (queryClient: QueryClient, options?: Inv
  * holdings, so positions need to be refetched alongside balances.
  */
 declare const invalidatePositionQueries: (queryClient: QueryClient, options?: InvalidateBalanceQueriesOptions) => void;
+declare const userActivityQueryKeys: {
+    all: () => readonly ["user-activity"];
+};
+type UserActivityInvalidationStrategy = "remove" | "invalidate";
+interface InvalidateUserActivityOptions {
+    /**
+     * - "remove" (default): drop the entire `["user-activity"]` family from the
+     *   cache so the observed `useInfiniteQuery` refetches from page 1 only.
+     *   Avoids duplicate/shifted rows when a new entry appears at the top after
+     *   a deposit/withdraw — page 2's cursor was computed against the old head.
+     * - "invalidate": invalidate in place; refetches all currently cached pages.
+     *   Cheaper paint-wise (keeps prior data visible) but can momentarily show
+     *   duplicate rows during the refetch.
+     */
+    strategy?: UserActivityInvalidationStrategy;
+}
+/**
+ * Refresh the `useUserActivity` infinite query family after money movement.
+ * Defaults to `removeQueries` so the next render refetches page 1 cleanly
+ * (cursor-based pagination can't guarantee ordering after a new head row).
+ */
+declare const invalidateUserActivityQueries: (queryClient: QueryClient, options?: InvalidateUserActivityOptions) => void;
+interface InvalidateUserMoneyStateOptions {
+    /** Forwarded to balance + position invalidations. Defaults to "active". */
+    refetchType?: BalanceRefetchType;
+    /** Forwarded to activity invalidation. Defaults to "remove". */
+    activityStrategy?: UserActivityInvalidationStrategy;
+}
+/**
+ * Invalidate every cache surface affected by a successful deposit or
+ * withdrawal. Call AFTER the backend has confirmed the operation — not on
+ * modal close, not on optimistic submit.
+ *
+ * Scope (kept narrow on purpose):
+ *   - balances (canonical + venue) — the balance number changed
+ *   - positions — derived "available to trade" / share-count UIs read this
+ *     alongside balances; refetch keeps them consistent
+ *   - user activity — the deposit/withdraw row needs to appear in the feed
+ *
+ * Out of scope: orders / execution-orders (trade-side, not money movement),
+ * current-user (no money fields change on deposit/withdraw today).
+ */
+declare const invalidateUserMoneyState: (queryClient: QueryClient, options?: InvalidateUserMoneyStateOptions) => void;
 
 declare function useRampQuotes(): _tanstack_react_query.UseMutationResult<RampQuote[], Error, RampQuoteRequest, unknown>;
 
@@ -1597,6 +1808,19 @@ interface ExecutionTerminalOrderEvent {
     event: "filled" | "partial_fill" | "failed";
     filledAmountRaw?: string;
     remainingAmountRaw?: string;
+    /** Actual shares + payout received, 6-decimal atomic. Set by the venue's
+     * finalize handler on filled/partial_fill — the source of truth for the
+     * execution summary so it never reuses the stale quote estimate. */
+    actualSharesRaw?: string;
+    actualToWinRaw?: string;
+    /** Quote-time shares + payout, 6-decimal atomic. Snapshot of what the user
+     * accepted; surfaced for "Quoted X / Got Y" diffs. */
+    quotedSharesRaw?: string;
+    quotedToWinRaw?: string;
+    /** Avg execution price (decimal string). Pair with `quotedPriceRaw`
+     * for inline slippage diffs and to derive shares when actual*Raw is absent. */
+    executionPriceRaw?: string;
+    quotedPriceRaw?: string;
     errorReason?: string;
     timestamp: number;
 }
@@ -1622,6 +1846,10 @@ interface ClosedPositionTotals {
 }
 declare const computeClosedPositionTotals: (group: PositionGroup) => ClosedPositionTotals;
 
+declare class RedeemRejectedError extends Error {
+    readonly response: RedeemResponse;
+    constructor(message: string, response: RedeemResponse);
+}
 declare const useRedeem: () => _tanstack_react_query.UseMutationResult<RedeemResponse, Error, RedeemRequest, unknown>;
 
 type RedeemEvent = WsRedeemEvent;
@@ -1629,6 +1857,96 @@ declare const useOnRedeemEvent: (listener: ((event: RedeemEvent) => void) | null
 
 declare const useRedeemEligibleCount: () => number;
 
+interface RedeemLegLifecycle {
+    status: "submitted" | "confirmed" | "failed";
+    txHash: string | null;
+    errorMessage: string | null;
+}
+interface RedeemLifecycleState {
+    /** True until terminal — drives the claim button spinner. */
+    pending: boolean;
+    /** True once every expected leg has flipped to confirmed or failed. */
+    terminal: boolean;
+    /** True iff terminal AND every leg.status === "confirmed". */
+    allConfirmed: boolean;
+    /** True iff any leg.status === "failed" (including pre-failed legs). */
+    anyFailed: boolean;
+    /** First non-null leg.errorMessage when anyFailed; null otherwise. */
+    errorMessage: string | null;
+    /** Per-leg lifecycle keyed by venueMarketOutcomeId. */
+    legs: Record<string, RedeemLegLifecycle>;
+}
+interface UseRedeemLifecycleInput {
+    redeemId: string;
+    /**
+     * Legs the API returned with status === "submitted" (EVM async path).
+     * Each receives a redeem_event with status confirmed or failed.
+     */
+    expectedOutcomeIds: string[];
+    /**
+     * Legs the API returned with status === "ineligible" or "rejected".
+     * Pre-seeded into legs as terminal-failed; no WS event will ever arrive.
+     */
+    preFailedOutcomeIds?: string[];
+    /** Optional pre-seeded errorMessage per pre-failed leg, indexed by venueMarketOutcomeId. */
+    preFailedReasons?: Record<string, string | null>;
+    /**
+     * Legs the API returned with status === "confirmed" (SVM sync path:
+     * tx landed inline inside the HTTP call, VMP.redeemedAt already set
+     * server-side). Pre-seeded into legs as terminal-confirmed; no WS
+     * event will ever arrive.
+     */
+    preConfirmedOutcomeIds?: string[];
+    /** Optional pre-seeded txHash per pre-confirmed leg, indexed by venueMarketOutcomeId. */
+    preConfirmedTxHashes?: Record<string, string | null>;
+}
+/**
+ * Subscribes once to `redeem_event` WS events and materializes a per-`redeemId`
+ * lifecycle record for every in-flight redeem the caller is tracking.
+ *
+ * **Input shape** — the caller passes one {@link UseRedeemLifecycleInput} entry
+ * per in-flight redeem. Legs are split into three buckets:
+ * - `expectedOutcomeIds` — the EVM async path. The API returned these legs with
+ *   `status === "submitted"`; each will eventually receive a `redeem_event` WS
+ *   message with `status === "confirmed"` or `"failed"`.
+ * - `preFailedOutcomeIds` — legs the API returned as `"ineligible"` or
+ *   `"rejected"` at submit time. Pre-seeded into the returned state as
+ *   terminal-failed; no WS event will ever arrive for them.
+ * - `preConfirmedOutcomeIds` — the SVM sync path. The transaction landed inline
+ *   inside the HTTP call so `VenueMarketPosition.redeemedAt` is already set
+ *   server-side before the response returns. Pre-seeded as terminal-confirmed;
+ *   no WS event will ever arrive.
+ *
+ * **Entry lifecycle** — when the caller drops a `redeemId` from `inputs`, its
+ * entry disappears from the returned record on the next render. There is no
+ * tombstone or TTL — the lifecycle is purely driven by what is in `inputs`.
+ *
+ * **Performance** — the `inputs` array's reference identity matters. The hook
+ * re-derives the internal `redeemId → input` map on every render where
+ * `inputs` is a new reference. Callers should memoize the array via `useMemo`
+ * to avoid the re-derivation overhead. A common pattern:
+ * ```ts
+ * const inputs = useMemo(
+ *   () => Object.values(activeRedeems).map(toLifecycleInput),
+ *   [activeRedeems],
+ * );
+ * ```
+ *
+ * **New-entry gap** — when the caller adds a new `redeemId` to `inputs`, the
+ * returned record does not include it for the render where it was added. The
+ * seed entry is written inside a `useEffect` (which runs after paint). Treat a
+ * missing entry as "pending / not terminal yet" — the same as
+ * `state.pending === true`.
+ *
+ * **No REST backfill** — if the WS subscription drops mid-flight (page refresh,
+ * disconnect), the in-memory lifecycle state is lost. Redeems typically settle
+ * in seconds and each position's `redeemStatus` is polled separately, so no
+ * REST backfill is provided here.
+ */
+declare function useRedeemLifecycles(inputs: UseRedeemLifecycleInput[]): Record<string, RedeemLifecycleState>;
+
+declare function useRedeemLifecycle(input: UseRedeemLifecycleInput | null): RedeemLifecycleState;
+
 declare function useAggWebSocket(): AggWebSocket | null;
 declare function useOnOrderSubmitted(callback: ((msg: WsOrderSubmitted) => void) | null): void;
 declare function useOnBalanceUpdate(callback: ((msg: WsBalanceUpdate) => void) | null): void;
@@ -1641,7 +1959,7 @@ interface MarketChartCandle {
     low: number;
     close: number;
     volume: number | null;
-    source: "rest" | "ws" | "trade";
+    source: "rest" | "ws" | "trade" | "midpoint";
 }
 interface MarketChartVenueData {
     venue: string;
@@ -1651,6 +1969,13 @@ interface MarketChartVenueData {
     liveCandle: MarketChartCandle | null;
     lineValue: number | undefined;
     lastTrade: WsTrade | null;
+    /**
+     * Epoch seconds of the most recent real REST or WS update that touched this
+     * venue (REST candle, trade, or midpoint). Used by the renderer's stale-data
+     * indicator — independent of any synthetic point that `extendSeriesToNow`
+     * projects onto the line. `null` when nothing has been seen yet.
+     */
+    lastUpdateTs: number | null;
 }
 interface MarketChartData {
     marketId: string;
@@ -1663,6 +1988,11 @@ interface MarketChartData {
     endTs: number | null;
     /** Per-venue chart state. The primary venue contains the canonical REST history. */
     venues: Record<string, MarketChartVenueData>;
+    /**
+     * Max of `lastUpdateTs` across all venues. Surfaced separately so the
+     * renderer can show a stale indicator without crawling the venues map.
+     */
+    lastUpdateTs: number | null;
 }
 
 type MarketOrderbookIntegrity = "ok" | "resyncing";
@@ -2183,11 +2513,20 @@ declare function useExecutionOrders(options?: UseExecutionOrdersOptions): {
 
 interface UseUserActivityOptions extends Omit<UserActivityQuery, "cursor"> {
     enabled?: boolean;
+    /**
+     * Poll interval (ms) used while any cached activity row is mid-lifecycle
+     * (deposit pending, withdrawal bridging, trade submitted, etc.). Idle
+     * feeds — every row in a terminal state — don't poll. Set to `false` to
+     * disable the lifecycle-aware poll entirely.
+     *
+     * Defaults to 15s.
+     */
+    pendingRefetchIntervalMs?: number | false;
 }
 declare function useUserActivity(options?: UseUserActivityOptions): {
     activities: UserActivityItem[];
     hasNextPage: boolean;
-    data: _tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>;
+    data: _tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>;
     error: Error;
     isError: true;
     isPending: false;
@@ -2197,8 +2536,8 @@ declare function useUserActivity(options?: UseUserActivityOptions): {
     isSuccess: false;
     isPlaceholderData: false;
     status: "error";
-    fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
-    fetchPreviousPage: (options?: _tanstack_react_query.FetchPreviousPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    fetchPreviousPage: (options?: _tanstack_react_query.FetchPreviousPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
     hasPreviousPage: boolean;
     isFetchNextPageError: boolean;
     isFetchingNextPage: boolean;
@@ -2217,13 +2556,13 @@ declare function useUserActivity(options?: UseUserActivityOptions): {
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
     fetchStatus: _tanstack_react_query.FetchStatus;
-    promise: Promise<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>>;
+    promise: Promise<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>>;
 } | {
     activities: UserActivityItem[];
     hasNextPage: boolean;
-    data: _tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>;
+    data: _tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>;
     error: null;
     isError: false;
     isPending: false;
@@ -2235,8 +2574,8 @@ declare function useUserActivity(options?: UseUserActivityOptions): {
     isSuccess: true;
     isPlaceholderData: false;
     status: "success";
-    fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
-    fetchPreviousPage: (options?: _tanstack_react_query.FetchPreviousPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    fetchPreviousPage: (options?: _tanstack_react_query.FetchPreviousPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
     hasPreviousPage: boolean;
     isFetchingNextPage: boolean;
     isFetchingPreviousPage: boolean;
@@ -2253,9 +2592,9 @@ declare function useUserActivity(options?: UseUserActivityOptions): {
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
     fetchStatus: _tanstack_react_query.FetchStatus;
-    promise: Promise<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>>;
+    promise: Promise<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>>;
 } | {
     activities: UserActivityItem[];
     hasNextPage: boolean;
@@ -2271,8 +2610,8 @@ declare function useUserActivity(options?: UseUserActivityOptions): {
     isSuccess: false;
     isPlaceholderData: false;
     status: "error";
-    fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
-    fetchPreviousPage: (options?: _tanstack_react_query.FetchPreviousPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    fetchPreviousPage: (options?: _tanstack_react_query.FetchPreviousPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
     hasPreviousPage: boolean;
     isFetchingNextPage: boolean;
     isFetchingPreviousPage: boolean;
@@ -2289,9 +2628,9 @@ declare function useUserActivity(options?: UseUserActivityOptions): {
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
     fetchStatus: _tanstack_react_query.FetchStatus;
-    promise: Promise<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>>;
+    promise: Promise<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>>;
 } | {
     activities: UserActivityItem[];
     hasNextPage: boolean;
@@ -2307,8 +2646,8 @@ declare function useUserActivity(options?: UseUserActivityOptions): {
     isSuccess: false;
     isPlaceholderData: false;
     status: "pending";
-    fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
-    fetchPreviousPage: (options?: _tanstack_react_query.FetchPreviousPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    fetchPreviousPage: (options?: _tanstack_react_query.FetchPreviousPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
     hasPreviousPage: boolean;
     isFetchingNextPage: boolean;
     isFetchingPreviousPage: boolean;
@@ -2325,9 +2664,9 @@ declare function useUserActivity(options?: UseUserActivityOptions): {
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
     fetchStatus: _tanstack_react_query.FetchStatus;
-    promise: Promise<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>>;
+    promise: Promise<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>>;
 } | {
     activities: UserActivityItem[];
     hasNextPage: boolean;
@@ -2342,8 +2681,8 @@ declare function useUserActivity(options?: UseUserActivityOptions): {
     isSuccess: false;
     isPlaceholderData: false;
     status: "pending";
-    fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
-    fetchPreviousPage: (options?: _tanstack_react_query.FetchPreviousPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    fetchPreviousPage: (options?: _tanstack_react_query.FetchPreviousPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
     hasPreviousPage: boolean;
     isFetchingNextPage: boolean;
     isFetchingPreviousPage: boolean;
@@ -2361,13 +2700,13 @@ declare function useUserActivity(options?: UseUserActivityOptions): {
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
     fetchStatus: _tanstack_react_query.FetchStatus;
-    promise: Promise<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>>;
+    promise: Promise<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>>;
 } | {
     activities: UserActivityItem[];
     hasNextPage: boolean;
-    data: _tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>;
+    data: _tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>;
     isError: false;
     error: null;
     isPending: false;
@@ -2379,8 +2718,8 @@ declare function useUserActivity(options?: UseUserActivityOptions): {
     isFetchNextPageError: false;
     isFetchPreviousPageError: false;
     status: "success";
-    fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
-    fetchPreviousPage: (options?: _tanstack_react_query.FetchPreviousPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    fetchPreviousPage: (options?: _tanstack_react_query.FetchPreviousPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
     hasPreviousPage: boolean;
     isFetchingNextPage: boolean;
     isFetchingPreviousPage: boolean;
@@ -2397,9 +2736,9 @@ declare function useUserActivity(options?: UseUserActivityOptions): {
     isRefetching: boolean;
     isStale: boolean;
     isEnabled: boolean;
-    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>, Error>>;
+    refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>, Error>>;
     fetchStatus: _tanstack_react_query.FetchStatus;
-    promise: Promise<_tanstack_react_query.InfiniteData<_agg_build_sdk.PaginatedResponse<UserActivityItem>, unknown>>;
+    promise: Promise<_tanstack_react_query.InfiniteData<PaginatedResponse<UserActivityItem>, unknown>>;
 };
 
 interface UseExternalIdOptions {
@@ -2754,6 +3093,38 @@ declare function useLiveOutcomePrices(venueMarkets: VenueMarket[] | null | undef
  */
 declare function findLivePriceById(livePrices: Map<string, number>, id: string): number | undefined;
 
+type LiveBestPrices = ReadonlyMap<string, {
+    bestBid?: number;
+    bestAsk?: number;
+}>;
+/**
+ * WS-derived cross-venue + cross-outcome best bid/ask per outcome.
+ *
+ * For each outcome in `venueMarkets` (plus matched twins via MVMO refs):
+ *   - bestBid/bestAsk taken from the per-outcome aggregated top of book.
+ *   - Then folded across MVMO groups: lowest bestAsk wins (cheapest to buy),
+ *     highest bestBid wins (best to sell). The chosen best is broadcast to
+ *     every member of the group so display surfaces pick it up regardless
+ *     of which outcome they look up.
+ *
+ * Empty until WS snapshots/deltas land for the subscribed outcomes. Designed
+ * to merge as overrides on top of REST `bestPrices` from `useMidpoints`, with
+ * WS winning where present.
+ */
+declare function useLiveBestPrices(venueMarkets: VenueMarket[] | null | undefined): LiveBestPrices;
+/**
+ * Merge WS bestBid/bestAsk over a REST `bestPrices` map, WS values winning
+ * where present. Returns the REST map unchanged when WS is empty. Designed
+ * for callers that need to pass a single `bestPrices` map to display logic.
+ */
+declare function mergeBestPricesPreferringLive(rest: ReadonlyMap<string, {
+    bestBid?: number;
+    bestAsk?: number;
+}> | null | undefined, live: LiveBestPrices): ReadonlyMap<string, {
+    bestBid?: number;
+    bestAsk?: number;
+}>;
+
 /**
  * Subscribe to real-time trade feed for a canonical market.
  * Manages a separate trade subscription on the WS (trades use a different channel).
@@ -2764,27 +3135,100 @@ declare function useLiveTrades(canonicalMarketId: string | null): WsTrade[];
 interface UseMidpointsResult {
     /** Map of outcomeId → price. Empty while loading. */
     prices: Map<string, number>;
+    /**
+     * Map of outcomeId → lowest midpoint available for that exact semantic outcome
+     * across the selected market cluster. Alias of `prices`, exposed under a
+     * clearer name for display surfaces that want a single source of truth.
+     */
+    bestMidpointsByOutcomeId: Map<string, number>;
     /**
      * Map of outcomeId → venue name that provided the price in `prices`.
-     * When a matched venue offers a lower YES price, this records that venue so
-     * callers can show the correct venue logo alongside the best price.
+     * When a matched sibling offers a lower midpoint for the same semantic
+     * side, this records that sibling's venue so callers can show the
+     * correct venue logo alongside the best price.
      * Empty while loading or when the API response omits `venue` fields.
      */
     venueByOutcomeId: Map<string, string>;
+    /**
+     * Map of outcomeId → { bestBid?, bestAsk? }. Top-of-book prices extracted
+     * from the midpoints response when bestPrice=true. Empty while loading
+     * or when bestPrice data is unavailable.
+     */
+    bestPrices: Map<string, {
+        bestBid?: number;
+        bestAsk?: number;
+    }>;
+    /**
+     * Map of outcomeId → { bestBidVenue?, bestAskVenue? }. Tracks which venue
+     * supplied the winning side of the book across the MVMO group so display
+     * surfaces can pair the logo with the price. Distinct per side because
+     * "best buy" and "best sell" can come from different venues.
+     */
+    bestPriceVenuesByOutcomeId: Map<string, {
+        bestBidVenue?: string;
+        bestAskVenue?: string;
+    }>;
     /** True while the midpoints fetch is in flight. */
     isLoading: boolean;
+    /** Best midpoint value across all venues. Undefined while loading. */
+    bestMidpoint: number | undefined;
+    /**
+     * Venue that produced `bestMidpoint`. Paired with `bestMidpoint` from the
+     * same winning outcome so display surfaces can render a matching logo +
+     * price. Undefined when no candidate produced a price or when the
+     * response lacked a `venue` field.
+     */
+    bestMidpointVenue: string | undefined;
 }
 /**
  * Fetches live midpoints for the given venue markets.
  *
  * Returns { prices, isLoading } so callers can show a skeleton while loading.
  *
- * Uses per-outcome midpoints from the API (each outcome has its own orderbook
- * midpoint) to avoid the primary-outcome inversion bug. Falls back to the
- * market-level midpoint with label-based derivation when outcomes are absent.
+ * Cross-venue best-price selection walks each parent outcome's
+ * `matchedVenueMarketOutcomes` (MVMO references) and looks up the matched
+ * counterpart's per-outcome midpoint in `matched[].outcomes`. The lowest
+ * midpoint wins per outcome — semantically correct for both Yes and No
+ * sides because MVMO links same-side counterparts regardless of label
+ * inversion. No label heuristics; no `1 - midpoint` flips.
  */
 declare function useMidpoints(venueMarkets: VenueMarket[] | null | undefined): UseMidpointsResult;
 
+interface UseTradableVenuesResult {
+    /**
+     * Set of venue strings that have at least one outcome with a non-null
+     * midpoint from the engine. When non-null, this is the authoritative
+     * set of venues that have a live orderbook for the given cluster.
+     *
+     * `null` while midpoints are still loading — callers should treat this
+     * as "unknown, don't filter yet" and show all venues optimistically.
+     */
+    tradableVenues: ReadonlySet<string> | null;
+    /** True while the underlying midpoints fetch is in flight. */
+    isLoading: boolean;
+}
+/**
+ * Dynamic venue-orderbook availability check.
+ *
+ * Walks the cluster's midpoints (already fetched via /midpoints by the
+ * surrounding component, or fetched fresh here if not) and returns the
+ * set of venues that have at least one outcome with a non-null midpoint.
+ * A venue with NO non-null midpoints across all its outcomes is treated
+ * as "no live orderbook" — it appeared in matching/discovery but the
+ * engine isn't quoting it (e.g. opinion).
+ *
+ * The signal is purely runtime: no hardcoded venue allowlist. New
+ * venues that join without orderbook support get filtered automatically;
+ * venues whose orderbook stream temporarily drops also get filtered
+ * until midpoints come back. This keeps the FE in lockstep with what the
+ * engine is actually able to quote, without coordinating constants
+ * across BE/FE on every venue addition.
+ *
+ * Use this in surfaces that need to show "X tradeable venues" or filter
+ * a venue logo strip — see `getVenueSummary`'s `tradableVenues` option.
+ */
+declare function useTradableVenues(venueMarkets: VenueMarket[] | null | undefined): UseTradableVenuesResult;
+
 interface UseMarketChartOptions {
     /** VenueMarketOutcome.id */
     marketId: string | null;
@@ -2797,6 +3241,25 @@ interface UseMarketChartOptions {
     enabled?: boolean;
     /** Enable live WS updates. Defaults to the global `enableLiveUpdates` config. */
     live?: boolean;
+    /**
+     * Auto-refetch the REST history at this cadence (ms). Pair with a rolling
+     * window whose `endTs` advances at the same bucket interval — each tick
+     * refetches the latest window under a stable cache key, so closed bars
+     * the WebSocket missed are backfilled. `null`/omitted disables auto-refetch.
+     */
+    refetchIntervalMs?: number | null;
+    /**
+     * Stable identifier for the user-selected range (e.g. `"1H"`, `"6H"`).
+     * Used as the React Query cache key so the entry survives bucket rollovers
+     * and tab/page revisits. The concrete `startTs`/`endTs` advance under the
+     * same key and are passed to the fetch via closure.
+     *
+     * If omitted, falls back to `interval` — preserves cache reuse for callers
+     * that don't drive a rolling window. Note that 6H and 1D both use a 5m
+     * interval, so callers using rolling windows should pass an explicit
+     * `rangeKey` to keep their cache entries separate.
+     */
+    rangeKey?: string;
 }
 interface UseMarketChartResult {
     data: MarketChartData | null;
@@ -2807,6 +3270,93 @@ interface UseMarketChartResult {
 }
 declare function useMarketChart(options: UseMarketChartOptions): UseMarketChartResult;
 
+interface UseRollingChartWindowOptions {
+    range: ChartTimeRange;
+    /**
+     * Override the WS candle interval. Defaults to the canonical mapping from
+     * `timeRangeToInterval`. Tests use this to inject a deterministic value.
+     */
+    interval?: WsCandleInterval;
+    /**
+     * Tick cadence for `nowSec`, in milliseconds. Defaults to 1s. The query
+     * boundary (`endTs`) is bucketized so React Query only refetches when the
+     * candle bucket advances, not on every tick.
+     */
+    tickMs?: number;
+    /**
+     * Read of `Date.now()` (ms). Overridable for tests.
+     */
+    nowMs?: () => number;
+}
+interface RollingChartWindow {
+    range: ChartTimeRange;
+    interval: WsCandleInterval;
+    /** Width of the visible/rolling domain in seconds. */
+    rangeSeconds: number;
+    /** Width of one closed bar in seconds. */
+    intervalSeconds: number;
+    /**
+     * Current wall-clock seconds, updated on every tick. The visible domain is
+     * always `[nowSec - rangeSeconds, nowSec]` — use this for filtering points
+     * to the rolling window.
+     */
+    nowSec: number;
+    /**
+     * Bucketized end of the rolling window. Snaps to the next interval
+     * boundary so the React Query key (and therefore REST refetch) only
+     * advances when a new candle bucket starts. Use this as `endTs` for the
+     * REST query.
+     */
+    endTs: number;
+    /**
+     * Bucketized start: `endTs - rangeSeconds`. Use as `startTs` for the
+     * REST query.
+     */
+    startTs: number;
+    /**
+     * Refetch interval to pass to React Query, in milliseconds. Matches one
+     * candle bucket so historical bars roll in cleanly even without WS.
+     */
+    refetchIntervalMs: number;
+}
+declare const rangeToSeconds: (range: ChartTimeRange) => number;
+/**
+ * Pure resolver for the rolling window, factored out of `useRollingChartWindow`
+ * so the time-math can be unit-tested without rendering React.
+ *
+ * Invariants:
+ *   - `nowSec - rangeSeconds === domainStartTs` (the visible domain is
+ *     always exactly `rangeSeconds` wide regardless of how long mounted).
+ *   - `endTs - startTs === rangeSeconds` (the bucketized query window is
+ *     also exactly `rangeSeconds` wide; only the alignment to bucket
+ *     boundaries differs from the visible domain).
+ *   - `endTs % intervalSeconds === 0` (snaps to next bucket boundary so
+ *     the React Query key stays stable between bucket rollovers).
+ */
+declare const resolveRollingWindow: (params: {
+    range: ChartTimeRange;
+    nowSec: number;
+    interval?: WsCandleInterval;
+}) => RollingChartWindow;
+/**
+ * Drives a rolling time domain `[nowSec - rangeSeconds, nowSec]` that ticks
+ * while the chart is mounted.
+ *
+ * Why two timestamps (`nowSec` vs `endTs`):
+ *   - `nowSec` updates every `tickMs` (default 1s) so the visible domain
+ *     stays exactly `rangeSeconds` wide. Series points outside that domain
+ *     should be filtered out by the caller.
+ *   - `endTs` is bucketized to the next interval boundary so React Query's
+ *     key only changes when a new candle bucket actually starts. Without
+ *     this, the chart would refetch every tick.
+ *
+ * The bucket advance is also what drives REST refetches that backfill any
+ * closed bars the WebSocket missed. WS updates feed the in-flight candle
+ * and promote it on rollover (see `chart-cache.applyMidpointToMarketChart`);
+ * the REST refetch only matters when WS is disconnected or quiet.
+ */
+declare const useRollingChartWindow: (options: UseRollingChartWindowOptions) => RollingChartWindow;
+
 interface UseMarketOrderbookVenueOutcome {
     venue: VenueMarket["venue"];
     venueMarketOutcomeId: string;
@@ -3066,6 +3616,15 @@ interface UseSearchOptions {
     limit?: number;
     /** If provided, enable/disable the query. Defaults to true. */
     enabled?: boolean;
+    /**
+     * Opt in to the server-side reranker for higher-quality top results.
+     *
+     * Recommended for the full search-results page (submit / Enter) and NOT
+     * for debounced typeahead — the latter shouldn't pay reranker latency on
+     * every keystroke. The flag is baked into the query cache key, so deep
+     * and light variants of the same query never share results. Default false.
+     */
+    deep?: boolean;
 }
 /**
  * Search events or markets via the /search endpoint with cursor-based pagination.
@@ -3075,6 +3634,9 @@ interface UseSearchOptions {
  * ```ts
  * const { data } = useSearch<VenueEventWithMarkets>({ q: "...", type: "events" });
  * ```
+ *
+ * For typeahead + full-results in one hook, prefer `useMarketSearch` — it
+ * wires up the debounce, submit, and cancellation semantics out of the box.
  */
 declare function useSearch<T = VenueEvent>(options: UseSearchOptions): {
     data: T[];
@@ -3092,6 +3654,100 @@ declare function useSearch<T = VenueEvent>(options: UseSearchOptions): {
     isPlaceholderData: boolean;
 };
 
+interface UseMarketSearchOptions {
+    /** Search type: "events" or "markets". */
+    type: "events" | "markets";
+    /** Optional category ID filter. */
+    categoryIds?: string[];
+    /** Page size for both modes. Default 20. */
+    limit?: number;
+    /**
+     * Debounce delay applied to the typeahead/light query, in ms. The submit
+     * path bypasses debounce entirely. Default 200.
+     */
+    debounceMs?: number;
+    /**
+     * Set to `false` to disable the typeahead/light query (no /search call
+     * while the user types). The submit path still fires deep searches.
+     * Default true.
+     */
+    enableSuggestions?: boolean;
+    /**
+     * Minimum query length before the typeahead fires. Default 1 — set higher
+     * (e.g. 3) if `/search` cost per keystroke is a concern. The submit path
+     * ignores this threshold.
+     */
+    minLength?: number;
+}
+/**
+ * Combined typeahead + submit hook for the canonical search UX.
+ *
+ *  ┌─────────────────────────────┐
+ *  │ user types "tru"            │ → debounced light /search → suggestions[]
+ *  │ user types "trum"           │ → debounced light /search → suggestions[]
+ *  │ user presses Enter          │ → deep /search           → results[]
+ *  └─────────────────────────────┘
+ *
+ * Typeahead (`suggestions`) and submit-results (`results`) are cached under
+ * separate TanStack Query keys, so navigating away and back doesn't lose
+ * either. Server-side the same separation holds: the `deep` flag is part of
+ * the cache key, so the two modes never collide.
+ *
+ * ```tsx
+ * const { query, setQuery, submit, suggestions, results } = useMarketSearch({
+ *   type: "markets",
+ * });
+ *
+ * <input
+ *   value={query}
+ *   onChange={(e) => setQuery(e.target.value)}
+ *   onKeyDown={(e) => { if (e.key === "Enter") submit(); }}
+ * />
+ * {suggestions.data.map(...)}    // dropdown
+ * {results.data.map(...)}        // full page after Enter
+ * ```
+ */
+declare function useMarketSearch<T = VenueEvent>(options: UseMarketSearchOptions): {
+    /** Current input value (controlled). */
+    query: string;
+    /** Update the input value. Triggers the debounced typeahead. */
+    setQuery: (value: string) => void;
+    /** The query value that produced the current `results`, or null if none. */
+    submittedQuery: string | null;
+    /** Fire a deep search. Use this on Enter / Search button. */
+    submit: (q?: string) => void;
+    /** Reset both input and results state. */
+    clear: () => void;
+    /**
+     * Typeahead state. Backed by a light /search call (no reranker).
+     * `data` is paginated like `useSearch.data` (flattened across pages).
+     */
+    suggestions: {
+        data: T[];
+        isLoading: boolean;
+        isError: boolean;
+        error: Error | null;
+    };
+    /**
+     * Full-page results state. Backed by a deep /search call (reranker on).
+     * Cursor pagination is exposed via `fetchNextPage` / `hasNextPage`.
+     */
+    results: {
+        data: T[];
+        isLoading: boolean;
+        isError: boolean;
+        error: Error | null;
+        hasNextPage: boolean;
+        fetchNextPage: (options?: _tanstack_react_query.FetchNextPageOptions) => Promise<_tanstack_react_query.InfiniteQueryObserverResult<_tanstack_react_query.InfiniteData<{
+            type: "markets" | "events";
+            data: T[];
+            nextCursor: string | null;
+            hasMore: boolean;
+        }, unknown>, Error>>;
+        isFetchingNextPage: boolean;
+    };
+};
+
 interface UseSmartRouteOptions {
     /** Venue market outcome ID used by the smart-route endpoint. */
     venueMarketOutcomeId?: string | null;
@@ -3113,8 +3769,18 @@ interface UseSmartRouteOptions {
     slipCapBps?: number;
     /** Include venue-by-venue comparison quotes. */
     compareVenues?: boolean;
+    /**
+     * Opt in to the deep cost-estimate surface — response `feeBreakdown`
+     * gains `setupCosts` (chain approvals + Kalshi ATAs) with `alreadyPaid`
+     * flags from prior trade history, and `setupCostsTotal` is folded into
+     * `totalCostIncFees` (with `estimatedProfit` / `returnPct` recomputed).
+     * Buy-only.
+     */
+    deepEstimate?: boolean;
     /** Enable/disable the query. Default true. */
     enabled?: boolean;
+    /** Cache freshness and polling interval in milliseconds. Defaults to SMART_ROUTE_STALE_TIME_MS. */
+    staleTimeMs?: number;
 }
 interface UseSmartRouteResult {
     data: SmartRouteResponse | null;
@@ -4469,15 +5135,18 @@ declare function computePriceGaps(input: ComputePriceGapsInput): Map<string, num
  *   • Markets that become visible for the first time are batched into a
  *     single request on the next render.
  *
- * The returned `prices` map is keyed by outcome id — "Yes" outcomes get the
- * aggregated best midpoint across matched venues; "No" outcomes get its
- * complement (1 - midpoint).
+ * Cross-venue best-price selection walks each parent outcome's
+ * `matchedVenueMarketOutcomes` (MVMO references) and looks up the matched
+ * counterpart's per-outcome midpoint. The lowest midpoint wins per
+ * outcome — semantically correct for both Yes and No sides because MVMO
+ * links same-side counterparts regardless of label inversion.
  */
 declare function useViewportMidpoints(visibleMarkets: VenueMarket[]): {
     prices: Map<string, number>;
     /**
      * Map of outcomeId → venue name that provided the price in `prices`.
-     * Populated when a matched venue offers a lower YES price than the primary.
+     * Populated when a matched sibling offers a lower midpoint for the same
+     * semantic side.
      */
     venueByOutcomeId: Map<string, string>;
 };
@@ -4510,6 +5179,7 @@ interface UseAppConfigResult {
     disabledVenues: AppClientConfigResponse["disabledVenues"];
     disabledCategoryPresets: AppClientConfigResponse["disabledCategoryPresets"];
     earlyAccessEnabled: AppClientConfigResponse["earlyAccessEnabled"];
+    authOptions: AppClientConfigResponse["authOptions"];
     isLoading: boolean;
     error: unknown;
 }
@@ -4519,4 +5189,4 @@ interface UseAppConfigResult {
  */
 declare function useAppConfig(): UseAppConfigResult;
 
-export { AUTH_CHOOSER_OPEN_EVENT, type AggAuthContextValue, type AggAuthSignInOptions, type AggBalanceContextValue, AggBalanceProvider, AggProvider, type AggProviderProps, AggProvider as AggSdkProvider, type AggProviderProps as AggSdkProviderProps, type AggUiConfig, type AggUiConfigInput, type AggUiLabels, type AggUiLabelsInput, AggUiProvider, CHART_TIME_RANGES, CONFIRMED_MATCH_STATUSES, type ChartTimeRange, type ClosedPositionTotals, type ComputePriceGapsInput, DEFAULT_AGG_ROOT_CLASS_NAME, type DagStepProgress, type EventListStateContextValue, EventListStateProvider, type EventListStateSnapshot, type EventTradingContextValue, type EventTradingState, type ExecutionProgressPhase, type ExecutionTerminalOrderEvent, type GeoBlockState, type GetOrdersQuery, type GetPositionsQuery, type LiveCandle, type MarketChartCandle, type MarketChartData, type MarketChartVenueData, type MarketOrderbookData, type MarketOrderbookIntegrity, MarketStatus, type MarketTradingState, MatchStatus, MatchType, type OrderEligibility, type OrderEligibilityReason, type OrderListItem, type OrderbookResult, type PositionGroup, type PriceGapMarket, type RedeemEvent, type ScaledCandlePoint, type SdkUiConfig, type SdkUiConfigInput, type SdkUiProviderProps, type ThemeMode, type TradingAction, type TradingState, type TradingStateBase, type TradingStateKind, type UseAggAuthOptions, type UseAggAuthReturn, type UseAppConfigResult, type UseCategoriesOptions, type UseEnrichedVenueEventOptions, type UseExecuteManagedOptions, type UseExecutionOrdersOptions, type UseExecutionPositionsOptions, type UseExecutionProgressOptions, type UseExecutionProgressResult, type UseExternalIdOptions, type UseExternalIdReturn, type UseLinkAccountReturn, type UseLiveCandleOverlayOptions, type UseLiveCandleOverlayResult, type UseLiveCandlesOptions, type UseLiveCandlesResult, type UseLiveMarketResult, type UseMarketChartOptions, type UseMarketChartResult, type UseMarketOrderbookOptions, type UseMarketOrderbookResult, type UseMarketOrderbookVenueOutcome, type UseOrderBookOptions, type UseOrderbookQuoteOptions, type UseOrderbookQuoteResult, type UseOrdersOptions, type UsePositionsOptions, type UseQuoteManagedOptions, type UseSearchOptions, type UseSmartRouteOptions, type UseSmartRouteResult, type UseUserActivityOptions, type UseUserHoldingsOptions, type UseVenueEventOptions, type UseVenueEventsOptions, type UseVenueMarketMidpointsOptions, type UseVenueMarketsOptions, type UseVisibleIdsOptions, type UseVisibleIdsResult, Venue, type VenueEvent, type VenueEventWithMarkets, type VenueMarket, type VenueMarketOutcome, type WalletActionSendTokenParams, type WalletActions, computeClosedPositionTotals, computePriceGaps, defaultAggUiConfig, defaultAggUiConfig as defaultSdkUiConfig, executionKeys, findLivePriceById, getBuilder, getOrCreateBuilder, getWalletAddressFromUserProfile, invalidateBalanceQueries, invalidatePositionQueries, optimizedImageUrl, parseEmail, parseEmailStrict, requestAggAuthChooserOpen, resolveAggUiLabels, resolveDefaultMarket as resolveDefaultTradingMarket, resolveEventTradingState, resolveMarketTradingState, resolveMarketWinningOutcome, resolveOrderEligibility, resolveTradingStateKind, sortVenues, timeRangeToInterval, tradingReducer, useAggAuth, useAggAuthContext, useAggAuthState, useAggBalance, useAggBalanceContext, useAggBalanceState, useAggClient, useAggLabels, useAggUiConfig, useAggWebSocket, useAppConfig, useCategories, useDebouncedValue, useEnrichedVenueEvent, useEventListState, useEventOrderbookData, useEventTradingContext, useExecuteManaged, useExecutionOrders, useExecutionPositions, useExecutionProgress, useExternalId, useGeoBlock, useLabels, useLinkAccount, useLiveCandleOverlay, useLiveCandles, useLiveMarket, useLiveMarketStores, useLiveOutcomePrices, useLiveTrades, useMarketChart, useMarketOrderbook, useMidpoints, useOnBalanceUpdate, useOnOrderSubmitted, useOnRedeemEvent, useOnWithdrawalLifecycle, useOrderBook, useOrderbookQuote, useOrders, usePositions, useQuoteManaged, useRampQuotes, useRampSession, useRedeem, useRedeemEligibleCount, useSdkLabels, useSdkUiConfig, useSearch, useSmartRoute, useUserActivity, useUserHoldings, useVenueEvent, useVenueEvents, useVenueMarketMidpoints, useVenueMarkets, useViewportMidpoints, useVisibleIds };
+export { AUTH_CHOOSER_OPEN_EVENT, type AggAuthContextValue, type AggAuthSignInOptions, type AggBalanceContextValue, AggBalanceProvider, AggProvider, type AggProviderProps, AggProvider as AggSdkProvider, type AggProviderProps as AggSdkProviderProps, type AggUiConfig, type AggUiConfigInput, type AggUiLabels, type AggUiLabelsInput, AggUiProvider, CHART_TIME_RANGES, CONFIRMED_MATCH_STATUSES, type ChartTimeRange, type ClosedPositionTotals, type ComputePriceGapsInput, DEFAULT_AGG_ROOT_CLASS_NAME, type DagStepProgress, type EventListStateContextValue, EventListStateProvider, type EventListStateSnapshot, type EventTradingContextValue, type EventTradingState, type ExecutionProgressPhase, type ExecutionTerminalOrderEvent, type GeoBlockState, type GetOrdersQuery, type GetPositionsQuery, type InvalidateUserActivityOptions, type InvalidateUserMoneyStateOptions, type LiveBestPrices, type LiveCandle, type MarketChartCandle, type MarketChartData, type MarketChartVenueData, type MarketOrderbookData, type MarketOrderbookIntegrity, MarketStatus, type MarketTradingState, MatchStatus, MatchType, type OrderEligibility, type OrderEligibilityReason, type OrderListItem, type OrderbookResult, type PositionGroup, type PriceGapMarket, type RedeemEvent, type RedeemLegLifecycle, type RedeemLifecycleState, RedeemRejectedError, type RollingChartWindow, type ScaledCandlePoint, type SdkUiConfig, type SdkUiConfigInput, type SdkUiProviderProps, type ThemeMode, TradeSide, type TradingAction, type TradingState, type TradingStateBase, type TradingStateKind, type UseAggAuthOptions, type UseAggAuthReturn, type UseAppConfigResult, type UseCategoriesOptions, type UseEnrichedVenueEventOptions, type UseExecuteManagedOptions, type UseExecutionOrdersOptions, type UseExecutionPositionsOptions, type UseExecutionProgressOptions, type UseExecutionProgressResult, type UseExternalIdOptions, type UseExternalIdReturn, type UseLinkAccountReturn, type UseLiveCandleOverlayOptions, type UseLiveCandleOverlayResult, type UseLiveCandlesOptions, type UseLiveCandlesResult, type UseLiveMarketResult, type UseMarketChartOptions, type UseMarketChartResult, type UseMarketOrderbookOptions, type UseMarketOrderbookResult, type UseMarketOrderbookVenueOutcome, type UseMarketSearchOptions, type UseMidpointsResult, type UseOrderBookOptions, type UseOrderbookQuoteOptions, type UseOrderbookQuoteResult, type UseOrdersOptions, type UsePositionsOptions, type UseQuoteManagedOptions, type UseRedeemLifecycleInput, type UseRollingChartWindowOptions, type UseSearchOptions, type UseSmartRouteOptions, type UseSmartRouteResult, type UseTradableVenuesResult, type UseUserActivityOptions, type UseUserHoldingsOptions, type UseVenueEventOptions, type UseVenueEventsOptions, type UseVenueMarketMidpointsOptions, type UseVenueMarketsOptions, type UseVisibleIdsOptions, type UseVisibleIdsResult, type UserActivityInvalidationStrategy, Venue, type VenueEvent, type VenueEventWithMarkets, type VenueMarket, type VenueMarketOutcome, type WalletActionSendTokenParams, type WalletActions, computeClosedPositionTotals, computePriceGaps, defaultAggUiConfig, defaultAggUiConfig as defaultSdkUiConfig, executionKeys, findLivePriceById, getBuilder, getOrCreateBuilder, getWalletAddressFromUserProfile, invalidateBalanceQueries, invalidatePositionQueries, invalidateUserActivityQueries, invalidateUserMoneyState, mergeBestPricesPreferringLive, optimizedImageUrl, parseEmail, parseEmailStrict, rangeToSeconds, requestAggAuthChooserOpen, resolveAggUiLabels, resolveDefaultMarket as resolveDefaultTradingMarket, resolveEventTradingState, resolveMarketTradingState, resolveMarketWinningOutcome, resolveOrderEligibility, resolveRollingWindow, resolveTradingStateKind, sortVenues, timeRangeToInterval, tradingReducer, useAggAuth, useAggAuthContext, useAggAuthState, useAggBalance, useAggBalanceContext, useAggBalanceState, useAggClient, useAggLabels, useAggUiConfig, useAggWebSocket, useAppConfig, useCategories, useDebouncedValue, useEnrichedVenueEvent, useEventListState, useEventOrderbookData, useEventTradingContext, useExecuteManaged, useExecutionOrders, useExecutionPositions, useExecutionProgress, useExternalId, useGeoBlock, useLabels, useLinkAccount, useLiveBestPrices, useLiveCandleOverlay, useLiveCandles, useLiveMarket, useLiveMarketStores, useLiveOutcomePrices, useLiveTrades, useMarketChart, useMarketOrderbook, useMarketSearch, useMidpoints, useOnBalanceUpdate, useOnOrderSubmitted, useOnRedeemEvent, useOnWithdrawalLifecycle, useOrderBook, useOrderbookQuote, useOrders, usePositions, useQuoteManaged, useRampQuotes, useRampSession, useRedeem, useRedeemEligibleCount, useRedeemLifecycle, useRedeemLifecycles, useRollingChartWindow, useSdkLabels, useSdkUiConfig, useSearch, useSmartRoute, useTradableVenues, useUserActivity, useUserHoldings, useVenueEvent, useVenueEvents, useVenueMarketMidpoints, useVenueMarkets, useViewportMidpoints, useVisibleIds, userActivityQueryKeys };