🤖 Gbot — Hyperliquid Trader SDK

Gbot Hyperliquid Trader SDK is a custom, professionally typed wrapper around the core @nktkas/hyperliquid library designed to natively handle multi-asset copy trading, HIP-3 strictly isolated assets, and zero-latency WebSocket stream normalization.

Table of Contents

• Highlights
• Installation
• Core Features & Execution Routes
• Quick Start
• HIP-3 Isolated Margin Compliance
• Development & Linting

Highlights

• Native HIP-3 Isolated Margin — Fully certified to calculate offsets and execute dynamic leverage boundaries specifically for strictly isolated assets (e.g., xyz:GOLD, PURR).
• Strictly Typed Payloads — Replaces legacy any callbacks with rigid, mapped WsTradePayload and WsTradeElement schemas extending safety into asynchronous workers.
• WebSocket Load Balancing — Multiple instances of WebSocketTransport dynamically cycle subscriptions via round-robin index mapping preventing connection saturation across hundreds of token streams.
• Unified Trader Execution — Abstracts ExchangeClient behaviors to intelligently select between Spot, Cross Perpetual, or Forced-Isolated execution routes based purely on configuration parameters.
• Zero Floating Promises — Pre-committed ESLint/TypeScript configurations guarantee that all events and connection handling gracefully resolve without hidden memory leaks.

Installation

# Using Yarn
yarn add @gdexsdk/hyper-liquid-trader

# Using npm
npm install @gdexsdk/hyper-liquid-trader

Core Features & Execution Routes

The HyperLiquidTrading class orchestrates interaction via three strictly defined routes ensuring clear intent over hidden state configuration:

• executeCrossPerp: Directly targets traditional cross-margin trading positions across standard Layer 1 assets like BTC and ETH.
• executeIsolatedPerp: Enforces isolated margin mode dynamically. Automatically forces a leverage synchronization packet to the L1 API before generating the matching isolated execution parameter blocks.
• executeSpot: Standard execution wrapper for Spot assets bypassing all TPSL trigger complications entirely.

Quick Start

import { HyperLiquidTrading } from '@gdexsdk/hyper-liquid-trader';

// 1. Initialize the SDK
const hlt = new HyperLiquidTrading();

// 2. Configure Trading Assets
hlt.setAssets([
  { szDecimals: 5, name: 'BTC', maxLeverage: 40, assetId: 4 },
  { szDecimals: 4, name: 'xyz:GOLD', maxLeverage: 25, assetId: 110003, onlyIsolated: true },
]);

// 3. Track specific Whales/Traders
hlt.setTargetWallets(['0xTargetTraderAddress']);

// 4. Start Event Stream
await hlt.startCopyTrade((trade) => {
  console.log('Incoming Trade Detected:', trade);
});

HIP-3 Isolated Margin Compliance

The Hyperliquid Layer 1 strictly forbids trading specific sub-deployer assets (like xyz:GOLD) from the global cross-margin account structure. Waitlist / HIP-3 components must be traded in pure isolation.

If you attempt to mistakenly route a HIP-3 token through the default processor, the SDK enforces a security block:

Error: [executeCrossPerp] HIP-3 Margin Error: xyz:GOLD is a strict isolated asset. You must use executeIsolatedPerp() with explicit leverage.

To route successfully, you must pass the target leverage integer locally:

await hlt.executeIsolatedPerp(pk, {
  coin: 'xyz:GOLD',
  isLong: true,
  price: '1900.5',
  positionSize: '0.005',
  leverage: 5 // Required explicitly
});

Development & Linting

This SDK forces stringent code quality standards out-of-the-box. The tsconfig.json runs locally with "noUnusedParameters": true & "noUnusedLocals": true.

To verify standards locally:

# Runs the strict Prettier auto-formatter
yarn format

# Performs ESLint code analysis and standardizations
yarn lint

# Runs the TypeScript compiler ignoring emits 
yarn typecheck