@liberfi.io/ui-perpetuals 0.2.21 → 0.3.0

package/dist/index.d.ts

@@ -12,7 +12,7 @@ declare global {
         };
     }
 }
-declare const _default: "0.2.21";
+declare const _default: "0.3.0";
 
 /**
  * Trading pair symbol format
@@ -271,6 +271,26 @@ interface AccountState {
     totalUnrealizedPnl: number;
     /** Venue-reported server time of the snapshot, if available (ms epoch). */
     serverTime?: number;
+    /**
+     * Per-(coin) leverage configuration extracted from the underlying
+     * push. Mirrors `clearinghouseState.assetPositions[].position.leverage.value`
+     * for every coin where the user has an open position. Consumers
+     * (e.g. {@link useAccountStateSubscription}) write this through to
+     * `useActiveAssetLeverageQuery`'s cache so the place-order form can
+     * read leverage without an extra REST hop.
+     */
+    leverageByCoin?: Record<string, {
+        value: number;
+        type: "isolated" | "cross";
+    }>;
+    /**
+     * Universe snapshot embedded in the push, when the venue's unified
+     * channel carries it (Hyperliquid `webData2` includes
+     * `meta` + `assetCtxs`). Lets {@link useAccountStateSubscription}
+     * keep `useUniverseQuery`'s cache fresh between polls without
+     * issuing extra REST traffic.
+     */
+    universe?: UniverseSnapshot;
     /** Raw payload from the venue (untransformed) for debugging. */
     raw?: any;
 }
@@ -383,6 +403,29 @@ interface Order {
      * "Price above 81470" / "Price below 73761". Mostly useful for tooltips.
      */
     triggerCondition?: string;
+    /**
+     * Live mark price for `coin` at parse time. Populated from
+     * `metaAndAssetCtxs[1][i].markPx` (or its `webData2` equivalent) so the
+     * Open Orders table can show a "Current Price" column without each row
+     * subscribing to the per-asset stream individually. Undefined when the
+     * market context is unavailable.
+     */
+    markPrice?: number;
+    /**
+     * Take-profit trigger price bundled with this order via Hyperliquid's
+     * `normalTpsl` grouping. Populated by walking `children[]` on the
+     * parent Limit order: the child whose `orderType` matches
+     * `Take Profit Market` / `Take Profit Limit` contributes its
+     * `triggerPx` here. Undefined for trigger orders themselves and for
+     * limit orders without a TP child.
+     */
+    takeProfitPrice?: number;
+    /**
+     * Stop-loss trigger price bundled with this order. Same semantics as
+     * {@link takeProfitPrice}, but for `Stop Market` / `Stop Limit`
+     * children.
+     */
+    stopLossPrice?: number;
 }
 /**
  * User trade history
@@ -408,6 +451,22 @@ interface TradeHistory {
     isMaker: boolean;
     /** Trade timestamp (milliseconds) */
     timestamp: number;
+    /**
+     * Venue-supplied human-readable description of what this fill did to
+     * the user's position. Hyperliquid's `dir` field, e.g.
+     * `"Open Long"`, `"Close Short"`, or
+     * `"Market liquidation triggered at <px>"`. Used by the Trades panel
+     * as the row's primary descriptor so we don't have to reconstruct the
+     * action from `side` + reduceOnly heuristics.
+     */
+    dir?: string;
+    /**
+     * Realised PnL on this fill, net of fees. For an opening trade this
+     * is essentially `-fee`; for a closing trade it's
+     * `(closePrice − entryPrice) × size − fee` (sign-flipped for shorts).
+     * Mirrors Hyperliquid's `closedPnl` exactly.
+     */
+    closedPnl?: number;
 }
 /**
  * Place order parameters
@@ -571,6 +630,52 @@ interface GetAssetMetaParams {
     /** Trading pair symbol (e.g. "BTC-USDC"). */
     symbol: string;
 }
+/**
+ * One coin in the venue's universe snapshot.
+ *
+ * Bundles the live market data and the static metadata (`szDecimals`,
+ * `maxLeverage`) so callers only have to round-trip through the venue
+ * once per refresh cycle. Enables {@link IPerpetualsClient.getUniverseSnapshot}
+ * which in turn powers the SDK's `useUniverseQuery` global singleton —
+ * the cure for N-ticker × M-component fan-out polling that triggers
+ * Hyperliquid 429s.
+ *
+ * `meta` is nullable because some adapters (e.g. the LiberFi backend
+ * before it surfaces `szDecimals`) cannot fill it. Consumers fall back
+ * to their own heuristics in that case.
+ */
+interface UniverseAssetEntry {
+    /** Bare coin symbol (e.g. "BTC"). */
+    coin: string;
+    /** Unified trading pair symbol (e.g. "BTC-USDC"). */
+    symbol: string;
+    /** Live market snapshot (price, funding, OI, 24h vol, ...). */
+    market: MarketData;
+    /** Static venue metadata when the adapter exposes it. */
+    meta: AssetMeta | null;
+}
+/**
+ * Whole-universe snapshot returned by
+ * {@link IPerpetualsClient.getUniverseSnapshot}. Indexed by symbol for
+ * O(1) lookup so derived hooks (`useMarketQuery`, `useAssetMetaQuery`,
+ * ticker bars) can pick a slice without iterating.
+ *
+ * Treat the contained `Map` as read-only — React Query's structural
+ * sharing optimisations don't apply to Maps, but the snapshot is
+ * refreshed wholesale once per refresh cycle so identity comparisons
+ * naturally invalidate dependants.
+ */
+interface UniverseSnapshot {
+    /** Every asset the venue currently lists, in venue-published order. */
+    assets: UniverseAssetEntry[];
+    /** O(1) symbol → entry lookup (e.g. "BTC-USDC" → entry). */
+    bySymbol: Map<string, UniverseAssetEntry>;
+    /**
+     * Snapshot timestamp (ms epoch). Sourced from the venue's
+     * `serverTime` when available, otherwise the local clock at parse.
+     */
+    fetchedAt: number;
+}
 /**
  * Get open orders parameters
  */
@@ -806,6 +911,28 @@ interface IPerpetualsClient {
      * @throws {Error} Network error or API error
      */
     getAssetMeta(params: GetAssetMetaParams): Promise<AssetMeta | null>;
+    /**
+     * Optional: fetch the venue's complete universe in a single call.
+     *
+     * When implemented, the SDK uses this to back `useUniverseQuery` —
+     * a global singleton that refreshes once per minute and feeds every
+     * per-symbol consumer (`useMarketQuery`, `useMarketsQuery`,
+     * `useAssetMetaQuery`, ticker bars, ...) from the same snapshot.
+     *
+     * The contract: one network round-trip returns every asset's market
+     * data + (when known) static metadata. This collapses the
+     * "100 tickers × 60s polling" pattern into a single 60s poll —
+     * essential for keeping Hyperliquid `/info` weight under the 1200
+     * weight/min/IP cap.
+     *
+     * Implementations that cannot deliver the entire universe in one
+     * call may omit this method; consumers fall back to per-symbol
+     * polling in that case (legacy behaviour).
+     *
+     * @returns The full universe snapshot.
+     * @throws {Error} Network error or API error.
+     */
+    getUniverseSnapshot?(): Promise<UniverseSnapshot>;
     /**
      * Connect to WebSocket server
      * @throws {Error} Connection failed
@@ -871,6 +998,62 @@ interface IPerpetualsClient {
     unsubscribe(subscriptionId: string): void;
 }
 
+/**
+ * Configuration for {@link RateLimiter}.
+ *
+ * Defaults track Hyperliquid's documented `/info` budget (1200 weight
+ * per minute per IP) and the per-type weight table reverse-engineered
+ * from axiom.trade's deployed `hyperliquid-ts-sdk`. The defaults are
+ * conservative — leaving the same headroom Axiom does — but every
+ * field is overridable so consumers can tighten the budget under
+ * shared egress IPs.
+ */
+interface RateLimiterConfig {
+    /** Total weight the bucket can spend per window. Default 1200. */
+    capacity?: number;
+    /** Window duration in milliseconds. Default 60_000 (1 minute). */
+    windowMs?: number;
+}
+/**
+ * Browser-side token bucket aligned with HL's `/info` weight budget.
+ *
+ * Mirrors the `RateLimiter` in axiom.trade's deployed
+ * `hyperliquid-ts-sdk` byte-for-byte: capacity 1200, refill once per
+ * minute (not continuous), `waitForToken(weight)` blocks until the
+ * next refill when the bucket is empty.
+ *
+ * Treat this as a process-wide singleton — all calls into the same
+ * Hyperliquid REST client share one bucket so concurrent ticker /
+ * order-form / portfolio components cooperate against the upstream
+ * cap.
+ */
+declare class RateLimiter {
+    private readonly capacity;
+    private readonly windowMs;
+    private tokens;
+    private lastRefill;
+    constructor(config?: RateLimiterConfig);
+    /**
+     * Reset the bucket to full capacity. Useful for tests; production
+     * callers should not need this.
+     */
+    reset(): void;
+    /**
+     * Block until `weight` tokens are available, then deduct them and
+     * resolve. Re-checks the refill boundary each pass so a long sleep
+     * never spins past more than one window.
+     */
+    waitForToken(weight: number): Promise<void>;
+    /**
+     * Top up the bucket if a full window has elapsed since the last
+     * refill. Mirrors axiom's discrete-window refill (vs continuous
+     * refill) so the bucket never lets a request through that HL would
+     * reject — the upstream weight counter snaps back at the same
+     * boundary.
+     */
+    private refill;
+}
+
 /**
  * Hyperliquid `l2Book` aggregation parameters.
  *
@@ -919,6 +1102,19 @@ interface HyperliquidClientConfig {
      * @default 30000
      */
     timeout?: number;
+    /**
+     * Outbound rate-limiter configuration. Defaults align with HL's
+     * documented `/info` budget (1200 weight per minute per IP) and the
+     * per-type weight table reverse-engineered from axiom.trade's
+     * deployed hyperliquid-ts-sdk.
+     *
+     * Pass `false` to disable client-side rate limiting (e.g. when
+     * a server-side proxy is already throttling on our behalf). Pass an
+     * existing {@link RateLimiter} instance to share a bucket across
+     * multiple client instances. Pass a partial config to tune capacity
+     * / window for a custom IP egress topology.
+     */
+    rateLimit?: RateLimiter | RateLimiterConfig | false;
 }
 /**
  * HyperliquidPerpetualsClient 类
@@ -955,12 +1151,58 @@ declare class HyperliquidPerpetualsClient implements IPerpetualsClient {
      * collapse onto a single network request when the cache misses.
      */
     private assetMetaPending;
