Hyperliquid MCP サーバー - 完全な実装

このMCP（モデル・コンテキスト・プロトコル）サーバーは、Hyperliquid SDKの包括的なラッパーを提供し、スポット市場と先物市場の両方における幅広い取引機能をAIアシスタントに公開します。これにより、AIアシスタントはHyperliquid取引所と連携し、市場データの取得、取引の執行、ポジション管理などを行うことができます。

特徴

包括的なAPIカバレッジ

スポット取引と先物取引の両方に対応するすべてのHyperliquid SDK APIの完全実装
市場データの取得（価格、注文書、ローソク足）
注文の配置と管理（マーケット、リミット、トリガー、TWAP）
ポジション管理（レバレッジ、マージン、クローズ）
アカウント情報と残高
資金調達率情報
送金と引き出し
金庫管理
サブアカウント管理
紹介システムの統合

技術的特徴

秘密鍵とウォレットアドレスの両方を使用した適切な認証
包括的なエラー処理と検証
リアルタイム市場データアクセス
注文追跡のためのクライアント注文ID（クラウド）のサポート
テストネットとメインネットの両方をサポート

特定されたAPIと実装

Hyperliquid SDK リポジトリを徹底的に調査した結果、次の API を特定して実装しました。

市場データAPI

API	説明	実装
`getAllMids`	利用可能なすべての暗号通貨の中間価格を取得します	SDK の`info.getAllMids()`への直接マッピング
`getL2Book`	シンボルの注文書データを取得する	SDK の`info.getL2Book()`への直接マッピング
`getCandleSnapshot`	過去のキャンドルデータを取得する	SDK の`info.getCandleSnapshot()`への直接マッピング
`getMetaAndAssetCtxs`	永久先物に関するメタデータと資産コンテキストを取得する	SDK の`info.perpetuals.getMetaAndAssetCtxs()`への直接マッピング
`getSpotMetaAndAssetCtxs`	スポット市場のメタデータと資産コンテキストを取得する	SDK の`info.spot.getSpotMetaAndAssetCtxs()`への直接マッピング

アカウント情報API

API	説明	実装
`getClearinghouseState`	永久先物口座の状態を取得する	SDK の`info.perpetuals.getClearinghouseState()`への直接マッピング
`getSpotClearinghouseState`	スポットアカウントの状態を取得する	SDK の`info.spot.getSpotClearinghouseState()`への直接マッピング
`getUserOpenOrders`	オープン注文を取得する	SDK の`info.getUserOpenOrders()`への直接マッピング
`getUserFills`	取引成立の取得	SDK の`info.getUserFills()`への直接マッピング
`getUserFillsByTime`	時間範囲別に取引成立を取得	SDK の`info.getUserFillsByTime()`への直接マッピング
`getUserFunding`	資金の支払いを受ける	SDK の`info.perpetuals.getUserFunding()`への直接マッピング
`getFundingHistory`	資金調達率の履歴を取得する	SDK の`info.perpetuals.getFundingHistory()`への直接マッピング
`getPredictedFundings`	予測資金調達率を取得する	SDK の`info.perpetuals.getPredictedFundings()`への直接マッピング

注文管理API

API	説明	実装
`placeOrder`	注文を出す（成行注文、指値注文、トリガー注文）	SDK の`exchange.placeOrder()`への直接マッピング
`placeTwapOrder`	TWAP注文をする	SDK の`exchange.placeTwapOrder()`への直接マッピング
`cancelOrder`	注文をキャンセルする	SDK の`exchange.cancelOrder()`への直接マッピング
`cancelOrderByCloid`	クライアント注文IDで注文をキャンセルする	SDK の`exchange.cancelOrderByCloid()`への直接マッピング
`cancelTwapOrder`	TWAP注文をキャンセルする	SDK の`exchange.cancelTwapOrder()`への直接マッピング
`modifyOrder`	既存の注文を変更する	SDK の`exchange.modifyOrder()`への直接マッピング

