npm package: @gdexsdk/hyper-liquid-trader
Description: HyperLiquid Trader SDK
Latest version: 1.1.1

# 🤖 Gbot — Hyperliquid Trader SDK

<p align="center">
    <picture>
        <source media="(prefers-color-scheme: dark)" srcset="assets/logo.png">
        <img src="assets/logo.png" alt="Gbot Logo" width="250">
    </picture>
</p>

<p align="center">
  <strong>HIGH-PERFORMANCE, STRICTLY TYPED HYPERLIQUID TRADING SDK</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/version-1.0.0-blue?style=for-the-badge" alt="Version 1.0.0">
  <img src="https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript">
  <img src="https://img.shields.io/badge/Node.js-339933?style=for-the-badge&logo=nodedotjs&logoColor=white" alt="Node.js">
  <img src="https://img.shields.io/badge/Hyperliquid-2BF4B6?style=for-the-badge&logoColor=black" alt="Hyperliquid">
</p>

**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](#highlights)
- [Installation](#installation)
- [Core Features & Execution Routes](#core-features--execution-routes)
- [Quick Start](#quick-start)
- [HIP-3 Isolated Margin Compliance](#hip-3-isolated-margin-compliance)
- [Development & Linting](#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

```bash
# 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

```typescript
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:

```bash
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:

```typescript
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:

```bash
# Runs the strict Prettier auto-formatter
yarn format

# Performs ESLint code analysis and standardizations
yarn lint

# Runs the TypeScript compiler ignoring emits 
yarn typecheck
```