通过 JSON-RPC 读取 HyperEVM 状态：EVM 方法与 HyperCore 桥接

Hyperliquid 的双系统架构

Hyperliquid 并非单一的单体区块链。它运行着两个服务于不同目的的独立接口。HyperCore 是原生订单簿和永续合约引擎，暴露自己的 Info 和 Exchange REST 及 WebSocket API，用于市场数据、账户状态和订单管理。HyperEVM 则是一条独立的以太坊兼容链，承载 EVM 智能合约并暴露标准的 eth_ JSON-RPC 命名空间。这种分离在 Hyperliquid HyperEVM 文档中有详细说明。

对开发者而言，关键问题是：我需要的数据在哪个系统上？市场价格、订单簿、永续合约引擎上的账户余额以及订单历史都位于 HyperCore。智能合约状态、EVM 代币余额和合约事件则位于 HyperEVM。要获得完整视图，通常需要交叉引用两个系统。Hyperliquid RPC 延迟：HyperEVM 与原生 API 指南从较高层面介绍了端点选择，而本文聚焦于 EVM 读取接口。

• HyperCore：原生订单簿和永续合约引擎；Info 和 Exchange API；市场与账户状态。
• HyperEVM：以太坊兼容链；标准 eth_ JSON-RPC 方法；智能合约状态和 EVM 余额。
• 数据位置决定应查询哪个接口——混淆两者会导致结果为空或错误。

HyperEVM 链身份与运行时验证

HyperEVM 主网使用链 ID 999，这一点已在 ChainList 和 Hyperliquid 文档中公布。然而，链 ID 在自定义端点上可能被伪造或配置错误。在发送任何状态变更或读取请求之前，务必使用 eth_chainId 在运行时验证链 ID。eth_chainId 方法以十六进制字符串返回链 ID，而 net_version 以十进制字符串返回。两者都属于标准以太坊 JSON-RPC 规范，详见 ethereum.org。

预期链 ID 与返回值不匹配，说明你连接到了错误的网络或配置错误的端点。当使用第三方 RPC 提供商时，这一检查尤为重要，因为端点行为虽有文档说明，但会因提供商而异。有关 Hyperliquid RPC 端点列表，请参阅 Hyperliquid RPC 端点（RPC Assistant） 页面。

• eth_chainId 以十六进制字符串返回链 ID（999 对应 0x3e7）。
• net_version 以十进制字符串返回链 ID（"999"）。
• 读取状态前务必验证链 ID，以避免查询错误的网络。

HyperEVM 上的标准 EVM 读取方法

HyperEVM 暴露与任何以太坊兼容链相同的 eth_ 命名空间方法。与状态检查最相关的只读方法包括 eth_blockNumber、eth_getBalance、eth_call、eth_getCode、eth_getStorageAt、eth_getLogs、eth_getTransactionReceipt 和 eth_getTransactionByHash。这些方法的行为与以太坊对应方法完全一致，定义见 以太坊 JSON-RPC 规范。

eth_blockNumber 返回最新区块号。eth_getBalance 返回地址的原生代币余额。eth_call 执行只读合约函数而不创建交易。eth_getCode 返回合约地址处的字节码，可用于验证合约是否已部署。eth_getStorageAt 读取特定存储槽。eth_getLogs 检索区块范围内的日志事件。eth_getTransactionReceipt 和 eth_getTransactionByHash 提供交易详情。所有这些方法在 HyperEVM 端点上均可用，但提供商特定的速率限制和缓存行为可能有所不同。

• eth_blockNumber：最新区块高度。
• eth_getBalance：地址的原生代币余额。
• eth_call：只读合约函数执行。
• eth_getCode：地址处的合约字节码。
• eth_getStorageAt：原始存储槽值。
• eth_getLogs：区块范围内的事件日志。
• eth_getTransactionReceipt：按哈希获取交易收据。
• eth_getTransactionByHash：按哈希获取交易详情。

HyperCore 到 HyperEVM 桥接与资产转移

HYPE 等资产可以通过桥接机制在 HyperCore 和 HyperEVM 之间转移。桥接在 EVM 侧使用一个系统地址来表示源自 HyperCore 的资产。读取余额时，必须查询正确的一侧：即使对于同一资产，HyperCore 上的余额与 HyperEVM 上的余额也不相同。Hyperliquid HyperEVM 文档描述了该桥接和系统地址。

