Integrating Hyperliquid Into a Wallet: A Developer Guide

As decentralized derivatives markets mature, more wallet teams are looking to bring Hyperliquid perps trading directly into the wallet interface. The goal is simple: let users manage assets, sign safely, monitor positions, and trade perps without jumping between disconnected apps. Source: Hyperliquid docs. Source: Hyperliquid Python SDK. Source: Hyperliquid docs. Source: OneKey GitHub. Source: Hyperliquid docs.

This guide is written for wallet developers. It covers the main integration paths for Hyperliquid, including account design, signing, SDK/API usage, and security considerations. It also highlights where OneKey Perps can serve as a practical reference workflow for combining hardware-backed security with a usable perps trading experience.

Hyperliquid’s account model

Hyperliquid uses EVM-compatible addresses in Ethereum format, with users signing via standard ECDSA private keys. In the official account model, there are two important address types:

• Vault Address: the primary protocol-level address that owns the assets.
• Agent Address: an authorized sub-signing address that can reduce friction for frequent trading actions.

For most wallet integrations, the common setup is:

1. Use the user’s main wallet address as the Vault Address.
2. Optionally let the user authorize a hot Agent Address for high-frequency trading operations.

This model is especially relevant for perps products because users often need a faster order flow while still keeping core asset ownership tied to their main wallet.

Connection options: WalletConnect vs direct RPC/API integration

Wallet teams generally have two routes: support Hyperliquid through standard wallet connection flows, or build deeper native functionality inside the wallet.

Option 1: WalletConnect 2.0

WalletConnect is the most widely used wallet connection protocol, and Hyperliquid’s web app supports WalletConnect 2.0 natively.

A typical integration flow looks like this:

1. Implement WalletConnect 2.0 Session Proposal handling in the wallet app.
2. Let users approve the connection by scanning a QR code or opening a deep link.
3. Listen for requests such as eth_sendTransaction and personal_sign, then return the required signatures.

The main advantage is low integration overhead. The wallet does not need to understand Hyperliquid’s full internal protocol. It only needs to provide standard Ethereum signing interfaces.

This approach is a good first step if your wallet wants broad compatibility without embedding a full trading UI.

Option 2: Direct Hyperliquid SDK/API integration

If you want to provide a more complete in-wallet trading experience — for example, viewing positions, placing orders, canceling orders, and showing account risk — you can integrate the Hyperliquid SDK or APIs directly.

Install the Python SDK:

pip install hyperliquid-python-sdk

Or use a JavaScript package:

npm install @nktkas/hyperliquid

The Hyperliquid Python SDK wraps the signing and request logic needed for protocol interactions. A direct integration gives you more control over the user experience, but it also means your wallet must handle signing presentation, account state, error handling, and risk messaging properly.

Signing model: EIP-712 typed data

Hyperliquid write operations — including placing orders, canceling orders, deposits, and withdrawals — use EIP-712 structured signing, not a simple eth_sign flow.

This matters for wallet UX and security.

A wallet with strong EIP-712 support can show users readable signing details, such as:

Open long BTC perp, size 0.01, limit price 65,000 USDC

A wallet without proper EIP-712 parsing may only show unreadable hex data. That creates a poor user experience and can increase signing risk because users cannot easily understand what they are approving.

For wallet integrations, it is strongly recommended to implement clear EIP-712 parsing and display logic. Use the signTypedData_v4 standard from the EIP-712 specification as the reference pattern.

Core API integration: placing an order

Below is a simplified JavaScript example showing how a wallet could place a limit buy order through a direct API call.

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

  // See the official [Hyperliquid](https://app.hyperliquid.xyz/) docs for the EIP-712 domain and types.
  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();
}

The full EIP-712 Domain and Types definitions should be taken from the official Hyperliquid Exchange Endpoint documentation.

Querying balances and positions

Read-only account queries do not require a signature.

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

The response includes fields such as:

