Hyperliquid in eine Wallet integrieren: vollständiger Guide für Entwickler

6. Mai 2026

Mit dem Reifegrad dezentraler Derivate-Märkte möchten immer mehr Wallet-Teams Hyperliquids Perpetual-Trading direkt in ihre Wallet-Oberfläche einbetten. Ziel ist eine einheitliche DeFi-Experience, in der Nutzer Assets verwalten, Positionen prüfen und Trades ausführen können, ohne ständig zwischen Apps zu wechseln.

Dieser Leitfaden richtet sich an Wallet-Entwickler und erklärt die wichtigsten technischen Bausteine einer Hyperliquid-Integration: Account-Modell, Signaturen, SDK/API-Nutzung, Frontend-Flows und Sicherheitsanforderungen.

Hyperliquids Account-Modell

Hyperliquid nutzt EVM-kompatible Adressen im Ethereum-Format. Nutzer signieren mit einem standardmäßigen ECDSA Private Key. In der offiziellen Dokumentation werden im Wesentlichen zwei Adresstypen unterschieden:

Vault Address: die Hauptadresse auf Protokollebene, die Eigentum an den Assets hält.
Agent Address: eine autorisierte Sub-Signing-Adresse, die genutzt werden kann, um die Reibung bei häufigen Trading-Aktionen zu reduzieren.

Für Wallet-Integrationen ist der häufigste Ansatz, die Haupt-Wallet-Adresse des Nutzers als Vault Address zu verwenden. Optional kann zusätzlich ein Hot-Wallet-ähnlicher Agent autorisiert werden, um häufige Order-Aktionen auszuführen.

Verbindung: WalletConnect oder direkte RPC/API-Integration

Option 1: WalletConnect 2.0

WalletConnect ist aktuell eines der gängigsten Protokolle, um Wallets mit dApps zu verbinden. Die Web-App von Hyperliquid unterstützt WalletConnect 2.0 nativ.

Typischer Integrationsablauf:

Die Wallet-App implementiert die Verarbeitung von WalletConnect-2.0-Session-Proposals.
Nutzer autorisieren die Verbindung per QR-Code oder Deep Link.
Die Wallet lauscht auf Requests wie eth_sendTransaction und personal_sign und gibt die passenden Signaturen zurück.

Der Vorteil dieses Ansatzes ist die geringe Eingriffstiefe: Die Wallet muss Hyperliquids interne Protokolllogik nicht vollständig nachbauen, sondern stellt primär standardisierte Ethereum-Signing-Funktionen bereit.

Option 2: Direkte Integration des Hyperliquid Python/JS SDK

Wenn du tiefere Funktionen direkt in der Wallet anbieten möchtest — etwa Positionsübersicht, Margin-Informationen oder direktes Order-Placement — kannst du die offiziellen bzw. verbreiteten SDKs nutzen:

pip install hyperliquid-python-sdk

# oder

npm install @nktkas/hyperliquid

Das Hyperliquid Python SDK kapselt große Teile der Signatur- und Request-Logik. Für Wallet-Teams ist trotzdem wichtig, die zugrunde liegenden Signing-Flows zu verstehen, damit die Nutzeroberfläche sicher und nachvollziehbar bleibt.

Signaturmodell: EIP-712 Structured Signing

Alle schreibenden Operationen auf Hyperliquid — zum Beispiel Orders, Cancels, Deposits und Withdrawals — verwenden EIP-712 Structured Signatures statt einfachem eth_sign.

Das hat direkte Auswirkungen auf die User Experience:

Wallets mit guter EIP-712-Unterstützung können menschenlesbare Inhalte anzeigen, zum Beispiel: „BTC Perp long, 0,01 Kontrakte, Limit 65.000 USDC“.
Wallets ohne EIP-712-Parsing zeigen häufig nur Hex-Daten an. Das ist für Nutzer schwer verständlich und erhöht das Risiko, schädliche oder falsche Signaturen zu bestätigen.