对集成者而言，这意味着用户在 HyperCore 上的 HYPE 余额（用于交易）与在 HyperEVM 上的 HYPE 余额（用于智能合约）是分开的。要显示统一余额，必须查询两个系统并合并结果。桥接地址本身是 HyperEVM 上的一个合约，其状态可以使用 eth_call 或 eth_getBalance 读取。务必从官方文档确认特定网络（主网与测试网）的桥接地址，因为合约地址因网络而异。

• HyperCore 余额与 HyperEVM 余额不同；要获得完整视图需查询两者。
• HyperEVM 上的桥接系统地址持有从 HyperCore 转移过来的资产。
• 合约地址在主网和测试网之间不同——请从官方来源验证。

JSON-RPC 信封与错误形态

所有 HyperEVM JSON-RPC 请求都遵循 JSON-RPC 2.0 规范。请求对象必须包含 jsonrpc: "2.0"、唯一的 id、方法字符串以及 params 数组（或对象）。响应包含 result 字段或带有 code、message 和可选 data 的 error 对象。常见错误码包括 -32601（方法未找到）、-32602（参数无效）和 -32000（服务器错误）。提供商特定的错误可能使用自定义代码。

调试时，始终先检查 error 对象。-32601 错误通常意味着端点不支持该方法。-32602 错误表示参数格式错误，例如无效地址或区块标签。-32000 错误可能表示速率限制或内部服务器问题。有关速率限制的具体信息，请参阅 Hyperliquid API 速率限制 指南。

• 请求：{ jsonrpc: "2.0", id: 1, method: "eth_chainId", params: [] }
• 成功响应：{ jsonrpc: "2.0", id: 1, result: "0x3e7" }
• 错误响应：{ jsonrpc: "2.0", id: 1, error: { code: -32601, message: "Method not found" } }

可运行的 Node.js 示例：链 ID、区块号、余额和代码

以下 Node.js 脚本使用原生 fetch API 向 HyperEVM 端点发送原始 JSON-RPC 请求。它首先验证链 ID，然后获取最新区块号、某个地址的原生余额以及某个合约地址处的字节码。请将端点 URL 替换为你的提供商的 HyperEVM 端点。此示例假设使用 Node.js 18 或更高版本，默认包含 fetch。

脚本以可读格式打印每个结果。如果你使用的提供商需要 API 密钥，请按照该提供商的文档将其包含在 URL 或请求头中。同样的模式适用于任何 EVM 兼容链，但链 ID 检查可确保你位于 HyperEVM。

const endpoint = 'https://your-hyperevm-endpoint.example';

async function rpc(method, params = []) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params })
  });
  const data = await response.json();
  if (data.error) throw new Error(`${method}: ${data.error.message}`);
  return data.result;
}

async function main() {
  const chainId = await rpc('eth_chainId');
  console.log('Chain ID:', chainId, '(', parseInt(chainId, 16), ')');

  const blockNumber = await rpc('eth_blockNumber');
  console.log('Latest block:', parseInt(blockNumber, 16));

  const address = '0x0000000000000000000000000000000000000000';
  const balance = await rpc('eth_getBalance', [address, 'latest']);
  console.log('Balance:', parseInt(balance, 16) / 1e18, 'HYPE');

  const contract = '0xYourContractAddress';
  const code = await rpc('eth_getCode', [contract, 'latest']);
  console.log('Code length:', code.length);
}

main().catch(console.error);

可运行的 Node.js 示例：使用 eth_call 调用视图函数

eth_call 方法在智能合约上执行只读函数。它需要一个包含 to、data 以及可选 from 和 gas 的交易对象。data 字段是 ABI 编码的函数选择器和参数。对于像 balanceOf(address) 这样的简单视图函数，选择器是 0x70a08231，后跟 32 字节填充的地址。以下示例在假设的 ERC-20 合约上调用 balanceOf 并解码返回的 uint256。

此模式适用于任何 view 或 pure 函数。对于复杂返回类型，请使用 ethers.js 或 viem 等库自动编码和解码。原始 JSON-RPC 方法有助于理解底层机制，也适用于轻量级脚本。

const endpoint = 'https://your-hyperevm-endpoint.example';

async function rpc(method, params = []) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params })
  });
  const data = await response.json();
  if (data.error) throw new Error(`${method}: ${data.error.message}`);
  return data.result;
}

async function main() {
  const token = '0xYourTokenAddress';
  const holder = '0xYourHolderAddress';
  const selector = '0x70a08231';
  const paddedHolder = holder.slice(2).padStart(64, '0');
  const data = selector + paddedHolder;

  const result = await rpc('eth_call', [{ to: token, data }, 'latest']);
  const balance = BigInt(result);
  console.log('Token balance:', balance.toString());
}

