Package Exports

@hypersignals/hyperliquid-privy-sdk
@hypersignals/hyperliquid-privy-sdk/backend
@hypersignals/hyperliquid-privy-sdk/client
@hypersignals/hyperliquid-privy-sdk/server
@hypersignals/hyperliquid-privy-sdk/web

Readme

@hypersignals/hyperliquid-privy-sdk

A unified TypeScript SDK for trading on Hyperliquid with Privy wallet integration. Works seamlessly across React Web, React Native/Expo, and Node.js backend with a consistent API.

Features

✅ Universal API - Same methods work across web, mobile, and backend
✅ Type-Safe - Full TypeScript support with comprehensive types
✅ Privy Integration - Built-in support for Privy embedded wallets
✅ Headless Signing - No UI popups (optional)
✅ Delegated Wallets - Backend can trade on behalf of users (with permission)
✅ Complete Trading Suite - Limit, market, trigger orders, TP/SL, TWAP, leverage management
✅ Tree Shakeable - Import only what you need

Installation

npm install @hypersignals/hyperliquid-privy-sdk

Peer Dependencies

For React Web:

npm install @privy-io/react-auth

For React Native/Expo:

npm install @privy-io/expo

For Backend (Node.js): No additional dependencies needed!

Documentation

📖 Web App Usage Guide - Complete guide for React web apps with examples
💰 Builder Fees Guide - How to configure and customize builder fees
📚 Full API reference below

Quick Start

React Web Example (Simplified API)

// 1. Wrap your app with SDK provider (in layout/root)
import { useWallets, useSignTypedData } from '@privy-io/react-auth';
import { HyperliquidSDKProvider } from '@hypersignals/hyperliquid-privy-sdk/web';

function Layout({ children }) {
  const { wallets } = useWallets();
  const { signTypedData } = useSignTypedData();

  return (
    <HyperliquidSDKProvider signTypedData={signTypedData} wallets={wallets}>
      {children}
    </HyperliquidSDKProvider>
  );
}

// 2. Use SDK in your components
import { useHyperliquidClient } from '@hypersignals/hyperliquid-privy-sdk/web';

function TradingComponent() {
  const { client, isReady } = useHyperliquidClient({
    showWalletUIs: false, // Headless mode (no popups)
    // builder: false,     // Optional: disable builder fees
  });

  // Place market order with TP/SL (builder fee automatically applied)
  const buyETH = async () => {
    if (!isReady || !client) return;

    const result = await client.placeSymbolOrder({
      symbol: 'ETH',        // Symbol-based (no asset IDs!)
      side: 'buy',
      orderType: 'market',
      quantity: '0.1',
      slippage: 0.05,       // Auto price calculation
      takeProfit: { triggerPrice: '4200' },
      stopLoss: { triggerPrice: '3800' },
    });

    if (result.status === 'ok') {
      console.log('Order placed with TP/SL!');
    }
  };

  return <button onClick={buyETH}>Buy ETH</button>;
}

📖 See WEB_USAGE.md for complete examples and all features

React Native/Expo Example

import { HyperliquidClient } from '@hypersignals/hyperliquid-privy-sdk';
import { useSignTypedData, useWallets } from '@privy-io/expo';

// EXACT SAME CODE AS REACT WEB! 🎉

Backend (Node.js/Telegram Bot) Example

import { createServerClient } from '@hypersignals/hyperliquid-privy-sdk/server';

// Create backend client (builder fees automatically applied)
const client = createServerClient({
  userId: 'did:privy:...',
  walletAddress: '0x...',
  appId: process.env.PRIVY_APP_ID,
  appSecret: process.env.PRIVY_APP_SECRET,
});

// Place order using symbol-based API
const result = await client.placeSymbolOrder({
  symbol: 'ETH',
  side: 'buy',
  orderType: 'market',
  quantity: '0.1',
  slippage: 0.05,
});

console.log('Order placed:', result);

Builder Fees

The SDK automatically includes a 5 basis point (0.05%) builder fee on all orders by default. This supports platform development and maintenance.

Default Configuration

Builder Address: 0x8af3545a3988b7A46f96F9F1AE40c0e64Fa493C2
Builder Fee: 5 basis points (0.05%)
Applied to: All order types automatically

