Hyperliquid MCP Server - Complete Implementation

Hyperliquid MCP Server - Complete Implementation

镜子 (jìng zi)

MCP-Mirror

开发者工具
访问服务器

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 描述 实现
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 没有直接的“市价单”端点。相反，市价单被实现为具有 Immediate-or-Cancel (IOC) 生效时间的激进限价单。为了确保执行，我们对当前价格应用滑点因子：

// 应用 0.5% 的滑点以确保市价单执行
const slippagePrice = isBuy ?
  currentPrice * 1.005 : // 买入价高于中间价 0.5%
  currentPrice * 0.995;  // 卖出价低于中间价 0.5%

2. 现货市场交易对处理

Hyperliquid 中的现货市场交易对具有“-SPOT”后缀。MCP 服务器透明地处理此问题，并在需要时添加后缀：

// 对于现货市场订单，我们需要使用相同的 API 端点，但使用现货交易对
const spotSymbol = `${symbol}-SPOT`;

3. 订单响应解析

Hyperliquid API 返回的订单下达响应格式复杂，需要仔细解析才能提取订单 ID：

// 从响应中提取订单 ID
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 服务器将这些转换为数字，以便于使用：

// 将字符串值转换为数字
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 服务器的访问限制为受信任的 AI 助手和应用程序。

免责声明

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

推荐服务器

Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
MCP Package Docs Server

MCP Package Docs Server

促进大型语言模型高效访问和获取 Go、Python 和 NPM 包的结构化文档，通过多语言支持和性能优化来增强软件开发。

精选
本地
TypeScript
Claude Code MCP

Claude Code MCP

一个实现了 Claude Code 作为模型上下文协议（Model Context Protocol, MCP）服务器的方案，它可以通过标准化的 MCP 接口来使用 Claude 的软件工程能力（代码生成、编辑、审查和文件操作）。

精选
本地
JavaScript
@kazuph/mcp-taskmanager

@kazuph/mcp-taskmanager

用于任务管理的模型上下文协议服务器。它允许 Claude Desktop（或任何 MCP 客户端）在基于队列的系统中管理和执行任务。

精选
本地
JavaScript
mermaid-mcp-server

mermaid-mcp-server

一个模型上下文协议 (MCP) 服务器，用于将 Mermaid 图表转换为 PNG 图像。

精选
JavaScript
Jira-Context-MCP

Jira-Context-MCP

MCP 服务器向 AI 编码助手（如 Cursor）提供 Jira 工单信息。

精选
TypeScript
Linear MCP Server

Linear MCP Server

一个模型上下文协议（Model Context Protocol）服务器，它与 Linear 的问题跟踪系统集成，允许大型语言模型（LLM）通过自然语言交互来创建、更新、搜索和评论 Linear 问题。

精选
JavaScript
Sequential Thinking MCP Server

Sequential Thinking MCP Server

这个服务器通过将复杂问题分解为顺序步骤来促进结构化的问题解决，支持修订，并通过完整的 MCP 集成来实现多条解决方案路径。

精选
Python
Curri MCP Server

Curri MCP Server

通过管理文本笔记、提供笔记创建工具以及使用结构化提示生成摘要，从而实现与 Curri API 的交互。

官方
本地
JavaScript