main().catch(console.error);

针对你的端点的可复现结果表格

要比较端点或验证提供商行为，请用你自己环境中的测量值填写下表。多次运行每个方法并记录中位延迟。该表格有意留空，以便你填入自己的数据。不要依赖第三方基准数字；请针对你的特定端点和网络条件进行测量。

使用一致的计时方法，例如 Node.js 中的 performance.now() 或 curl 的 time_total。记录 eth_chainId 返回的链 ID，以确认你位于 HyperEVM 主网（0x3e7）或测试网。最新区块号会随时间变化，因此请注明测量时间戳。

• 端点 URL：________________
• eth_chainId 返回值：________________
• 最新区块（eth_blockNumber）：________________
• Gas 价格（eth_gasPrice）：________________
• eth_call 延迟（毫秒）：________________
• eth_getBalance 延迟（毫秒）：________________
• 测量时间戳：________________

HyperEVM JSON-RPC 读取的局限性与权衡

HyperEVM 是与原生 HyperCore API 分离的链。将市场数据与 EVM 状态交叉引用需要查询两个接口，这引入了复杂性，并且如果两个系统不同步，可能导致不一致。没有任何单一的 JSON-RPC 方法能同时返回 HyperCore 订单簿数据和 HyperEVM 合约状态。开发者必须设计其数据层以处理这两个来源。

合约地址因网络而异。HyperEVM 主网上的地址与测试网上的不同，桥接系统地址也可能不同。务必从官方文档或链上来源验证地址。端点行为虽有文档说明，但会因提供商而异：某些提供商可能缓存 eth_call 结果、限制 eth_getLogs 区块范围或施加速率限制。这些差异可能影响一致性和延迟。对于历史市场数据，原生 API 更为合适；请参阅 Hyperliquid 历史市场数据 API 指南。

• 两个系统：HyperCore 用于市场/账户状态，HyperEVM 用于合约状态。
• 没有统一的 RPC 方法——交叉引用需要两个接口。
• 合约地址因网络而异；请从官方来源验证。
• 提供商特定的缓存、速率限制和区块范围限制适用。

排查常见的 HyperEVM JSON-RPC 问题

如果 eth_chainId 返回意外值，你很可能连接到了错误的网络或配置错误的端点。请仔细检查端点 URL 和任何 API 密钥。如果 eth_call 返回空结果或错误，请验证合约地址、函数选择器和参数编码。常见错误是使用错误的小数位数或未将地址填充到 32 字节。对于 eth_getLogs，如果收到关于区块范围的错误，请缩小范围或使用支持更大查询的提供商。

速率限制通常表现为 HTTP 429 或 JSON-RPC 错误 -32000。请实现指数退避并考虑使用多个端点。如果方法未找到（-32601），端点可能不支持该方法；请查阅提供商的文档。对于持续存在的问题，请查阅 Hyperliquid RPC 端点（RPC Assistant） 页面或 OnFinality Learn 中心 获取相关指南。

• 链 ID 意外：检查端点 URL 和网络。
• eth_call 错误：验证地址、选择器和参数填充。
• eth_getLogs 范围错误：缩小区块范围或切换提供商。
• 速率限制：实现退避并使用多个端点。
• 方法未找到：确认提供商支持该方法。

后续步骤与更多资源

现在你可以读取 HyperEVM 状态了，接下来可以探索原生 HyperCore API 以获取市场和账户数据。Hyperliquid 预言机价格与构建者拍卖 指南解释了预言机价格如何通过 Info API 暴露。有关支持网络的完整列表，请参阅 Hyperliquid 网络页面。如果你需要可靠的 RPC 访问，可以考虑 OnFinality RPC 定价 或 API 服务 以获取托管端点。

要深入了解性能和端点选择，请阅读 Hyperliquid RPC 延迟：HyperEVM 与原生 API 文章。有关速率限制的具体信息，Hyperliquid API 速率限制 指南提供了详细阈值。请始终针对你自己的用例进行测试，并使用上面的结果表格进行测量。

• 探索 HyperCore Info 和 Exchange API 以获取市场数据。
• 查看 Hyperliquid 网络页面以了解支持的链。
• 考虑使用托管 RPC 提供商以应对生产工作负载。
• 使用结果表格测量你自己的端点性能。