@pear-protocol/hyperliquid-sdk 0.0.41 → 0.0.43

package/README.md

@@ -1,15 +1,18 @@
-# @pear-protocol/hyperliquid-sdk
+# Pear Hyperliquid SDK
 
-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.
+A comprehensive React SDK for integrating with the Pear Protocol Hyperliquid API. This SDK provides a complete toolkit for building trading applications with real-time WebSocket data, authentication, position management, order execution, and market data access.
 
 ## Features
 
-- **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
+- **React Context Provider** - Easy integration with React applications
+- **Real-time WebSocket Connections** - Dual WebSocket support (Pear API + HyperLiquid native)
+- **Authentication** - EIP-712 signature and Privy token authentication
+- **Position Management** - Create, adjust, and close trading positions
+- **Order Management** - Place, modify, and cancel orders (MARKET, LIMIT, TWAP, TP/SL)
+- **Market Data** - Access real-time price feeds, asset information, and candle data
+- **Agent Wallet** - Manage agent wallet creation and status
+- **TypeScript** - Full type safety with comprehensive type definitions
+- **Zustand State Management** - Efficient state management for market and user data
 
 ## Installation
 
@@ -21,17 +24,17 @@ yarn add @pear-protocol/hyperliquid-sdk
 
 ### Peer Dependencies
 
-This package requires React 18+ as a peer dependency:
+This SDK requires React 18 or higher:
 
 ```bash
 npm install react react-dom
+# or
+yarn add react react-dom
 ```
 
 ## Quick Start
 
-### 1. Provider Setup
-
-Wrap your application with the `PearHyperliquidProvider`:
+### 1. Wrap your application with the Provider
 
 ```tsx
 import { PearHyperliquidProvider } from '@pear-protocol/hyperliquid-sdk';
@@ -39,389 +42,681 @@ import { PearHyperliquidProvider } from '@pear-protocol/hyperliquid-sdk';
 function App() {
   return (
     <PearHyperliquidProvider
-      apiBaseUrl="https://api.pear.garden"
-      wsUrl="wss://api.pear.garden/ws"
-      clientId="your-app-name"
+      apiBaseUrl="https://hl-v2.pearprotocol.io"
+      wsUrl="wss://hl-v2.pearprotocol.io/ws"
+      clientId="YOUR_CLIENT_ID"
     >
-      <TradingApp />
+      <YourApp />
     </PearHyperliquidProvider>
   );
 }
 ```
 
-### 2. Authentication
+### 2. Use hooks in your components
+
+```tsx
+import {
+  usePearAuth,
+  usePearHyperliquid,
+  usePosition,
+  useOrders
+} from '@pear-protocol/hyperliquid-sdk';
+
+function TradingComponent() {
+  const { address, setAddress } = usePearHyperliquid();
+  const { isAuthenticated, loginWithSignedMessage } = usePearAuth();
+  const { openPositions, createPosition } = usePosition();
+  const { openOrders, cancelOrder } = useOrders();
+
+  // Your component logic
+}
+```
+
+## Core Concepts
+
+### Provider Configuration
+
+The `PearHyperliquidProvider` accepts the following props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiBaseUrl` | `string` | `https://hl-v2.pearprotocol.io` | Pear API base URL |
+| `wsUrl` | `string` | `wss://hl-v2.pearprotocol.io/ws` | Pear WebSocket URL |
+| `clientId` | `string` | `PEARPROTOCOLUI` | Client identifier for authentication |
 