• marginSummary: available margin, account value, and related margin data.
• assetPositions: detailed position information for each asset.
• crossMaintenanceMarginUsed: cross-margin maintenance requirement data.

For wallet UI design, these fields are the basis for position pages, margin dashboards, liquidation-risk indicators, and PnL displays.

Security considerations for wallet integrations

When integrating a derivatives protocol into a wallet, security should come before trading speed or interface convenience.

Private key isolation

Signing must happen inside a secure environment such as a Secure Enclave or a hardware wallet. Private keys should never be exposed to application-layer code.

For hardware-wallet-based designs, OneKey’s open-source architecture is a useful reference for isolating keys while still supporting modern signing flows.

Clear order confirmation

Before an order is signed, the wallet should show a human-readable confirmation screen that includes at least:

• Market or asset
• Direction: long/short or buy/sell
• Order size
• Order type and price
• Reduce-only status, if applicable
• Leverage or margin mode, where relevant
• Estimated liquidation price, where available

This is especially important for perps, where leverage can amplify both gains and losses.

Agent permission controls

If your integration supports Agent Addresses, users should be able to:

• See the currently authorized Agent Address.
• Understand what the Agent can and cannot do.
• Revoke Agent authorization at any time.

Agent permissions can reduce the blast radius of a compromised hot key, but only if the UI makes the permission model clear.

Replay protection

Use Hyperliquid’s nonce mechanism correctly. Each order should use a monotonically increasing nonce to help prevent replay attacks.

Wallets should also handle failed submissions carefully so that retry logic does not accidentally reuse stale assumptions about account state or order status.

Recommended architecture: use OneKey as a reference

OneKey hardware wallets support Ethereum EIP-712 signing, and the open-source SDK provides structured signing APIs suitable for deeper integrations with EVM-compatible derivatives protocols such as Hyperliquid.

For wallet teams building perps functionality, OneKey Perps is a practical workflow to study: it aims to combine hardware-backed key protection with a smoother derivatives trading experience, instead of sacrificing signing safety for speed.

A sensible architecture is:

1. Keep private keys isolated in secure hardware or a secure signing environment.
2. Parse and display EIP-712 typed data in a readable format.
3. Use Hyperliquid read APIs for balances, margin, positions, and PnL.
4. Use signed Exchange Endpoint requests for order placement and other write actions.
5. Provide clear risk prompts before users submit leveraged trades.

If you want a safer way to access perps from a wallet-first workflow, try OneKey and explore OneKey Perps. Developers can also review OneKey’s open-source materials for implementation ideas.

FAQ

Q1: Which wallet connection methods does Hyperliquid support?

Hyperliquid supports MetaMask, WalletConnect 2.0-compatible wallets, and programmatic access through direct private-key signing. In theory, any Ethereum wallet capable of ECDSA signing can be integrated.

Q2: What is the difference between an Agent Address and the main address?

An Agent Address is a sub-signing address authorized by the main address. It is commonly used for automated trading systems or faster order submission. An Agent can perform specific actions such as placing orders, but it cannot withdraw funds. This helps limit potential damage if the Agent key is compromised. See the Hyperliquid documentation for the full permission model.

Q3: Do developers need API approval from the Hyperliquid team?

Hyperliquid is a permissionless protocol. The Info Endpoint is public, and write operations through the Exchange Endpoint require a valid EIP-712 signature. No API approval or whitelist is required for standard integration.

Q4: How can a wallet UI show unrealized PnL?

Use the clearinghouseState response. Each item in assetPositions contains an unrealizedPnl field for the relevant position. This value is denominated in USDC.

Q5: What is the Hyperliquid testnet endpoint?

The Hyperliquid testnet endpoint is:

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

Use it during development and testing. Testnet activity does not involve real funds.

Risk note

This article is a technical integration reference and is not investment, legal, or financial advice. Perpetual futures trading involves leverage and can result in significant losses. Developers should understand Hyperliquid’s protocol rules, signing model, margin behavior, and user-risk requirements before shipping a production integration.