Intégrer Hyperliquid dans un wallet : guide complet pour développeurs

6 mai 2026

À mesure que les marchés de dérivés décentralisés gagnent en maturité, de plus en plus d’équipes wallet veulent intégrer le trading de contrats perpétuels Hyperliquid directement dans leur interface. L’objectif : proposer une expérience DeFi plus fluide, sans obliger l’utilisateur à jongler entre plusieurs apps.

Ce guide s’adresse aux développeurs de wallets. On y passe en revue les principaux choix techniques pour intégrer Hyperliquid : modèle de compte, schémas de signature, appels SDK côté front-end, API, sécurité et bonnes pratiques d’UX. L’idée est de t’aider à éviter les pièges classiques avant une intégration en production.

Le modèle de compte Hyperliquid

Hyperliquid utilise un système d’adresses compatible EVM, au format Ethereum. Les utilisateurs signent avec des clés privées ECDSA standards. Dans la documentation Hyperliquid, on distingue généralement deux types d’adresses :

Vault Address : l’adresse principale au niveau du protocole, propriétaire des actifs.
Agent Address : une adresse de signature secondaire pouvant être autorisée pour réduire la friction lors d’opérations fréquentes.

Pour une intégration wallet, le schéma le plus courant consiste à utiliser l’adresse principale de l’utilisateur comme Vault Address, avec la possibilité d’autoriser une adresse chaude en tant qu’Agent pour certaines opérations de trading à haute fréquence.

Méthodes de connexion : WalletConnect ou RPC direct

Option 1 : WalletConnect 2.0

WalletConnect reste l’un des protocoles de connexion wallet les plus utilisés. L’application web Hyperliquid prend en charge WalletConnect 2.0 nativement.

Les grandes étapes d’intégration sont les suivantes :

Implémenter la gestion des Session Proposals WalletConnect 2.0 dans ton application wallet.
Laisser l’utilisateur autoriser la connexion via QR code ou deep link.
Écouter les requêtes eth_sendTransaction et personal_sign, puis retourner les signatures.

L’avantage de cette approche est sa faible complexité : ton wallet n’a pas besoin de connaître en détail le protocole interne d’Hyperliquid. Il suffit de fournir une interface de signature Ethereum standard.

Option 2 : intégrer directement les SDK Python ou JavaScript Hyperliquid

Si tu veux proposer une intégration plus avancée directement dans le wallet — par exemple afficher les positions, gérer les ordres ou passer des ordres sans quitter l’app — tu peux utiliser les SDK disponibles :

pip install hyperliquid-python-sdk

# ou

npm install @nktkas/hyperliquid

Le SDK Python Hyperliquid encapsule une grande partie de la logique de signature et d’appel aux endpoints. Côté JavaScript, l’intégration permet de construire une expérience plus native dans une interface wallet ou mobile.

Schéma de signature : EIP-712 structuré

Toutes les opérations d’écriture sur Hyperliquid — passage d’ordre, annulation, dépôt, retrait — utilisent des signatures structurées EIP-712, et non de simples signatures eth_sign.

C’est un point important pour l’expérience utilisateur :

Un wallet compatible EIP-712 peut afficher un contenu lisible, par exemple : « ouvrir un long BTC perpétuel de 0,01 contrat à prix limite 65 000 USDC ».
Un wallet qui ne prend pas correctement en charge EIP-712 risque d’afficher uniquement des octets hexadécimaux, ce qui crée une mauvaise UX et augmente les risques de validation aveugle.

Pour une intégration sérieuse, il est recommandé de prioriser le parsing et l’affichage clair des signatures EIP-712. Tu peux t’appuyer sur le standard signTypedData_v4 défini dans la spécification EIP-712.

Intégration API principale : exemple de passage d’ordre

Voici un exemple simplifié en JavaScript pour envoyer un ordre limite d’achat via un appel API direct :

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"
  };

  // Les définitions EIP-712 Domain et Types sont disponibles dans la documentation officielle
  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();
}

Les définitions complètes du Domain et des Types EIP-712 doivent être reprises depuis la documentation officielle Hyperliquid, notamment pour l’Exchange Endpoint.

Consulter les soldes et positions

Les opérations de lecture ne nécessitent pas de signature. Par exemple, pour récupérer l’état d’un compte :

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();
}

La réponse contient notamment :

marginSummary : marge disponible, valeur totale du compte et autres informations de marge.
assetPositions : détail des positions par actif.
crossMaintenanceMarginUsed : marge de maintenance utilisée en mode cross.

Points clés de sécurité

Quand tu intègres un protocole de dérivés dans un wallet, la sécurité doit passer avant la vitesse ou la fluidité apparente.