-Use the authentication hook to handle wallet connections:
+### Authentication
+
+The SDK supports two authentication methods:
+
+#### EIP-712 Signature Authentication
 
 ```tsx
 import { usePearAuth } from '@pear-protocol/hyperliquid-sdk';
 
 function LoginComponent() {
-  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);
+  const { getEip712, loginWithSignedMessage, isAuthenticated } = usePearAuth();
 
-      // Sign the message with user's wallet
-      const signature = await signMessage(messageData.message);
+  const handleLogin = async (address: string, signer: any) => {
+    // Get EIP-712 message
+    const eip712Data = await getEip712(address);
 
-      // Authenticate with Pear Protocol
-      await loginWithSignedMessage(address, signature, messageData.timestamp);
-    } catch (error) {
-      console.error('Authentication failed:', error);
-    }
+    // Sign with wallet
+    const signature = await signer.signTypedData(
+      eip712Data.domain,
+      eip712Data.types,
+      eip712Data.message
+    );
+
+    // Authenticate
+    await loginWithSignedMessage(address, signature, eip712Data.timestamp);
   };
 
-  if (isAuthenticated) {
-    return <button onClick={logout}>Logout</button>;
-  }
+  return (
+    <div>
+      {isAuthenticated ? 'Logged In' : 'Logged Out'}
+    </div>
+  );
+}
+```
+
+#### Privy Token Authentication
 
-  return <WalletConnectButton onConnect={handleWalletConnect} />;
+```tsx
+import { usePearAuth } from '@pear-protocol/hyperliquid-sdk';
+
+function PrivyLoginComponent() {
+  const { loginWithPrivyToken, isAuthenticated } = usePearAuth();
+
+  const handlePrivyLogin = async (address: string, appId: string, accessToken: string) => {
+    await loginWithPrivyToken(address, appId, accessToken);
+  };
 }
 ```
 
-### 3. Trading Data
+## API Reference
+
+### Hooks
+
+#### Core Hooks
 
-Access real-time trading data with built-in hooks:
+##### `usePearHyperliquid()`
+
+Access the entire SDK context. Prefer using more specific hooks when possible.
 
 ```tsx
-import {
-  useOpenPositions,
-  useOpenOrders,
-  useAccountSummary,
-  usePearHyperliquid
-} from '@pear-protocol/hyperliquid-sdk';
+const {
+  apiBaseUrl,
+  wsUrl,
+  address,
+  setAddress,
+  connectionStatus,
+  isConnected,
+  nativeConnectionStatus,
+  nativeIsConnected,
+  authStatus,
+  isAuthenticated,
+  accessToken,
+  user,
+  // ... and more
+} = usePearHyperliquid();
+```
 
-function TradingDashboard() {
-  const { address, setAddress } = usePearHyperliquid();
-  const { data: positions, isLoading: positionsLoading } = useOpenPositions();
-  const { data: orders, isLoading: ordersLoading } = useOpenOrders();
-  const { data: accountSummary } = useAccountSummary();
+##### `usePearAuth()`
 
-  // Set the address to track
-  useEffect(() => {
-    if (userWalletAddress) {
-      setAddress(userWalletAddress);
-    }
-  }, [userWalletAddress, setAddress]);
+Authentication state and actions.
 
-  if (positionsLoading) return <div>Loading positions...</div>;
+```tsx
+const {
+  status,           // AuthStatus enum
+  isAuthenticated,  // boolean
+  user,             // UserProfile | null
+  error,            // string | null
+  getEip712,        // (address: string) => Promise<EIP712MessageResponse>
+  loginWithSignedMessage, // (address, signature, timestamp) => Promise<void>
+  loginWithPrivyToken,    // (address, appId, accessToken) => Promise<void>
+  refreshTokens,    // () => Promise<any>
+  logout,           // () => Promise<void>
+} = usePearAuth();
+```
 
-  return (
-    <div>
-      <h2>Account Summary</h2>
-      <div>Total Value: ${accountSummary?.accountValue?.toFixed(2)}</div>
+##### `usePearAgentWallet()`
 
-      <h2>Open Positions</h2>
-      {positions?.map((position) => (
-        <div key={position.coin}>
-          {position.coin}: {position.szi} @ ${position.entryPx}
-        </div>
-      ))}
+Agent wallet management.
 
-      <h2>Open Orders</h2>
-      {orders?.map((order) => (
-        <div key={order.oid}>
-          {order.coin}: {order.sz} @ ${order.limitPx}
-        </div>
-      ))}
-    </div>
-  );
-}
+```tsx
+const {
+  agentWallet,              // AgentWalletState
+  isReady,                  // boolean
+  loading,                  // boolean
+  error,                    // string | null
+  refreshAgentWalletStatus, // () => Promise<any>
+  createAgentWallet,        // () => Promise<any>
+  notifyAgentWalletApproved, // () => Promise<any>
+} = usePearAgentWallet();
 ```
 
