feat: import hyperliquid SDK codebase into sma-emulator

Copies the full hyperliquid SDK source including expanded API coverage,
exchange actions, order builder, validation, WebSocket improvements,
tests, scripts, docs, and CI workflows.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: nomeida

.env.example

@@ -1,3 +1,10 @@
-private_key=private_key
-user_address=xxx
-cloid=cloid
+# These env vars are only used in the test suite/test scripts
+TEST_WALLET_ADDRESS="" #Main wallet, NOT API Agent wallet
+TEST_KEY="" #API Agent Wallet or Private Key
+
+TEST_PERP_SYMBOL=""
+TEST_SPOT_TOKEN_ID=""
+TEST_BUILDER_ADDRESS=""
+TEST_AGENT_ADDRESS=""
+TEST_AGENT_NAME=""
+

.github/workflows/integration.yml

@@ -0,0 +1,30 @@
+name: Integration Tests
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main')
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Run integration tests
+        run: npx vitest run tests/integration/
+        env:
+          HL_INTEGRATION_TEST: 'true'
+          PRIVATE_KEY: ${{ secrets.HL_TESTNET_PRIVATE_KEY }}

.github/workflows/schema-drift.yml

@@ -0,0 +1,28 @@
+name: Schema Drift Check
+
+on:
+  schedule:
+    - cron: '0 6 * * 1' # Every Monday at 6am UTC
+  workflow_dispatch:
+
+jobs:
+  schema-drift:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Run schema coverage tests
+        run: npx vitest run tests/integration/schemaCoverage.test.ts
+        env:
+          HL_INTEGRATION_TEST: 'true'

.github/workflows/test.yml

@@ -0,0 +1,39 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x, 22.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Run tests
+        run: npx vitest run --coverage
+
+      - name: Build
+        run: npm run build
+
+      - name: Verify package
+        run: npm pack --dry-run

.gitignore

@@ -10,3 +10,5 @@ src/**/*.js
 .DS_Store
 .idea
 csdk/
+id/
+CLAUDE.md

.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged

PLAN.md

@@ -0,0 +1,75 @@
+# Hyperliquid SDK Parity Plan (nktkas Alignment)
+
+## Goals
+
+- Match nktkas SDK coverage for all REST `/info`, REST `/exchange`, and WebSocket methods.
+- Implement schema validation for responses and structured error handling.
+- Preserve raw/parsed response behavior (parsed default, raw opt-in).
+- Keep undocumented endpoints when present in nktkas.
+
+## Scope
+
+- New first-class methods for missing info/exchange endpoints.
+- WebSocket subscription and post-message parity.
+- Types, response parsing, schema validation, and error taxonomy.
+- Minimal docs and tests to cover new functionality.
+
+## Non-goals
+
+- Large architectural rewrite or runtime portability changes.
+- Dropping existing behavior without a compatible path.
+
+## Plan of Record
+
+1. Inventory and Mapping
+
+   - Extract full method list from nktkas (info/exchange/ws).
+   - Compare against current SDK exports and document gaps.
+   - Identify undocumented endpoints that must be included.
+
+2. Types and Constants Baseline
+
+   - Add missing `InfoType`, `ExchangeType`, and WS subscription constants.
+   - Define request/response types for all new methods.
+   - Add shared payload fragments for reuse (e.g. user/subaccount, dex).
+
+3. REST `/info` Parity
+
+   - Implement all missing info endpoints as first-class methods.
+   - Add missing documented params and optional fields.
+   - Ensure per-call raw override and default parsing behavior.
+
+4. REST `/exchange` Parity
+
+   - Implement all missing exchange actions and method wrappers.
+   - Ensure signing supports new action payload shapes.
+   - Add any required subaccount overrides where applicable.
+
+5. WebSocket Parity
+
+   - Add missing subscriptions, params, and payload builders.
+   - Add response type support and raw/parsed handling.
+   - Align WS errors and reconnect behavior with structured errors.
+
+6. Schema Validation
+
+   - Add a validation layer for REST and WS responses using valibot.
+   - Support: parsed (transform) and raw (shape-only) validation.
+   - Allow global config toggle for validation with per-call override.
+
+7. Structured Errors
+
+   - Introduce base `HyperliquidError` with typed subclasses:
+     - `HyperliquidHttpError`, `HyperliquidSchemaError`, `HyperliquidWsError`,
+       `HyperliquidRateLimitError`, `HyperliquidTimeoutError`, `HyperliquidRequestError`.
+   - Attach context: method name, endpoint, requestId, status, payload.
+   - Normalize server error payloads into consistent error codes.
+
+8. Tests and Docs
+
+   - Add tests for new methods, validation, and error mapping.
+   - Update README and changelog for new coverage and options.
+
+9. Rollout Strategy
+   - Implement in phases: types/constants -> info -> exchange -> ws -> validation -> errors -> docs/tests.
+   - Ship incremental commits to reduce review and integration risk.

README.md

@@ -12,6 +12,7 @@ All info on the Hyperliquid API can be found here: [HyperLiquid API Documentatio
 - Automatic handling of trailing zeros in price and size fields
 - Rate limiting support
 - Comprehensive error handling
+- Schema validation with configurable strictness
 
 ## Installation
 
@@ -78,7 +79,11 @@ const sdk = new Hyperliquid({
   vaultAddress: <vaultAddress - string (OPTIONAL)>,
   maxReconnectAttempts: <number (OPTIONAL)>, // Default is 5, controls WebSocket reconnection attempts
   disableAssetMapRefresh: <boolean (OPTIONAL)>, // Default is false, set to true to disable automatic asset map refresh
-  assetMapRefreshIntervalMs: <number (OPTIONAL)> // Default is 60000 (1 minute), controls how often asset maps are refreshed
+  assetMapRefreshIntervalMs: <number (OPTIONAL)>, // Default is 60000 (1 minute), controls how often asset maps are refreshed
+  rawResponses: <boolean (OPTIONAL)>, // Default is false, return raw API responses without numeric parsing
+  validationMode: <'strict' | 'warn' | 'off' (OPTIONAL)>, // Default is 'strict'
+  wsUrl: <string (OPTIONAL)>, // Override WebSocket URL (e.g. wss://rpc.hyperliquid.xyz/ws for explorer subs)
+  explorerUrl: <string (OPTIONAL)> // Override explorer HTTP base (default https://rpc.hyperliquid.xyz)
 });
 
 // Use the SDK methods
@@ -90,6 +95,15 @@ sdk.info.getAllMids().then(allMids => {
 **Note:** You don't have to provide your private key, but it is required if you want to
 use the exchange API to place, cancel or modify orders or access your accounts assets.
 WebSocket functionality is enabled by default but can be disabled by setting `enableWs: false` in the constructor options.
+Validation runs in `strict` mode by default; use `validationMode: 'warn'` or `validationMode: 'off'` to change behavior.
+
+### Response Validation
+
+To override validation for a single call, wrap it with `withValidationMode`:
+
+```typescript
+await sdk.withValidationMode('off', () => sdk.info.getAllMids());
+```
 
 ## Key Features