Customization (Optional)

See BUILDER_FEES.md for:

How to disable builder fees
How to use custom builder address and fee
How to integrate with backend API for dynamic configuration

Example:

const { client } = useHyperliquidClient({
  builder: false, // Disable builder fees
});

API Reference

Order Methods

`placeLimitOrder(params)`

Place a limit order.

await client.placeLimitOrder({
  asset: 0,          // Asset ID (0=BTC, 1=ETH, etc.)
  isBuy: true,       // true=long, false=short
  price: '30000',    // Limit price
  size: '0.1',       // Order size
  reduceOnly: false, // Only reduce position
  timeInForce: 'Gtc', // 'Gtc', 'Ioc', or 'Alo'
  clientOrderId: '0x...', // Optional client order ID
});

`placeMarketOrder(params)`

Place a market order (executed immediately with IoC).

await client.placeMarketOrder({
  asset: 0,
  isBuy: true,
  price: '30000',    // Current market price (still required by API)
  size: '0.1',
  reduceOnly: false,
});

`placeTriggerOrder(params)`

Place a trigger order (stop loss or take profit).

await client.placeTriggerOrder({
  asset: 0,
  isBuy: false,
  size: '0.1',
  triggerPrice: '29000', // Trigger when price hits this
  limitPrice: '28900',   // Optional: limit price when triggered (omit for market)
  reduceOnly: true,
  tpsl: 'sl',           // 'tp' or 'sl'
});

`placeTpSlOrder(params)`

Place both TP and SL orders for a position.

await client.placeTpSlOrder({
  asset: 0,
  size: '0.1',
  isLong: true,        // Closing a long position
  takeProfit: {
    triggerPrice: '35000',
    limitPrice: '34900', // Optional
  },
  stopLoss: {
    triggerPrice: '28000',
    limitPrice: '27900', // Optional
  },
});

`batchOrders(params)`

Place multiple orders in a single transaction.

await client.batchOrders({
  orders: [
    {
      asset: 0,
      isBuy: true,
      price: '30000',
      size: '0.01',
      reduceOnly: false,
      orderType: 'limit',
      timeInForce: 'Gtc',
    },
    {
      asset: 0,
      isBuy: false,
      price: '31000',
      size: '0.01',
      reduceOnly: false,
      orderType: 'limit',
      timeInForce: 'Gtc',
    },
    {
      asset: 1, // ETH
      isBuy: true,
      price: '2000',
      size: '0.1',
      reduceOnly: false,
      orderType: 'limit',
      timeInForce: 'Gtc',
    },
  ],
  grouping: 'na', // 'na' | 'normalTpsl' | 'positionTpsl'
});

`modifyOrder(params)`

Modify an existing order.

await client.modifyOrder({
  orderId: 123,
  order: {
    asset: 0,
    isBuy: true,
    price: '31000',    // New price
    size: '0.2',       // New size
    reduceOnly: false,
    timeInForce: 'Gtc',
  },
});

`batchModifyOrders(params)`

Modify multiple orders in a single transaction.

await client.batchModifyOrders({
  modifies: [
    {
      orderId: 123,
      order: {
        asset: 0,
        isBuy: true,
        price: '31000',
        size: '0.2',
        reduceOnly: false,
        timeInForce: 'Gtc',
      },
    },
    {
      orderId: 456,
      order: {
        asset: 1,
        isBuy: false,
        price: '2100',
        size: '0.15',
        reduceOnly: false,
        timeInForce: 'Gtc',
      },
    },
  ],
});

`cancelOrders(params)`

Cancel orders by ID.

await client.cancelOrders({
  cancels: [
    { asset: 0, orderId: 123 },
    { asset: 1, orderId: 456 },
  ],
});

`cancelAllOrders(asset?)`

Cancel all orders (optionally for a specific asset).

await client.cancelAllOrders(0); // Cancel all BTC orders
await client.cancelAllOrders();  // Cancel all orders

Leverage & Margin Methods

`updateLeverage(params)`

Set leverage and margin mode.

await client.updateLeverage({
  asset: 0,
  isCross: true,    // true=cross, false=isolated
  leverage: 5,      // 1-50x
});

