@pear-protocol/hyperliquid-sdk 0.0.73-beta.2 → 0.0.73-beta.5

package/dist/provider.d.ts

@@ -1,4 +1,4 @@
-import React, { ReactNode } from "react";
+import React, { ReactNode } from 'react';
 export interface PearHyperliquidContextType {
     clientId: string;
     apiBaseUrl: string;

package/dist/store/hyperliquidDataStore.d.ts

@@ -1,4 +1,4 @@
-import { ActiveAssetData, CandleChartData, CandleData, ClearinghouseState, UniverseAsset, WebData3AssetCtx, WsAllMidsData } from "../types";
+import { ActiveAssetData, CandleChartData, CandleData, ClearinghouseState, UniverseAsset, WebData3AssetCtx, WsAllMidsData } from '../types';
 interface HyperliquidDataState {
     allMids: WsAllMidsData | null;
     activeAssetData: Record<string, ActiveAssetData> | null;
@@ -6,8 +6,11 @@ interface HyperliquidDataState {
     finalAssetContexts: WebData3AssetCtx[] | null;
     finalAtOICaps: string[] | null;
     aggregatedClearingHouseState: ClearinghouseState | null;
+    rawClearinghouseStates: [string, ClearinghouseState][] | null;
     perpMetaAssets: UniverseAsset[] | null;
-    hip3DisplayToFull: Map<string, string>;
+    allPerpMetaAssets: UniverseAsset[] | null;
+    hip3Assets: Map<string, string[]>;
+    hip3MarketPrefixes: Map<string, string>;
     setAllMids: (value: WsAllMidsData | null) => void;
     setActiveAssetData: (value: Record<string, ActiveAssetData> | null | ((prev: Record<string, ActiveAssetData> | null) => Record<string, ActiveAssetData> | null)) => void;
     deleteActiveAssetData: (key: string) => void;
@@ -18,8 +21,11 @@ interface HyperliquidDataState {
     setFinalAssetContexts: (value: WebData3AssetCtx[] | null) => void;
     setFinalAtOICaps: (value: string[] | null) => void;
     setAggregatedClearingHouseState: (value: ClearinghouseState | null) => void;
+    setRawClearinghouseStates: (value: [string, ClearinghouseState][] | null) => void;
     setPerpMetaAssets: (value: UniverseAsset[] | null) => void;
-    setHip3DisplayToFull: (value: Map<string, string>) => void;
+    setAllPerpMetaAssets: (value: UniverseAsset[] | null) => void;
+    setHip3Assets: (value: Map<string, string[]>) => void;
+    setHip3MarketPrefixes: (value: Map<string, string>) => void;
 }
 export declare const useHyperliquidData: import("zustand").UseBoundStore<import("zustand").StoreApi<HyperliquidDataState>>;
 export {};

package/dist/store/userDataStore.d.ts

@@ -1,4 +1,4 @@
-import { PlatformAccountSummaryResponseDto, OpenLimitOrderDto, RawPositionDto, TradeHistoryDataDto, TwapMonitoringDto, NotificationDto, ExtraAgent } from "../types";
+import { PlatformAccountSummaryResponseDto, OpenLimitOrderDto, RawPositionDto, TradeHistoryDataDto, TwapMonitoringDto, NotificationDto, ExtraAgent, SpotState } from "../types";
 interface UserDataState {
     accessToken: string | null;
     refreshToken: string | null;
@@ -12,6 +12,7 @@ interface UserDataState {
     twapDetails: TwapMonitoringDto[] | null;
     notifications: NotificationDto[] | null;
     userExtraAgents: ExtraAgent[] | null;
+    spotState: SpotState | null;
     setAccessToken: (token: string | null) => void;
     setRefreshToken: (token: string | null) => void;
     setIsAuthenticated: (value: boolean) => void;
@@ -24,6 +25,7 @@ interface UserDataState {
     setUserExtraAgents: (value: ExtraAgent[] | null) => void;
     setTwapDetails: (value: TwapMonitoringDto[] | null) => void;
     setNotifications: (value: NotificationDto[] | null) => void;
+    setSpotState: (value: SpotState | null) => void;
     clean: () => void;
 }
 export declare const useUserData: import("zustand").UseBoundStore<import("zustand").StoreApi<UserDataState>>;

package/dist/types.d.ts

@@ -20,7 +20,7 @@ export interface ExternalFillDto {
     coin: string;
     px: string;
     sz: string;
-    side: "B" | "A";
+    side: 'B' | 'A';
     time: number;
     dir: string;
     fee: string;
@@ -52,7 +52,7 @@ export interface TwapSliceFillResponseItem {
 /**
  * WebSocket connection states
  */
-export type WebSocketConnectionState = "connecting" | "connected" | "disconnected" | "error";
+export type WebSocketConnectionState = 'connecting' | 'connected' | 'disconnected' | 'error';
 export declare enum ReadyState {
     CONNECTING = 0,
     OPEN = 1,
@@ -62,12 +62,12 @@ export declare enum ReadyState {
 /**
  * WebSocket channels
  */
-export type WebSocketChannel = "trade-histories" | "open-positions" | "open-orders" | "account-summary" | "twap-details" | "notifications" | "market-data" | "market-data-all" | "webData3" | "allMids" | "activeAssetData";
+export type WebSocketChannel = 'trade-histories' | 'open-positions' | 'open-orders' | 'account-summary' | 'twap-details' | 'notifications' | 'market-data' | 'market-data-all' | 'webData3' | 'allMids' | 'activeAssetData';
 /**
  * WebSocket subscription message
  */
 export interface WebSocketSubscribeMessage {
-    action?: "subscribe" | "unsubscribe";
+    action?: 'subscribe' | 'unsubscribe';
     address: string;
 }
 /**
@@ -97,7 +97,7 @@ export interface WatchlistItemDto {
 export interface ToggleWatchlistResponseDto {
     items: WatchlistItemDto[];
 }
-export 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";
+export 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';
 export interface NotificationDto {
     id: string;
     address: string;
@@ -114,7 +114,7 @@ export interface ChunkFillDto {
     size: number;
     executedAt: string;
 }
-export type TwapChunkStatus = "PENDING" | "SCHEDULED" | "EXECUTING" | "COMPLETED" | "FAILED" | "CANCELLED";
+export type TwapChunkStatus = 'PENDING' | 'SCHEDULED' | 'EXECUTING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
 export interface TwapChunkStatusDto {
     chunkId: string;
     chunkIndex: number;
@@ -125,7 +125,7 @@ export interface TwapChunkStatusDto {
     fills: ChunkFillDto[];
     errorMessage?: string;
 }
-export type TwapOrderOverallStatus = "OPEN" | "EXECUTING" | "COMPLETED" | "PARTIALLY_COMPLETED" | "FAILED" | "CANCELLED";
+export type TwapOrderOverallStatus = 'OPEN' | 'EXECUTING' | 'COMPLETED' | 'PARTIALLY_COMPLETED' | 'FAILED' | 'CANCELLED';
 export interface TwapMonitoringDto {
     orderId: string;
     positionId?: string;
@@ -162,6 +162,8 @@ export interface TradeHistoryAssetDataDto {
     externalFeePaid: number;
     builderFeePaid: number;
     realizedPnl: number;
+    marketPrefix?: string | null;
+    collateralToken?: CollateralToken;
 }
 /**
  * Trade history data structure
@@ -210,9 +212,11 @@ export interface PositionAssetDetailDto {
     liquidationPrice: number;
     initialWeight: number;
     fundingPaid?: number;
+    marketPrefix?: string | null;
+    collateralToken?: CollateralToken;
 }
 export interface TpSlThreshold {
-    type: "PERCENTAGE" | "DOLLAR" | "POSITION_VALUE";
+    type: 'PERCENTAGE' | 'DOLLAR' | 'POSITION_VALUE';
     value: number;
 }
 /**
@@ -243,20 +247,22 @@ export interface OpenPositionDto {
 export interface OrderAssetDto {
     asset: string;
     weight: number;
+    marketPrefix?: string | null;
+    collateralToken?: CollateralToken;
 }
 /**
  * Order status
  */
-export type OrderStatus = "OPEN" | "PARTIALLY_FILLED" | "PROCESSING";
+export type OrderStatus = 'OPEN' | 'PARTIALLY_FILLED' | 'PROCESSING';
 /**
  * Order type
  */
-export type OrderType = "TP" | "SL" | "LIMIT" | "MARKET" | "LIMIT_BTCDOM" | "TWAP";
+export type OrderType = 'TP' | 'SL' | 'LIMIT' | 'MARKET' | 'LIMIT_BTCDOM' | 'TWAP';
 /**
  * TP/SL trigger type
  */
-export type TpSlTriggerType = "PERCENTAGE" | "DOLLAR" | "POSITION_VALUE";
-export type OrderDirection = "MORE_THAN" | "LESS_THAN" | null;
+export type TpSlTriggerType = 'PERCENTAGE' | 'DOLLAR' | 'POSITION_VALUE';
+export type OrderDirection = 'MORE_THAN' | 'LESS_THAN' | null;
 /**
  * Open limit order data structure
  */
@@ -370,7 +376,7 @@ export interface PrivyAuthDetails {
     accessToken: string;
 }
 export interface AuthenticateRequest {
-    method: "eip712" | "api_key" | "privy_access_token";
+    method: 'eip712' | 'api_key' | 'privy_access_token';
     address: string;
     clientId: string;
     details: {
@@ -403,7 +409,7 @@ export interface LogoutRequest {
 export interface LogoutResponse {
     message: string;
 }
-export type AgentWalletStatus = "ACTIVE" | "EXPIRED" | "NOT_FOUND";
+export type AgentWalletStatus = 'ACTIVE' | 'EXPIRED' | 'NOT_FOUND';
 export interface GetAgentWalletResponseDto {
     agentWalletAddress?: string;
     agentName: string;
@@ -421,14 +427,14 @@ export interface ExtraAgent {
 export interface AgentWalletState {
     address: string | null;
     name: string | null;
-    status: AgentWalletStatus | "PENDING" | null;
+    status: AgentWalletStatus | 'PENDING' | null;
     isActive: boolean;
 }
 /**
  * WebSocket message from HyperLiquid native API
  */
 export interface WebSocketMessage {
-    method: "subscribe" | "unsubscribe";
+    method: 'subscribe' | 'unsubscribe';
     subscription: {
         type: string;
         dex?: string;
@@ -441,12 +447,16 @@ export interface WebSocketMessage {
 /**
  * WebSocket response from HyperLiquid native API
  */
-export type HLChannel = "webData3" | "allMids" | "activeAssetData" | "candle" | "allDexsClearinghouseState" | "allDexsAssetCtxs";
+export type HLChannel = 'webData3' | 'allMids' | 'activeAssetData' | 'candle' | 'spotState' | 'allDexsClearinghouseState' | 'allDexsAssetCtxs';
 export interface HLChannelDataMap {
     webData3: WebData3Response;
     allMids: WsAllMidsData;
     activeAssetData: ActiveAssetData;
     candle: CandleData;
+    spotState: {
+        user: string;
+        spotState: SpotState;
+    };
     allDexsClearinghouseState: AllDexsClearinghouseStateData;
     allDexsAssetCtxs: AllDexsAssetCtxsData;
 }
@@ -511,6 +521,12 @@ export interface AssetCtx {
     impactPxs?: string[];
     oraclePx: string;
 }
+/**
+ * Collateral token type
+ * 0 = USDC
+ * 360 = USDH
+ */
+export type CollateralToken = 'USDC' | 'USDH';
 /**
  * Universe asset metadata
  */
@@ -520,6 +536,8 @@ export interface UniverseAsset {
     maxLeverage: number;
     onlyIsolated?: boolean;
     isDelisted?: boolean;
+    marketPrefix?: string;
+    collateralToken?: CollateralToken;
 }
 export interface PerpMetaAsset extends UniverseAsset {
     marginTableId: number;
@@ -608,6 +626,8 @@ export interface RawAssetDto {
     size: number;
     side: string;
     fundingPaid?: number;
+    marketPrefix?: string | null;
+    collateralToken?: CollateralToken;
     leverage: number;
 }
 /**
@@ -656,6 +676,7 @@ export interface TokenMetadata {
     leverage?: LeverageInfo;
     maxTradeSzs?: [string, string];
     availableToTrade?: [string, string];
+    collateralToken?: CollateralToken;
 }
 /**
  * Enhanced token selection with weight and metadata for basket trading
@@ -669,16 +690,37 @@ export interface TokenSelection {
  */
 export interface TokenConflict {
     symbol: string;
-    conflictType: "long" | "short";
+    conflictType: 'long' | 'short';
     conflictMessage: string;
 }
 export 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: {...} }
+ *   }
+ * }
+ * ```
+ */
+export type MarketDataBySymbol = Record<string, Record<string, AssetMarketData>>;
 export interface PairAssetDto {
     asset: string;
     weight: number;
+    collateralToken: CollateralToken;
+    marketPrefix: string | null;
 }
 export interface ActiveAssetGroupItem {
     longAssets: PairAssetDto[];
@@ -692,6 +734,7 @@ export interface ActiveAssetGroupItem {
     weightedRatio?: string;
     weightedPrevRatio?: string;
     weightedChange24h?: string;
+    collateralType: 'USDC' | 'USDH' | 'MIXED';
 }
 export interface ActiveAssetsResponse {
     active: ActiveAssetGroupItem[];
@@ -709,7 +752,7 @@ export interface ActiveAssetsAllResponse {
 /**
  * Candle interval options
  */
-export type CandleInterval = "1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "8h" | "12h" | "1d" | "3d" | "1w" | "1M";
+export type CandleInterval = '1m' | '3m' | '5m' | '15m' | '30m' | '1h' | '2h' | '4h' | '8h' | '12h' | '1d' | '3d' | '1w' | '1M';
 /**
  * Candle data structure from WebSocket
  */
@@ -737,9 +780,20 @@ export interface CandleSnapshotRequest {
         endTime: number;
         interval: CandleInterval;
     };
-    type: "candleSnapshot";
+    type: 'candleSnapshot';
 }
 export interface TokenSelectorConfig {
     isLong: boolean;
     index: number;
 }
+export interface SpotBalance {
+    coin: string;
+    token: number;
+    total: string;
+    hold: string;
+    entryNtl: string;
+}
+export interface SpotState {
+    user: string;
+    balances: SpotBalance[];
+}

package/dist/utils/symbol-translator.d.ts

@@ -5,7 +5,36 @@ export 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.
- * @param displaySymbol e.g., "XYZ100"
- * @param displayToFull map of display -> full (e.g., "XYZ100" -> "xyz:XYZ100")
+ * 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"])
  */
-export declare function toBackendSymbol(displaySymbol: string, displayToFull: Map<string, string>): string;
+export 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
+ */
+export 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"]
+ */
+export 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
+ */
+export 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
+ */
+export declare function isHip3Market(symbol: string): boolean;

package/dist/utils/token-metadata-extractor.d.ts

@@ -5,24 +5,28 @@ import type { WsAllMidsData, TokenMetadata, ActiveAssetData, UniverseAsset, WebD
 export 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/hyperliquid-sdk",
-  "version": "0.0.73-beta.2",
+  "version": "0.0.73-beta.5",
   "description": "React SDK for Pear Protocol Hyperliquid API integration",
   "type": "module",
   "main": "dist/index.js",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "axios": "^1.6.0",
-    "zustand": "^5.0.8"
+    "zustand": "^5.0.9"
   },
   "peerDependencies": {
     "react": "^18.0.0",