@pear-protocol/hyperliquid-sdk 0.0.32 → 0.0.34

package/dist/clients/notifications.d.ts

@@ -0,0 +1,7 @@
+import type { ApiResponse } from '../types';
+/**
+ * Mark notifications as read up to a given timestamp (ms)
+ */
+export declare function markNotificationsRead(baseUrl: string, accessToken: string, timestampMs: number): Promise<ApiResponse<{
+    updated: number;
+}>>;

package/dist/hooks/index.d.ts

@@ -12,3 +12,4 @@ export * from './useAutoSyncFills';
 export * from './usePosition';
 export * from './useOrders';
 export * from './useTwap';
+export * from './useNotifications';

package/dist/hooks/useNotifications.d.ts

@@ -0,0 +1,13 @@
+import type { NotificationDto } from '../types';
+export interface UseNotificationsResult {
+    notifications: NotificationDto[] | null;
+    unreadCount: number;
+    markReadUntil: (timestampMs: number) => Promise<{
+        updated: number;
+    }>;
+}
+/**
+ * Provides notifications and fills checkpoint data sourced from the SDK WebSocket.
+ * Data is persisted in the SDK's Zustand store.
+ */
+export declare function useNotifications(): UseNotificationsResult;

package/dist/index.d.ts

@@ -30,7 +30,7 @@ type WebSocketConnectionState = 'connecting' | 'connected' | 'disconnected' | 'e
 /**
  * WebSocket channels
  */
-type WebSocketChannel = 'trade-histories' | 'open-positions' | 'open-orders' | 'account-summary' | 'twap-details' | 'webData2' | 'allMids' | 'activeAssetData';
+type WebSocketChannel = 'trade-histories' | 'open-positions' | 'open-orders' | 'account-summary' | 'twap-details' | 'notifications' | 'webData2' | 'allMids' | 'activeAssetData';
 /**
  * WebSocket subscription message
  */
@@ -53,6 +53,16 @@ interface WebSocketDataMessage<T = unknown> {
     channel: WebSocketChannel;
     data: T;
 }
