@pear-protocol/hyperliquid-sdk 0.0.24 → 0.0.26

package/README.md

@@ -1,35 +1,35 @@
 # @pear-protocol/hyperliquid-sdk
 
-> React SDK for Pear Protocol Hyperliquid API integration
-
-[![npm version](https://badge.fury.io/js/%40pear-protocol%2Fhyperliquid-sdk.svg)](https://badge.fury.io/js/%40pear-protocol%2Fhyperliquid-sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-A comprehensive React SDK for integrating with Pear Protocol's Hyperliquid trading platform. This SDK provides React hooks, TypeScript support, real-time WebSocket connections, and migration utilities for seamless integration.
+A React SDK for integrating with Pear Protocol's Hyperliquid trading API. This SDK provides React hooks, WebSocket connections, and utilities for building trading applications on the Hyperliquid perpetuals exchange.
 
 ## Features
 
-- 🚀 **React Hooks**: Easy-to-use hooks for trading data and account management
-- 🔌 **Real-time WebSocket**: Live updates for positions, orders, and trade history
-- 📝 **TypeScript**: Full TypeScript support with comprehensive type definitions
-- 🔄 **Migration Tools**: Built-in SDK for migrating trading data
-- 📱 **Responsive**: Works with React 16.8+ and modern React patterns
+- **React Integration**: Purpose-built React hooks for trading data and operations
+- **Real-time Data**: WebSocket connections for live market data and account updates
+- **Authentication**: EIP-712 signature and Privy wallet integration
+- **Trading Operations**: Position management, order placement, and portfolio tracking
+- **Agent Wallets**: Automated trading wallet creation and management
+- **TypeScript Support**: Full TypeScript definitions for all APIs and data structures
 
 ## Installation
 
 ```bash
 npm install @pear-protocol/hyperliquid-sdk
+# or
+yarn add @pear-protocol/hyperliquid-sdk
 ```
 
-or
+### Peer Dependencies
+
+This package requires React 18+ as a peer dependency:
 
 ```bash
-yarn add @pear-protocol/hyperliquid-sdk
+npm install react react-dom
 ```
 
 ## Quick Start
 
-### 1. Setup the Provider
+### 1. Provider Setup
 
 Wrap your application with the `PearHyperliquidProvider`:
 
@@ -39,82 +39,97 @@ import { PearHyperliquidProvider } from '@pear-protocol/hyperliquid-sdk';
 function App() {
   return (
     <PearHyperliquidProvider
-      config={{
-        baseUrl: 'https://hl-v2.pearprotocol.io',
-        timeout: 30000, // Optional: Request timeout in ms
-      }}
-      wsUrl="wss://hl-v2.pearprotocol.io/ws" // Optional: Custom WebSocket URL
+      apiBaseUrl="https://api.pear.garden"
+      wsUrl="wss://api.pear.garden/ws"
+      clientId="your-app-name"
     >
-      <YourApp />
+      <TradingApp />
     </PearHyperliquidProvider>
   );
 }
 ```
 
-### 2. Use the Hooks
+### 2. Authentication
 
-#### Address Management
+Use the authentication hook to handle wallet connections:
 
 ```tsx
-import { useAddress } from '@pear-protocol/hyperliquid-sdk';
+import { usePearAuth } from '@pear-protocol/hyperliquid-sdk';
 
 function LoginComponent() {
-  const { address, setAddress, clearAddress, isLoggedIn } = useAddress();
-
-  return (
-    <div>
-      {isLoggedIn ? (
-        <div>
-          <p>Logged in as: {address}</p>
-          <button onClick={clearAddress}>Logout</button>
-        </div>
-      ) : (
-        <button onClick={() => setAddress('0x1234...')}>
-          Login
-        </button>
-      )}
-    </div>
-  );
+  const {
+    isAuthenticated,
+    getEip712,
+    loginWithSignedMessage,
+    logout
+  } = usePearAuth();
+
+  const handleWalletConnect = async (address: string, signMessage: Function) => {
+    try {
+      // Get EIP-712 message to sign
+      const messageData = await getEip712(address);
+
+      // Sign the message with user's wallet
+      const signature = await signMessage(messageData.message);
+
+      // Authenticate with Pear Protocol
+      await loginWithSignedMessage(address, signature, messageData.timestamp);
+    } catch (error) {
+      console.error('Authentication failed:', error);
+    }
+  };
+
+  if (isAuthenticated) {
+    return <button onClick={logout}>Logout</button>;
+  }
+
+  return <WalletConnectButton onConnect={handleWalletConnect} />;
 }
 ```
 
-#### Trading Data
+### 3. Trading Data
+
+Access real-time trading data with built-in hooks:
 
 ```tsx
-import { 
-  useTradeHistories, 
-  useOpenPositions, 
-  useOpenOrders, 
-  useAccountSummary 
+import {
+  useOpenPositions,
+  useOpenOrders,
+  useAccountSummary,
+  usePearHyperliquid
 } from '@pear-protocol/hyperliquid-sdk';
 
 function TradingDashboard() {
-  const tradeHistories = useTradeHistories();
-  const openPositions = useOpenPositions();
-  const openOrders = useOpenOrders();
-  const accountSummary = useAccountSummary();
+  const { address, setAddress } = usePearHyperliquid();
+  const { data: positions, isLoading: positionsLoading } = useOpenPositions();
+  const { data: orders, isLoading: ordersLoading } = useOpenOrders();
+  const { data: accountSummary } = useAccountSummary();
+
+  // Set the address to track
+  useEffect(() => {
+    if (userWalletAddress) {
+      setAddress(userWalletAddress);
+    }
+  }, [userWalletAddress, setAddress]);
+
+  if (positionsLoading) return <div>Loading positions...</div>;
 
   return (
     <div>
       <h2>Account Summary</h2>
-      {accountSummary && (
-        <div>
-          <p>Balance: {accountSummary.balance}</p>
-          <p>Margin Used: {accountSummary.marginUsed}</p>
-        </div>
-      )}
+      <div>Total Value: ${accountSummary?.accountValue?.toFixed(2)}</div>
 
       <h2>Open Positions</h2>
-      {openPositions?.map(position => (
+      {positions?.map((position) => (
         <div key={position.coin}>
-          <p>{position.coin}: {position.szi} @ {position.entryPx}</p>
+          {position.coin}: {position.szi} @ ${position.entryPx}
         </div>
       ))}
 
       <h2>Open Orders</h2>
-      {openOrders?.map(order => (
+      {orders?.map((order) => (
         <div key={order.oid}>
-          <p>{order.coin}: {order.sz} @ {order.limitPx}</p>
+          {order.coin}: {order.sz} @ ${order.limitPx}
         </div>
       ))}
     </div>
@@ -122,109 +137,291 @@ function TradingDashboard() {
 }
 ```
 
-## API Reference
+### 4. Position Management
+
+Create and manage trading positions:
+
+```tsx
+import { usePosition } from '@pear-protocol/hyperliquid-sdk';
+
+function PositionManager() {
+  const { createPosition, data: positions } = usePosition();
+
+  const handleCreatePosition = async () => {
+    try {
+      const result = await createPosition({
+        coin: 'ETH',
+        side: 'long',
+        size: 0.1,
+        leverage: 10,
+        orderType: 'market'
+      });
+      console.log('Position created:', result);
+    } catch (error) {
+      console.error('Failed to create position:', error);
+    }
+  };
 
-### Configuration
+  return (
+    <div>
+      <button onClick={handleCreatePosition}>
+        Open ETH Long Position
+      </button>
 
-```typescript
-interface PearHyperliquidConfig {
-  baseUrl: string;
-  timeout?: number;
-  headers?: Record<string, string>;
+      {positions?.map((position) => (
+        <PositionCard key={position.coin} position={position} />
+      ))}
+    </div>
+  );
 }
 ```
 
-### Hooks
+### 5. Agent Wallets
 
-#### `useAddress()`
-Manages user address and login state.
+Manage automated trading wallets:
 
-**Returns:**
-- `address: string | null` - Current user address
-- `setAddress: (address: string | null) => void` - Set user address
-- `clearAddress: () => void` - Clear current address
-- `isLoggedIn: boolean` - Whether user is logged in
+```tsx
+import { usePearAgentWallet } from '@pear-protocol/hyperliquid-sdk';
+
+function AgentWalletManager() {
+  const {
+    agentWallet,
+    isReady,
+    loading,
+    createAgentWallet,
+    refreshAgentWalletStatus
+  } = usePearAgentWallet();
+
+  const handleCreateWallet = async () => {
+    try {
+      await createAgentWallet();
+      console.log('Agent wallet created successfully');
+    } catch (error) {
+      console.error('Failed to create agent wallet:', error);
+    }
+  };
+
+  if (loading) return <div>Loading agent wallet...</div>;
+
+  if (!agentWallet.exists) {
+    return (
+      <button onClick={handleCreateWallet}>
+        Create Agent Wallet
+      </button>
+    );
+  }
 
-#### `useTradeHistories()`
-Returns paginated trade history data from WebSocket.
+  return (
+    <div>
+      <h3>Agent Wallet</h3>
+      <div>Address: {agentWallet.address}</div>
+      <div>Status: {agentWallet.status}</div>
+      <button onClick={refreshAgentWalletStatus}>
+        Refresh Status
+      </button>
+    </div>
+  );
+}
+```
 
-#### `useOpenPositions()`
-Returns array of current open positions from WebSocket.
+## Advanced Usage
 
-#### `useOpenOrders()`
-Returns array of current open orders from WebSocket.
+### WebSocket Connections
 
-#### `useAccountSummary()`
-Returns account summary including balance and margin information.
+The SDK automatically manages WebSocket connections for real-time data:
 
-### Client Methods
+```tsx
+import { useHyperliquidWebSocket, useHyperliquidNativeWebSocket } from '@pear-protocol/hyperliquid-sdk';
 
-The `PearHyperliquidClient` provides methods for:
-- `syncTradeHistories(data: SyncTradeHistoryDto)` - Sync trade history
-- `syncOpenPositions(data: SyncOpenPositionDto)` - Sync open positions  
-- `syncOpenOrders(data: SyncOpenOrderDto)` - Sync open orders
+function WebSocketStatus() {
+  const { isConnected, lastError } = useHyperliquidWebSocket({
+    wsUrl: 'wss://api.pear.garden/ws',
+    address: userAddress
+  });
 
-### WebSocket Channels
+  const {
+    isConnected: nativeConnected
+  } = useHyperliquidNativeWebSocket({
+    address: userAddress
+  });
 
-The SDK automatically subscribes to these channels when an address is set:
-- `trade-histories` - Real-time trade history updates
-- `open-positions` - Real-time position updates
-- `open-orders` - Real-time order updates
-- `account-summary` - Real-time account summary updates
+  return (
+    <div>
+      <div>Pear API: {isConnected ? 'Connected' : 'Disconnected'}</div>
+      <div>Hyperliquid: {nativeConnected ? 'Connected' : 'Disconnected'}</div>
+      {lastError && <div>Error: {lastError}</div>}
+    </div>
+  );
+}
+```
 
-## TypeScript Support
+### Historical Data
 
-The SDK includes comprehensive TypeScript definitions for all data structures:
+Access historical price data and performance metrics:
 
-```typescript
-import type {
-  PearHyperliquidConfig,
-  TradeHistoryV1Dto,
-  OpenPositionDto,
-  OpenLimitOrderDto,
-  AccountSummaryResponseDto,
-  // ... and many more
+```tsx
+import {
+  useHistoricalPriceData,
+  useBasketCandles,
+  useHistoricalPriceDataStore
 } from '@pear-protocol/hyperliquid-sdk';
-```
 
-## Error Handling
+function ChartComponent() {
+  const { data: priceData } = useHistoricalPriceData({
+    tokens: ['ETH', 'BTC'],
+    range: '1D'
+  });
 
-The SDK provides structured error handling:
+  const { data: candleData } = useBasketCandles({
+    tokens: [{ symbol: 'ETH', weight: 0.6 }, { symbol: 'BTC', weight: 0.4 }],
+    interval: '1h',
+    startTime: Date.now() - 24 * 60 * 60 * 1000
+  });
 
-```typescript
-try {
-  await client.syncTradeHistories(data);
-} catch (error) {
-  // Error is typed as ApiErrorResponse
-  console.error(`API Error ${error.statusCode}: ${error.message}`);
+  return (
+    <div>
+      {/* Render your charts here */}
+    </div>
+  );
 }
 ```
 
-## Requirements
+### Utilities
+
+The SDK includes utility functions for calculations and data processing:
+
+```tsx
+import {
+  AccountSummaryCalculator,
+  ConflictDetector,
+  TokenMetadataExtractor,
+  calculateWeightedRatio
+} from '@pear-protocol/hyperliquid-sdk';
 
-- React >= 16.8.0
-- Node.js >= 16.0.0
+// Calculate account metrics
+const calculator = new AccountSummaryCalculator(positions, marketData);
+const accountValue = calculator.getTotalAccountValue();
 
-## Development
+// Detect token conflicts
+const detector = new ConflictDetector();
+const conflicts = detector.detectConflicts(tokenSelections);
 
-```bash
-# Install dependencies
-npm install
+// Extract token metadata
+const extractor = new TokenMetadataExtractor();
+const metadata = extractor.extractMetadata(tokenData);
+```
+
+## Configuration
+
+### Environment Setup
+
+The SDK supports different environments through configuration:
+
+```tsx
+// Development
+<PearHyperliquidProvider
+  apiBaseUrl="http://localhost:3000"
+  wsUrl="ws://localhost:3000/ws"
+>
+
+// Production
+<PearHyperliquidProvider
+  apiBaseUrl="https://api.pear.garden"
+  wsUrl="wss://api.pear.garden/ws"
+>
+
+// Beta
+<PearHyperliquidProvider
+  apiBaseUrl="https://beta-api.pear.garden"
+  wsUrl="wss://beta-api.pear.garden/ws"
+>
+```
+
+### Authentication Methods
 
-# Build the package
-npm run build
+The SDK supports multiple authentication methods:
 
-# Run in development mode (watch)
-npm run dev
+```tsx
+// EIP-712 signature (recommended)
+await loginWithSignedMessage(address, signature, timestamp);
 
-# Type check
-npm run type-check
+// Privy integration
+await loginWithPrivyToken(address, appId, privyAccessToken);
 ```
 
+## API Reference
+
+### Core Hooks
+
+- `usePearHyperliquid()` - Access the main context
+- `usePearAuth()` - Authentication state and methods
+- `usePearAgentWallet()` - Agent wallet management
+
+### Trading Hooks
+
+- `useOpenPositions()` - Get open positions with real-time updates
+- `useOpenOrders()` - Get open orders
+- `useAccountSummary()` - Account summary with calculated metrics
+- `useTradeHistories()` - Historical trade data
+- `usePosition()` - Position management operations
+
+### Data Hooks
+
+- `useWebData()` - Market data from Hyperliquid
+- `useHistoricalPriceData()` - Historical price charts
+- `useBasketCandles()` - Basket/portfolio candle data
+- `useTokenSelectionMetadata()` - Token metadata and conflicts
+
+### WebSocket Hooks
+
+- `useHyperliquidWebSocket()` - Pear API WebSocket connection
+- `useHyperliquidNativeWebSocket()` - Direct Hyperliquid WebSocket
+
+## TypeScript Support
+
+The SDK is fully typed with TypeScript. All hooks, utilities, and data structures include comprehensive type definitions:
+
+```tsx
+import type {
+  OpenPositionDto,
+  AccountSummaryResponseDto,
+  AgentWalletState,
+  WebSocketConnectionState,
+  CandleData
+} from '@pear-protocol/hyperliquid-sdk';
+```
+
+## Error Handling
+
+The SDK provides comprehensive error handling:
+
+```tsx
+const { error, authError } = usePearAuth();
+const { agentWalletError } = usePearAgentWallet();
+const { lastError } = useHyperliquidWebSocket();
+
+// Handle authentication errors
+if (authError) {
+  console.error('Auth failed:', authError);
+}
+
+// Handle connection errors
+if (lastError) {
+  console.error('WebSocket error:', lastError);
+}
+```
+
+## Contributing
+
+This SDK is part of the Pear Protocol ecosystem. For issues, feature requests, or contributions, please visit the [GitHub repository](https://github.com/pear-protocol/hyperliquid).
+
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+MIT License - see LICENSE file for details.
 
 ## Support
 
-For questions and support, please contact the Pear Protocol team.
+For technical support and questions:
+- GitHub Issues: [pear-protocol/hyperliquid](https://github.com/pear-protocol/hyperliquid/issues)
+- Documentation: [docs.pear.garden](https://docs.pear.garden)
+- Discord: [Pear Protocol Community](https://discord.gg/pear-protocol)

package/dist/client.d.ts

@@ -1,52 +1,36 @@
-import { PearHyperliquidConfig, ApiResponse, SyncTradeHistoryDto, SyncTradeHistoryResponseDto, SyncOpenPositionDto, SyncOpenPositionResponseDto, SyncOpenOrderDto, SyncOpenOrderResponseDto, CandleData, CandleInterval } from './types';
+import { ApiResponse, CandleInterval, CandleData, SyncFillsRequestDto, SyncFillsResponseDto, ExternalFillDto, GetEIP712MessageResponse, AuthenticateRequest, AuthenticateResponse, RefreshTokenResponse, LogoutResponse, GetAgentWalletResponseDto, CreateAgentWalletResponseDto } from "./types";
 /**
- * Main SDK client for Pear Protocol Hyperliquid API integration
+   * Fetch historical candle data from HyperLiquid API
+   * @param coin - Token symbol (e.g., 'BTC', 'ETH')
+   * @param startTime - Start time in milliseconds
+   * @param endTime - End time in milliseconds
+   * @param interval - Candle interval
+   * @returns Promise with historical candle data
+   */
+export declare const fetchHistoricalCandles: (coin: string, startTime: number, endTime: number, interval: CandleInterval) => Promise<ApiResponse<CandleData[]>>;
+/**
+ * Retrieve recent fills for a user from HyperLiquid and map to ExternalFillDto[]
+ * @param user - EVM address (0x...)
+ * @param aggregateByTime - Combine partial fills for the same crossing order
+ */
+export declare const fetchUserFillsFromHyperliquid: (user: string, aggregateByTime?: boolean) => Promise<ApiResponse<ExternalFillDto[]>>;
+/**
+ * Convenience: fetch user fills from HyperLiquid, then sync them to Pear backend
+ * Returns the Pear backend SyncFillsResponseDto
+ */
+export declare const syncUserFillsFromHyperliquid: (baseUrl: string, accessToken: string, user: string, aggregateByTime?: boolean) => Promise<ApiResponse<SyncFillsResponseDto>>;
+export declare function getEIP712Message(baseUrl: string, address: string, clientId: string): Promise<ApiResponse<GetEIP712MessageResponse>>;
+export declare function authenticate(baseUrl: string, body: AuthenticateRequest): Promise<ApiResponse<AuthenticateResponse>>;
+export declare function refreshToken(baseUrl: string, refreshTokenVal: string): Promise<ApiResponse<RefreshTokenResponse>>;
+export declare function logout(baseUrl: string, refreshTokenVal: string): Promise<ApiResponse<LogoutResponse>>;
+export declare function getAgentWallet(baseUrl: string, accessToken: string): Promise<ApiResponse<GetAgentWalletResponseDto>>;
+export declare function createAgentWallet(baseUrl: string, accessToken: string): Promise<ApiResponse<CreateAgentWalletResponseDto>>;
+/**
+ * Sync external fills into Pear Hyperliquid service
+ * Mirrors POST /sync/fills in pear-hyperliquid service
+ * @param baseUrl - Base URL of Pear Hyperliquid API (e.g., 'http://localhost:3000')
+ * @param accessToken - Bearer access token for Authorization header
+ * @param payload - Sync fills request body
+ * @returns Promise with sync result summary
  */
-export declare class PearHyperliquidClient {
-    private httpClient;
-    private baseUrl;
-    constructor(config: PearHyperliquidConfig);
-    /**
-     * Get the configured base URL
-     */
-    getBaseUrl(): string;
-    /**
-     * Update request headers
-     */
-    setHeaders(headers: Record<string, string>): void;
-    /**
-     * Set authorization header
-     */
-    setAuthToken(token: string): void;
-    /**
-     * Make a generic HTTP request
-     */
-    private makeRequest;
-    /**
-     * Sync trade history data from old database structure to new database format
-     * @param payload - Trade history data with user address
-     * @returns Promise with sync result
-     */
-    syncTradeHistory(payload: SyncTradeHistoryDto): Promise<ApiResponse<SyncTradeHistoryResponseDto>>;
-    /**
-     * Sync open positions data from old database structure to new database format
-     * @param payload - Open positions data with user address
-     * @returns Promise with sync result
-     */
-    syncOpenPositions(payload: SyncOpenPositionDto): Promise<ApiResponse<SyncOpenPositionResponseDto>>;
-    /**
-     * Sync open orders data from old database structure to new database format
-     * @param payload - Open orders data with user address
-     * @returns Promise with sync result
-     */
-    syncOpenOrders(payload: SyncOpenOrderDto): Promise<ApiResponse<SyncOpenOrderResponseDto>>;
-    /**
-     * Fetch historical candle data from HyperLiquid API
-     * @param coin - Token symbol (e.g., 'BTC', 'ETH')
-     * @param startTime - Start time in milliseconds
-     * @param endTime - End time in milliseconds
-     * @param interval - Candle interval
-     * @returns Promise with historical candle data
-     */
-    fetchHistoricalCandles(coin: string, startTime: number, endTime: number, interval: CandleInterval): Promise<ApiResponse<CandleData[]>>;
-}
+export declare const syncFills: (baseUrl: string, accessToken: string, payload: SyncFillsRequestDto) => Promise<ApiResponse<SyncFillsResponseDto>>;

package/dist/clients/agentWallet.d.ts

@@ -0,0 +1,3 @@
+import type { ApiResponse, GetAgentWalletResponseDto, CreateAgentWalletResponseDto } from '../types';
+export declare function getAgentWallet(baseUrl: string, accessToken: string): Promise<ApiResponse<GetAgentWalletResponseDto>>;
+export declare function createAgentWallet(baseUrl: string, accessToken: string): Promise<ApiResponse<CreateAgentWalletResponseDto>>;

package/dist/clients/auth.d.ts

@@ -0,0 +1,14 @@
+import type { ApiResponse, GetEIP712MessageResponse, AuthenticateRequest, AuthenticateResponse, RefreshTokenResponse, LogoutResponse } from '../types';
+export declare function getEIP712Message(baseUrl: string, address: string, clientId: string): Promise<ApiResponse<GetEIP712MessageResponse>>;
+export declare function authenticate(baseUrl: string, body: AuthenticateRequest): Promise<ApiResponse<AuthenticateResponse>>;
+/**
+ * Convenience wrapper for Privy access token authentication
+ */
+export declare function authenticateWithPrivy(baseUrl: string, params: {
+    address: string;
+    clientId: string;
+    appId: string;
+    accessToken: string;
+}): Promise<ApiResponse<AuthenticateResponse>>;
+export declare function refreshToken(baseUrl: string, refreshTokenVal: string): Promise<ApiResponse<RefreshTokenResponse>>;
+export declare function logout(baseUrl: string, refreshTokenVal: string): Promise<ApiResponse<LogoutResponse>>;

package/dist/clients/hyperliquid.d.ts

@@ -0,0 +1,9 @@
+import type { ApiResponse, CandleInterval, CandleData, ExternalFillDto } from '../types';
+/**
+ * Fetch historical candle data from HyperLiquid API
+ */
+export declare const fetchHistoricalCandles: (coin: string, startTime: number, endTime: number, interval: CandleInterval) => Promise<ApiResponse<CandleData[]>>;
+/**
+ * Retrieve recent user fills from HyperLiquid and map to ExternalFillDto[]
+ */
+export declare const fetchUserFillsFromHyperliquid: (user: string, aggregateByTime?: boolean) => Promise<ApiResponse<ExternalFillDto[]>>;