-### 4. Position Management
+#### Position Management
 
-Create and manage trading positions:
+##### `usePosition()`
+
+Manage trading positions.
 
 ```tsx
-import { usePosition } from '@pear-protocol/hyperliquid-sdk';
+const {
+  createPosition,        // (payload) => Promise<ApiResponse<CreatePositionResponseDto>>
+  updateRiskParameters,  // (positionId, payload) => Promise<ApiResponse<UpdateRiskParametersResponseDto>>
+  closePosition,         // (positionId, payload) => Promise<ApiResponse<ClosePositionResponseDto>>
+  closeAllPositions,     // (payload) => Promise<ApiResponse<CloseAllPositionsResponseDto>>
+  adjustPosition,        // (positionId, payload) => Promise<ApiResponse<AdjustPositionResponseDto>>
+  openPositions,         // OpenPositionDto[] | null
+  isLoading,             // boolean
+} = usePosition();
+```
 
-function PositionManager() {
-  const { createPosition, data: positions } = usePosition();
+**Example: Create a Position**
 
-  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);
-    }
-  };
+```tsx
+const { createPosition } = usePosition();
+
+const handleCreatePosition = async () => {
+  try {
+    const response = await createPosition({
+      leverage: 5,
+      usdValue: 1000,
+      longAssets: [{ asset: 'ETH', weight: 1 }],
+      shortAssets: [{ asset: 'BTC', weight: 1 }],
+      orderType: 'MARKET',
+    });
+    console.log('Position created:', response.data);
+  } catch (error) {
+    console.error('Failed to create position:', error);
+  }
+};
+```
 
-  return (
-    <div>
-      <button onClick={handleCreatePosition}>
-        Open ETH Long Position
-      </button>
+**Example: Close a Position**
 
-      {positions?.map((position) => (
-        <PositionCard key={position.coin} position={position} />
-      ))}
-    </div>
-  );
-}
+```tsx
+const { closePosition } = usePosition();
+
+const handleClosePosition = async (positionId: string) => {
+  try {
+    const response = await closePosition(positionId, {
+      orderType: 'MARKET',
+    });
+    console.log('Position closed:', response.data);
+  } catch (error) {
+    console.error('Failed to close position:', error);
+  }
+};
 ```
 
-### 5. Agent Wallets
+#### Order Management
+
+##### `useOrders()`
 
-Manage automated trading wallets:
+Manage orders (LIMIT, TP/SL, TWAP).
 
 ```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);
-    }
-  };
+const {
+  adjustOrder,      // (orderId, payload) => Promise<ApiResponse<AdjustOrderResponseDto>>
+  cancelOrder,      // (orderId) => Promise<ApiResponse<CancelOrderResponseDto>>
+  cancelTwapOrder,  // (orderId) => Promise<ApiResponse<CancelTwapResponseDto>>
+  openOrders,       // OpenLimitOrderDto[] | null
+  isLoading,        // boolean
+} = useOrders();
+```
 
-  if (loading) return <div>Loading agent wallet...</div>;
+**Example: Cancel an Order**
 
-  if (!agentWallet.exists) {
-    return (
-      <button onClick={handleCreateWallet}>
-        Create Agent Wallet
-      </button>
-    );
+```tsx
+const { cancelOrder } = useOrders();
+
+const handleCancelOrder = async (orderId: string) => {
+  try {
+    await cancelOrder(orderId);
+    console.log('Order cancelled successfully');
+  } catch (error) {
+    console.error('Failed to cancel order:', error);
   }
+};
+```
 
-  return (
-    <div>
-      <h3>Agent Wallet</h3>
-      <div>Address: {agentWallet.address}</div>
-      <div>Status: {agentWallet.status}</div>
-      <button onClick={refreshAgentWalletStatus}>
-        Refresh Status
-      </button>
-    </div>
-  );
-}
+#### Trading Data
+
+##### `useTradeHistories()`
+
+Access trade history data.
+
+```tsx
+const { data, isLoading } = useTradeHistories();
 ```
 
