H

Hyperliquid MCP服务器V9

@TradingBalthazar/hyperliquid-mcp-server-v9
1 Stars 55 次浏览 TradingBalthazar 更新于 2026-08-23

一个全面的MCP服务器，它为Hyperliquid SDK提供了完整的包装器，使AI助手能够与现货和期货市场进行交互，以检索数据、执行交易和管理头寸。

该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

Hyperliquid MCP 服务器 - 完整实现

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

功能特点

全面的API覆盖

  • 对现货和期货交易的Hyperliquid SDK API进行了完整实现
  • 市场数据检索（价格、订单簿、K线图）
  • 订单下达及管理（市价单、限价单、触发单、TWAP）
  • 仓位管理（杠杆、保证金、平仓）
  • 账户信息与余额
  • 资金费率信息
  • 转账与提现
  • 金库管理
  • 子账户管理
  • 推荐系统集成

技术特点

  • 使用私钥和钱包地址进行适当的身份验证
  • 全面的错误处理和验证
  • 实时市场数据访问
  • 支持客户端订单ID (cloid) 用于订单追踪
  • 支持测试网和主网

已识别的API及其实现

基于对Hyperliquid SDK仓库的彻底检查，我已识别并实现了以下API：

市场数据API

API 描述 实现
getAllMids 获取所有可用加密货币的中间价格 直接映射到SDK的info.getAllMids()
getL2Book 获取某一符号的订单簿数据 直接映射到SDK的info.getL2Book()
getCandleSnapshot 获取历史K线数据 直接映射到SDK的info.getCandleSnapshot()
getMetaAndAssetCtxs 获取永续合约的元数据和资产上下文 直接映射到SDK的info.perpetuals.getMetaAndAssetCtxs()
getSpotMetaAndAssetCtxs 获取现货市场的元数据和资产上下文 直接映射到SDK的info.spot.getSpotMetaAndAssetCtxs()

账户信息API

由于原文档在此处结束，并未列出具体的账户信息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 到 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 服务器使用私钥和钱包地址两种方式进行认证：

  1. 私钥认证：服务器通过环境变量或配置文件接受一个私钥。该私钥用于签署交易并认证 Hyperliquid API。

  2. 钱包地址认证：服务器还接受钱包地址，用于只读操作。如果提供了私钥但没有提供钱包地址，服务器将从私钥中派生出钱包地址。

  3. 金库地址支持：对于金库操作，服务器还支持指定金库地址。

在执行任何需要认证的操作之前，都会进行认证验证，确保用户在尝试执行交易或访问账户信息之前已正确认证。

错误处理和验证

MCP 服务器实现了全面的错误处理和验证：

  1. 客户端验证：在执行任何操作之前，服务器会验证 Hyperliquid 客户端是否已初始化。

  2. 身份验证验证：对于需要身份验证的操作，服务器会验证用户是否已正确进行身份验证。

  3. 参数验证：服务器在将参数传递给 SDK 之前会验证所有参数，确保它们的类型和格式正确。

  4. 错误处理：服务器捕获并处理来自 SDK 的所有错误，向用户提供清晰的错误信息。

  5. 日志记录：服务器记录所有操作和错误，便于调试问题。

实现挑战与特别注意事项

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 账户
  • 用于身份验证的以太坊私钥（交易必需）
  • 您的钱包地址（交易必需）

配置

可以通过环境变量或配置文件来配置服务器：

环境变量

  • 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: 获取指定加密货币的历史K线数据
  • 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: 在金库与永续期货钱包之间转移资金
  • vaultDistribute: 从金库向跟随者分配资金
  • vaultModify: 修改金库配置

子账户管理工具

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

可用资源

服务器提供以下资源：

  • market-data: 永续期货市场中热门加密货币的市场数据
  • account-info: 包括余额和仓位在内的永续期货账户信息
  • spot-market-data: 现货市场中热门加密货币的市场数据
  • spot-account-info: 包括余额在内的现货交易账户信息
  • open-orders: 用户的所有未成交订单
  • positions: 用户的所有未平仓位
  • funding-rates: 所有加密货币的当前资金费率

安全注意事项

  • 私钥安全：您的以太坊私钥提供了对您资金的完全访问权限。切勿分享或在公开仓库中暴露它。
  • 先使用测试网：在主网上使用真实资金之前，务必先在测试网上测试您的设置。
  • 限制访问：仅允许受信任的人工智能助手和应用程序访问MCP服务器。

免责声明

交易加密货币涉及重大风险。此工具仅用于教育和信息目的。在进行交易前，请务必了解所涉及的风险，并且永远不要用您无法承受损失的资金进行交易。

查看源码 项目主页