@pear-protocol/hyperliquid-sdk 0.0.64 → 0.0.66-usdh-1

package/dist/index.d.ts

@@ -47,7 +47,7 @@ interface ExternalFillDto {
     coin: string;
     px: string;
     sz: string;
-    side: "B" | "A";
+    side: 'B' | 'A';
     time: number;
     dir: string;
     fee: string;
@@ -74,16 +74,16 @@ interface TwapSliceFillResponseItem {
 /**
  * WebSocket connection states
  */
-type WebSocketConnectionState = "connecting" | "connected" | "disconnected" | "error";
+type WebSocketConnectionState = 'connecting' | 'connected' | 'disconnected' | 'error';
 /**
  * WebSocket channels
  */
-type WebSocketChannel = "trade-histories" | "open-positions" | "open-orders" | "account-summary" | "twap-details" | "notifications" | "market-data" | "market-data-all" | "webData3" | "allMids" | "activeAssetData";
+type WebSocketChannel = 'trade-histories' | 'open-positions' | 'open-orders' | 'account-summary' | 'twap-details' | 'notifications' | 'market-data' | 'market-data-all' | 'webData3' | 'allMids' | 'activeAssetData';
 /**
  * WebSocket subscription message
  */
 interface WebSocketSubscribeMessage {
-    action?: "subscribe" | "unsubscribe";
+    action?: 'subscribe' | 'unsubscribe';
     address: string;
 }
 /**
@@ -113,7 +113,7 @@ interface WatchlistItemDto {
 interface ToggleWatchlistResponseDto {
     items: WatchlistItemDto[];
 }
-type NotificationCategory = "TRADE_OPENED_OUTSIDE_PEAR" | "TRADE_CLOSED_OUTSIDE_PEAR" | "POSITION_LIQUIDATED" | "LIMIT_ORDER_FILLED" | "LIMIT_ORDER_FAILED" | "TP_ORDER_FILLED" | "TP_ORDER_FAILED" | "SL_ORDER_FILLED" | "SL_ORDER_FAILED";
+type NotificationCategory = 'TRADE_OPENED_OUTSIDE_PEAR' | 'TRADE_CLOSED_OUTSIDE_PEAR' | 'POSITION_LIQUIDATED' | 'LIMIT_ORDER_FILLED' | 'LIMIT_ORDER_FAILED' | 'TP_ORDER_FILLED' | 'TP_ORDER_FAILED' | 'SL_ORDER_FILLED' | 'SL_ORDER_FAILED';
 interface NotificationDto {
     id: string;
     address: string;
@@ -130,7 +130,7 @@ interface ChunkFillDto {
     size: number;
     executedAt: string;
 }
-type TwapChunkStatus = "PENDING" | "SCHEDULED" | "EXECUTING" | "COMPLETED" | "FAILED" | "CANCELLED";
+type TwapChunkStatus = 'PENDING' | 'SCHEDULED' | 'EXECUTING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
 interface TwapChunkStatusDto {
     chunkId: string;
     chunkIndex: number;
@@ -141,7 +141,7 @@ interface TwapChunkStatusDto {
     fills: ChunkFillDto[];
     errorMessage?: string;
 }
-type TwapOrderOverallStatus = "OPEN" | "EXECUTING" | "COMPLETED" | "PARTIALLY_COMPLETED" | "FAILED" | "CANCELLED";
+type TwapOrderOverallStatus = 'OPEN' | 'EXECUTING' | 'COMPLETED' | 'PARTIALLY_COMPLETED' | 'FAILED' | 'CANCELLED';
 interface TwapMonitoringDto {
     orderId: string;
     positionId?: string;
@@ -178,6 +178,8 @@ interface TradeHistoryAssetDataDto {
     externalFeePaid: number;
     builderFeePaid: number;
     realizedPnl: number;
+    marketPrefix?: string | null;
+    collateralToken?: CollateralToken;
 }
 /**
  * Trade history data structure
@@ -226,9 +228,11 @@ interface PositionAssetDetailDto {
     liquidationPrice: number;
     initialWeight: number;
     fundingPaid?: number;
+    marketPrefix?: string | null;
+    collateralToken?: CollateralToken;
 }
 interface TpSlThreshold {
-    type: "PERCENTAGE" | "DOLLAR" | "POSITION_VALUE";
+    type: 'PERCENTAGE' | 'DOLLAR' | 'POSITION_VALUE';
     value: number;
 }
 /**
@@ -259,20 +263,22 @@ interface OpenPositionDto {
 interface OrderAssetDto {
     asset: string;
     weight: number;
+    marketPrefix?: string | null;
+    collateralToken?: CollateralToken;
 }
 /**
  * Order status
  */
-type OrderStatus = "OPEN" | "PARTIALLY_FILLED" | "PROCESSING";
+type OrderStatus = 'OPEN' | 'PARTIALLY_FILLED' | 'PROCESSING';
 /**
  * Order type
  */
-type OrderType = "TP" | "SL" | "LIMIT" | "MARKET" | "LIMIT_BTCDOM" | "TWAP";
+type OrderType = 'TP' | 'SL' | 'LIMIT' | 'MARKET' | 'LIMIT_BTCDOM' | 'TWAP';
 /**
  * TP/SL trigger type
  */
-type TpSlTriggerType = "PERCENTAGE" | "DOLLAR" | "POSITION_VALUE";
-type OrderDirection = "MORE_THAN" | "LESS_THAN" | null;
+type TpSlTriggerType = 'PERCENTAGE' | 'DOLLAR' | 'POSITION_VALUE';
+type OrderDirection = 'MORE_THAN' | 'LESS_THAN' | null;
 /**
  * Open limit order data structure
  */
@@ -378,7 +384,7 @@ interface RefreshTokenResponse {
     tokenType: string;
     expiresIn: number;
 }
-type AgentWalletStatus = "ACTIVE" | "EXPIRED" | "NOT_FOUND";
+type AgentWalletStatus = 'ACTIVE' | 'EXPIRED' | 'NOT_FOUND';
 interface CreateAgentWalletResponseDto {
     agentWalletAddress: string;
     message: string;
@@ -391,14 +397,14 @@ interface ExtraAgent {
 interface AgentWalletState {
     address: string | null;
     name: string | null;
-    status: AgentWalletStatus | "PENDING" | null;
+    status: AgentWalletStatus | 'PENDING' | null;
     isActive: boolean;
 }
 /**
  * WebSocket message from HyperLiquid native API
  */
 interface WebSocketMessage {
-    method: "subscribe" | "unsubscribe";
+    method: 'subscribe' | 'unsubscribe';
     subscription: {
         type: string;
         dex?: string;
@@ -411,12 +417,16 @@ interface WebSocketMessage {
 /**
  * WebSocket response from HyperLiquid native API
  */
-type HLChannel = "webData3" | "allMids" | "activeAssetData" | "candle" | "allDexsClearinghouseState" | "allDexsAssetCtxs";
+type HLChannel = 'webData3' | 'allMids' | 'activeAssetData' | 'candle' | 'spotState' | 'allDexsClearinghouseState' | 'allDexsAssetCtxs';
 interface HLChannelDataMap {
     webData3: WebData3Response;
     allMids: WsAllMidsData;
     activeAssetData: ActiveAssetData;
     candle: CandleData;
+    spotState: {
+        user: string;
+        spotState: SpotState;
+    };
     allDexsClearinghouseState: AllDexsClearinghouseStateData;
     allDexsAssetCtxs: AllDexsAssetCtxsData;
 }
@@ -481,6 +491,12 @@ interface AssetCtx {
     impactPxs?: string[];
     oraclePx: string;
 }
+/**
+ * Collateral token type
+ * 0 = USDC
+ * 360 = USDH
+ */
+type CollateralToken = 'USDC' | 'USDH';
 /**
  * Universe asset metadata
  */
@@ -490,6 +506,8 @@ interface UniverseAsset {
     maxLeverage: number;
     onlyIsolated?: boolean;
     isDelisted?: boolean;
+    marketPrefix?: string;
+    collateralToken?: CollateralToken;
 }
 interface ClearinghouseState {
     assetPositions: AssetPosition[];
@@ -560,6 +578,8 @@ interface RawAssetDto {
     size: number;
     side: string;
     fundingPaid?: number;
+    marketPrefix?: string | null;
+    collateralToken?: CollateralToken;
 }
 /**
  * Raw position data from open-positions channel
@@ -607,6 +627,7 @@ interface TokenMetadata {
     leverage?: LeverageInfo;
     maxTradeSzs?: [string, string];
     availableToTrade?: [string, string];
+    collateralToken?: CollateralToken;
 }
 /**
  * Enhanced token selection with weight and metadata for basket trading
@@ -620,16 +641,37 @@ interface TokenSelection {
  */
 interface TokenConflict {
     symbol: string;
-    conflictType: "long" | "short";
+    conflictType: 'long' | 'short';
     conflictMessage: string;
 }
 interface AssetMarketData {
     asset: WebData3AssetCtx | AssetCtx;
     universe: UniverseAsset;
 }
+/**
+ * Nested market data structure for multi-market assets.
+ * Each symbol maps to its market variants (keyed by prefix).
+ * For non-HIP3 assets, use "default" as the key.
+ *
+ * @example
+ * ```ts
+ * {
+ *   "TSLA": {
+ *     "xyz": { asset: {...}, universe: { collateralToken: "USDC", ... } },
+ *     "flx": { asset: {...}, universe: { collateralToken: "USDH", ... } }
+ *   },
+ *   "BTC": {
+ *     "default": { asset: {...}, universe: {...} }
+ *   }
+ * }
+ * ```
+ */
+type MarketDataBySymbol = Record<string, Record<string, AssetMarketData>>;
 interface PairAssetDto {
     asset: string;
     weight: number;
+    collateralToken: CollateralToken;
+    marketPrefix: string | null;
 }
 interface ActiveAssetGroupItem {
     longAssets: PairAssetDto[];
@@ -643,6 +685,7 @@ interface ActiveAssetGroupItem {
     weightedRatio?: string;
     weightedPrevRatio?: string;
     weightedChange24h?: string;
+    collateralType: 'USDC' | 'USDH' | 'MIXED';
 }
 interface ActiveAssetsResponse {
     active: ActiveAssetGroupItem[];
@@ -660,7 +703,7 @@ interface ActiveAssetsAllResponse {
 /**
  * Candle interval options
  */
-type CandleInterval = "1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "8h" | "12h" | "1d" | "3d" | "1w" | "1M";
+type CandleInterval = '1m' | '3m' | '5m' | '15m' | '30m' | '1h' | '2h' | '4h' | '8h' | '12h' | '1d' | '3d' | '1w' | '1M';
 /**
  * Candle data structure from WebSocket
  */
@@ -688,12 +731,23 @@ interface CandleSnapshotRequest {
         endTime: number;
         interval: CandleInterval;
     };
-    type: "candleSnapshot";
+    type: 'candleSnapshot';
 }
 interface TokenSelectorConfig {
     isLong: boolean;
     index: number;
 }
+interface SpotBalance {
+    coin: string;
+    token: number;
+    total: string;
+    hold: string;
+    entryNtl: string;
+}
+interface SpotState {
+    user: string;
+    balances: SpotBalance[];
+}
 
 declare const useAccountSummary: () => {
     data: AccountSummaryResponseDto | null;
@@ -704,9 +758,6 @@ declare const useTradeHistories: () => {
     data: TradeHistoryDataDto[] | null;
     isLoading: boolean;
 };
-/**
- * Hook to access open orders with loading state
- */
 declare const useOpenOrders: () => {
     data: OpenLimitOrderDto[] | null;
     isLoading: boolean;
@@ -729,7 +780,8 @@ interface UserSelectionState {
     setConflicts: (conflicts: TokenConflict[]) => void;
     setCandleInterval: (interval: CandleInterval) => void;
     updateTokenWeight: (isLong: boolean, index: number, newWeight: number) => void;
-    addToken: (isLong: boolean) => void;
+    addToken: (isLong: boolean) => boolean;
+    canAddToken: (isLong: boolean) => boolean;
     removeToken: (isLong: boolean, index: number) => void;
     handleTokenSelect: (selectedToken: string) => void;
     setTokenSelections: (longTokens: TokenSelection[], shortTokens: TokenSelection[]) => void;
@@ -744,8 +796,26 @@ declare const useUserSelection: () => UserSelectionState;
 declare const useWebData: () => {
     clearinghouseState: ClearinghouseState | null;
     perpsAtOpenInterestCap: string[] | null;
-    marketDataBySymbol: Record<string, AssetMarketData>;
-    hip3Assets: Map<string, string>;
+    /**
+     * Market data keyed by symbol, with nested market variants.
+     * Each symbol maps to its market variants (keyed by prefix).
+     * For non-HIP3 assets, use "default" as the key.
+     *
+     * @example
+     * ```ts
+     * // HIP-3 asset with multiple markets
+     * marketDataBySymbol["TSLA"]["xyz"]  // { asset, universe: { collateralToken: "USDC" } }
+     * marketDataBySymbol["TSLA"]["flx"]  // { asset, universe: { collateralToken: "USDH" } }
+     *
+     * // Regular asset
+     * marketDataBySymbol["BTC"]["default"]  // { asset, universe }
+     * ```
+     */
+    marketDataBySymbol: MarketDataBySymbol;
+    /** Map of display name -> all full market names (e.g., "TSLA" -> ["xyz:TSLA", "flx:TSLA"]) */
+    hip3Assets: Map<string, string[]>;
+    /** Map of full market name -> prefix (e.g., "xyz:TSLA" -> "xyz") */
+    hip3MarketPrefixes: Map<string, string>;
     isConnected: boolean;
     error: string | null;
 };
@@ -879,6 +949,47 @@ interface CancelTwapResponseDto {
     cancelledAt: string;
 }
 declare function cancelTwapOrder(baseUrl: string, orderId: string): Promise<ApiResponse<CancelTwapResponseDto>>;
+interface SpotOrderRequestInput {
+    /** Asset to buy/sell (e.g., "USDH") */
+    asset: string;
+    /** Whether to buy (true) or sell (false) the asset */
+    isBuy: boolean;
+    /** Amount of asset to buy/sell (minimum: 11) */
+    amount: number;
+}
+/** Filled order status from Hyperliquid */
+interface SpotOrderFilledStatus {
+    filled: {
+        totalSz: string;
+        avgPx: string;
+        oid: number;
+        cloid: string;
+    };
+}
+/** Hyperliquid order response data */
+interface SpotOrderHyperliquidData {
+    statuses: SpotOrderFilledStatus[];
+}
+/** Hyperliquid result from spot order execution */
+interface SpotOrderHyperliquidResult {
+    status: 'ok' | 'error';
+    response: {
+        type: 'order';
+        data: SpotOrderHyperliquidData;
+    };
+}
+interface SpotOrderResponseDto {
+    orderId: string;
+    status: 'EXECUTED' | 'FAILED' | 'PENDING';
+    asset: string;
+    createdAt: string;
+    hyperliquidResult?: SpotOrderHyperliquidResult;
+}
+/**
+ * Execute a spot order (swap) using Pear Hyperliquid service
+ * POST /orders/spot
+ */
+declare function executeSpotOrder(baseUrl: string, payload: SpotOrderRequestInput): Promise<ApiResponse<SpotOrderResponseDto>>;
 
 type ExecutionType = "MARKET" | "LIMIT" | "TWAP" | "LADDER" | "LIMIT_BTCDOM";
 type TpSlThresholdType = "PERCENTAGE" | "DOLLAR" | "POSITION_VALUE";
@@ -935,8 +1046,9 @@ interface CreatePositionResponseDto {
  * Create a position (MARKET/LIMIT/TWAP) using Pear Hyperliquid service
  * Authorization is derived from headers (Axios defaults or browser localStorage fallback)
  * @throws MinimumPositionSizeError if any asset has less than $11 USD value
+ * @throws MaxAssetsPerLegError if any leg exceeds the maximum allowed assets (15)
  */
-declare function createPosition(baseUrl: string, payload: CreatePositionRequestInput, displayToFull: Map<string, string>): Promise<ApiResponse<CreatePositionResponseDto>>;
+declare function createPosition(baseUrl: string, payload: CreatePositionRequestInput, hip3Assets: Map<string, string[]>): Promise<ApiResponse<CreatePositionResponseDto>>;
 interface UpdateRiskParametersRequestInput {
     stopLoss?: TpSlThresholdInput | null;
     takeProfit?: TpSlThresholdInput | null;
@@ -1003,7 +1115,7 @@ interface AdjustAdvanceResponseDto {
     status: string;
     executedAt: string;
 }
-declare function adjustAdvancePosition(baseUrl: string, positionId: string, payload: AdjustAdvanceItemInput[], displayToFull: Map<string, string>): Promise<ApiResponse<AdjustAdvanceResponseDto>>;
+declare function adjustAdvancePosition(baseUrl: string, positionId: string, payload: AdjustAdvanceItemInput[], hip3Assets: Map<string, string[]>): Promise<ApiResponse<AdjustAdvanceResponseDto>>;
 declare function cancelTwap(baseUrl: string, orderId: string): Promise<ApiResponse<CancelTwapResponseDto>>;
 
 declare function usePosition(): {
@@ -1025,6 +1137,18 @@ declare function useOrders(): {
     readonly isLoading: boolean;
 };
 
+interface UseSpotOrderResult {
+    executeSpotOrder: (payload: SpotOrderRequestInput) => Promise<ApiResponse<SpotOrderResponseDto>>;
+    isLoading: boolean;
+    error: ApiErrorResponse | null;
+    resetError: () => void;
+}
+/**
+ * Hook for executing spot orders (swaps) on Hyperliquid
+ * Use this to swap between USDC and USDH or other spot assets
+ */
+declare function useSpotOrder(): UseSpotOrderResult;
+
 declare function useTwap(): {
     readonly orders: TwapMonitoringDto[];
     readonly cancelTwap: (orderId: string) => Promise<ApiResponse<CancelTwapResponseDto>>;
@@ -1046,14 +1170,16 @@ interface UseNotificationsResult {
  */
 declare function useNotifications(): UseNotificationsResult;
 
+type CollateralFilter = 'USDC' | 'USDH' | 'ALL';
 declare const useMarketDataPayload: () => ActiveAssetsResponse | null;
 declare const useMarketDataAllPayload: () => ActiveAssetsAllResponse | null;
-declare const useActiveBaskets: () => ActiveAssetGroupItem[];
-declare const useTopGainers: (limit?: number) => ActiveAssetGroupItem[];
-declare const useTopLosers: (limit?: number) => ActiveAssetGroupItem[];
-declare const useHighlightedBaskets: () => ActiveAssetGroupItem[];
-declare const useWatchlistBaskets: () => ActiveAssetGroupItem[];
-declare const useAllBaskets: () => ActiveAssetGroupItem[];
+declare const usePerpMetaAssets: () => UniverseAsset[] | null;
+declare const useActiveBaskets: (collateralFilter?: CollateralFilter) => ActiveAssetGroupItem[];
+declare const useTopGainers: (limit?: number, collateralFilter?: CollateralFilter) => ActiveAssetGroupItem[];
+declare const useTopLosers: (limit?: number, collateralFilter?: CollateralFilter) => ActiveAssetGroupItem[];
+declare const useHighlightedBaskets: (collateralFilter?: CollateralFilter) => ActiveAssetGroupItem[];
+declare const useWatchlistBaskets: (collateralFilter?: CollateralFilter) => ActiveAssetGroupItem[];
+declare const useAllBaskets: (collateralFilter?: CollateralFilter) => ActiveAssetGroupItem[];
 declare const useFindBasket: (longs: string[], shorts: string[]) => ActiveAssetGroupItem | undefined;
 
 declare function useWatchlist(): {
@@ -1126,6 +1252,13 @@ declare function useAuth(): {
     readonly logout: () => Promise<void>;
 };
 
+interface SpotBalances {
+    usdhBalance: number | undefined;
+    spotUsdcBalance: number | undefined;
+    isLoading: boolean;
+}
+declare const useSpotBalances: () => SpotBalances;
+
 interface UseHyperliquidWebSocketProps {
     wsUrl: string;
     address: string | null;
@@ -1160,7 +1293,7 @@ declare function markNotificationReadById(baseUrl: string, id: string): Promise<
     updated: number;
 }>>;
 
-declare function toggleWatchlist(baseUrl: string, longAssets: WatchlistAssetDto[], shortAssets: WatchlistAssetDto[], displayToFull: Map<string, string>): Promise<ApiResponse<ToggleWatchlistResponseDto>>;
+declare function toggleWatchlist(baseUrl: string, longAssets: WatchlistAssetDto[], shortAssets: WatchlistAssetDto[], hip3Assets: Map<string, string[]>): Promise<ApiResponse<ToggleWatchlistResponseDto>>;
 
 /**
  * Account summary calculation utility class
@@ -1199,24 +1332,28 @@ declare class ConflictDetector {
 declare class TokenMetadataExtractor {
     /**
      * Extracts comprehensive token metadata
-     * @param symbol - Token symbol
+     * @param symbol - Token symbol (base symbol without prefix, e.g., "TSLA")
      * @param perpMetaAssets - Aggregated universe assets (flattened across dexes)
      * @param finalAssetContexts - Aggregated asset contexts (flattened across dexes)
      * @param allMids - AllMids data containing current prices
      * @param activeAssetData - Optional active asset data containing leverage information
+     * @param marketPrefix - Optional market prefix (e.g., "xyz", "flx") for HIP3 multi-market assets
      * @returns TokenMetadata or null if token not found
      */
-    static extractTokenMetadata(symbol: string, perpMetaAssets: UniverseAsset[] | null, finalAssetContexts: WebData3AssetCtx[] | null, allMids: WsAllMidsData | null, activeAssetData?: Record<string, ActiveAssetData> | null): TokenMetadata | null;
+    static extractTokenMetadata(symbol: string, perpMetaAssets: UniverseAsset[] | null, finalAssetContexts: WebData3AssetCtx[] | null, allMids: WsAllMidsData | null, activeAssetData?: Record<string, ActiveAssetData> | null, marketPrefix?: string | null): TokenMetadata | null;
     /**
      * Extracts metadata for multiple tokens
-     * @param symbols - Array of token symbols
+     * @param tokens - Array of token objects with symbol and optional marketPrefix
      * @param perpMetaAssets - Aggregated universe assets
      * @param finalAssetContexts - Aggregated asset contexts
      * @param allMids - AllMids data
      * @param activeAssetData - Optional active asset data containing leverage information
-     * @returns Record of symbol to TokenMetadata
+     * @returns Record of unique key to TokenMetadata. Key is "{prefix}:{symbol}" for HIP3 assets, or just "{symbol}" otherwise
      */
-    static extractMultipleTokensMetadata(symbols: string[], perpMetaAssets: UniverseAsset[] | null, finalAssetContexts: WebData3AssetCtx[] | null, allMids: WsAllMidsData | null, activeAssetData?: Record<string, ActiveAssetData> | null): Record<string, TokenMetadata | null>;
+    static extractMultipleTokensMetadata(tokens: Array<{
+        symbol: string;
+        marketPrefix?: string | null;
+    }>, perpMetaAssets: UniverseAsset[] | null, finalAssetContexts: WebData3AssetCtx[] | null, allMids: WsAllMidsData | null, activeAssetData?: Record<string, ActiveAssetData> | null): Record<string, TokenMetadata | null>;
     /**
      * Checks if token data is available in aggregated universe assets
      * @param symbol - Token symbol
@@ -1263,6 +1400,10 @@ declare function mapCandleIntervalToTradingViewInterval(interval: CandleInterval
  * Minimum USD value required per asset when creating a position
  */
 declare const MINIMUM_ASSET_USD_VALUE = 11;
+/**
+ * Maximum number of assets allowed per leg (long or short) in a position
+ */
+declare const MAX_ASSETS_PER_LEG = 15;
 /**
  * Validation error for minimum position size
  */
@@ -1272,6 +1413,22 @@ declare class MinimumPositionSizeError extends Error {
     minimumRequired: number;
     constructor(assetName: string, assetValue: number, minimumRequired: number);
 }
+/**
+ * Validation error for exceeding maximum assets per leg
+ */
+declare class MaxAssetsPerLegError extends Error {
+    leg: "long" | "short";
+    assetCount: number;
+    maxAllowed: number;
+    constructor(leg: "long" | "short", assetCount: number, maxAllowed: number);
+}
+/**
+ * Validates that each leg doesn't exceed the maximum number of assets
+ * @param longAssets Array of long assets
+ * @param shortAssets Array of short assets
+ * @throws MaxAssetsPerLegError if any leg exceeds the maximum allowed assets
+ */
+declare function validateMaxAssetsPerLeg(longAssets?: PairAssetInput[], shortAssets?: PairAssetInput[]): void;
 /**
  * Validates that each asset in a position has at least the minimum USD value
  * @param usdValue Total USD value for the position
@@ -1300,7 +1457,48 @@ declare function validatePositionSize(usdValue: number, longAssets?: PairAssetIn
     minimumRequired?: number;
 };
 
+/**
+ * Convert a full/prefixed symbol (e.g., "xyz:XYZ100") to a display symbol (e.g., "XYZ100").
+ */
+declare function toDisplaySymbol(symbol: string): string;
+/**
+ * Convert a display symbol back to backend form using a provided map.
+ * If mapping is missing, returns the original symbol.
+ * For multi-market assets, returns the first available market.
+ * @param displaySymbol e.g., "TSLA"
+ * @param hip3Assets map of display -> all full market names (e.g., "TSLA" -> ["xyz:TSLA", "flx:TSLA"])
+ */
+declare function toBackendSymbol(displaySymbol: string, hip3Assets: Map<string, string[]>): string;
+/**
+ * Convert a display symbol to backend form for a specific market prefix.
+ * This is useful when an asset is available on multiple markets (e.g., xyz:TSLA and flx:TSLA).
+ * @param displaySymbol e.g., "TSLA"
+ * @param marketPrefix e.g., "xyz" or "flx"
+ * @param hip3Assets map of display -> all full market names
+ * @returns Full market name if found, null if prefix not specified for multi-market asset, otherwise displaySymbol with prefix
+ */
+declare function toBackendSymbolWithMarket(displaySymbol: string, marketPrefix: string | undefined, hip3Assets: Map<string, string[]>): string | null;
+/**
+ * Get all available markets for a display symbol.
+ * @param displaySymbol e.g., "TSLA"
+ * @param hip3Assets map of display -> all full market names
+ * @returns Array of full market names, e.g., ["xyz:TSLA", "flx:TSLA"]
+ */
+declare function getAvailableMarkets(displaySymbol: string, hip3Assets: Map<string, string[]>): string[];
+/**
+ * Extract the market prefix from a full market name.
+ * @param fullSymbol e.g., "xyz:TSLA"
+ * @returns The prefix (e.g., "xyz") or undefined if no prefix
+ */
+declare function getMarketPrefix(fullSymbol: string): string | undefined;
+/**
+ * Check if a symbol is a HIP-3 market (has a prefix).
+ * @param symbol e.g., "xyz:TSLA" or "TSLA"
+ * @returns true if the symbol has a market prefix
+ */
+declare function isHip3Market(symbol: string): boolean;
+
 declare const useMarketData: any;
 
-export { AccountSummaryCalculator, ConflictDetector, MINIMUM_ASSET_USD_VALUE, MinimumPositionSizeError, PearHyperliquidProvider, TokenMetadataExtractor, adjustAdvancePosition, adjustOrder, adjustPosition, calculateMinimumPositionValue, calculateWeightedRatio, cancelOrder, cancelTwap, cancelTwapOrder, closeAllPositions, closePosition, computeBasketCandles, createCandleLookups, createPosition, getCompleteTimestamps, getPortfolio, mapCandleIntervalToTradingViewInterval, mapTradingViewIntervalToCandleInterval, markNotificationReadById, markNotificationsRead, toggleWatchlist, updateRiskParameters, useAccountSummary, useActiveBaskets, useAgentWallet, useAllBaskets, useAuth, useAutoSyncFills, useBasketCandles, useFindBasket, useHighlightedBaskets, useHistoricalPriceData, useHistoricalPriceDataStore, useHyperliquidNativeWebSocket, useHyperliquidWebSocket, useMarketData, useMarketDataAllPayload, useMarketDataPayload, useNotifications, useOpenOrders, useOrders, usePearHyperliquid, usePerformanceOverlays, usePortfolio, usePosition, useTokenSelectionMetadata, useTopGainers, useTopLosers, useTradeHistories, useTwap, useUserSelection, useWatchlist, useWatchlistBaskets, useWebData, validateMinimumAssetSize, validatePositionSize };
-export type { AccountSummaryResponseDto, ActiveAssetGroupItem, ActiveAssetsResponse, AdjustAdvanceAssetInput, AdjustAdvanceItemInput, AdjustAdvanceResponseDto, AdjustExecutionType, AdjustOrderRequestInput, AdjustOrderResponseDto, AdjustPositionRequestInput, AdjustPositionResponseDto, AgentWalletDto, AgentWalletState, ApiErrorResponse, ApiResponse, AssetCtx, AssetInformationDetail, AssetMarketData, AssetPosition, AutoSyncFillsOptions, AutoSyncFillsState, BalanceSummaryDto, CancelOrderResponseDto, CancelTwapResponseDto, CandleChartData, CandleData, CandleInterval, CandleSnapshotRequest, ClearinghouseState, CloseAllPositionsResponseDto, CloseAllPositionsResultDto, CloseExecutionType, ClosePositionRequestInput, ClosePositionResponseDto, CreatePositionRequestInput, CreatePositionResponseDto, CrossMarginSummaryDto, CumFundingDto, ExecutionType, ExtraAgent, HLWebSocketResponse, HistoricalRange, LadderConfigInput, MarginSummaryDto, NotificationCategory, NotificationDto, OpenLimitOrderDto, OpenPositionDto, OrderAssetDto, OrderStatus, PairAssetDto, PairAssetInput, PerformanceOverlay, PlatformAccountSummaryResponseDto, PortfolioBucketDto, PortfolioInterval, PortfolioIntervalsDto, PortfolioOverallDto, PortfolioResponseDto, PositionAdjustmentType, PositionAssetDetailDto, PositionAssetSummaryDto, PositionResponseStatus, RealtimeBar, RealtimeBarsCallback, ToggleWatchlistResponseDto, TokenConflict, TokenHistoricalPriceData, TokenMetadata, TokenSelection, TpSlThresholdInput, TpSlThresholdType, TradeHistoryAssetDataDto, TradeHistoryDataDto, TwapChunkStatusDto, TwapMonitoringDto, TwapSliceFillResponseItem, UniverseAsset, UpdateRiskParametersRequestInput, UpdateRiskParametersResponseDto, UseAuthOptions, UseBasketCandlesReturn, UseHistoricalPriceDataReturn, UseNotificationsResult, UsePerformanceOverlaysReturn, UsePortfolioResult, UseTokenSelectionMetadataReturn, UserProfile, UserSelectionState, WatchlistItemDto, WebSocketAckResponse, WebSocketChannel, WebSocketConnectionState, WebSocketDataMessage, WebSocketMessage, WebSocketSubscribeMessage, WsAllMidsData };
+export { AccountSummaryCalculator, ConflictDetector, MAX_ASSETS_PER_LEG, MINIMUM_ASSET_USD_VALUE, MaxAssetsPerLegError, MinimumPositionSizeError, PearHyperliquidProvider, TokenMetadataExtractor, adjustAdvancePosition, adjustOrder, adjustPosition, calculateMinimumPositionValue, calculateWeightedRatio, cancelOrder, cancelTwap, cancelTwapOrder, closeAllPositions, closePosition, computeBasketCandles, createCandleLookups, createPosition, executeSpotOrder, getAvailableMarkets, getCompleteTimestamps, getMarketPrefix, getPortfolio, isHip3Market, mapCandleIntervalToTradingViewInterval, mapTradingViewIntervalToCandleInterval, markNotificationReadById, markNotificationsRead, toBackendSymbol, toBackendSymbolWithMarket, toDisplaySymbol, toggleWatchlist, updateRiskParameters, useAccountSummary, useActiveBaskets, useAgentWallet, useAllBaskets, useAuth, useAutoSyncFills, useBasketCandles, useFindBasket, useHighlightedBaskets, useHistoricalPriceData, useHistoricalPriceDataStore, useHyperliquidNativeWebSocket, useHyperliquidWebSocket, useMarketData, useMarketDataAllPayload, useMarketDataPayload, useNotifications, useOpenOrders, useOrders, usePearHyperliquid, usePerformanceOverlays, usePerpMetaAssets, usePortfolio, usePosition, useSpotBalances, useSpotOrder, useTokenSelectionMetadata, useTopGainers, useTopLosers, useTradeHistories, useTwap, useUserSelection, useWatchlist, useWatchlistBaskets, useWebData, validateMaxAssetsPerLeg, validateMinimumAssetSize, validatePositionSize };
+export type { AccountSummaryResponseDto, ActiveAssetGroupItem, ActiveAssetsResponse, AdjustAdvanceAssetInput, AdjustAdvanceItemInput, AdjustAdvanceResponseDto, AdjustExecutionType, AdjustOrderRequestInput, AdjustOrderResponseDto, AdjustPositionRequestInput, AdjustPositionResponseDto, AgentWalletDto, AgentWalletState, ApiErrorResponse, ApiResponse, AssetCtx, AssetInformationDetail, AssetMarketData, AssetPosition, AutoSyncFillsOptions, AutoSyncFillsState, BalanceSummaryDto, CancelOrderResponseDto, CancelTwapResponseDto, CandleChartData, CandleData, CandleInterval, CandleSnapshotRequest, ClearinghouseState, CloseAllPositionsResponseDto, CloseAllPositionsResultDto, CloseExecutionType, ClosePositionRequestInput, ClosePositionResponseDto, CollateralFilter, CollateralToken, CreatePositionRequestInput, CreatePositionResponseDto, CrossMarginSummaryDto, CumFundingDto, ExecutionType, ExtraAgent, HLWebSocketResponse, HistoricalRange, LadderConfigInput, MarginSummaryDto, MarketDataBySymbol, NotificationCategory, NotificationDto, OpenLimitOrderDto, OpenPositionDto, OrderAssetDto, OrderStatus, PairAssetDto, PairAssetInput, PerformanceOverlay, PlatformAccountSummaryResponseDto, PortfolioBucketDto, PortfolioInterval, PortfolioIntervalsDto, PortfolioOverallDto, PortfolioResponseDto, PositionAdjustmentType, PositionAssetDetailDto, PositionAssetSummaryDto, PositionResponseStatus, RealtimeBar, RealtimeBarsCallback, SpotBalance, SpotOrderFilledStatus, SpotOrderHyperliquidData, SpotOrderHyperliquidResult, SpotOrderRequestInput, SpotOrderResponseDto, SpotState, ToggleWatchlistResponseDto, TokenConflict, TokenHistoricalPriceData, TokenMetadata, TokenSelection, TpSlThresholdInput, TpSlThresholdType, TradeHistoryAssetDataDto, TradeHistoryDataDto, TwapChunkStatusDto, TwapMonitoringDto, TwapSliceFillResponseItem, UniverseAsset, UpdateRiskParametersRequestInput, UpdateRiskParametersResponseDto, UseAuthOptions, UseBasketCandlesReturn, UseHistoricalPriceDataReturn, UseNotificationsResult, UsePerformanceOverlaysReturn, UsePortfolioResult, UseSpotOrderResult, UseTokenSelectionMetadataReturn, UserProfile, UserSelectionState, WatchlistItemDto, WebSocketAckResponse, WebSocketChannel, WebSocketConnectionState, WebSocketDataMessage, WebSocketMessage, WebSocketSubscribeMessage, WsAllMidsData };