Hyperliquid MCP 服务器 - 完整实现

该 MCP（模型上下文协议）服务器为 Hyperliquid SDK 提供了全面的封装，将现货和期货市场的全部交易功能开放给 AI 助手。它使 AI 助手能够与 Hyperliquid 交易所交互，以检索市场数据、执行交易、管理仓位等。

特征

全面的 API 覆盖

完整实现所有 Hyperliquid SDK API，用于现货和期货交易
市场数据检索（价格、订单簿、K线图）
订单下达及管理（市价、限价、触发、TWAP）
头寸管理（杠杆、保证金、平仓）
账户信息和余额
资金费率信息
转账和提款
保险库管理
子账户管理
推荐系统集成

技术特点

使用私钥和钱包地址进行正确的身份验证
全面的错误处理和验证
实时市场数据访问
支持客户订单 ID（cloud）以进行订单跟踪
支持测试网和主网

已识别的 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`	根据客户订单号取消订单	直接映射到 SDK 的`exchange.cancelOrderByCloid()`
`cancelTwapOrder`	取消时长加权平均价订单	直接映射到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 提现至 Arbitrum	直接映射到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_PRIVATE_KEY ：用于身份验证的以太坊私钥（交易所需）
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 提现至 Arbitrum
spotTransfer ：将现货资产转移到另一个钱包
transferBetweenSpotAndPerp ：现货账户和永续账户之间转移资金

保险库管理工具

createVault ：创建一个新的保管库
getVaultDetails ：获取有关保管库的详细信息
vaultTransfer ：在 vault 和永续合约钱包之间转移资金
vaultDistribute ：将保险库中的资金分配给关注者
vaultModify ：修改保险库配置

子账户管理工具

createSubAccount ：创建一个新的子账户
getSubAccounts ：获取用户的所有子账户
subAccountTransfer ：子账户之间转移资金（永久）
subAccountSpotTransfer ：子账户间现货资产转移

可用资源

服务器提供以下资源：

market-data ：永续期货市场中流行加密货币的市场数据
account-info ：账户信息，包括永续期货的余额和仓位
spot-market-data ：现货市场中流行加密货币的市场数据
spot-account-info ：账户信息，包括现货交易余额
open-orders ：用户所有未结订单
positions ：用户的所有空缺职位
funding-rates ：所有加密货币的当前融资利率

安全注意事项

私钥安全：您的以太坊私钥将提供对您资金的完全访问权限。切勿将其与他人共享或在公共存储库中暴露。
首先使用测试网：在主网上使用真实资金之前，请务必在测试网上测试您的设置。
限制访问：限制受信任的 AI 助手和应用程序对 MCP 服务器的访问。

免责声明

加密货币交易涉及高风险。本工具仅供教育和信息参考之用。交易前请务必了解相关风险，切勿使用您无法承受损失的资金进行交易。

Hyperliquid MCP Server