@pear-protocol/hyperliquid-sdk 0.0.49 → 0.0.50

package/README.md

@@ -1,735 +0,0 @@
-# Pear Hyperliquid SDK
-
-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 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
-
-```bash
-npm install @pear-protocol/hyperliquid-sdk
-# or
-yarn add @pear-protocol/hyperliquid-sdk
-```
-
-### Peer Dependencies
-
-This SDK requires React 18 or higher:
-
-```bash
-npm install react react-dom
-# or
-yarn add react react-dom
-```
-
-## Quick Start
-
-### 1. Wrap your application with the Provider
-
-```tsx
-import { PearHyperliquidProvider } from "@pear-protocol/hyperliquid-sdk";
-
-function App() {
-  return (
-    <PearHyperliquidProvider
-      apiBaseUrl="https://hl-v2.pearprotocol.io"
-      wsUrl="wss://hl-v2.pearprotocol.io/ws"
-      clientId="YOUR_CLIENT_ID"
-    >
-      <YourApp />
-    </PearHyperliquidProvider>
-  );
-}
-```
-
-### 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 |
-
-### Authentication
-
-The SDK supports two authentication methods:
-
-#### EIP-712 Signature Authentication
-
-```tsx
-import { usePearAuth } from "@pear-protocol/hyperliquid-sdk";
-
-function LoginComponent() {
-  const { getEip712, loginWithSignedMessage, isAuthenticated } = usePearAuth();
-
-  const handleLogin = async (address: string, signer: any) => {
-    // Get EIP-712 message
-    const eip712Data = await getEip712(address);
-
-    // Sign with wallet
-    const signature = await signer.signTypedData(
-      eip712Data.domain,
-      eip712Data.types,
-      eip712Data.message
-    );
-
-    // Authenticate
-    await loginWithSignedMessage(address, signature, eip712Data.timestamp);
-  };
-
-  return <div>{isAuthenticated ? "Logged In" : "Logged Out"}</div>;
-}
-```
-
-#### Privy Token Authentication
-
-```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);
-  };
-}
-```
-
-## API Reference
-
-### Hooks
-
-#### Core Hooks
-
-##### `usePearHyperliquid()`
-
-Access the entire SDK context. Prefer using more specific hooks when possible.
-
-```tsx
-const {
-  apiBaseUrl,
-  wsUrl,
-  address,
-  setAddress,
-  connectionStatus,
-  isConnected,
-  nativeConnectionStatus,
-  nativeIsConnected,
-  authStatus,
-  isAuthenticated,
-  accessToken,
-  user,
-  // ... and more
-} = usePearHyperliquid();
-```
-
-##### `usePearAuth()`
-
-Authentication state and actions.
-
-```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();
-```
-
-##### `usePearAgentWallet()`
-
-Agent wallet management.
-
-```tsx
-const {
-  agentWallet, // AgentWalletState
-  isReady, // boolean
-  loading, // boolean
-  error, // string | null
-  refreshAgentWalletStatus, // () => Promise<any>
-  createAgentWallet, // () => Promise<any>
-  notifyAgentWalletApproved, // () => Promise<any>
-} = usePearAgentWallet();
-```
-
-#### Position Management
-
-##### `usePosition()`
-
-Manage trading positions.
-
-```tsx
-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();
-```
-
-**Example: Create a Position**
-
-```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);
-  }
-};
-```
-
-**Example: Close a Position**
-
-```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);
-  }
-};
-```
-
-#### Order Management
-
-##### `useOrders()`
-
-Manage orders (LIMIT, TP/SL, TWAP).
-
-```tsx
-const {
-  adjustOrder, // (orderId, payload) => Promise<ApiResponse<AdjustOrderResponseDto>>
-  cancelOrder, // (orderId) => Promise<ApiResponse<CancelOrderResponseDto>>
-  cancelTwapOrder, // (orderId) => Promise<ApiResponse<CancelTwapResponseDto>>
-  openOrders, // OpenLimitOrderDto[] | null
-  isLoading, // boolean
-} = useOrders();
-```
-
-**Example: Cancel an Order**
-
-```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);
-  }
-};
-```
-
-#### Trading Data
-
-##### `useTradeHistories()`
-
-Access trade history data.
-
-```tsx
-const { data, isLoading } = useTradeHistories();
-```
-
-##### `useOpenOrders()`
-
-Access open orders with loading state.
-
-```tsx
-const { data, isLoading } = useOpenOrders();
-```
-
-##### `useAccountSummary()`
-
-Access account summary with real-time calculations.
-
-```tsx
-const { data, isLoading } = useAccountSummary();
-// data: AccountSummaryResponseDto | null
-```
-
-#### Market Data
-
-##### `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>
-      {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>
-  );
-}
-```
-
-##### `useHistoricalPriceData()`
-
-Fetch and manage historical price data for tokens.
-
-```tsx
-import { useHistoricalPriceData } from "@pear-protocol/hyperliquid-sdk";
-
-function ChartComponent() {
-  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";
-
-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",
-    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>
-      {twapOrders?.map((order) => (
-        <div key={order.orderId}>
-          Status: {order.status}
-          Progress: {(order.filledUsdValue / order.totalUsdValue) * 100}%
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-#### Notifications
-
-##### `useNotifications()`
-
-Access user notifications.
-
-```tsx
-import { useNotifications } from "@pear-protocol/hyperliquid-sdk";
-
-function NotificationCenter() {
-  const { notifications, isLoading, markAsRead, markAllAsRead } =
-    useNotifications();
-
-  return (
-    <div>
-      {notifications?.map((notif) => (
-        <div key={notif.id} onClick={() => markAsRead(notif.id)}>
-          {notif.category}: {JSON.stringify(notif.parameters)}
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-### Utility Classes
-
-#### `AccountSummaryCalculator`
-
-Calculate account summary with real-time data.
-
-```tsx
-import { AccountSummaryCalculator } from "@pear-protocol/hyperliquid-sdk";
-
-const calculator = new AccountSummaryCalculator(webData2);
-const summary = calculator.calculateAccountSummary(
-  accountSummary,
-  openOrders,
-  agentWalletAddress,
-  agentWalletStatus
-);
-```
-
-#### `ConflictDetector`
-
-Detect position conflicts for new trades.
-
-```tsx
-import { ConflictDetector } from "@pear-protocol/hyperliquid-sdk";
-
-const conflicts = ConflictDetector.detectConflicts(
-  longTokens,
-  shortTokens,
-  existingPositions
-);
-```
-
-#### `TokenMetadataExtractor`
-
-Extract token metadata from WebSocket data.
-
-```tsx
-import { TokenMetadataExtractor } from "@pear-protocol/hyperliquid-sdk";
-
-const metadata = TokenMetadataExtractor.extractMetadata(
-  "ETH",
-  webData2,
-  allMids,
-  activeAssetData
-);
-```
-
-### Direct API Clients
-
-For advanced use cases, you can import and use API clients directly:
-
-```tsx
-import {
-  createPosition,
-  updateRiskParameters,
-  closePosition,
-  adjustOrder,
-  cancelOrder,
-} from "@pear-protocol/hyperliquid-sdk";
-
-// 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 written in TypeScript and provides comprehensive type definitions. All hooks, functions, and data structures are fully typed.
-
-```tsx
-import type {
-  OpenPositionDto,
-  OpenLimitOrderDto,
-  TradeHistoryDataDto,
-  AccountSummaryResponseDto,
-  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
-
-All API functions return promises and throw errors on failure. Always wrap API calls in try-catch blocks:
-
-```tsx
-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";
-
-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;
-```
-
-### Market Data Component
-
-```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
-
-## Repository
-
-GitHub: [https://github.com/pear-protocol/hyperliquid](https://github.com/pear-protocol/hyperliquid/tree/main/pear-hyperliquid-sdk)
-
-## Support
-
-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.