ポジション管理API

API	説明	実装
`updateLeverage`	シンボルのレバレッジを更新	SDK の`exchange.updateLeverage()`への直接マッピング
`updateIsolatedMargin`	ポジションの分離マージンを更新する	SDK の`exchange.updateIsolatedMargin()`への直接マッピング
`marketClose`	成行注文でポジションをクローズする	SDKの`custom.marketClose()`を介して実装されました
`closeAllPositions`	すべてのポジションをクローズ	SDKの`custom.closeAllPositions()`を介して実装されました

送金および出金API

API	説明	実装
`usdTransfer`	USDCを別のウォレットに転送する	SDK の`exchange.usdTransfer()`への直接マッピング
`initiateWithdrawal`	USDCをアービトラムに出金する	SDK の`exchange.initiateWithdrawal()`への直接マッピング
`spotTransfer`	スポット資産を別のウォレットに転送する	SDK の`exchange.spotTransfer()`への直接マッピング
`transferBetweenSpotAndPerp`	スポット口座と永久口座間の振替	SDK の`exchange.transferBetweenSpotAndPerp()`への直接マッピング

ボールト管理API

API	説明	実装
`createVault`	新しい金庫を作成する	SDK の`exchange.createVault()`への直接マッピング
`getVaultDetails`	金庫の詳細を取得する	SDK の`info.getVaultDetails()`への直接マッピング
`vaultTransfer`	金庫とウォレット間で資金を移動	SDK の`exchange.vaultTransfer()`への直接マッピング
`vaultDistribute`	金庫からフォロワーに資金を分配する	SDK の`exchange.vaultDistribute()`への直接マッピング
`vaultModify`	ボールト構成の変更	SDK の`exchange.vaultModify()`への直接マッピング

サブアカウント管理API

API	説明	実装
`createSubAccount`	新しいサブアカウントを作成する	SDK の`exchange.createSubAccount()`への直接マッピング
`getSubAccounts`	すべてのサブアカウントを取得する	SDK の`info.getSubAccounts()`への直接マッピング
`subAccountTransfer`	サブアカウント間の資金移動（永久）	SDK の`exchange.subAccountTransfer()`への直接マッピング
`subAccountSpotTransfer`	サブアカウント間でスポット資産を移動	SDK の`exchange.subAccountSpotTransfer()`への直接マッピング

その他のAPI

API	説明	実装
`setReferrer`	リファラーコードを設定する	SDK の`exchange.setReferrer()`への直接マッピング
`referral`	紹介情報を取得する	SDK の`info.referral()`への直接マッピング
`setDisplayName`	リーダーボードの表示名を設定する	SDK の`exchange.setDisplayName()`への直接マッピング
`getUserRole`	ユーザーの役割を取得する	SDK の`info.getUserRole()`への直接マッピング
`approveAgent`	ユーザーに代わって取引するエージェントを承認する	SDK の`exchange.approveAgent()`への直接マッピング
`approveBuilderFee`	建築業者手数料を承認する	SDK の`exchange.approveBuilderFee()`への直接マッピング

認証の実装

MCP サーバーは、秘密鍵とウォレットアドレスの両方を使用して認証を実装します。

秘密鍵認証：サーバーは環境変数または設定ファイルを介して秘密鍵を受け入れます。この秘密鍵は、トランザクションの署名とHyperliquid APIによる認証に使用されます。
ウォレットアドレス認証：サーバーは読み取り専用操作に使用されるウォレットアドレスも受け入れます。秘密鍵が提供されてもウォレットアドレスが提供されない場合、サーバーは秘密鍵からウォレットアドレスを導出します。
ボールトアドレスのサポート: ボールト操作の場合、サーバーはボールトアドレスの指定もサポートします。

認証検証は、認証を必要とする操作を実行する前に実行され、取引を実行したりアカウント情報にアクセスしようとする前にユーザーが適切に認証されていることを保証します。

エラー処理と検証