`setMarginMode(params)`

Helper to set margin mode.

await client.setMarginMode({
  asset: 0,
  mode: 'cross',    // 'cross' or 'isolated'
  leverage: 5,
});

`updateIsolatedMargin(params)`

Add or remove margin from isolated position.

await client.updateIsolatedMargin({
  asset: 0,
  isBuy: true,      // Long or short side
  amountUsd: 100,   // Positive to add, negative to remove
});

TWAP Methods

`placeTwapOrder(params)`

Place a TWAP (Time-Weighted Average Price) order.

await client.placeTwapOrder({
  asset: 0,
  isBuy: true,
  size: '1.0',
  durationMinutes: 60,  // Spread over 1 hour
  randomizeTiming: true,
  reduceOnly: false,
});

`cancelTwapOrder(params)`

Cancel a TWAP order.

await client.cancelTwapOrder({
  asset: 0,
  twapId: 1,
});

Schedule Cancel (Dead Man's Switch)

`scheduleCancel(timeMs?)`

Schedule automatic cancellation of all orders.

// Cancel all orders in 1 hour
await client.scheduleCancel(Date.now() + 3600000);

// Remove scheduled cancel
await client.removeScheduledCancel();

Backend-Specific Features

Getting Delegated Wallets

import { HyperliquidBackendClient } from '@hypersignals/hyperliquid-privy-sdk/backend';

const client = new HyperliquidBackendClient({
  privy: { appId: '...', appSecret: '...', walletId: '...' },
});

// Get all delegated wallets for a user
const wallets = await client.getUserDelegatedWallets('privy-user-id');
console.log(wallets);
// [{ address: '0x...', walletId: 'prv_...', chainType: 'ethereum' }]

Delegated Wallet Setup (Required for Backend)

For backend trading, users must first delegate their wallet:

Frontend: Delegate Wallet

import { useDelegatedActions, useWallets } from '@privy-io/react-auth';

function DelegateButton() {
  const { delegateWallet } = useDelegatedActions();
  const { wallets } = useWallets();

  const handleDelegate = async () => {
    await delegateWallet({
      address: wallets[0].address,
      chainType: 'ethereum',
    });
    // User sees Privy modal to approve delegation
  };

  return <button onClick={handleDelegate}>Delegate Wallet</button>;
}

Asset IDs

Common asset IDs (use these in the asset parameter):

import { ASSET_IDS } from '@hypersignals/hyperliquid-privy-sdk';

ASSET_IDS.BTC   // 0
ASSET_IDS.ETH   // 1
ASSET_IDS.SOL   // 2
ASSET_IDS.ARB   // 3
ASSET_IDS.AVAX  // 4

Error Handling

try {
  await client.placeLimitOrder({ ... });
} catch (error) {
  if (error instanceof Error) {
    console.error('Order failed:', error.message);
    // Common errors:
    // - "Insufficient margin"
    // - "Invalid price"
    // - "User rejected the request"
    // - "Request timeout after 30000ms"
  }
}

Advanced Usage

Custom Timeout

import { HyperliquidClient } from '@hypersignals/hyperliquid-privy-sdk';
import { HyperliquidAPIClient } from '@hypersignals/hyperliquid-privy-sdk/core/utils/api';

// Default timeout is 30 seconds
// For custom timeout, you'll need to extend the client

Testing with Testnet

const client = new HyperliquidClient({
  privyWallet: wallets[0],
  signTypedData,
  isTestnet: true, // Use Hyperliquid testnet
});

TypeScript Support

Full TypeScript support with comprehensive types:

import type {
  OrderResponse,
  SuccessResponse,
  CancelResponse,
  LimitOrderParams,
  MarketOrderParams,
  TriggerOrderParams,
} from '@hypersignals/hyperliquid-privy-sdk';

Examples

See the examples directory for complete implementations:

examples/react-web - React web app example
examples/react-native - React Native/Expo example
examples/telegram-bot - Telegram bot example

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build
npm run build

# Lint
npm run lint

# Type check
npm run typecheck

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Support

Acknowledgments

Hyperliquid - The decentralized exchange
Privy - Embedded wallet infrastructure
Built by HyperSignals