+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;
+    category: NotificationCategory;
+    parameters: Record<string, any>;
+    is_read: boolean;
+    created_at: string;
+    updated_at: string;
+}
 interface ChunkFillDto {
     fillId: string;
     assetName: string;
@@ -935,6 +945,19 @@ declare function useTwap(): {
     readonly cancelTwap: (orderId: string) => Promise<ApiResponse<CancelTwapResponseDto>>;
 };
 
+interface UseNotificationsResult {
+    notifications: NotificationDto[] | null;
+    unreadCount: number;
+    markReadUntil: (timestampMs: number) => Promise<{
+        updated: number;
+    }>;
+}
+/**
+ * Provides notifications and fills checkpoint data sourced from the SDK WebSocket.
+ * Data is persisted in the SDK's Zustand store.
+ */
+declare function useNotifications(): UseNotificationsResult;
+
 interface UseHyperliquidWebSocketProps {
     wsUrl: string;
     address: string | null;
@@ -956,6 +979,13 @@ interface UseHyperliquidNativeWebSocketReturn {
 }
 declare const useHyperliquidNativeWebSocket: ({ address, }: UseHyperliquidNativeWebSocketProps) => UseHyperliquidNativeWebSocketReturn;
 
+/**
+ * Mark notifications as read up to a given timestamp (ms)
+ */
+declare function markNotificationsRead(baseUrl: string, accessToken: string, timestampMs: number): Promise<ApiResponse<{
+    updated: number;
+}>>;
+
 /**
  * Account summary calculation utility class
  */
@@ -1058,5 +1088,5 @@ declare function mapTradingViewIntervalToCandleInterval(interval: string): Candl
  */
 declare function mapCandleIntervalToTradingViewInterval(interval: CandleInterval): string;
 
-export { AccountSummaryCalculator, AuthStatus, ConflictDetector, PearHyperliquidProvider, TokenMetadataExtractor, adjustOrder, adjustPosition, calculateWeightedRatio, cancelOrder, cancelTwap, cancelTwapOrder, closePosition, computeBasketCandles, createCandleLookups, createPosition, getCompleteTimestamps, mapCandleIntervalToTradingViewInterval, mapTradingViewIntervalToCandleInterval, updateRiskParameters, useAccountSummary, useAddress, useAgentWallet, useAuth, useAutoSyncFills, useBasketCandles, useHistoricalPriceData, useHistoricalPriceDataStore, useHyperliquidNativeWebSocket, useHyperliquidWebSocket, useOpenOrders, useOrders, usePearAgentWallet, usePearAuth, usePearHyperliquid, usePerformanceOverlays, usePosition, useTokenSelectionMetadata, useTradeHistories, useTwap, useUserSelection, useWebData };
-export type { AccountSummaryResponseDto, AdjustExecutionType, AdjustOrderRequestInput, AdjustOrderResponseDto, AdjustPositionRequestInput, AdjustPositionResponseDto, AgentWalletDto, AgentWalletState, ApiErrorResponse, ApiResponse, AssetCtx, AssetInformationDetail, AssetMarketData, AssetPosition, AutoSyncFillsOptions, AutoSyncFillsState, BalanceSummaryDto, CancelOrderResponseDto, CancelTwapResponseDto, CandleChartData, CandleData, CandleInterval, CandleSnapshotRequest, ClearinghouseState, CloseExecutionType, ClosePositionRequestInput, ClosePositionResponseDto, CreatePositionRequestInput, CreatePositionResponseDto, CrossMarginSummaryDto, CumFundingDto, ExecutionType, HLWebSocketResponse, HistoricalRange, LadderConfigInput, MarginSummaryDto, OpenLimitOrderDto, OpenPositionDto, OrderAssetDto, OrderStatus, PairAssetInput, PerformanceOverlay, PositionAdjustmentType, PositionAssetDetailDto, PositionAssetSummaryDto, PositionResponseStatus, RealtimeBar, RealtimeBarsCallback, TokenConflict, TokenHistoricalPriceData, TokenMetadata, TokenSelection, TpSlThresholdInput, TpSlThresholdType, TradeHistoryAssetDataDto, TradeHistoryDataDto, TwapChunkStatusDto, TwapMonitoringDto, UniverseAsset, UpdateRiskParametersRequestInput, UpdateRiskParametersResponseDto, UseAgentWalletOptions, UseAuthOptions, UseBasketCandlesReturn, UseHistoricalPriceDataReturn, UsePerformanceOverlaysReturn, UseTokenSelectionMetadataReturn, UserProfile, UserSelectionState, WebData2Response, WebSocketAckResponse, WebSocketChannel, WebSocketConnectionState, WebSocketDataMessage, WebSocketMessage, WebSocketSubscribeMessage, WsAllMidsData };
+export { AccountSummaryCalculator, AuthStatus, ConflictDetector, PearHyperliquidProvider, TokenMetadataExtractor, adjustOrder, adjustPosition, calculateWeightedRatio, cancelOrder, cancelTwap, cancelTwapOrder, closePosition, computeBasketCandles, createCandleLookups, createPosition, getCompleteTimestamps, mapCandleIntervalToTradingViewInterval, mapTradingViewIntervalToCandleInterval, markNotificationsRead, updateRiskParameters, useAccountSummary, useAddress, useAgentWallet, useAuth, useAutoSyncFills, useBasketCandles, useHistoricalPriceData, useHistoricalPriceDataStore, useHyperliquidNativeWebSocket, useHyperliquidWebSocket, useNotifications, useOpenOrders, useOrders, usePearAgentWallet, usePearAuth, usePearHyperliquid, usePerformanceOverlays, usePosition, useTokenSelectionMetadata, useTradeHistories, useTwap, useUserSelection, useWebData };
+export type { AccountSummaryResponseDto, AdjustExecutionType, AdjustOrderRequestInput, AdjustOrderResponseDto, AdjustPositionRequestInput, AdjustPositionResponseDto, AgentWalletDto, AgentWalletState, ApiErrorResponse, ApiResponse, AssetCtx, AssetInformationDetail, AssetMarketData, AssetPosition, AutoSyncFillsOptions, AutoSyncFillsState, BalanceSummaryDto, CancelOrderResponseDto, CancelTwapResponseDto, CandleChartData, CandleData, CandleInterval, CandleSnapshotRequest, ClearinghouseState, CloseExecutionType, ClosePositionRequestInput, ClosePositionResponseDto, CreatePositionRequestInput, CreatePositionResponseDto, CrossMarginSummaryDto, CumFundingDto, ExecutionType, HLWebSocketResponse, HistoricalRange, LadderConfigInput, MarginSummaryDto, NotificationCategory, NotificationDto, OpenLimitOrderDto, OpenPositionDto, OrderAssetDto, OrderStatus, PairAssetInput, PerformanceOverlay, PositionAdjustmentType, PositionAssetDetailDto, PositionAssetSummaryDto, PositionResponseStatus, RealtimeBar, RealtimeBarsCallback, TokenConflict, TokenHistoricalPriceData, TokenMetadata, TokenSelection, TpSlThresholdInput, TpSlThresholdType, TradeHistoryAssetDataDto, TradeHistoryDataDto, TwapChunkStatusDto, TwapMonitoringDto, UniverseAsset, UpdateRiskParametersRequestInput, UpdateRiskParametersResponseDto, UseAgentWalletOptions, UseAuthOptions, UseBasketCandlesReturn, UseHistoricalPriceDataReturn, UseNotificationsResult, UsePerformanceOverlaysReturn, UseTokenSelectionMetadataReturn, UserProfile, UserSelectionState, WebData2Response, WebSocketAckResponse, WebSocketChannel, WebSocketConnectionState, WebSocketDataMessage, WebSocketMessage, WebSocketSubscribeMessage, WsAllMidsData };

package/dist/index.js

@@ -2434,22 +2434,25 @@ const useUserData = create((set) => ({
     openOrders: null,
     accountSummary: null,
     twapDetails: null,
+    notifications: null,
     setTradeHistories: (value) => set({ tradeHistories: value }),
     setRawOpenPositions: (value) => set({ rawOpenPositions: value }),
     setOpenOrders: (value) => set({ openOrders: value }),
     setAccountSummary: (value) => set({ accountSummary: value }),
     setTwapDetails: (value) => set({ twapDetails: value }),
+    setNotifications: (value) => set({ notifications: value }),
     clean: () => set({
         tradeHistories: null,
         rawOpenPositions: null,
         openOrders: null,
         accountSummary: null,
         twapDetails: null,
+        notifications: null,
     }),
 }));
 
 const useHyperliquidWebSocket = ({ wsUrl, address }) => {
-    const { setTradeHistories, setRawOpenPositions, setOpenOrders, setAccountSummary, setTwapDetails, clean } = useUserData();
+    const { setTradeHistories, setRawOpenPositions, setOpenOrders, setAccountSummary, setTwapDetails, setNotifications, clean, } = useUserData();
     const [lastError, setLastError] = useState(null);
     const [lastSubscribedAddress, setLastSubscribedAddress] = useState(null);
     // WebSocket connection
@@ -2493,6 +2496,10 @@ const useHyperliquidWebSocket = ({ wsUrl, address }) => {
                         case 'twap-details':
                             setTwapDetails(dataMessage.data);
                             break;
+                        case 'notifications':
+                            setNotifications(dataMessage.data);
+                            break;
+                        // 'fills-checkpoint' is intentionally ignored here
                     }
                 }
             }
@@ -8557,6 +8564,56 @@ function useTwap() {
     return { orders, cancelTwap: cancelTwap$1 };
 }
 
+/**
+ * Mark notifications as read up to a given timestamp (ms)
+ */
+async function markNotificationsRead(baseUrl, accessToken, timestampMs) {
+    const url = joinUrl(baseUrl, '/notifications/read');
+    try {
+        const response = await axios$1.post(url, { timestamp: timestampMs }, { headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${accessToken}` } });
+        return { data: response.data, status: response.status, headers: response.headers };
+    }
+    catch (error) {
+        throw toApiError(error);
+    }
+}
+
+/**
+ * Provides notifications and fills checkpoint data sourced from the SDK WebSocket.
+ * Data is persisted in the SDK's Zustand store.
+ */
+function useNotifications() {
+    const notifications = useUserData((state) => state.notifications);
+    const setNotifications = useUserData((state) => state.setNotifications);
+    const { apiBaseUrl, accessToken, isAuthenticated } = usePearHyperliquid();
+    const unreadCount = useMemo(() => {
+        if (!notifications)
+            return 0;
+        return notifications.reduce((acc, n) => acc + (n.is_read ? 0 : 1), 0);
+    }, [notifications]);
+    return {
+        notifications,
+        unreadCount,
+        markReadUntil: useCallback(async (timestampMs) => {
+            if (!isAuthenticated || !accessToken)
+                throw new Error('Not authenticated');
+            const { data } = await markNotificationsRead(apiBaseUrl, accessToken, timestampMs);
+            // Optimistic local update for immediate UI feedback
+            if (notifications) {
+                const updated = notifications.map((n) => {
+                    const created = Date.parse(n.created_at);
+                    if (!isNaN(created) && created <= timestampMs) {
+                        return { ...n, is_read: true };
+                    }
+                    return n;
+                });
+                setNotifications(updated);
+            }
+            return data;
+        }, [apiBaseUrl, accessToken, isAuthenticated, notifications, setNotifications]),
+    };
+}
+
 const PearHyperliquidContext = createContext(undefined);
 /**
  * React Provider for PearHyperliquidClient
@@ -8855,4 +8912,4 @@ function mapCandleIntervalToTradingViewInterval(interval) {
     }
 }
 
-export { AccountSummaryCalculator, AuthStatus, ConflictDetector, PearHyperliquidProvider, TokenMetadataExtractor, adjustOrder, adjustPosition, calculateWeightedRatio, cancelOrder, cancelTwap, cancelTwapOrder, closePosition, computeBasketCandles, createCandleLookups, createPosition, getCompleteTimestamps, mapCandleIntervalToTradingViewInterval, mapTradingViewIntervalToCandleInterval, updateRiskParameters, useAccountSummary, useAddress, useAgentWallet, useAuth, useAutoSyncFills, useBasketCandles, useHistoricalPriceData, useHistoricalPriceDataStore, useHyperliquidNativeWebSocket, useHyperliquidWebSocket, useOpenOrders, useOrders, usePearAgentWallet, usePearAuth, usePearHyperliquid, usePerformanceOverlays, usePosition, useTokenSelectionMetadata, useTradeHistories, useTwap, useUserSelection, useWebData };
+export { AccountSummaryCalculator, AuthStatus, ConflictDetector, PearHyperliquidProvider, TokenMetadataExtractor, adjustOrder, adjustPosition, calculateWeightedRatio, cancelOrder, cancelTwap, cancelTwapOrder, closePosition, computeBasketCandles, createCandleLookups, createPosition, getCompleteTimestamps, mapCandleIntervalToTradingViewInterval, mapTradingViewIntervalToCandleInterval, markNotificationsRead, updateRiskParameters, useAccountSummary, useAddress, useAgentWallet, useAuth, useAutoSyncFills, useBasketCandles, useHistoricalPriceData, useHistoricalPriceDataStore, useHyperliquidNativeWebSocket, useHyperliquidWebSocket, useNotifications, useOpenOrders, useOrders, usePearAgentWallet, usePearAuth, usePearHyperliquid, usePerformanceOverlays, usePosition, useTokenSelectionMetadata, useTradeHistories, useTwap, useUserSelection, useWebData };

package/dist/types.d.ts

@@ -51,7 +51,7 @@ export type WebSocketConnectionState = 'connecting' | 'connected' | 'disconnecte
 /**
  * WebSocket channels
  */
-export type WebSocketChannel = 'trade-histories' | 'open-positions' | 'open-orders' | 'account-summary' | 'twap-details' | 'webData2' | 'allMids' | 'activeAssetData';
+export type WebSocketChannel = 'trade-histories' | 'open-positions' | 'open-orders' | 'account-summary' | 'twap-details' | 'notifications' | 'webData2' | 'allMids' | 'activeAssetData';
 /**
  * WebSocket subscription message
  */
@@ -74,6 +74,16 @@ export interface WebSocketDataMessage<T = unknown> {
     channel: WebSocketChannel;
     data: T;
 }
+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;
+    category: NotificationCategory;
+    parameters: Record<string, any>;
+    is_read: boolean;
+    created_at: string;
+    updated_at: string;
+}
 export interface ChunkFillDto {
     fillId: string;
     assetName: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/hyperliquid-sdk",
-  "version": "0.0.32",
+  "version": "0.0.34",
   "description": "React SDK for Pear Protocol Hyperliquid API integration",
   "type": "module",
   "main": "dist/index.js",