-## Advanced Usage
+##### `useOpenOrders()`
 
-### WebSocket Connections
+Access open orders with loading state.
+
+```tsx
+const { data, isLoading } = useOpenOrders();
+```
 
-The SDK automatically manages WebSocket connections for real-time data:
+##### `useAccountSummary()`
+
+Access account summary with real-time calculations.
 
 ```tsx
-import { useHyperliquidWebSocket, useHyperliquidNativeWebSocket } from '@pear-protocol/hyperliquid-sdk';
+const { data, isLoading } = useAccountSummary();
+// data: AccountSummaryResponseDto | null
+```
 
-function WebSocketStatus() {
-  const { isConnected, lastError } = useHyperliquidWebSocket({
-    wsUrl: 'wss://api.pear.garden/ws',
-    address: userAddress
-  });
+#### Market Data
 
-  const {
-    isConnected: nativeConnected
-  } = useHyperliquidNativeWebSocket({
-    address: userAddress
-  });
+##### `useMarketData()`
+
+Access real-time market data from Zustand store.
+
+```tsx
+import { useMarketData } from '@pear-protocol/hyperliquid-sdk';
+
+function MarketDataComponent() {
+  const activeAssets = useMarketData((state) => state.activeAssets);
 
   return (
     <div>
-      <div>Pear API: {isConnected ? 'Connected' : 'Disconnected'}</div>
-      <div>Hyperliquid: {nativeConnected ? 'Connected' : 'Disconnected'}</div>
-      {lastError && <div>Error: {lastError}</div>}
+      {activeAssets?.active.map((asset, idx) => (
+        <div key={idx}>
+          Long: {asset.longAssets.map(a => a.asset).join(', ')} vs
+          Short: {asset.shortAssets.map(a => a.asset).join(', ')}
+        </div>
+      ))}
     </div>
   );
 }
 ```
 
-### Historical Data
+##### `useHistoricalPriceData()`
 
-Access historical price data and performance metrics:
+Fetch and manage historical price data for tokens.
 
 ```tsx
-import {
-  useHistoricalPriceData,
-  useBasketCandles,
-  useHistoricalPriceDataStore
-} from '@pear-protocol/hyperliquid-sdk';
+import { useHistoricalPriceData } from '@pear-protocol/hyperliquid-sdk';
 
 function ChartComponent() {
-  const { data: priceData } = useHistoricalPriceData({
-    tokens: ['ETH', 'BTC'],
-    range: '1D'
-  });
+  const { fetchHistoricalData, getTokenData } = useHistoricalPriceData();
+
+  useEffect(() => {
+    fetchHistoricalData('ETH', '1d'); // 1 day range
+  }, []);
+
+  const ethData = getTokenData('ETH');
+}
+```
+
+##### `useBasketCandles()`
+
+Get candle data for basket (multi-asset) positions.
+
+```tsx
+import { useBasketCandles } from '@pear-protocol/hyperliquid-sdk';
 
-  const { data: candleData } = useBasketCandles({
-    tokens: [{ symbol: 'ETH', weight: 0.6 }, { symbol: 'BTC', weight: 0.4 }],
+function BasketChartComponent() {
+  const { candles, isLoading, error } = useBasketCandles({
+    longAssets: [{ symbol: 'ETH', weight: 0.5 }, { symbol: 'BTC', weight: 0.5 }],
+    shortAssets: [{ symbol: 'SOL', weight: 1 }],
     interval: '1h',
-    startTime: Date.now() - 24 * 60 * 60 * 1000
+    lookbackHours: 24,
   });
+}
+```
+
+##### `useTokenSelectionMetadata()`
+
+Get metadata for selected tokens including prices, funding, and leverage info.
+
+```tsx
+import { useTokenSelectionMetadata } from '@pear-protocol/hyperliquid-sdk';
+
+function TokenSelector() {
+  const { getMetadata, isLoading } = useTokenSelectionMetadata();
+
+  const ethMetadata = getMetadata('ETH');
+  // ethMetadata: { currentPrice, priceChange24hPercent, maxLeverage, ... }
+}
+```
+
+#### WebSocket Hooks
+
+##### `useHyperliquidWebSocket()`
+
+Access Pear API WebSocket connection (managed by provider).
+
+##### `useHyperliquidNativeWebSocket()`
+
+Access HyperLiquid native WebSocket connection (managed by provider).
+
+#### TWAP Orders
+
+##### `useTwap()`
+
+Access TWAP (Time-Weighted Average Price) order monitoring.
+
+```tsx
+import { useTwap } from '@pear-protocol/hyperliquid-sdk';
+
+function TwapMonitor() {
+  const { twapOrders, isLoading } = useTwap();
 
   return (
     <div>
-      {/* Render your charts here */}
+      {twapOrders?.map(order => (
+        <div key={order.orderId}>
+          Status: {order.status}
+          Progress: {order.filledUsdValue / order.totalUsdValue * 100}%
+        </div>
+      ))}
     </div>
   );
 }
 ```
 
-### Utilities
+#### Notifications
 
-The SDK includes utility functions for calculations and data processing:
+##### `useNotifications()`
 
-```tsx
-import {
-  AccountSummaryCalculator,
-  ConflictDetector,
-  TokenMetadataExtractor,
-  calculateWeightedRatio
-} from '@pear-protocol/hyperliquid-sdk';
+Access user notifications.
 
-// Calculate account metrics
-const calculator = new AccountSummaryCalculator(positions, marketData);
-const accountValue = calculator.getTotalAccountValue();
+```tsx
+import { useNotifications } from '@pear-protocol/hyperliquid-sdk';
 
-// Detect token conflicts
-const detector = new ConflictDetector();
-const conflicts = detector.detectConflicts(tokenSelections);
+function NotificationCenter() {
+  const { notifications, isLoading, markAsRead, markAllAsRead } = useNotifications();
 
-// Extract token metadata
-const extractor = new TokenMetadataExtractor();
-const metadata = extractor.extractMetadata(tokenData);
+  return (
+    <div>
+      {notifications?.map(notif => (
+        <div key={notif.id} onClick={() => markAsRead(notif.id)}>
+          {notif.category}: {JSON.stringify(notif.parameters)}
+        </div>
+      ))}
+    </div>
+  );
+}
 ```
 
-## Configuration
+### Utility Classes
 
-### Environment Setup
+#### `AccountSummaryCalculator`
 
-The SDK supports different environments through configuration:
+Calculate account summary with real-time data.
 
 ```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"
->
+import { AccountSummaryCalculator } from '@pear-protocol/hyperliquid-sdk';
+
+const calculator = new AccountSummaryCalculator(webData2);
+const summary = calculator.calculateAccountSummary(
+  accountSummary,
+  openOrders,
+  agentWalletAddress,
+  agentWalletStatus
+);
 ```
 
-### Authentication Methods
+#### `ConflictDetector`
 
-The SDK supports multiple authentication methods:
+Detect position conflicts for new trades.
 
 ```tsx
-// EIP-712 signature (recommended)
-await loginWithSignedMessage(address, signature, timestamp);
+import { ConflictDetector } from '@pear-protocol/hyperliquid-sdk';
 
-// Privy integration
-await loginWithPrivyToken(address, appId, privyAccessToken);
+const conflicts = ConflictDetector.detectConflicts(
+  longTokens,
+  shortTokens,
+  existingPositions
+);
 ```
 
-## API Reference
-
-### Core Hooks
+#### `TokenMetadataExtractor`
 
-- `usePearHyperliquid()` - Access the main context
-- `usePearAuth()` - Authentication state and methods
-- `usePearAgentWallet()` - Agent wallet management
+Extract token metadata from WebSocket data.
 
-### 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
+```tsx
+import { TokenMetadataExtractor } from '@pear-protocol/hyperliquid-sdk';
+
+const metadata = TokenMetadataExtractor.extractMetadata(
+  'ETH',
+  webData2,
+  allMids,
+  activeAssetData
+);
+```
 
-### Data Hooks
+### Direct API Clients
 
-- `useWebData()` - Market data from Hyperliquid
-- `useHistoricalPriceData()` - Historical price charts
-- `useBasketCandles()` - Basket/portfolio candle data
-- `useTokenSelectionMetadata()` - Token metadata and conflicts
+For advanced use cases, you can import and use API clients directly:
 
-### WebSocket Hooks
+```tsx
+import {
+  createPosition,
+  updateRiskParameters,
+  closePosition,
+  adjustOrder,
+  cancelOrder,
+} from '@pear-protocol/hyperliquid-sdk';
 
-- `useHyperliquidWebSocket()` - Pear API WebSocket connection
-- `useHyperliquidNativeWebSocket()` - Direct Hyperliquid WebSocket
+// All client functions require baseUrl and accessToken
+const response = await createPosition(baseUrl, accessToken, {
+  leverage: 5,
+  usdValue: 1000,
+  longAssets: [{ asset: 'ETH', weight: 1 }],
+  shortAssets: [{ asset: 'BTC', weight: 1 }],
+  orderType: 'MARKET',
+});
+```
 
 ## TypeScript Support
 
-The SDK is fully typed with TypeScript. All hooks, utilities, and data structures include comprehensive type definitions:
+The SDK is written in TypeScript and provides comprehensive type definitions. All hooks, functions, and data structures are fully typed.
 
 ```tsx
 import type {
   OpenPositionDto,
+  OpenLimitOrderDto,
+  TradeHistoryDataDto,
   AccountSummaryResponseDto,
-  AgentWalletState,
-  WebSocketConnectionState,
-  CandleData
+  WebSocketChannel,
+  CandleInterval,
+  TokenMetadata,
+  // ... and many more
 } from '@pear-protocol/hyperliquid-sdk';
 ```
 
+## WebSocket Data Flow
+
+The SDK manages two WebSocket connections:
+
+1. **Pear API WebSocket** - User-specific data (positions, orders, trade history, account summary)
+2. **HyperLiquid Native WebSocket** - Market data (prices, asset info, candles)
+
+Data is automatically stored in Zustand stores and accessible via hooks:
+
+- `useUserData` store - User positions, orders, and account data
+- `useHyperliquidData` store - Market data (webData2, allMids, activeAssetData)
+- `useHistoricalPriceDataStore` - Historical price data
+- `useMarketData` store - Active assets and market overview
+
 ## Error Handling
 
-The SDK provides comprehensive error handling:
+All API functions return promises and throw errors on failure. Always wrap API calls in try-catch blocks:
 
 ```tsx
-const { error, authError } = usePearAuth();
-const { agentWalletError } = usePearAgentWallet();
-const { lastError } = useHyperliquidWebSocket();
-
-// Handle authentication errors
-if (authError) {
-  console.error('Auth failed:', authError);
+try {
+  await createPosition(payload);
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('Error:', error.message);
+  }
 }
+```
+
+## Environment Variables
+
+When using the SDK, you may want to configure different environments:
+
+```tsx
+// Production
+<PearHyperliquidProvider
+  apiBaseUrl="https://hl-v2.pearprotocol.io"
+  wsUrl="wss://hl-v2.pearprotocol.io/ws"
+/>
+
+// Beta
+<PearHyperliquidProvider
+  apiBaseUrl="https://hl-v2-beta.pearprotocol.io"
+  wsUrl="wss://hl-v2-beta.pearprotocol.io/ws"
+/>
+```
+
+## Examples
+
+### Complete Trading Component
+
+```tsx
+import { useState } from 'react';
+import {
+  usePearAuth,
+  usePearHyperliquid,
+  usePosition,
+  useOrders,
+  useAccountSummary,
+} from '@pear-protocol/hyperliquid-sdk';
 
-// Handle connection errors
-if (lastError) {
-  console.error('WebSocket error:', lastError);
+function TradingDashboard() {
+  const { address, setAddress, isConnected } = usePearHyperliquid();
+  const { isAuthenticated, loginWithSignedMessage } = usePearAuth();
+  const { openPositions, createPosition, closePosition } = usePosition();
+  const { openOrders, cancelOrder } = useOrders();
+  const { data: accountSummary } = useAccountSummary();
+
+  const handleCreatePosition = async () => {
+    try {
+      await createPosition({
+        leverage: 3,
+        usdValue: 500,
+        longAssets: [{ asset: 'ETH', weight: 1 }],
+        shortAssets: [{ asset: 'BTC', weight: 1 }],
+        orderType: 'MARKET',
+      });
+    } catch (error) {
+      console.error('Failed to create position:', error);
+    }
+  };
+
+  return (
+    <div>
+      <h1>Trading Dashboard</h1>
+
+      <div>
+        <h2>Account</h2>
+        <p>Address: {address || 'Not connected'}</p>
+        <p>Status: {isAuthenticated ? 'Authenticated' : 'Not authenticated'}</p>
+        <p>WebSocket: {isConnected ? 'Connected' : 'Disconnected'}</p>
+      </div>
+
+      <div>
+        <h2>Account Summary</h2>
+        <p>Account Value: ${accountSummary?.balanceSummary.marginSummary.accountValue}</p>
+        <p>Withdrawable: ${accountSummary?.balanceSummary.withdrawable}</p>
+      </div>
+
+      <div>
+        <h2>Open Positions</h2>
+        {openPositions?.map(pos => (
+          <div key={pos.positionId}>
+            <p>PNL: ${pos.unrealizedPnl.toFixed(2)}</p>
+            <p>Value: ${pos.positionValue.toFixed(2)}</p>
+            <button onClick={() => closePosition(pos.positionId, { orderType: 'MARKET' })}>
+              Close
+            </button>
+          </div>
+        ))}
+      </div>
+
+      <div>
+        <h2>Open Orders</h2>
+        {openOrders?.map(order => (
+          <div key={order.orderId}>
+            <p>Type: {order.orderType}</p>
+            <p>Value: ${order.usdValue}</p>
+            <button onClick={() => cancelOrder(order.orderId)}>Cancel</button>
+          </div>
+        ))}
+      </div>
+
+      <button onClick={handleCreatePosition}>
+        Create New Position
+      </button>
+    </div>
+  );
 }
+
+export default TradingDashboard;
 ```
 
-## Contributing
+### Market Data Component
 
-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).
+```tsx
+import {
+  useMarketData,
+  useTokenSelectionMetadata,
+  useHyperliquidWebSocket,
+} from '@pear-protocol/hyperliquid-sdk';
+
+function MarketOverview() {
+  const activeAssets = useMarketData((state) => state.activeAssets);
+  const { getMetadata } = useTokenSelectionMetadata();
+
+  return (
+    <div>
+      <h2>Top Gainers</h2>
+      {activeAssets?.topGainers.slice(0, 5).map((asset, idx) => {
+        const longAsset = asset.longAssets[0]?.asset;
+        const metadata = longAsset ? getMetadata(longAsset) : null;
+
+        return (
+          <div key={idx}>
+            <p>{longAsset}: {metadata?.priceChange24hPercent.toFixed(2)}%</p>
+          </div>
+        );
+      })}
+
+      <h2>Top Losers</h2>
+      {activeAssets?.topLosers.slice(0, 5).map((asset, idx) => {
+        const shortAsset = asset.shortAssets[0]?.asset;
+        const metadata = shortAsset ? getMetadata(shortAsset) : null;
+
+        return (
+          <div key={idx}>
+            <p>{shortAsset}: {metadata?.priceChange24hPercent.toFixed(2)}%</p>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+```
 
 ## License
 
-MIT License - see LICENSE file for details.
+MIT
+
+## Repository
+
+GitHub: [https://github.com/pear-protocol/hyperliquid](https://github.com/pear-protocol/hyperliquid/tree/main/pear-hyperliquid-sdk)
 
 ## Support
 
-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)
+For issues and questions, please visit the [GitHub Issues](https://github.com/pear-protocol/hyperliquid/issues) page.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.