MCP サーバーは包括的なエラー処理と検証を実装します。

クライアント検証: 操作を実行する前に、サーバーは Hyperliquid クライアントが初期化されているかどうかを検証します。
認証検証: 認証を必要とする操作の場合、サーバーはユーザーが適切に認証されていることを検証します。
パラメータの検証: サーバーは、すべてのパラメータを SDK に渡す前に検証し、正しいタイプと形式であることを確認します。
エラー処理: サーバーは SDK からのすべてのエラーをキャッチして処理し、ユーザーに明確なエラーメッセージを提供します。
ログ記録: サーバーはすべての操作とエラーをログに記録するため、問題のデバッグが容易になります。

実装上の課題と特別な考慮事項

1. 成行注文の実装

HyperliquidのAPIには直接的な「成行注文」エンドポイントはありません。成行注文は、即時キャンセル（IOC）の有効期間を持つアグレッシブ指値注文として実装されています。確実な執行のため、現在の価格にスリッページ係数を適用します。

// Apply 0.5% slippage for market orders to ensure execution
const slippagePrice = isBuy ?
  currentPrice * 1.005 : // Buy 0.5% higher than mid price
  currentPrice * 0.995;  // Sell 0.5% lower than mid price

2. スポット市場のシンボル処理

Hyperliquidのスポット市場シンボルには「-SPOT」というサフィックスが付きます。MCPサーバーはこれを透過的に処理し、必要に応じてサフィックスを追加します。

// For spot market orders, we need to use the same API endpoint but with the spot symbol
const spotSymbol = `${symbol}-SPOT`;

3. 注文応答の解析

注文を配置するための Hyperliquid API からの応答形式は複雑であり、注文 ID を抽出するには慎重な解析が必要です。

// Extract order ID from the response
let orderId = null;
if (result.response && result.response.data && result.response.data.statuses) {
  for (const status of result.response.data.statuses) {
    if (status.resting) {
      orderId = status.resting.oid;
      break;
    } else if (status.filled) {
      orderId = status.filled.oid;
      break;
    }
  }
}

4. 数値の扱い

Hyperliquid API は多くの場合、数値を文字列として返します。MCP サーバーは、これを使いやすくするために数値に変換します。

// Convert string values to numbers
const result = {};
for (const [symbol, price] of Object.entries(allMids)) {
  result[symbol] = parseFloat(price);
}

5. WebSocketサポート

Hyperliquid SDKは、リアルタイムデータ用のWebSocket接続をサポートしています。MCPサーバーは、WebSocketサポートを有効にしてクライアントを初期化します。

client = new Hyperliquid({
  privateKey: config.privateKey,
  testnet: config.testnet,
  walletAddress: config.walletAddress,
  vaultAddress: config.vaultAddress,
  enableWs: true
});

前提条件

Node.js (v14以上)
Hyperliquidアカウント
認証用のEthereum秘密鍵（取引に必要）
ウォレットアドレス（取引に必要）

構成

サーバーは、環境変数または構成ファイルを使用して構成できます。

環境変数

HYPERLIQUID_PRIVATE_KEY : 認証用のEthereum秘密鍵（取引に必要）
HYPERLIQUID_WALLET_ADDRESS : ウォレットアドレス（取引に必須）
HYPERLIQUID_VAULT_ADDRESS : 保管庫のアドレス（オプション、保管庫操作用）
HYPERLIQUID_TESTNET : テストネットを使用する場合は「true」に設定し、メインネットを使用する場合は「false」に設定します（デフォルト: false）
LOG_LEVEL : ログレベル - 'debug'、'info'、'warn'、または 'error' (デフォルト: 'info')

設定ファイル

サーバーと同じディレクトリに、次の構造を持つ.hyperliquid-config.jsonファイルを作成することもできます。

{
  "privateKey": "your-ethereum-private-key",
  "walletAddress": "your-wallet-address",
  "vaultAddress": "your-vault-address",
  "testnet": false,
  "logLevel": "info",
  "popularCoins": ["BTC", "ETH", "SOL", "AVAX", "ARB", "DOGE", "LINK", "MATIC"]
}