Für eine saubere Integration solltest du daher frühzeitig EIP-712-Parsing und eine verständliche Darstellung im Wallet-UI einplanen. Als Referenz dient der Standard signTypedData_v4 aus der EIP-712-Spezifikation.

Core-API-Integration: Order-Flow

Das folgende vereinfachte JavaScript-Beispiel zeigt, wie eine Limit-Buy-Order über direkte API-Calls vorbereitet werden kann:

import { ethers } from "ethers";

const EXCHANGE_ENDPOINT = "https://api.hyperliquid.xyz/exchange";

async function placeOrder(wallet, coin, isBuy, price, size) {
  const nonce = Date.now();

  const orderPayload = {
    type: "order",
    orders: [{
      a: 0,          // asset index (0 = BTC)
      b: isBuy,
      p: price.toString(),
      s: size.toString(),
      r: false,      // reduce-only
      t: { limit: { tif: "Gtc" } }
    }],
    grouping: "na"
  };

  // EIP-712 Domain und Types siehe offizielle Hyperliquid-Dokumentation
  const signature = await wallet._signTypedData(domain, types, orderPayload);

  const body = {
    action: orderPayload,
    nonce,
    signature,
  };

  const resp = await fetch(EXCHANGE_ENDPOINT, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  return resp.json();
}

Die vollständigen Definitionen für Domain und Types solltest du direkt aus der offiziellen Hyperliquid-Dokumentation zum Exchange Endpoint übernehmen, damit deine Implementierung mit dem Protokoll kompatibel bleibt.

Kontostand und Positionen abfragen

Read-only-Operationen benötigen keine Signatur. Ein typischer Call zur Abfrage des Account-Status sieht so aus:

async function getAccountInfo(address) {
  const resp = await fetch("https://api.hyperliquid.xyz/info", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      type: "clearinghouseState",
      user: address,
    }),
  });

  return resp.json();
}

Die Rückgabe enthält unter anderem:

marginSummary: verfügbare Margin, Gesamtwert und weitere Margin-Daten
assetPositions: Details zu den einzelnen Positionen
crossMaintenanceMarginUsed: genutzte Maintenance Margin im Cross-Margin-Modus

Diese Daten bilden die Grundlage für Portfolio-Ansichten, Positionskarten, PnL-Anzeigen und Risiko-Hinweise im Wallet-UI.

Wichtige Sicherheitsanforderungen

Bei der Integration von Derivate-Protokollen in eine Wallet sollte Sicherheit an erster Stelle stehen. Perps sind komplexer als einfache Token-Transfers, da Nutzer mit Leverage, Liquidationsrisiko und Margin-Mechaniken interagieren.

Private-Key-Isolation

Trading-Signaturen sollten in einer sicheren Umgebung erzeugt werden, zum Beispiel in einer Secure Enclave oder auf einem Hardware-Gerät. Der Private Key darf nicht an Anwendungscode oder Webviews weitergegeben werden.

Für Hardware-Wallet-Architekturen lohnt sich ein Blick auf den Open-Source-Ansatz von OneKey.

Klare zweite Bestätigung vor Orders

Vor dem Absenden einer Order sollte die Wallet eine verständliche Bestätigungsansicht anzeigen. Mindestens enthalten sein sollten:

Markt bzw. Coin
Richtung: Long/Short bzw. Buy/Sell
Ordergröße
Ordertyp und Preis
Leverage bzw. Margin-Modus, sofern relevant
geschätzter Liquidationspreis, falls verfügbar
Reduce-only-Status

Nutzer sollten nicht nur „Sign“ sehen, sondern verstehen, welche Trading-Aktion sie bestätigen.

Agent-Rechte begrenzen

Wenn du den Agent-Modus nutzt, sollte der Nutzer jederzeit sehen können:

welche Agent Address aktuell autorisiert ist,
welche Rechte sie hat,
wann sie eingerichtet wurde,
und wie sie widerrufen werden kann.

Ein Agent kann das Risiko reduzieren, weil er typischerweise nur bestimmte Aktionen wie Orders ausführen kann und keine Withdrawals durchführen darf. Trotzdem bleibt eine transparente UI entscheidend.