+    /**
+     * Process-local cache of the venue's universe snapshot. Concurrent
+     * `getUniverseSnapshot()` callers within {@link UNIVERSE_SNAPSHOT_TTL_MS}
+     * share the same parsed object (and the underlying
+     * `metaAndAssetCtxs` HTTP call) instead of each firing their own.
+     */
+    private universeSnapshotCache;
+    /**
+     * In-flight `getUniverseSnapshot` request, deduped via
+     * singleflight semantics so concurrent fan-outs (e.g.
+     * `useUniverseQuery` + `getPositions()` + `getOpenOrders()` mounted
+     * in the same render tick) collapse onto a single network request.
+     */
+    private universeSnapshotPending;
+    /**
+     * Process-local cache of per-user state snapshots
+     * (`clearinghouseState` + `frontendOpenOrders`), keyed by lowercased
+     * user address. Concurrent `getPositions(user)` / `getOpenOrders(user)`
+     * callers within {@link USER_STATE_SNAPSHOT_TTL_MS} share the same
+     * parsed object (and the underlying two HL round-trips) instead of
+     * each firing their own pair.
+     */
+    private userStateCache;
+    /**
+     * In-flight `getUserStateSnapshot` requests, deduped per user via
+     * singleflight semantics. Keyed the same way as
+     * {@link userStateCache}.
+     */
+    private userStatePending;
+    /**
+     * Outbound rate limiter shared across every REST call this client
+     * issues. `null` when explicitly disabled via
+     * `config.rateLimit === false` — the request path then becomes a
+     * straight fetch with no bucket bookkeeping.
+     */
+    private readonly rateLimiter;
     /**
      * 构造 Hyperliquid 客户端
      *
      * @param config 客户端配置，不传则使用默认配置（testnet）
      */
     constructor(config?: HyperliquidClientConfig);
+    /**
+     * Compute the bucket weight to charge for a given endpoint + body.
+     *
+     * Mirrors axiom.trade's `hyperliquid-ts-sdk` weight table:
+     *   - `/info` payload `type` → see {@link weightForInfoType}
+     *   - `/exchange` (signed actions) → 1
+     *   - everything else → default 2 (matches HL's "miscellaneous read"
+     *     weight)
+     */
+    private weightFor;
     /**
      * 内部 HTTP 请求方法
      *
@@ -997,11 +1239,64 @@ declare class HyperliquidPerpetualsClient implements IPerpetualsClient {
     getMarket(symbol: string): Promise<MarketData | null>;
     /**
      * 获取多个或所有币种的市场数据
-     * @param symbols 币种符号数组（可选）
-     * @returns 市场数据数组
-     * @throws {HyperliquidApiError} API 请求失败
+     *
+     * Backed by {@link getUniverseSnapshot} so this and `useMarketsQuery`
+     * share the same single `metaAndAssetCtxs` round-trip — keeps the
+     * legacy contract green while the SDK migrates to the universe
+     * singleton.
      */
     getMarkets(symbols?: string[]): Promise<MarketData[]>;
