Hyperliquidをウォレットに統合する：開発者向け完全ガイド

2026年5月6日

分散型デリバティブ市場が成熟するにつれ、Hyperliquidの無期限先物取引機能をウォレット画面に直接組み込み、ユーザーにワンストップのDeFi体験を提供したいと考えるウォレット開発チームが増えています。

本記事では、ウォレット開発者向けに、Hyperliquid統合の技術的な流れを整理します。アカウントモデル、署名方式、フロントエンドSDK/APIの呼び出し、安全設計のポイントまで、実装時につまずきやすい部分を体系的に確認します。

Hyperliquidのアカウントモデル

HyperliquidはEVM互換のアドレス体系、つまりEthereum形式のアドレスを使用します。ユーザーは標準的なECDSA秘密鍵で署名します。

公式ドキュメントでは、アカウントは主に次の2種類に分けられます。

  • Vault Address：プロトコル上のメインアドレスで、資産の所有権を持つアドレス
  • Agent Address：認可されたサブ署名アドレスで、取引ごとの操作負担を減らすために使われるアドレス

ウォレット統合では、ユーザーのメインウォレットアドレスをVault Addressとして使い、必要に応じて高頻度取引用のホットウォレットAgentを認可する構成が一般的です。

接続方式：WalletConnectか、直接RPC/API統合か

方式1：WalletConnect 2.0

WalletConnectは、現在もっとも広く使われているウォレット接続プロトコルのひとつです。HyperliquidのWebアプリはWalletConnect 2.0にネイティブ対応しています。

統合の基本的な流れは次のとおりです。

  1. ウォレットアプリ側でWalletConnect 2.0のSession Proposal処理を実装する
  2. ユーザーがQRコードまたはDeep Linkで接続を承認する
  3. ウォレットが eth_sendTransaction や personal_sign リクエストを監視し、署名結果を返す

この方式のメリットは、侵襲性が低いことです。ウォレット側はHyperliquid内部のプロトコル仕様を深く理解しなくても、標準的なEthereum署名インターフェースに対応していれば接続できます。

方式2：Hyperliquid Python/JS SDKを直接統合する

ウォレット内でポジション表示や直接注文など、より深い機能を提供したい場合は、公式SDKまたはコミュニティSDKを利用できます。

pip install hyperliquid-python-sdk

# または
npm install @nktkas/hyperliquid

Hyperliquid Python SDKは、署名やリクエスト処理の多くをラップしており、独自実装の負担を減らせます。

署名方式：EIP-712構造化署名

Hyperliquidのすべての書き込み操作、たとえば注文、キャンセル、入出金などは、単純な eth_sign ではなく、EIP-712構造化署名を使用します。

これはユーザー体験とセキュリティの両面で重要です。

  • EIP-712に対応したウォレットでは、「BTC無期限を0.01枚ロング、指値65,000 USDC」のように、人間が読める形式で署名内容を表示できます
  • EIP-712に対応していないウォレットでは、16進数のバイト列しか表示できない場合があり、ユーザー体験が悪くなるだけでなく、誤署名のリスクも高まります

ウォレット統合では、EIP-712の解析と表示ロジックを優先的に実装することをおすすめします。実装時は、EIP-712仕様の signTypedData_v4 標準を参照してください。

コアAPI統合：注文フロー

JavaScriptで直接APIを呼び出し、指値買い注文を行う例です。

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

完全なDomainとTypesの定義は、Hyperliquid公式ドキュメントのExchange Endpointを確認してください。

口座残高とポジションの取得

残高やポジションの照会は読み取り専用操作のため、署名は不要です。

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

レスポンスには、次のような情報が含まれます。

  • marginSummary：利用可能証拠金、総資産価値など
  • assetPositions：各ポジションの詳細
  • crossMaintenanceMarginUsed：クロスマージンの維持証拠金使用量など

セキュリティ設計のポイント

ウォレットにデリバティブプロトコルを統合する場合、最優先すべきはセキュリティです。

秘密鍵の分離

