@pear-protocol/hyperliquid-sdk

React SDK for Pear Protocol Hyperliquid API integration

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.

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

Installation

npm install @pear-protocol/hyperliquid-sdk

or

yarn add @pear-protocol/hyperliquid-sdk

Quick Start

1. Setup the Provider

Wrap your application with the PearHyperliquidProvider:

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
    >
      <YourApp />
    </PearHyperliquidProvider>
  );
}

2. Use the Hooks

Address Management

import { useAddress } 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>
  );
}

Trading Data

import { 
  useTradeHistories, 
  useOpenPositions, 
  useOpenOrders, 
  useAccountSummary 
} from '@pear-protocol/hyperliquid-sdk';

function TradingDashboard() {
  const tradeHistories = useTradeHistories();
  const openPositions = useOpenPositions();
  const openOrders = useOpenOrders();
  const accountSummary = useAccountSummary();

  return (
    <div>
      <h2>Account Summary</h2>
      {accountSummary && (
        <div>
          <p>Balance: {accountSummary.balance}</p>
          <p>Margin Used: {accountSummary.marginUsed}</p>
        </div>
      )}

      <h2>Open Positions</h2>
      {openPositions?.map(position => (
        <div key={position.coin}>
          <p>{position.coin}: {position.szi} @ {position.entryPx}</p>
        </div>
      ))}

      <h2>Open Orders</h2>
      {openOrders?.map(order => (
        <div key={order.oid}>
          <p>{order.coin}: {order.sz} @ {order.limitPx}</p>
        </div>
      ))}
    </div>
  );
}

API Reference

Configuration

interface PearHyperliquidConfig {
  baseUrl: string;
  timeout?: number;
  headers?: Record<string, string>;
}

Hooks

useAddress()

Manages user address and login state.

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

useTradeHistories()

Returns paginated trade history data from WebSocket.

useOpenPositions()

Returns array of current open positions from WebSocket.

useOpenOrders()

Returns array of current open orders from WebSocket.

useAccountSummary()

Returns account summary including balance and margin information.

Client Methods

The PearHyperliquidClient provides methods for:

• syncTradeHistories(data: SyncTradeHistoryDto) - Sync trade history
• syncOpenPositions(data: SyncOpenPositionDto) - Sync open positions
• syncOpenOrders(data: SyncOpenOrderDto) - Sync open orders

WebSocket Channels

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

TypeScript Support

The SDK includes comprehensive TypeScript definitions for all data structures:

import type {
  PearHyperliquidConfig,
  TradeHistoryV1Dto,
  OpenPositionDto,
  OpenLimitOrderDto,
  AccountSummaryResponseDto,
  // ... and many more
} from '@pear-protocol/hyperliquid-sdk';

Error Handling

The SDK provides structured error handling:

try {
  await client.syncTradeHistories(data);
} catch (error) {
  // Error is typed as ApiErrorResponse
  console.error(`API Error ${error.statusCode}: ${error.message}`);
}

Requirements

• React >= 16.8.0
• Node.js >= 16.0.0

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run in development mode (watch)
npm run dev

# Type check
npm run type-check

License

MIT License - see LICENSE file for details.

Support

For questions and support, please contact the Pear Protocol team.