+    /**
+     * Snapshot the venue's full perp universe in a single network call.
+     *
+     * Mirrors axiom.trade's `SymbolConversion.refreshAssetMaps()` — one
+     * `metaAndAssetCtxs` round-trip yields both the live market context
+     * (price / funding / OI / 24h vol) AND the static metadata
+     * (`szDecimals` / `maxLeverage`) for every coin. The SDK funnels every
+     * per-symbol consumer (`useMarketQuery`, `useAssetMetaQuery`,
+     * ticker bars, `getPositions()` / `getOpenOrders()` mark price
+     * enrichment, ...) through this, so 100 components watching the
+     * universe still trigger only one HL request per refresh cycle.
+     *
+     * Backed by a 1.5 s TTL + singleflight cache on the client instance,
+     * so concurrent direct callers within the same tick collapse onto a
+     * single in-flight request — the React Query layer above adds
+     * another tier of dedup keyed by `staleTime`, but caching here too
+     * keeps the contract correct for non-React callers and for
+     * cross-method fan-outs (positions / orders / markets) that go
+     * through `client.*` directly.
+     *
+     * @see {@link IPerpetualsClient.getUniverseSnapshot}
+     */
+    getUniverseSnapshot(): Promise<UniverseSnapshot>;
+    /**
+     * Internal: actually fetch and parse a fresh universe snapshot.
+     * Always issues one `metaAndAssetCtxs` round-trip — call
+     * {@link getUniverseSnapshot} (which guards this with TTL +
+     * singleflight) instead of invoking directly.
+     */
+    private fetchUniverseSnapshot;
+    /**
+     * Snapshot the user's full venue state (`clearinghouseState` +
+     * `frontendOpenOrders`) in a single coordinated fetch, with an
+     * instance-level TTL + singleflight cache.
+     *
+     * Why this exists: `getPositions()` and `getOpenOrders()` each
+     * naturally fan out a `clearinghouseState` and a
+     * `frontendOpenOrders` request to enrich their respective return
+     * shapes. When `usePositionsQuery` and `useOrdersQuery` mount in
+     * the same render tick, that's 2× CHS + 2× FOO over the wire, all
+     * for the same user. Routing both through this snapshot collapses
+     * the burst into a single pair of HL calls (per
+     * {@link USER_STATE_SNAPSHOT_TTL_MS} window). When `webData2` is
+     * online it overwrites the React Query caches directly, so this
+     * REST path stops firing entirely after the first WS frame.
+     *
+     * `clearinghouseState` is mandatory; `frontendOpenOrders` is
+     * fault-tolerant — the venue occasionally errors on the second leg
+     * for fresh users, and we still want positions to render.
+     */
+    private getUserStateSnapshot;
     /**
      * Fetch kline / candlestick data.
      *
@@ -1545,6 +1840,20 @@ declare class LiberFiPerpetualsClient implements IPerpetualsClient {
     getSupportedCoins(): Promise<string[]>;
     getMarket(symbol: string): Promise<MarketData | null>;
     getMarkets(symbols?: string[]): Promise<MarketData[]>;
+    /**
+     * Snapshot the venue's full perp universe via a single `/v1/markets`
+     * call.
+     *
+     * Hosts the SDK's `useUniverseQuery` global singleton — every
+     * per-symbol consumer (ticker bars, market headers, asset meta
+     * lookups, ...) derives from this so 100 components watching the
+     * universe still trigger only one request per refresh cycle.
+     *
+     * `meta` stays `null` because the LiberFi backend does not yet
+     * expose `szDecimals` / `maxLeverage`. Consumers that need that data
+     * fall back to their own heuristics (the form already does this).
+     */
+    getUniverseSnapshot(): Promise<UniverseSnapshot>;
     getKlines(symbol: string, interval: KlineInterval, limitOrOptions?: number | KlineQueryOptions): Promise<Kline[]>;
     getOrderBook(symbol: string, maxLevel?: number, options?: {
         nSigFigs?: number;
@@ -1951,6 +2260,16 @@ interface UseMarketQueryParams {
 }
 declare function marketQueryKey(params: UseMarketQueryParams): string[];
 declare function fetchMarket(client: IPerpetualsClient, { symbol }: UseMarketQueryParams): Promise<MarketData | null>;
+/**
+ * Read the live market snapshot for `symbol`.
+ *
+ * When the active adapter exposes {@link IPerpetualsClient.getUniverseSnapshot}
+ * (Hyperliquid + LiberFi today), this hook becomes a thin selector
+ * over the global {@link useUniverseQuery} cache — every ticker /
+ * header / order form in the page shares the same single 60s poll.
+ * Otherwise we fall back to the legacy per-symbol REST query so older
+ * deployments keep working unchanged.
+ */
 declare function useMarketQuery(params: UseMarketQueryParams, options?: Omit<UseQueryOptions<MarketData | null, Error, MarketData | null, string[]>, "queryKey" | "queryFn">): _tanstack_react_query.UseQueryResult<MarketData | null, Error>;
 
 interface UseMarketsQueryParams {
@@ -1958,8 +2277,65 @@ interface UseMarketsQueryParams {
 }
 declare function marketsQueryKey(params?: UseMarketsQueryParams): string[];
 declare function fetchMarkets(client: IPerpetualsClient, { symbols }?: UseMarketsQueryParams): Promise<MarketData[]>;
+/**
+ * Read live market snapshots for one or more symbols.
+ *
+ * When the active adapter exposes
+ * {@link IPerpetualsClient.getUniverseSnapshot}, this is a derived
+ * read over the global {@link useUniverseQuery} cache — a 100-ticker
+ * bar still triggers only one HL `metaAndAssetCtxs` request per 60s.
+ * Otherwise we fall back to the legacy `getMarkets()` REST poll.
+ */
 declare function useMarketsQuery(params?: UseMarketsQueryParams, options?: Omit<UseQueryOptions<MarketData[], Error, MarketData[], string[]>, "queryKey" | "queryFn">): _tanstack_react_query.UseQueryResult<MarketData[], Error>;
 
+/**
+ * Stable React Query key for the global universe snapshot.
+ *
+ * The key is intentionally argument-free so every consumer in the
+ * application reads from the same cache slot. Hooks like
+ * {@link useMarketQuery}, {@link useMarketsQuery},
+ * {@link useAssetMetaQuery} and ticker bars derive their data from
+ * here via `select`, sharing one network round-trip per refresh cycle.
+ */
+declare function universeQueryKey(): string[];
+/**
+ * Fetch the venue's universe snapshot through the active client.
+ *
+ * Throws when the active adapter doesn't implement
+ * `getUniverseSnapshot` — callers should gate on
+ * {@link supportsUniverseSnapshot} first or rely on
+ * {@link useUniverseQuery}'s `enabled` guard, which checks the same
+ * thing.
+ */
+declare function fetchUniverse(client: IPerpetualsClient): Promise<UniverseSnapshot>;
+/**
+ * Reports whether the active client can back {@link useUniverseQuery}.
+ *
+ * Adapters that omit `getUniverseSnapshot` (e.g. legacy LiberFi
+ * deployments that still proxy market data per symbol) leave
+ * `useUniverseQuery` disabled; consumers gracefully fall back to the
+ * legacy per-symbol queries in that case.
+ */
+declare function supportsUniverseSnapshot(client: IPerpetualsClient): boolean;
+/**
+ * Subscribe to the venue's universe snapshot.
+ *
+ * One global singleton: every {@link useUniverseQuery} call shares the
+ * same `["perps", "universe"]` cache slot, so React Query collapses
+ * concurrent consumers onto a single in-flight request and a single
+ * 60-second polling timer regardless of how many components mount.
+ *
+ * Per-symbol hooks (`useMarketQuery`, `useMarketsQuery`,
+ * `useAssetMetaQuery`) read this cache via `select` so they don't
+ * issue their own network requests — the cure for the N-ticker fan-out
+ * pattern that triggers Hyperliquid 429s.
+ *
+ * The cache is also populated by `useAccountStateSubscription` when
+ * `webData2` pushes meta / assetCtxs, so an active WebSocket session
+ * keeps the universe fresh between polls without extra REST traffic.
+ */
+declare function useUniverseQuery(options?: Omit<UseQueryOptions<UniverseSnapshot, Error, UniverseSnapshot, string[]>, "queryKey" | "queryFn">): _tanstack_react_query.UseQueryResult<UniverseSnapshot, Error>;
+
 interface UseKlinesQueryParams {
     symbol: string;
     interval: KlineInterval;
@@ -1994,14 +2370,34 @@ declare function useRecentTradesQuery(params: UseRecentTradesQueryParams, option
 interface UsePositionsQueryParams extends GetPositionsParams {
     enabled?: boolean;
 }
-declare function positionsQueryKey(params: Omit<UsePositionsQueryParams, "enabled">): string[];
+/**
+ * Canonical query key for the user's full positions snapshot. Always
+ * keyed by `userAddress` only — per-symbol consumers derive a filtered
+ * view via TanStack Query's `select` option so the entire app shares
+ * one in-flight request per user, regardless of how many symbol-scoped
+ * widgets are mounted (positions table + order form + position card +
+ * ...).
+ *
+ * Backwards-compatibility: callers that previously passed a `symbol`
+ * still get the same shape they expect (filtered positions), just
+ * without firing an extra `clearinghouseState` / `frontendOpenOrders` /
+ * `metaAndAssetCtxs` round-trip.
+ */
+declare function positionsQueryKey(params: Omit<UsePositionsQueryParams, "enabled" | "symbol">): string[];
 declare function fetchPositions(client: IPerpetualsClient, params: GetPositionsParams): Promise<GetPositionsResult>;
 declare function usePositionsQuery(params: UsePositionsQueryParams, options?: Omit<UseQueryOptions<GetPositionsResult, Error, GetPositionsResult, string[]>, "queryKey" | "queryFn">): _tanstack_react_query.UseQueryResult<GetPositionsResult, Error>;
 
 interface UseOrdersQueryParams extends GetOpenOrdersParams {
     enabled?: boolean;
 }
-declare function ordersQueryKey(params: Omit<UseOrdersQueryParams, "enabled">): string[];
+/**
+ * Canonical query key for the user's full open-orders snapshot. Like
+ * {@link positionsQueryKey}, the symbol is intentionally absent from
+ * the key — per-symbol callers derive a filtered view via `select`
+ * so the entire app shares one in-flight `frontendOpenOrders` /
+ * `clearinghouseState` / `metaAndAssetCtxs` fan-out per user.
+ */
+declare function ordersQueryKey(params: Omit<UseOrdersQueryParams, "enabled" | "symbol">): string[];
 declare function fetchOrders(client: IPerpetualsClient, params: GetOpenOrdersParams): Promise<GetOpenOrdersResult>;
 declare function useOrdersQuery(params: UseOrdersQueryParams, options?: Omit<UseQueryOptions<GetOpenOrdersResult, Error, GetOpenOrdersResult, string[]>, "queryKey" | "queryFn">): _tanstack_react_query.UseQueryResult<GetOpenOrdersResult, Error>;
 
@@ -2066,15 +2462,17 @@ declare function assetMetaQueryKey(params: {
 declare function fetchAssetMeta(client: IPerpetualsClient, params: GetAssetMetaParams): Promise<AssetMeta | null>;
 /**
  * Read the venue's static metadata (`szDecimals`, `maxLeverage`) for
- * `symbol`. Backed by Hyperliquid's `meta` info endpoint when the
- * active provider is Hyperliquid; the LiberFi adapter currently
- * returns `null` (the form falls back to an adaptive precision rule).
+ * `symbol`.
  *
- * The data is process-stable for minutes at a time (Hyperliquid only
- * updates the universe on listing additions / leverage cap changes),
- * so we set a generous `staleTime` of 60 seconds. Consumers don't
- * need to invalidate this on user actions — the data is keyed on
- * symbol alone.
+ * When the active adapter exposes `getUniverseSnapshot` (Hyperliquid +
+ * LiberFi today), this is a derived read over the
+ * {@link useUniverseQuery} cache — no extra `meta` round-trip is
+ * issued per symbol. Otherwise we fall back to the legacy
+ * `client.getAssetMeta(...)` call.
+ *
+ * The data is process-stable for minutes at a time, so the fallback
+ * uses a 60s `staleTime`; consumers don't need to invalidate this on
+ * user actions — the data is keyed on symbol alone.
  */
 declare function useAssetMetaQuery(params: UseAssetMetaQueryParams, options?: Omit<UseQueryOptions<AssetMeta | null, Error, AssetMeta | null, string[]>, "queryKey" | "queryFn">): _tanstack_react_query.UseQueryResult<AssetMeta | null, Error>;
 
@@ -2232,6 +2630,50 @@ declare function accountStateQueryKey(params: Pick<UseAccountStateQueryParams, "
  */
 declare function useAccountStateQuery(params: UseAccountStateQueryParams, options?: Omit<UseQueryOptions<AccountState | null, Error, AccountState | null, string[]>, "queryKey" | "queryFn">): _tanstack_react_query.UseQueryResult<AccountState | null, Error>;
 
+interface UseHyperliquidUserBootstrapParams {
+    /**
+     * Wallet address whose positions / open orders should be seeded.
+     * The hook is a no-op when undefined or empty so it's safe to mount
+     * before authentication completes.
+     */
+    userAddress?: string;
+    /**
+     * Disable the bootstrap entirely (useful for SSR). Defaults to true.
+     */
+    enabled?: boolean;
+    /**
+     * Grace period before falling back to REST. webData2's initial
+     * snapshot typically lands within ~500ms; we wait a little longer
+     * to cover slow WS handshakes / network blips before paying for a
+     * REST round-trip. Defaults to 3 000 ms.
+     */
+    timeoutMs?: number;
+}
+/**
+ * One-shot REST bootstrap for the user's perpetuals state.
+ *
+ * Mirrors axiom.trade's first-connect behaviour: when the page
+ * mounts, the WS singleton (`useAccountStateSubscription`) is the
+ * primary channel for positions / orders / spot balances, and any
+ * subsequent updates are pushed via `webData2`. The first frame
+ * usually arrives before any UI gating matters, but on slow WS
+ * handshakes the place-order form can blink a "loading" state for
+ * seconds.
+ *
+ * This hook covers that gap: after `timeoutMs` of inactivity it
+ * issues exactly **one** REST round-trip (positions + open orders) to
+ * seed the React Query cache, then stops. If `webData2`'s initial
+ * snapshot has already populated the cache by the time the timer
+ * fires, the fallback is skipped — keeping HL `/info` traffic at a
+ * minimum even on cold pages.
+ *
+ * Mount this hook **once** at the same level as
+ * `useAccountStateSubscription` (typically the perpetuals shell /
+ * layout). Children read positions / orders through the existing
+ * query hooks; nothing else needs to know the bootstrap exists.
+ */
+declare function useHyperliquidUserBootstrap(params: UseHyperliquidUserBootstrapParams): void;
+
 /**
  * Hook to access the deposit client from `PerpetualsProvider`.
  *
@@ -2841,6 +3283,8 @@ type UsePlaceOrderFormScriptResult = {
     handleSubmit: (data: PlaceOrderFormData) => Promise<void>;
     isSubmitting: boolean;
     currentPrice?: number;
+    /** Raw venue mark price, unaffected by user's limit price input. */
+    marketPrice: number;
     estimatedFee: number;
     estimatedTotal: number;
     liquidationPrice?: number;
@@ -2915,6 +3359,8 @@ type PlaceOrderFormUIProps = {
     isSubmitting: boolean;
     symbol: string;
     currentPrice?: number;
+    /** Raw venue mark price for display reference (unaffected by limit price input). */
+    marketPrice?: number;
     estimatedFee: number;
     estimatedTotal: number;
     liquidationPrice?: number;
@@ -2976,24 +3422,74 @@ type PlaceOrderFormUIProps = {
      */
     onUpdateLeverage?: (leverage: number) => Promise<void>;
 };
-declare function PlaceOrderFormUI({ methods, side, orderType, onSideChange, onOrderTypeChange, onSubmit, isSubmitting, symbol, currentPrice, estimatedFee, liquidationPrice, availableMargin, accountValue, currentPosition, maxLeverage, isLeverageReady, hasOpenOrdersForSymbol, szDecimals, onAddFunds, onUpdateLeverage, }: PlaceOrderFormUIProps): react_jsx_runtime.JSX.Element;
+declare function PlaceOrderFormUI({ methods, side, orderType, onSideChange, onOrderTypeChange, onSubmit, isSubmitting, symbol, currentPrice, marketPrice, estimatedFee, liquidationPrice, availableMargin, accountValue, currentPosition, maxLeverage, isLeverageReady, hasOpenOrdersForSymbol, szDecimals, onAddFunds, onUpdateLeverage, }: PlaceOrderFormUIProps): react_jsx_runtime.JSX.Element;
+
+type CloseType = "market" | "limit";
+type UseClosePositionParams = {
+    userAddress?: string;
+    onCloseSuccess?: () => void;
+    onCloseError?: (error: Error) => void;
+    /**
+     * Optional callback that bypasses the SDK's internal mutation and lets
+     * the host sign + relay the close order itself (same pattern as the
+     * place-order form's `onPlaceOrder`).
+     */
+    onPlaceOrder?: (params: {
+        symbol: string;
+        side: "long" | "short";
+        orderType: OrderType;
+        amount: number;
+        price?: number;
+        leverage: number;
+        reduceOnly: boolean;
+        userAddress: string;
+    }) => Promise<PlaceOrderResult>;
+};
+type UseClosePositionResult = {
+    isModalOpen: boolean;
+    selectedPosition: Position | null;
+    closeType: CloseType;
+    isClosing: boolean;
+    openMarketClose: (position: Position) => void;
+    openLimitClose: (position: Position) => void;
+    handleConfirm: (size: number, price?: number) => Promise<void>;
+    closeModal: () => void;
+};
+/**
+ * Hook that owns the close-position modal lifecycle:
+ *   - Which position is selected and which close type (market / limit)
+ *   - Submitting the close order via `useCreateOrderMutation`
+ *
+ * The UI layer (modal component) owns the size / percentage / price
+ * input state — this hook only cares about the final confirmed values.
+ */
+declare function useClosePosition({ userAddress, onCloseSuccess, onCloseError, onPlaceOrder, }: UseClosePositionParams): UseClosePositionResult;
 
 type PositionsWidgetProps = {
     userAddress?: string;
     symbol?: string;
     onCloseSuccess?: () => void;
     onCloseError?: (error: Error) => void;
+    onPlaceOrder?: UseClosePositionParams["onPlaceOrder"];
     className?: string;
 };
 /**
  * Positions table widget. Owns no business logic — wires the
- * `usePositionsScript` data layer (sort + close-mutation) to the
- * presentational `PositionsUI`. The host page just provides the
- * connected wallet address and (optionally) a symbol filter; the
- * widget handles everything else (sort state, realtime updates,
- * close-position toasts in the consumer's mutation lifecycle).
+ * `usePositionsScript` data layer (sort + close-modal) to the
+ * presentational `PositionsUI` and the `ClosePositionModal`. The host
+ * page just provides the connected wallet address and (optionally) a
+ * symbol filter; the widget handles everything else.
  */
-declare function PositionsWidget({ userAddress, symbol, onCloseSuccess, onCloseError, className, }: PositionsWidgetProps): react_jsx_runtime.JSX.Element;
+declare function PositionsWidget({ userAddress, symbol, onCloseSuccess, onCloseError, onPlaceOrder, className, }: PositionsWidgetProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Two-state sort direction. We deliberately do not model a "no sort"
+ * state: when a user clicks a fresh column the table starts at `asc`
+ * (or `desc` if that's the column's natural default) and toggles
+ * between `asc` ↔ `desc` thereafter — mirroring Axiom's UX so users
+ * never have to click three times to clear an accidental sort.
+ */
+type SortDirection = "asc" | "desc";
 
 /**
  * Stable identifier for a sortable column. Mirrors Axiom's set: 7 of the
@@ -3005,7 +3501,7 @@ declare function PositionsWidget({ userAddress, symbol, onCloseSuccess, onCloseE
  * insulated from enum-numbering churn.
  */
 type PositionSortKey = "asset" | "position" | "value" | "entry" | "mark" | "liq" | "marginPnl";
-type SortDirection = "asc" | "desc";
+
 type PositionsUIProps = {
     /** Already-sorted positions. The script layer owns sort state. */
     positions: Position[];
@@ -3013,12 +3509,13 @@ type PositionsUIProps = {
     sortKey: PositionSortKey | null;
     sortDir: SortDirection;
     onSort: (key: PositionSortKey) => void;
-    onClosePosition: (position: Position) => void;
+    onMarketClose: (position: Position) => void;
+    onLimitClose: (position: Position) => void;
     isClosing: boolean;
     /** Optional className for the outer container. */
     className?: string;
 };
-declare function PositionsUI({ positions, sortKey, sortDir, onSort, onClosePosition, isClosing, className, }: PositionsUIProps): react_jsx_runtime.JSX.Element;
+declare function PositionsUI({ positions, sortKey, sortDir, onSort, onMarketClose, onLimitClose, isClosing, className, }: PositionsUIProps): react_jsx_runtime.JSX.Element;
 /** Loading skeleton for positions panel */
 declare function PositionsSkeleton(): react_jsx_runtime.JSX.Element;
 /**
@@ -3033,6 +3530,7 @@ type UsePositionsScriptParams = {
     symbol?: string;
     onCloseSuccess?: () => void;
     onCloseError?: (error: Error) => void;
+    onPlaceOrder?: UseClosePositionParams["onPlaceOrder"];
 };
 type UsePositionsScriptResult = {
     /** Positions already sorted by the active `sortKey` / `sortDir`. */
@@ -3046,8 +3544,8 @@ type UsePositionsScriptResult = {
      * first click on a new column → asc, subsequent clicks toggle asc ↔
      * desc. There is no "no-sort" state. */
     onSort: (key: PositionSortKey) => void;
-    handleClosePosition: (position: Position) => Promise<void>;
-    isClosing: boolean;
+    /** Close-position modal lifecycle (market + limit). */
+    closePosition: UseClosePositionResult;
 };
 /**
  * Container hook for the positions table. Responsibilities:
@@ -3059,85 +3557,343 @@ type UsePositionsScriptResult = {
  *   - own sort state (default `marginPnl ↓` — biggest margin first).
  *   - expose a `handleClosePosition` shim over `useCreateOrderMutation`.
  */
-declare function usePositionsScript({ userAddress, symbol, onCloseSuccess, onCloseError, }: UsePositionsScriptParams): UsePositionsScriptResult;
+declare function usePositionsScript({ userAddress, symbol, onCloseSuccess, onCloseError, onPlaceOrder, }: UsePositionsScriptParams): UsePositionsScriptResult;
 
-type OpenOrdersWidgetProps = {
-    userAddress?: string;
-    symbol?: string;
-    onCancelSuccess?: () => void;
-    onCancelError?: (error: Error) => void;
-    className?: string;
+type ClosePositionModalProps = {
+    isOpen: boolean;
+    position: Position | null;
+    closeType: CloseType;
+    isSubmitting: boolean;
+    onClose: () => void;
+    onConfirm: (size: number, price?: number) => Promise<void>;
 };
-declare function OpenOrdersWidget({ userAddress, symbol, onCancelSuccess, onCancelError, className, }: OpenOrdersWidgetProps): react_jsx_runtime.JSX.Element;
+declare function ClosePositionModal({ isOpen, position, closeType, isSubmitting, onClose, onConfirm, }: ClosePositionModalProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Stable identifier for a sortable column. 9 of the 12 columns are
+ * sortable; `triggerCondition`, `tpsl`, `cancel` are interaction-only.
+ *
+ * Kept as a discriminated string union (rather than an enum) so it
+ * survives a tsup build to a stable runtime string — consumers that
+ * persist the active sort key to local-storage / URL params are
+ * insulated from enum-numbering churn.
+ */
+type OpenOrderSortKey = "time" | "size" | "asset" | "direction" | "type" | "leverage" | "orderValue" | "executePrice" | "currentPrice";
 
 type OpenOrdersUIProps = {
+    /** Already-sorted orders. The script layer owns sort state. */
     orders: Order[];
+    /** Currently active sort column, or `null` when no sort applied. */
+    sortKey: OpenOrderSortKey | null;
+    sortDir: SortDirection;
+    onSort: (key: OpenOrderSortKey) => void;
     onCancelOrder: (order: Order) => void;
-    isCanceling: boolean;
+    onCancelAll: () => void;
+    /**
+     * Set of order ids currently being cancelled via the per-row path.
+     * The row whose id is present in the set renders an inline spinner
+     * in place of its `x` icon; sibling rows stay clickable so the
+     * user can cancel several orders concurrently.
+     */
+    cancelingOrderIds: ReadonlySet<string>;
+    /**
+     * `true` while a `Cancel All` batch is in flight. Drives the
+     * header button's spinner and gates *every* row's cancel button
+     * (mid-batch, individual rows shouldn't accept new clicks).
+     */
+    isCancelingAll: boolean;
+    /** Optional className for the outer container. */
+    className?: string;
 };
-declare function OpenOrdersUI({ orders, onCancelOrder, isCanceling, }: OpenOrdersUIProps): react_jsx_runtime.JSX.Element;
+declare function OpenOrdersUI({ orders, sortKey, sortDir, onSort, onCancelOrder, onCancelAll, cancelingOrderIds, isCancelingAll, className, }: OpenOrdersUIProps): react_jsx_runtime.JSX.Element;
+/** Loading skeleton for open orders panel */
 declare function OpenOrdersSkeleton(): react_jsx_runtime.JSX.Element;
+/**
+ * Standalone empty-state component. The main `OpenOrdersUI` renders
+ * its own empty layout (header + centred message) so this export
+ * exists for consumers that wire their own empty state outside the
+ * widget.
+ */
 declare function OpenOrdersEmpty(): react_jsx_runtime.JSX.Element;
 
+/**
+ * Caller-provided cancel implementation for a single order. Mirrors
+ * the `onPlaceOrder` IoC point on the place-order form: when supplied,
+ * the script / widget delegates the actual signing + submit to the
+ * host instead of routing through the active
+ * `IPerpetualsClient.cancelOrder`.
+ *
+ * Hosts that talk directly to a venue from the browser (e.g. signing
+ * Hyperliquid `cancel` actions with the user's wallet) inject this
+ * to bypass the SDK's read-only `HyperliquidPerpetualsClient.cancelOrder`
+ * stub. Hosts that proxy through perpetuals-server (LiberFi TEE) leave
+ * it undefined and let the default path run.
+ */
+type CancelOrderImpl = (params: CancelOrderParams) => Promise<CancelOrderResult>;
+/**
+ * Optional batch counterpart to {@link CancelOrderImpl}. When supplied,
+ * `handleCancelAll` invokes this once with every leg, so direct-venue
+ * hosts (Hyperliquid, Lighter, etc.) can issue a single signature
+ * covering all cancels rather than prompting the user N times.
+ *
+ * When omitted, the script falls back to
+ * `Promise.allSettled(orders.map(cancelOrder))` — correct behaviour
+ * for backends like perpetuals-server that own the signature flow
+ * (each leg is a no-op API call), but a UX trap when the host signs
+ * locally because every leg will trigger a fresh wallet prompt.
+ */
+type CancelOrdersImpl = (params: CancelOrderParams[]) => Promise<CancelOrderResult[]>;
 type UseOpenOrdersScriptParams = {
     userAddress?: string;
     symbol?: string;
     onCancelSuccess?: () => void;
     onCancelError?: (error: Error) => void;
+    /**
+     * Optional host-provided single-order cancel implementation. When
+     * omitted, the script falls back to {@link useCancelOrderMutation}
+     * which routes through the active client — appropriate for backends
+     * that own the signature flow (e.g. LiberFi perpetuals-server). For
+     * direct-venue setups (consumer holds the wallet keys), pass an
+     * implementation that signs + relays the cancel itself.
+     */
+    cancelOrder?: CancelOrderImpl;
+    /**
+     * Optional host-provided batch cancel implementation. When supplied
+     * it is used by `handleCancelAll` (and by single cancels too —
+     * the script wraps the param into a 1-element array so the host
+     * can keep one entry point). When omitted, batch cancels fan out to
+     * the per-order path with `Promise.allSettled`.
+     */
+    cancelOrders?: CancelOrdersImpl;
 };
 type UseOpenOrdersScriptResult = {
+    /** Orders already sorted by the active `sortKey` / `sortDir`. */
     orders: Order[];
     isLoading: boolean;
     error: Error | null;
+    /** Active sort column. Default: `time` desc — newest first, like Axiom. */
+    sortKey: OpenOrderSortKey | null;
+    sortDir: SortDirection;
+    /**
+     * Toggle the sort column / direction. Mirrors Axiom's 2-state cycle:
+     * first click on a new column → asc, subsequent clicks toggle asc ↔
+     * desc. There is no "no-sort" state.
+     */
+    onSort: (key: OpenOrderSortKey) => void;
+    /** Cancel a single order by id. */
     handleCancelOrder: (order: Order) => Promise<void>;
+    /**
+     * Cancel every currently-loaded order. Resolves once every leg has
+     * finished (success **or** failure — leg failures are reported via
+     * `onCancelError` per-leg, but do not abort the batch). The widget's
+     * confirmation dialog calls this only after the user explicitly
+     * confirms — the script does not gate on a dialog itself.
+     */
+    handleCancelAll: () => Promise<void>;
+    /**
+     * `true` while *any* cancel mutation (single OR batch) is in flight.
+     * Kept for backwards-compatibility with hosts that only need the
+     * coarse-grained "is anything cancelling?" signal. New UI surfaces
+     * (per-row spinners, header `Cancel All` spinner) should prefer
+     * the more specific signals below — this flag is intentionally
+     * **not** the recommended way to drive a row's spinner because it
+     * would light up every row whenever any row is cancelling.
+     */
     isCanceling: boolean;
+    /**
+     * Set of order ids currently being cancelled via the per-row path.
+     * The UI uses this to render an inline spinner on the exact row(s)
+     * the user clicked while leaving sibling rows untouched — clicks
+     * on different rows can run concurrently, so a single boolean
+     * would conflate them.
+     *
+     * Returned as a `ReadonlySet` so consumers can't accidentally
+     * mutate the script's internal state. `Set` (not `Array`) keeps
+     * `has(orderId)` O(1) for the row-render hot path.
+     */
+    cancelingOrderIds: ReadonlySet<string>;
+    /**
+     * `true` while a `Cancel All` batch is in flight (regardless of
+     * whether the host injected a batch impl or we fanned out to
+     * per-leg cancels). The UI uses this to swap the header's
+     * `Cancel All` text for a spinner so the user gets feedback the
+     * click was registered. Distinct from `cancelingOrderIds` so the
+     * header spinner doesn't fire when only a single per-row cancel
+     * is running, and vice versa.
+     */
+    isCancelingAll: boolean;
 };
-declare function useOpenOrdersScript({ userAddress, symbol, onCancelSuccess, onCancelError, }: UseOpenOrdersScriptParams): UseOpenOrdersScriptResult;
+/**
+ * Container hook for the Open Orders table.
+ *
+ * Responsibilities:
+ *   - Read open orders via {@link useOrdersQuery}. The consumer's
+ *     `useAccountStateSubscription` keeps the cache live via the
+ *     `webData2` write-through path, which already enriches each
+ *     order with leverage / mark-price / bundled TP/SL — so we
+ *     deliberately do **not** subscribe to a per-order user-data
+ *     stream here. Doing so would clobber that enrichment.
+ *   - Own sort state (default `time ↓` — newest order first).
+ *   - Expose `handleCancelOrder` (single) and `handleCancelAll`
+ *     (batch) shims over `useCancelOrderMutation`.
+ *
+ * Cancel-all does not present a confirmation prompt itself — that
+ * responsibility lives in the widget, which renders the dialog and
+ * only calls `handleCancelAll()` after the user confirms. Keeping the
+ * confirmation in the widget makes the script trivially testable
+ * (deterministic mutation calls) and lets headless consumers skip the
+ * dialog entirely.
+ */
+declare function useOpenOrdersScript({ userAddress, symbol, onCancelSuccess, onCancelError, cancelOrder: cancelOrderImpl, cancelOrders: cancelOrdersImpl, }: UseOpenOrdersScriptParams): UseOpenOrdersScriptResult;
 
-type TimeRange = "today" | "7d" | "30d" | "all";
-type UseTradeHistoryScriptParams = {
+type OpenOrdersWidgetProps = {
     userAddress?: string;
     symbol?: string;
-    initialTimeRange?: TimeRange;
-    pageSize?: number;
-};
-type UseTradeHistoryScriptResult = {
-    trades: TradeHistory[];
-    isLoading: boolean;
-    error: Error | null;
-    timeRange: TimeRange;
-    setTimeRange: (range: TimeRange) => void;
-    currentPage: number;
-    totalPages: number;
-    goToNextPage: () => void;
-    goToPreviousPage: () => void;
-    goToPage: (page: number) => void;
+    onCancelSuccess?: () => void;
+    onCancelError?: (error: Error) => void;
+    /**
+     * Optional host-provided single-order cancel implementation — see
+     * {@link CancelOrderImpl}. Forwarded verbatim to
+     * {@link useOpenOrdersScript}. Hosts that own the wallet keys
+     * (direct-venue setups) inject this; hosts that proxy via a
+     * server with TEE signing leave it undefined.
+     */
+    cancelOrder?: CancelOrderImpl;
+    /**
+     * Optional host-provided batch cancel implementation — see
+     * {@link CancelOrdersImpl}. When supplied, `Cancel All` issues a
+     * single signature for every open order at once (the recommended
+     * UX for direct-venue setups; perpetuals-server proxies don't need
+     * it because each leg is a no-op API call from the user's
+     * perspective).
+     */
+    cancelOrders?: CancelOrdersImpl;
+    className?: string;
 };
-declare function useTradeHistoryScript({ userAddress, symbol, initialTimeRange, pageSize, }: UseTradeHistoryScriptParams): UseTradeHistoryScriptResult;
+/**
+ * Convenience widget that wires {@link useOpenOrdersScript} (data + sort
+ * + cancel mutations) to {@link OpenOrdersUI} (presentation), and adds
+ * a confirmation dialog for the destructive `Cancel All` action.
+ *
+ * The dialog state lives here (not in the script) so:
+ *   - The script stays trivially testable — its `handleCancelAll` is a
+ *     deterministic mutation call without any UI side effects.
+ *   - Headless / programmatic callers that import the script directly
+ *     can skip the dialog entirely (e.g. CI tooling, batch scripts).
+ *
+ * Single-order cancels go through directly: clicking the per-row `x`
+ * button is already an explicit, low-impact gesture, and adding a
+ * second prompt for every row would feel obstructive — matches Axiom.
+ *
+ * The confirm dialog matches the visual language of the place-order
+ * `LeverageModal` and `DepositHyperliquidUsdcModal` (zinc-900 surface,
+ * 14px corner radius, soft shadow, custom 5-px-padded header with an
+ * X close button) so all destructive / confirm modals in the
+ * perpetuals UI feel like one family.
+ */
+declare function OpenOrdersWidget({ userAddress, symbol, onCancelSuccess, onCancelError, cancelOrder, cancelOrders, className, }: OpenOrdersWidgetProps): react_jsx_runtime.JSX.Element;
 
 type TradeHistoryWidgetProps = {
+    /** User wallet address. The widget gates the underlying query on this. */
     userAddress?: string;
+    /**
+     * Optional venue-side filter. Omit to show fills from every coin —
+     * Axiom's bottom-Trades panel is all-coin, and the consumer-facing
+     * widgets (Positions / Open Orders / Trades) follow the same
+     * convention so the three tabs share a coherent UX.
+     */
     symbol?: string;
-    initialTimeRange?: TimeRange;
-    pageSize?: number;
+    /** Optional className on the outermost container. */
     className?: string;
 };
-declare function TradeHistoryWidget({ userAddress, symbol, initialTimeRange, pageSize, className, }: TradeHistoryWidgetProps): react_jsx_runtime.JSX.Element;
+/**
+ * Convenience widget that wires {@link useTradeHistoryScript} (data +
+ * sort) to {@link TradeHistoryUI} (presentation). Intentionally thin —
+ * unlike Open Orders there's no destructive action to gate behind a
+ * confirmation dialog, so the widget is just a pass-through.
+ *
+ * Headless callers (CI, programmatic exports) can import the script
+ * directly without the UI; the script's return shape is the public
+ * contract.
+ */
+declare function TradeHistoryWidget({ userAddress, symbol, className, }: TradeHistoryWidgetProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Stable identifier for a sortable column. All 7 visible columns are
+ * sortable; mirrors Axiom's bottom-Trades panel 1:1. Using a discriminated
+ * string union (rather than an enum) so the value survives a tsup build
+ * to a stable runtime string — consumers persisting the active sort to
+ * local-storage / URL params don't pay an enum-numbering tax.
+ */
+type TradeHistorySortKey = "time" | "size" | "asset" | "description" | "price" | "tradeValue" | "closedPnl";
 
 type TradeHistoryUIProps = {
+    /** Already-sorted trades. The script layer owns sort state. */
     trades: TradeHistory[];
-    timeRange: TimeRange;
-    onTimeRangeChange: (range: TimeRange) => void;
-    currentPage: number;
-    totalPages: number;
-    onNextPage: () => void;
-    onPreviousPage: () => void;
-    onGoToPage: (page: number) => void;
+    /** Currently active sort column. Always non-null — Axiom never exits
+     *  the sort state, defaulting to `Time ↓`. */
+    sortKey: TradeHistorySortKey;
+    sortDir: SortDirection;
+    onSort: (key: TradeHistorySortKey) => void;
+    /** Optional className on the outermost container. */
+    className?: string;
 };
-declare function TradeHistoryUI({ trades, timeRange, onTimeRangeChange, currentPage, totalPages, onNextPage, onPreviousPage, onGoToPage, }: TradeHistoryUIProps): react_jsx_runtime.JSX.Element;
+declare function TradeHistoryUI({ trades, sortKey, sortDir, onSort, className, }: TradeHistoryUIProps): react_jsx_runtime.JSX.Element;
+/** Loading skeleton for the trade-history panel. */
 declare function TradeHistorySkeleton(): react_jsx_runtime.JSX.Element;
+/**
+ * Standalone empty-state component. The main `TradeHistoryUI` renders
+ * its own empty layout (header + centred message) so this export
+ * exists for consumers wiring their own empty state outside the widget.
+ */
 declare function TradeHistoryEmpty(): react_jsx_runtime.JSX.Element;
 
+type UseTradeHistoryScriptParams = {
+    userAddress?: string;
+    /**
+     * Optional venue-side filter. Omit (the default consumed by
+     * `TradeHistoryWidget`) to surface fills from every coin — Axiom's
+     * bottom Trades tab is all-coin, and our Positions / Open Orders
+     * widgets follow the same convention.
+     */
+    symbol?: string;
+};
+type UseTradeHistoryScriptResult = {
+    /** Trades already sorted by the active `sortKey` / `sortDir`. */
+    trades: TradeHistory[];
+    isLoading: boolean;
+    error: Error | null;
+    /**
+     * Active sort column. Defaults to `time` — Axiom never exits the sort
+     * state, so we model this as a non-nullable union (the UI assumes
+     * a column is always active).
+     */
+    sortKey: TradeHistorySortKey;
+    sortDir: SortDirection;
+    /**
+     * Toggle the sort column / direction. Mirrors Axiom's 2-state cycle:
+     * clicking the active column flips `asc` ↔ `desc`; clicking a fresh
+     * column starts at `desc` (newest / largest first — the natural
+     * default for time, money, and PnL columns alike).
+     */
+    onSort: (key: TradeHistorySortKey) => void;
+};
+/**
+ * Container hook for the Trade History (user fills) table.
+ *
+ * Responsibilities:
+ *   - Read fills via {@link useTradesQuery}. Hyperliquid's `webData2`
+ *     stream does **not** carry fill events (only state snapshots), so
+ *     we can't piggy-back on the same WS write-through path used by
+ *     Positions / Open Orders. Instead the query uses a tighter
+ *     `staleTime` so refocusing the tab triggers a near-instant
+ *     refresh — close enough to real-time for a fills view that the
+ *     user only consults episodically.
+ *   - Own sort state (default `time ↓` — newest fill first, Axiom-
+ *     style).
+ */
+declare function useTradeHistoryScript({ userAddress, symbol, }: UseTradeHistoryScriptParams): UseTradeHistoryScriptResult;
+
 /**
  * Highest-level deposit widget. Wires the three presentational
  * components (form / confirm / status) to the deposit hooks +
@@ -3374,4 +4130,4 @@ interface HyperliquidInitWidgetProps extends Pick<UseHyperliquidSetupOptions, "a
 }
 declare function HyperliquidInitWidget({ adapter, userAddress, steps, autoLoad, onComplete, onError, onDismiss, className, }: HyperliquidInitWidgetProps): react_jsx_runtime.JSX.Element;
 
-export { type Account, type AccountState, type ActiveAssetLeverage, type ApproveBuilderFeeParams, type AssetMeta, type CancelOrderParams, type CancelOrderResult, type Coin, CoinInfoNotFoundUI, CoinInfoSkeletonsUI, CoinInfoUI, type CoinInfoUIProps, CoinInfoWidget, type CoinInfoWidgetProps, DEFAULT_ORDER_BOOK_PRECISION_OPTIONS, type DepositBreakdown, DepositConfirmUI, type DepositConfirmUIProps, type DepositErrorInfo, type DepositEvent, DepositFlowWidget, type DepositFlowWidgetProps, DepositFormUI, type DepositFormUIProps, type DepositPhase, type DepositQuoteRequest, type DepositQuoteResponse, type DepositSource, type DepositState, type DepositStatus, type DepositStatusResponse, type DepositStatusTransition, DepositStatusUI, type DepositStatusUIProps, type DepositSubmitRequest, type DepositSubmitResponse, type ExecuteDepositInput, type GetActiveAssetLeverageParams, type GetAssetMetaParams, type GetOpenOrdersParams, type GetOpenOrdersResult, type GetPositionsParams, type GetPositionsResult, type GetTradesParams, type GetTradesResult, HL_USDC_DECIMALS, type HyperliquidAccountState, HyperliquidApiError, type HyperliquidClientConfig, type HyperliquidEnvironment, HyperliquidInitUI, type HyperliquidInitUIProps, HyperliquidInitWidget, type HyperliquidInitWidgetProps, HyperliquidPerpetualsClient, type HyperliquidSetupActionResult, type IHyperliquidSetupAdapter, type IPerpDepositClient, type IPerpetualsClient, type Kline, type KlineInterval, type KlineQueryOptions, LiberFiApiError, type LiberFiHttpMethod, type RequestOptions as LiberFiHttpRequestOptions, LiberFiHttpTransport, type LiberFiHttpTransportConfig, LiberFiPerpDepositClient, type LiberFiPerpDepositClientConfig, LiberFiPerpetualsClient, type LiberFiPerpetualsClientConfig, type MarketData, type MarketDataType, OpenOrdersEmpty, OpenOrdersSkeleton, OpenOrdersUI, type OpenOrdersUIProps, OpenOrdersWidget, type OpenOrdersWidgetProps, type Order, type OrderBook, type OrderBookAggregationOptions, type OrderBookLevel, OrderBookUI, type OrderBookUIProps, OrderBookWidget, type OrderBookWidgetProps, type OrderSide, type OrderStatus, type OrderType, PerpetualsContext, type PerpetualsContextValue, PerpetualsProvider, type PerpetualsProviderProps, type PlaceOrderFormData, PlaceOrderFormUI, type PlaceOrderFormUIProps, PlaceOrderFormWidget, type PlaceOrderFormWidgetProps, type PlaceOrderParams, type PlaceOrderRequest, type PlaceOrderResult, type Position, type PositionSortKey, PositionsEmpty, PositionsSkeleton, PositionsUI, type PositionsUIProps, PositionsWidget, type PositionsWidgetProps, type PriceLevel, SearchCoinsUI, type SearchCoinsUIProps, SearchCoinsWidget, type SearchCoinsWidgetProps, type SetReferrerParams, type SetupAction, type SetupPhase, type SetupState, type SetupStep, type SetupStepId, type SignAndBroadcastSolanaTx, type SignTypedDataFn, type SortDirection, type SpotBalance, type StepRecord, type StepStatus, type Symbol, TERMINAL_DEPOSIT_STATUSES, type TimeRange, type Trade, type TradeHistory, TradeHistoryEmpty, TradeHistorySkeleton, TradeHistoryUI, type TradeHistoryUIProps, TradeHistoryWidget, type TradeHistoryWidgetProps, type TradeSide, TradesUI, type TradesUIProps, TradesWidget, type TradesWidgetProps, type TradingProvider, type UpdateLeverageParams, type UseAccountStateQueryParams, type UseAccountStateSubscriptionParams, type UseAccountStateSubscriptionResult, type UseActiveAssetLeverageQueryParams, type UseAssetMetaQueryParams, type UseCancelOrderMutationParams, type UseCandlesSubscriptionParams, type UseCandlesSubscriptionResult, type UseCoinInfoReturnType, type UseCreateOrderMutationParams, type UseHyperliquidSetupOptions, type UseHyperliquidSetupResult, type UseKlinesQueryParams, type UseMarketDataSubscriptionParams, type UseMarketDataSubscriptionResult, type UseMarketQueryParams, type UseMarketsQueryParams, type UseOpenOrdersScriptParams, type UseOpenOrdersScriptResult, type UseOrderBookQueryParams, type UseOrderBookScriptParams, type UseOrderBookScriptResult, type UseOrdersQueryParams, type UsePerpDepositExecuteResult, type UsePerpDepositQuoteOptions, type UsePerpDepositStatusOptions, type UsePlaceOrderFormScriptParams, type UsePlaceOrderFormScriptResult, type UsePositionsQueryParams, type UsePositionsScriptParams, type UsePositionsScriptResult, type UseRecentTradesQueryParams, type UseSearchCoinsScriptParams, type UseSearchCoinsScriptResult, type UseTradeHistoryScriptParams, type UseTradeHistoryScriptResult, type UseTradesQueryParams, type UseTradesScriptParams, type UseTradesScriptResult, type UseUserDataSubscriptionParams, type UseUserDataSubscriptionResult, type UserDataType, accountStateQueryKey, activeAssetLeverageQueryKey, aggregationFromStep, assetMetaQueryKey, cancelOrder, classifyStep, coinsQueryKey, createOrder, currentBreakdown as currentDepositBreakdown, currentStatus as currentDepositStatus, fetchActiveAssetLeverage, fetchAssetMeta, fetchCoins, fetchKlines, fetchMarket, fetchMarkets, fetchOrderBook, fetchOrders, fetchPerpDepositQuote, fetchPerpDepositStatus, fetchPositions, fetchRecentTrades, fetchTrades, hlUsdcRawToUsdc, initialDepositState, initialSetupState, isPolling as isDepositPolling, isTerminal as isDepositTerminal, isTerminalLifecycle as isTerminalDepositLifecycle, klinesQueryKey, lamportsToSol, marketQueryKey, marketsQueryKey, microUsdcToUsdc, nextRunnableStep, orderBookQueryKey, ordersQueryKey, perpDepositQuoteQueryKey, perpDepositStatusQueryKey, positionsQueryKey, recentTradesQueryKey, reduceDepositState, reduceSetupState, secondsUntil, shortAddress, solToLamports, tradesQueryKey, useAccountStateQuery, useAccountStateSubscription, useActiveAssetLeverageQuery, useAssetMetaQuery, useCancelOrderMutation, useCandlesSubscription, useCoinInfo, useCoinsQuery, useCreateOrderMutation, useHyperliquidSetup, useKlinesQuery, useMarketDataSubscription, useMarketQuery, useMarketsQuery, useOpenOrdersScript, useOrderBookQuery, useOrderBookScript, useOrdersQuery, usePerpDepositClient, usePerpDepositClientMaybe, usePerpDepositExecute, usePerpDepositQuote, usePerpDepositStatus, usePerpetualsClient, usePlaceOrderFormScript, usePositionsQuery, usePositionsScript, useRecentTradesQuery, useSearchCoinsScript, useTradeHistoryScript, useTradesQuery, useTradesScript, useUserDataSubscription, _default as version };
+export { type Account, type AccountState, type ActiveAssetLeverage, type ApproveBuilderFeeParams, type AssetMeta, type CancelOrderImpl, type CancelOrderParams, type CancelOrderResult, type CancelOrdersImpl, ClosePositionModal, type ClosePositionModalProps, type CloseType, type Coin, CoinInfoNotFoundUI, CoinInfoSkeletonsUI, CoinInfoUI, type CoinInfoUIProps, CoinInfoWidget, type CoinInfoWidgetProps, DEFAULT_ORDER_BOOK_PRECISION_OPTIONS, type DepositBreakdown, DepositConfirmUI, type DepositConfirmUIProps, type DepositErrorInfo, type DepositEvent, DepositFlowWidget, type DepositFlowWidgetProps, DepositFormUI, type DepositFormUIProps, type DepositPhase, type DepositQuoteRequest, type DepositQuoteResponse, type DepositSource, type DepositState, type DepositStatus, type DepositStatusResponse, type DepositStatusTransition, DepositStatusUI, type DepositStatusUIProps, type DepositSubmitRequest, type DepositSubmitResponse, type ExecuteDepositInput, type GetActiveAssetLeverageParams, type GetAssetMetaParams, type GetOpenOrdersParams, type GetOpenOrdersResult, type GetPositionsParams, type GetPositionsResult, type GetTradesParams, type GetTradesResult, HL_USDC_DECIMALS, type HyperliquidAccountState, HyperliquidApiError, type HyperliquidClientConfig, type HyperliquidEnvironment, HyperliquidInitUI, type HyperliquidInitUIProps, HyperliquidInitWidget, type HyperliquidInitWidgetProps, HyperliquidPerpetualsClient, type HyperliquidSetupActionResult, type IHyperliquidSetupAdapter, type IPerpDepositClient, type IPerpetualsClient, type Kline, type KlineInterval, type KlineQueryOptions, LiberFiApiError, type LiberFiHttpMethod, type RequestOptions as LiberFiHttpRequestOptions, LiberFiHttpTransport, type LiberFiHttpTransportConfig, LiberFiPerpDepositClient, type LiberFiPerpDepositClientConfig, LiberFiPerpetualsClient, type LiberFiPerpetualsClientConfig, type MarketData, type MarketDataType, type OpenOrderSortKey, OpenOrdersEmpty, OpenOrdersSkeleton, OpenOrdersUI, type OpenOrdersUIProps, OpenOrdersWidget, type OpenOrdersWidgetProps, type Order, type OrderBook, type OrderBookAggregationOptions, type OrderBookLevel, OrderBookUI, type OrderBookUIProps, OrderBookWidget, type OrderBookWidgetProps, type OrderSide, type OrderStatus, type OrderType, PerpetualsContext, type PerpetualsContextValue, PerpetualsProvider, type PerpetualsProviderProps, type PlaceOrderFormData, PlaceOrderFormUI, type PlaceOrderFormUIProps, PlaceOrderFormWidget, type PlaceOrderFormWidgetProps, type PlaceOrderParams, type PlaceOrderRequest, type PlaceOrderResult, type Position, type PositionSortKey, PositionsEmpty, PositionsSkeleton, PositionsUI, type PositionsUIProps, PositionsWidget, type PositionsWidgetProps, type PriceLevel, SearchCoinsUI, type SearchCoinsUIProps, SearchCoinsWidget, type SearchCoinsWidgetProps, type SetReferrerParams, type SetupAction, type SetupPhase, type SetupState, type SetupStep, type SetupStepId, type SignAndBroadcastSolanaTx, type SignTypedDataFn, type SortDirection, type SpotBalance, type StepRecord, type StepStatus, type Symbol, TERMINAL_DEPOSIT_STATUSES, type Trade, type TradeHistory, TradeHistoryEmpty, TradeHistorySkeleton, type TradeHistorySortKey, TradeHistoryUI, type TradeHistoryUIProps, TradeHistoryWidget, type TradeHistoryWidgetProps, type TradeSide, TradesUI, type TradesUIProps, TradesWidget, type TradesWidgetProps, type TradingProvider, type UniverseAssetEntry, type UniverseSnapshot, type UpdateLeverageParams, type UseAccountStateQueryParams, type UseAccountStateSubscriptionParams, type UseAccountStateSubscriptionResult, type UseActiveAssetLeverageQueryParams, type UseAssetMetaQueryParams, type UseCancelOrderMutationParams, type UseCandlesSubscriptionParams, type UseCandlesSubscriptionResult, type UseClosePositionParams, type UseClosePositionResult, type UseCoinInfoReturnType, type UseCreateOrderMutationParams, type UseHyperliquidSetupOptions, type UseHyperliquidSetupResult, type UseHyperliquidUserBootstrapParams, type UseKlinesQueryParams, type UseMarketDataSubscriptionParams, type UseMarketDataSubscriptionResult, type UseMarketQueryParams, type UseMarketsQueryParams, type UseOpenOrdersScriptParams, type UseOpenOrdersScriptResult, type UseOrderBookQueryParams, type UseOrderBookScriptParams, type UseOrderBookScriptResult, type UseOrdersQueryParams, type UsePerpDepositExecuteResult, type UsePerpDepositQuoteOptions, type UsePerpDepositStatusOptions, type UsePlaceOrderFormScriptParams, type UsePlaceOrderFormScriptResult, type UsePositionsQueryParams, type UsePositionsScriptParams, type UsePositionsScriptResult, type UseRecentTradesQueryParams, type UseSearchCoinsScriptParams, type UseSearchCoinsScriptResult, type UseTradeHistoryScriptParams, type UseTradeHistoryScriptResult, type UseTradesQueryParams, type UseTradesScriptParams, type UseTradesScriptResult, type UseUserDataSubscriptionParams, type UseUserDataSubscriptionResult, type UserDataType, accountStateQueryKey, activeAssetLeverageQueryKey, aggregationFromStep, assetMetaQueryKey, cancelOrder, classifyStep, coinsQueryKey, createOrder, currentBreakdown as currentDepositBreakdown, currentStatus as currentDepositStatus, fetchActiveAssetLeverage, fetchAssetMeta, fetchCoins, fetchKlines, fetchMarket, fetchMarkets, fetchOrderBook, fetchOrders, fetchPerpDepositQuote, fetchPerpDepositStatus, fetchPositions, fetchRecentTrades, fetchTrades, fetchUniverse, hlUsdcRawToUsdc, initialDepositState, initialSetupState, isPolling as isDepositPolling, isTerminal as isDepositTerminal, isTerminalLifecycle as isTerminalDepositLifecycle, klinesQueryKey, lamportsToSol, marketQueryKey, marketsQueryKey, microUsdcToUsdc, nextRunnableStep, orderBookQueryKey, ordersQueryKey, perpDepositQuoteQueryKey, perpDepositStatusQueryKey, positionsQueryKey, recentTradesQueryKey, reduceDepositState, reduceSetupState, secondsUntil, shortAddress, solToLamports, supportsUniverseSnapshot, tradesQueryKey, universeQueryKey, useAccountStateQuery, useAccountStateSubscription, useActiveAssetLeverageQuery, useAssetMetaQuery, useCancelOrderMutation, useCandlesSubscription, useClosePosition, useCoinInfo, useCoinsQuery, useCreateOrderMutation, useHyperliquidSetup, useHyperliquidUserBootstrap, useKlinesQuery, useMarketDataSubscription, useMarketQuery, useMarketsQuery, useOpenOrdersScript, useOrderBookQuery, useOrderBookScript, useOrdersQuery, usePerpDepositClient, usePerpDepositClientMaybe, usePerpDepositExecute, usePerpDepositQuote, usePerpDepositStatus, usePerpetualsClient, usePlaceOrderFormScript, usePositionsQuery, usePositionsScript, useRecentTradesQuery, useSearchCoinsScript, useTradeHistoryScript, useTradesQuery, useTradesScript, useUniverseQuery, useUserDataSubscription, _default as version };