取引署名はSecure Enclaveやハードウェアデバイス内で完結させ、秘密鍵をアプリケーション層のコードに露出させない設計が重要です。ハードウェアウォレットの設計を検討する場合は、OneKeyのオープンソースアーキテクチャが参考になります。

金額と注文内容の二重確認

注文前には、ユーザーが理解できる確認画面を必ず表示するべきです。最低限、次の情報を明確に示します。

  • 銘柄
  • 売買方向
  • 数量
  • レバレッジ
  • 予想清算価格
  • reduce-onlyの有無

Agent権限の制限

Agent Addressを使う場合は、ユーザーがいつでもAgent認可を取り消せるようにする必要があります。また、現在認可されているAgentアドレスをUI上で分かりやすく表示することも重要です。

リプレイ攻撃への対策

Hyperliquidのnonceメカニズムを利用し、各注文のnonceが単調増加するように管理します。これにより、過去の署名が再利用されるリプレイ攻撃を防ぎます。

推奨アーキテクチャ：OneKeyの活用

OneKeyハードウェアウォレットはEthereumのEIP-712署名に対応しており、オープンソースSDKでも構造化署名APIを提供しています。そのため、HyperliquidのようなEVM互換のデリバティブプロトコルを深く統合したい開発チームにとって、実装参考として有用です。

ユーザーに無期限先物取引機能を提供したい場合は、OneKey Perpsのワークフローを参考にできます。OneKey Perpsは、ハードウェアウォレットによる鍵管理を前提にしながら、スムーズなデリバティブ取引体験を目指す設計です。速度のためにセキュリティを犠牲にするのではなく、署名内容の可視化と安全な鍵管理を組み合わせることが重要です。

実装や利用を検討している方は、OneKeyをダウンロードし、OneKey Perpsで実際の操作フローを確認してみてください。開発者はOneKey GitHubのオープンソースコードも参考にできます。

よくある質問

Q1：Hyperliquidはどのウォレット接続方式に対応していますか？

A：MetaMask、WalletConnect 2.0対応ウォレット、秘密鍵による直接署名を使ったプログラムアクセスに対応しています。ECDSA署名が可能なEthereumウォレットであれば、理論上は統合可能です。

Q2：Agent Addressとメインアドレスの違いは何ですか？

A：Agent Addressは、メインアドレスによって認可されたサブ署名アドレスです。通常は自動売買ボットなどに使われます。Agentは注文など特定の操作のみを実行でき、出金はできないため、秘密鍵が漏えいした場合の被害範囲を抑えられます。詳細はHyperliquidのドキュメントを確認してください。

Q3：統合時にHyperliquidチームへAPI利用許可を申請する必要はありますか？

A：Hyperliquidはパーミッションレスなプロトコルです。Info Endpointは公開されており、Exchange Endpointの書き込み操作も有効なEIP-712署名があれば実行できます。API利用のための許可申請やホワイトリスト登録は不要です。

Q4：ウォレットUIで未実現損益（PnL）を表示するにはどうすればよいですか？

A：clearinghouseState インターフェースが返す assetPositions の中に、各ポジションの unrealizedPnl フィールドがあります。この値を表示すれば未実現損益を示せます。なお、値はUSDC建てです。

Q5：Testnetのエンドポイントは何ですか？

A：HyperliquidのテストネットAPIは https://api.hyperliquid-testnet.xyz/ です。開発段階の機能検証に利用でき、実資金は関係しません。

リスクに関する注意

本記事は技術統合の参考情報であり、投資助言、金融助言、法的助言ではありません。無期限先物取引には高いレバレッジリスクがあり、損失が大きくなる可能性があります。開発者は、プロトコル仕様、署名内容、証拠金ルール、清算メカニズムを十分に理解したうえで、本番環境への統合を行ってください。

OneKeyで暗号化の旅を守る

View details for OneKeyのご購入OneKeyのご購入

OneKeyのご購入

世界最先端のハードウェアウォレット。

View details for アプリをダウンロードアプリをダウンロード

アプリをダウンロード

詐欺アラート。すべてのコインをサポート。

View details for OneKey SifuOneKey Sifu

OneKey Sifu

暗号化の疑問を解消するために、一つの電話で。