Skip to content

ADR-002: Hyperliquid Integration

Status: Proposed
Date: 2026-03-06
Replaces: Binance-only Legacy Architecture

1. Kontext: Warum Hyperliquid?

1.1 Binance Probleme

  • Zentralisierte Custody
  • API-Key-Risiko
  • Rate Limits
  • Regulatory Risiko

1.2 Hyperliquid Vorteile

  • Dezentrale Perp-DEX
  • Self-Custody (Wallet)
  • Vault-System für Sub-Accounts
  • Bessere Liquidität für Alts

1.3 Neue Herausforderungen

  • EIP-712 Signing komplex
  • On-Chain Confirmation Delays
  • Gas Costs (aber auf L2)

2. Entscheidung: Architektur

┌────────────────────────────────────────────────────────┐
│              HYPERLIQUID INTEGRATION                    │
├────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐    ┌──────────────┐    ┌───────────┐ │
│  │  Core Engine │───▶│  Execution   │───▶│  HL Mock  │ │
│  │              │    │  Router      │    │ (Default) │ │
│  └──────────────┘    └──────────────┘    └───────────┘ │
│                              │                        │
│                    ┌─────────┴─────────┐              │
│                    ↓                   ↓              │
│              ┌──────────┐       ┌──────────┐         │
│              │  Paper   │       │  Real HL │         │
│              │  Engine  │       │  Gateway │         │
│              │ (active) │       │ (BLOCKED)│         │
│              └──────────┘       └──────────┘         │
│                                                         │
│  ┌────────────────────────────────────────────────┐    │
│  │           AUTHENTICATION FLOW                    │    │
│  │                                                  │    │
│  │  Option A: External Signer (recommended)         │    │
│  │    - Private Key niemals im System             │    │
│  │    - Signer-Service oder Hardware Wallet        │    │
│  │                                                  │    │
│  │  Option B: Vault (für später)                   │    │
│  │    - Hyperliquid Vault für Sub-Account         │    │
│  │    - Delegated Signing                          │    │
│  │                                                  │    │
│  │  Option C: ENV (BLOCKED)                        │    │
│  │    - Private Key in ENV                         │    │
│  │    - NIE FÜR PRODUKTION!                        │    │
│  └────────────────────────────────────────────────┘    │
│                                                         │
└────────────────────────────────────────────────────────┘

3. Hyperliquid-Spezifika

3.1 Authentication

Nicht wie Binance: 

// ❌ Binance-Style
const signature = hmac_sha256(params, api_secret);

Aber EIP-712: 

// ✅ Hyperliquid-Style
const signature = eip712_sign(typed_data, private_key);

Typed Data Example: 

const action = {
  type: 'order',
  asset: 'BTC',
  is_buy: true,
  limit_px: 50000,
  sz: 0.1,
  reduce_only: false
};

// Sign with EIP-712
const signature = signTypedData(domain, types, action, privateKey);

3.2 Symbols

Binance (alt) Hyperliquid (neu)
BTCUSDT BTC-USD
ETHUSDT ETH-USD
SOLUSDT SOL-USD

3.3 Order Types

Type Verfügbar Nutzung
Market ✅ Primary (im Paper-Canary)
Limit ✅ Für präzise Entries
Stop-Market ✅ SL Orders
TP-Market ✅ TP Orders

4. Sicherheits-Architektur

4.1 Private Key Handling

ABSOLUT VERBOTEN: 

// ❌ NIE MACHEN
const privateKey = process.env.HL_API_PRIVATE_KEY;

Akzeptabel (Paper/Mock): 

// ✅ Mock-Mode, kein echter Key
const mockWallet = '0x' + '1'.repeat(40); // Dummy

Zukunft (Live): 

// ✅ External Signer-Server
const signerUrl = process.env.HL_SIGNER_URL;
const signature = await http_post(signerUrl, action);

4.2 Hard Security Gates

// src/config/security_gates.js
const SECURITY_GATES = {
  // Gate 1: Execution Master Switch
  ENABLE_EXECUTION_LIVE: {
    default: false,
    change_requires: ['manual_approval', 'strategy_lab_complete'],
    hard_block: true
  },

  // Gate 2: Mainnet Blocker
  MAINNET_TRADING_ALLOWED: {
    default: false,
    change_requires: ['phase_9_complete', 'written_sign_off'],
    hard_block: true
  },

  // Gate 3: Mode Validation
  HL_MODE: {
    allowed: ['mock', 'paper'],  // 'testnet', 'mainnet' BLOCKED
    change_requires: ['manual_approval']
  },

  // Gate 4: Private Key Check (nicht als Freigabe!)
  PRIVATE_KEY_PRESENT: {
    action: 'log_only',
    never_triggers_go: true
  }
};

5. Implementierungs-Phasen

Phase 1-6: Mock/Paper only

// Nur diese Modi erlaubt
const allowedModes = ['mock', 'paper'];

Phase 7: Strategy Lab

  • Backtests mit Hyperliquid-Daten
  • Keine Live-Integration

Phase 8+: Live-Freigabe

  • ERST nach manueller Freigabe durch Nutzer
  • External Signer Setup
  • Testnet (wenn verfügbar)
  • Mainnet (extrem restriktiv)

6. ENV-Variablen

6.1 Erlaubt (Paper/Mock)

# Mode
HL_MODE=mock                    # oder "paper"

# Mock/Placeholder (kein echter Wert!)
HL_MOCK_WALLET=0x1234...      # Dummy für Tests

# RPC (nur lesend in Paper)
HL_RPC_ENDPOINT=https://api.hyperliquid.xyz

6.2 BLOCKIERT (bis manuelle Freigabe)

# ❌ NICHT setzen ohne ausdrückliche Genehmigung:
HL_API_PRIVATE_KEY=<PRIVATE_KEY>
HL_VAULT_ADDRESS=<VAULT>
HL_MODE=testnet
HL_MODE=mainnet
ENABLE_EXECUTION_LIVE=true
MAINNET_TRADING_ALLOWED=true

7. Konsequenzen

7.1 Positiv

  • Self-custody (kein Exchange-Risiko)
  • Besseres Altcoin-Universum
  • Transparente on-chain Verification

7.2 Negativ

  • Komplexeres Signing (EIP-712)
  • Initial: kein Testnet (HL hat kein öffentliches Testnet)
  • On-chain Latency

7.3 Risken

  • Smart Contract Risiken
  • Bridge-Risiken (für Ein-/Auszahlung)

8. Alternativen

Alternative Abgelehnt wegen
Beibehaltung Binance Custody-Risiko
dYdX Weniger Liquidität
GMX Höhere Fees

9. Nächste Schritte

  1. Hyperliquid Mock-Modul implementieren
  2. Paper-Trading mit HL-Preisen
  3. ERST nach Phase 7: External Signer evaluieren
  4. ERST nach Phase 9: Manuelle Live-Freigabe

Approved: 2026-03-06
Implementation: Mock-Modul in Phase 1-2