Isolation de la clé privée

Les signatures de trading doivent être réalisées dans un environnement sécurisé, comme un Secure Enclave ou un hardware wallet. La clé privée ne doit jamais être exposée au code applicatif classique.

Pour une architecture ouverte orientée hardware wallet, tu peux t’inspirer de l’approche open source de OneKey.

Confirmation explicite des montants

Avant tout passage d’ordre, l’utilisateur doit voir un écran de confirmation clair et lisible, incluant au minimum :

l’actif concerné ;
le sens de l’ordre, achat ou vente ;
la taille ;
l’effet de levier ;
le prix limite ou les conditions d’exécution ;
si possible, une estimation du prix de liquidation.

L’objectif est d’éviter que l’utilisateur signe une action dont il ne comprend pas les conséquences.

Limiter les permissions des Agents

Si tu utilises le modèle Agent Address, l’interface doit permettre à l’utilisateur de voir clairement quelles adresses sont autorisées et de révoquer un Agent à tout moment.

Un Agent est utile pour réduire la friction de trading, mais il ne doit pas devenir une boîte noire. Les permissions, le périmètre d’action et les risques doivent être visibles.

Protection contre le rejeu

Utilise correctement le mécanisme de nonce d’Hyperliquid. Chaque ordre doit avoir un nonce monotone afin de réduire le risque d’attaques par rejeu.

Architecture recommandée : s’appuyer sur OneKey

OneKey prend en charge les signatures Ethereum EIP-712 et propose un SDK open source adapté aux intégrations avancées de signatures structurées. C’est un bon point de départ pour les équipes qui veulent connecter un wallet à des protocoles EVM de dérivés comme Hyperliquid sans sacrifier la sécurité.

Pour les wallets qui souhaitent proposer des contrats perpétuels à leurs utilisateurs, l’approche de OneKey Perps est une référence pratique : garder les garanties d’un environnement hardware et d’une validation explicite, tout en offrant une expérience de trading suffisamment fluide pour un usage réel.

Tu peux télécharger OneKey ou consulter le GitHub OneKey pour étudier l’architecture open source et les APIs de signature. Si tu veux tester un workflow orienté utilisateur, OneKey Perps est le chemin le plus direct pour explorer le trading perpétuel avec une logique wallet-first.

Questions fréquentes

Q1 : Quels modes de connexion Hyperliquid prend-il en charge ?

Hyperliquid prend en charge MetaMask, les wallets compatibles WalletConnect 2.0, ainsi que l’accès programmatique par signature directe avec une clé privée. En théorie, tout wallet Ethereum capable de produire des signatures ECDSA peut être intégré.

Q2 : Quelle est la différence entre une Agent Address et l’adresse principale ?

Une Agent Address est une adresse de signature secondaire autorisée par l’adresse principale. Elle est souvent utilisée pour des bots ou des stratégies de trading automatisées.

L’Agent peut exécuter certaines opérations, comme le passage d’ordres, mais ne peut pas retirer les fonds. Cela permet de réduire l’impact potentiel en cas de compromission de cette adresse secondaire. Pour les détails exacts, il faut se référer à la documentation Hyperliquid.

Q3 : Faut-il demander une autorisation API à l’équipe Hyperliquid ?

Non. Hyperliquid est un protocole permissionless. L’Info Endpoint est public, et les opérations d’écriture sur l’Exchange Endpoint nécessitent simplement une signature EIP-712 valide. Il n’est pas nécessaire de demander une licence API ou une inscription sur liste blanche.

Q4 : Comment afficher le PnL non réalisé dans l’interface du wallet ?

Le endpoint clearinghouseState retourne un champ assetPositions. Chaque position contient un champ unrealizedPnl, que tu peux afficher directement dans l’interface. Attention : cette valeur est libellée en USDC.

Q5 : Quelle est l’adresse du testnet ?

L’endpoint testnet d’Hyperliquid est :

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

Il peut être utilisé pendant le développement pour tester les fonctionnalités sans engager de fonds réels.

Risques à garder en tête

Cet article est une référence technique pour l’intégration wallet et ne constitue pas un conseil financier, juridique ou d’investissement. Le trading de contrats perpétuels comporte des risques importants, notamment liés à l’effet de levier et à la liquidation. Avant toute intégration en production, les développeurs doivent comprendre les règles du protocole, tester les flux de signature et concevoir une interface qui aide l’utilisateur à vérifier ce qu’il signe.

Pour une approche plus sûre et pragmatique, essaie OneKey et explore OneKey Perps afin de voir comment combiner signature structurée, sécurité hardware et expérience de trading perpétuel dans un workflow wallet moderne.