サーバーの実行

次のコマンドを実行してサーバーを起動します。

node hyperliquid-mcp-server-complete.js

利用可能なツール

サーバーは、Hyperliquid取引所とやり取りするための包括的なツールセットを提供します。以下にいくつか例を挙げます。

市場データツール

getMarketPrice : 指定された暗号通貨の現在の価格を取得します
getOrderBook : 指定された暗号通貨の現在の注文書を取得します。
getCandleData : 指定された暗号通貨の過去のキャンドルデータを取得します
getAllMids : 利用可能なすべての暗号通貨の中間価格を取得します

アカウント情報ツール

getAccountInfo : ユーザーの永久先物口座に関する情報を取得します
getSpotAccountInfo : ユーザーのスポット取引口座に関する情報を取得する
getUserOpenOrders : ユーザーのすべてのオープン注文を取得する
getUserFills : ユーザーの最近の入力内容を取得する

注文管理ツール

placeMarketOrder : 指定された暗号通貨の市場注文を出す
placeLimitOrder : 指定された暗号通貨の指値注文を出す
placeTriggerOrder : トリガー注文（損切りまたは利益確定）を出す
placeTwapOrder : TWAP（時間加重平均価格）注文を出す
cancelOrder : 既存の注文をキャンセルする
cancelOrderByCloid : クライアントの注文IDで注文をキャンセルする
cancelAllOrders : すべてのオープン注文をキャンセルする
modifyOrder : 既存の注文を変更する

ポジション管理ツール

updateLeverage : 指定された暗号通貨のレバレッジを更新する
updateIsolatedMargin : ポジションの分離マージンを更新する
closePosition : オープンポジションをクローズする
closeAllPositions : すべてのオープンポジションをクローズする

送金・出金ツール

usdTransfer : USDCを別のウォレットに転送する
initiateWithdrawal : USDCをアービトラムに出金する
spotTransfer : スポット資産を別のウォレットに転送する
transferBetweenSpotAndPerp : スポット口座と永久口座間の資金移動

保管庫管理ツール

createVault : 新しいボールトを作成する
getVaultDetails : ボールトの詳細を取得する
vaultTransfer : 金庫と永久先物ウォレット間の資金移動
vaultDistribute : 金庫からフォロワーに資金を分配する
vaultModify : ボールト構成を変更する

サブアカウント管理ツール

createSubAccount : 新しいサブアカウントを作成する
getSubAccounts : ユーザーのすべてのサブアカウントを取得する
subAccountTransfer : サブアカウント間の資金移動（永続的）
subAccountSpotTransfer : サブアカウント間でスポット資産を転送する

利用可能なリソース

サーバーは次のリソースを提供します。

market-data ：永久先物市場における人気の暗号通貨の市場データ
account-info : 永久先物の残高やポジションを含む口座情報
spot-market-data : スポット市場で人気の暗号通貨の市場データ
spot-account-info : スポット取引の残高を含む口座情報
open-orders : ユーザーのすべてのオープン注文
positions : ユーザーのオープンポジションすべて
funding-rates : すべての暗号通貨の現在の資金調達率

セキュリティに関する考慮事項

秘密鍵のセキュリティ：Ethereumの秘密鍵は、あなたの資金への完全なアクセスを提供します。秘密鍵を決して共有したり、公開リポジトリに公開したりしないでください。
最初にテストネットを使用する: メインネットで実際の資金を使用する前に、必ずテストネットでセットアップをテストしてください。
アクセス制限: MCP サーバーへのアクセスを、信頼できる AI アシスタントとアプリケーションに制限します。

免責事項

暗号通貨の取引には大きなリスクが伴います。このツールは教育および情報提供のみを目的として提供されています。取引を行う前に必ずリスクを理解し、失っても構わない資金で取引しないでください。

Hyperliquid MCP Server