Replay-Schutz

Nutze Hyperliquids Nonce-Mechanismus korrekt. Jede Order sollte eine monoton steigende bzw. eindeutig verwendbare Nonce haben, um Replay-Angriffe zu verhindern.

Empfohlene Architektur: OneKey und OneKey Perps als Referenz-Workflow

OneKey Hardware Wallets unterstützen Ethereum EIP-712-Signaturen und stellen über das Open-Source-Ökosystem strukturierte Signing-Flows bereit. Das ist besonders relevant für Protokolle wie Hyperliquid, bei denen Nutzer nicht nur Token verschieben, sondern komplexe Trading-Aktionen signieren.

Für Teams, die Perpetual-Funktionen in eine Wallet integrieren möchten, ist OneKey Perps ein praktischer Referenz-Workflow: Perps-Trading wird in eine Wallet-Experience eingebettet, ohne das Sicherheitsmodell zugunsten von Geschwindigkeit aufzugeben.

Statt Nutzer in unklare Signaturdialoge zu schicken, sollte die Wallet:

strukturierte EIP-712-Daten lesbar anzeigen,
kritische Order-Parameter hervorheben,
Hardware- oder isolierte Signaturpfade nutzen,
und Risiko-Informationen verständlich darstellen.

Wenn du als Nutzer Perps mit einer Wallet-First-Erfahrung ausprobieren möchtest, kannst du OneKey herunterladen und OneKey Perps nutzen. Wenn du als Entwickler baust, kann das OneKey-Ökosystem als praktische Referenz für sichere Signing- und UI-Flows dienen.

Häufige Fragen

Q1: Welche Wallet-Verbindungen unterstützt Hyperliquid?

Hyperliquid unterstützt nativ MetaMask, WalletConnect-2.0-kompatible Wallets sowie programmatischen Zugriff über direkte Private-Key-Signaturen. Grundsätzlich kann jede Ethereum-Wallet integriert werden, die ECDSA-Signaturen und die erforderlichen Signing-Methoden unterstützt.

Q2: Was ist der Unterschied zwischen Agent Address und Hauptadresse?

Die Agent Address ist eine von der Hauptadresse autorisierte Sub-Signing-Adresse. Sie wird häufig für Trading-Bots oder High-Frequency-Workflows genutzt. Ein Agent kann bestimmte Aktionen wie Orders ausführen, aber keine Withdrawals vornehmen. Dadurch kann das Schadensausmaß bei einem kompromittierten Agent Key reduziert werden.

Q3: Muss man bei Hyperliquid eine API-Freigabe beantragen?

Nein. Hyperliquid ist ein permissionless Protokoll. Der Info Endpoint ist öffentlich zugänglich. Schreibende Operationen über den Exchange Endpoint benötigen eine gültige EIP-712-Signatur, aber keine separate API-Freigabe oder Whitelist.

Q4: Wie zeigt man unrealisierten Gewinn oder Verlust im Wallet-UI an?

Im Response von clearinghouseState enthält jedes Objekt in assetPositions ein Feld unrealizedPnl. Dieses kann direkt im UI angezeigt werden. Beachte, dass der Wert in USDC denominiert ist.

Q5: Wie lautet die Testnet-API?

Die Hyperliquid-Testnet-Schnittstelle lautet:

https://api.hyperliquid-testnet.xyz/

Sie eignet sich für Entwicklung und Funktionstests, ohne echtes Kapital zu riskieren.

Risikohinweis

Dieser Artikel dient ausschließlich als technische Integrationsreferenz und ist keine Anlage-, Rechts- oder Finanzberatung. Der Handel mit Perpetual Contracts ist mit erheblichen Risiken verbunden, insbesondere durch Leverage, Liquidationen und Marktvolatilität. Entwickler sollten die Protokollregeln, Signaturanforderungen und Risikomechaniken vollständig verstehen, bevor sie eine produktive Integration bereitstellen.