HyperEVM /evm vs /nanoreth: when to use each endpoint

This guide covers the two HyperEVM JSON-RPC paths: /evm and /nanoreth what each one returns, why both exist, and exactly when to use each.

TL;DR

Every Chainstack Hyperliquid node exposes the same HyperEVM state over two paths:

• /evm is the standard path. It behaves like any Ethereum JSON-RPC. The correct choice for dApps, wallets, contract calls, and transaction submission.
• /nanoreth is the full-data path. It includes system transactions. The correct choice for indexers, block explorers, analytics pipelines, and trace-level debugging.

Both paths are always active on the same node. Select per request by appending the path to the endpoint URL.

Prerequisite

• Hyperliquid Architecture

📖 This guide will cover HyperEVM in detail. If you wish to learn in detail about Hyperliquid and it’s architecture, dive into Hyperliquid HIPS and Hyperliquid Architecture

Why build on HyperEVM?

HyperEVM is embedded inside a purpose-built L1 financial system. Smart contracts on HyperEVM can read live order book depth, oracle prices, perp positions, and vault balances through precompiles without any external price feeds.

The HyperEVM is live. This is a major step toward the vision of housing all finance by bringing general-purpose programmability to Hyperliquid’s performant financial system. The initial mainnet release of the HyperEVM includes:

1. HyperEVM blocks built as part of L1 execution,… pic.twitter.com/sleqk1N7T5

— Hyper Foundation (@HyperFND) February 18, 2025

For developers, this means:

• no external oracle dependency for price data
• smart contracts that compose directly with live order book state
• a single consensus layer governing both trading execution and EVM finality
• familiar tooling: Foundry, Hardhat, ethers.js, viem all work without modification

What is HyperEVM?

Hyperliquid runs two execution environments under a shared HyperBFT consensus layer:

HyperCore

HyperCore is the native trading engine. It manages the on-chain Central Limit Order Book (CLOB), perpetuals execution, spot markets, margin logic, vault logic, and liquidations. Exposed via the /info and /exchange APIs.

🤔 For a detailed understanding of the /info and /exchange endpoints, refer to the Hyperliquid API blog.

HyperEVM

HyperEVM is EVM compatible execution layer, secured directly by HyperBFT consensus. It is a fork of the Cancun hardfork (without blobs) and supports EIP-1559. HYPE is the native gas token on HyperEVM. HYPE uses 18 decimals on both networks.

HyperEVM runs two block types simultaneously on a shared, incrementing block number sequence. This dual-block architecture decouples block speed from block size allowing users to have faster confirmations and builders to have more compute for batch operations, complex contracts etc.

Block type	Duration	Gas limit
Small blocks	1 second	2 million
Big blocks	60 seconds	30 million

The initial configuration is set conservatively, and throughput is expected to increase over successive technical upgrades

To use big blocks, submit:

{"type": "evmUserModify", "usingBigBlocks": true}

Because both layers share state, actions that happen in HyperCore can be reflected on the HyperEVM ledger.

/evm

The /evm path is the hl-node-compliant JSON-RPC interface. It speaks standard Ethereum JSON-RPC exactly as Ethereum tooling expects it. Any Ethereum library, pointed at this URL with chain ID 999 works without modification.

Block responses only contain user-signed EVM transactions. Protocol-generated system transactions are stripped out before the response is returned. This is intentional, most EVM tooling has no handling for unsigned protocol entries, and dApps have no use for them.

Chainstack exposes the /evm path with full standard Ethereum JSON-RPC method set available on Chainstack. For eg: fetch the latest block number to verify the connection is live.

import requests

url = "<https://hyperliquid-mainnet.core.chainstack.com/><KEY>/evm"

payload = {
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

🤔 Deploying a contract? Use big blocks. Set evmUserModify: usingBigBlocks: true on the HyperCore account first. Big blocks allow 30M gas vs 2M on small blocks. See the Chainstack guide on forking HyperEVM with Foundry.

/nanoreth

Before moving to /nanoreth, system transactions need to be understood first.

System transactions

HyperCore and HyperEVM share state under one consensus layer. When HyperCore processes an action that has an EVM-side effect eg: a HYPE bridge from HyperCore to HyperEVM, a spot token transfer, a liquidation event, HyperBFT injects a synthetic record into the EVM block to reflect that state change on the EVM ledger. These records look like transactions in block data, but they are not user-initiated. No private key signed them. The protocol generated them. These are system transactions.

System transactions always originate from one of these protocol-controlled addresses. Both appear frequently in full block data returned by /nanoreth.

• Bridge deposits: USDC or HYPE arriving from HyperCore into HyperEVM via the native transfer mechanism. The canonical native transfer address is 0x2222222222222222222222222222222222222222. Sending HYPE to this address moves it from HyperCore to HyperEVM
• Liquidation settlements: On-chain liquidation events from HyperCore reflected as EVM state changes
• Oracle writes: Price data and state written into HyperEVM from the L1 oracle layer
• Precompile-triggered writes: Initiated by smart contracts calling CoreWriter

Below is a system transaction as returned by /nanoreth on block 0x202e371.

{
  "hash":     "0xd41d8cd98f00b204e9800998ecf8427e...",
  "from":     "0x2222222222222222222222222222222222222222",
  "to":       "0xUserAddress...",    // HYPE recipient on EVM side
  "value":    "0x16345785d8a0000",   // 0.1 HYPE in wei
  "gasPrice": "0x0",                 // always zero, protocol-generated
  "gas":      "0x0",                 // always zero
  "input":    "0x",                  // no calldata
  "v": "0x0", "r": "0x0", "s": "0x0" // no ECDSA signature
}

With system transactions understood, /nanoreth makes immediate sense. It is the same JSON-RPC interface, on the same node, returning the same chain data with system transactions included in every block response.

Nanoreth is a high-performance Rust-based archive node implementation derived from the reth Ethereum client, adapted for HyperEVM. It reads raw block data from Hyperliquid’s real-time S3 stream, the same authoritative source the protocol itself uses. This gives it two capabilities that /evm does not provide:

• complete block data including system transactions
• full historical state from genesis with trace method support

Eg: Fetch the same block retrieved from /evm earlier, this time from /nanoreth. The transaction count in the response will be higher, system entries are now included.

curl -X POST <https://hyperliquid-mainnet.core.chainstack.com/><KEY>/nanoreth \\
  -H "Content-Type: application/json" \\
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBlockByNumber",
    "params": ["0x202e371", true],
    "id": 1
  }'

# transactions array now includes system tx:
{
  "number": "0x202e371",
  "transactions": [
    {
      "hash": "0xabc...",
      "from": "0x1234...",
      "gasPrice": "0x3b9aca00"   // user tx
    },
    {
      "hash": "0xdef...",
      "from": "0x2222222222222222222222222222222222222222",
      "gasPrice": "0x0",         // system tx — HYPE bridge deposit
      "v": "0x0", "r": "0x0", "s": "0x0"
    }
    // ... additional user txs
  ]
}

/evm vs /nanoreth

The two paths share the vast majority of the standard Ethereum JSON-RPC method set, since they run on the same node against the same chain state. The differences come down to:

• System transactions are stripped from all block and receipt responses. Any method that returns block contents will silently omit system entries
• Querying a system transaction hash on /evm returns null
• Transaction submission is available on /evm only, /nanoreth is a read path
• /nanoreth adds ****a complete block data with system transactions included, plus the full trace and debug method suite (debug_traceTransaction, trace_block, trace_replayTransaction, etc.)
• /nanoreth also provides full historical state from genesis, making eth_call usable at any past block number
• System transactions always carry gasPrice: 0x0

Method	/evm	/nanoreth
eth_getBlockByNumber / eth_getBlockByHash	transactions array excludes system tx	transactions array includes system tx
eth_getBlockTransactionCountByNumber / ByHash	count excludes system tx	count includes system tx
eth_getBlockReceipts	receipts array excludes system tx receipt	receipts array includes system tx receipt
eth_getTransactionReceipt for a system tx hash	returns null	returns the receipt
eth_getTransactionByHash for a system tx hash	returns the transaction	returns the transaction
eth_getSystemTxsByBlockNumber / ByHash	returns system txs	returns system txs
debug_* / trace_* / ots_* methods	unchanged	unchanged
All non-system-tx methods (regular blocks, txs, receipts, traces)	unchanged	unchanged

Refer to the Chainstack Hyperliquid Methods for a full endpoint and method availability matrix.

WebSockets

HyperEVM also exposes standard Ethereum WebSocket subscriptions. This is important because /evm and /nanoreth are not limited to HTTP JSON-RPC requests. Both paths support real-time subscriptions over WebSockets as well.

Polling blocks repeatedly with eth_blockNumber or fetching receipts in loops introduces latency and unnecessary RPC overhead. For real-time applications such as dashboards, bots, explorers, and indexing systems, WebSockets are the correct approach.

The WebSocket endpoint follows the same path distinction as HTTP:

/evm : wss://hyperliquid-mainnet.core.chainstack.com/YOUR_KEY/evm

/nanoreth : wss://hyperliquid-mainnet.core.chainstack.com/YOUR_KEY/nanoreth

📖 See the full method availability table on Chainstack docs for all websockets subscriptions.

Hyperliquid Builder Tools

Archive nodes and full historical data

• Nanoreth: Rust-based HyperEVM archive node implementation used for full historical indexing, tracing, and system transaction visibility.
• Dual Block Architecture: Official documentation explaining HyperEVM’s small-block and big-block execution model.

Smart contract development

These tools work against /evm exactly like Ethereum RPC infrastructure.

• Foundry: Smart contract development and deployment framework.
• Hardhat: Ethereum development environment fully compatible with HyperEVM.
• ethers.js: JavaScript Ethereum interaction library.
• viem: Type-safe TypeScript Ethereum interface.
• web3.py: Python Ethereum interaction library.
• Big Block Python SDK Example: Example showing how to enable big blocks for large deployments.

Blogs and guides

• Hyperliquid API Guide: Guide covering /info, /exchange, and WebSocket APIs.
• Hyperliquid Architecture Explained: Deep dive into HyperCore, HyperBFT, and execution architecture.
• Hyperliquid HyperBFT Explained: Consensus and accounting internals.
• /evm vs /nanoreth: Hyperliquid node configurations
• Forking HyperEVM with Foundry: Guide for local HyperEVM development and testing.
• Hyperliquid Methods Reference: Full RPC method compatibility and availability table.

Considerations

Choosing between /evm and /nanoreth is mostly about understanding whether your application needs protocol-level visibility or standard wallet-facing behavior.

Hash conventions: System transaction hashes differ between /evm and /nanoreth. If your system stores transaction hashes from one path and queries them on the other, lookups for system transactions will return null. Store the path alongside the hash, or normalize to one convention at ingestion time.

Block transaction counts: eth_getBlockTransactionCountByNumber returns different values on each path for any block containing system transactions. If your protocol logic uses transaction count as a signal, ensure you query the same path consistently.

Archive workloads on /nanoreth: /evm is optimized for application-facing workloads. Heavy historical workloads should use /nanoreth instead. This separation improves performance and avoids unnecessary protocol-level overhead for standard application traffic.

Rate limits: The public RPC at rpc.hyperliquid.xyz/evm is rate-limited to 100 requests per minute per IP which is suitable for experimentation. At that limit, a simple polling loop at 1-second intervals will hit the ceiling within two minutes. Any bot, indexer, or analytics pipeline needs a private endpoint.

Chainstack RPC infrastructure avoids rate-limit bottlenecks and provides more predictable latency.

Key management: All execution depends on private key signing. Compromised keys mean full account exposure. Use dedicated API wallets, hardware security modules, or vaults for production systems.

Conclusion

HyperEVM gives you two paths on the same node for a reason: application traffic and infrastructure workloads have different requirements, and a single interface cannot serve both well. /evm keeps standard Ethereum tooling working without modification. /nanoreth keeps indexers, explorers, and analytics pipelines from operating on incomplete data.

Both paths are available on every Chainstack Hyperliquid node, on the same endpoint, switchable per request. No separate connections, no additional configuration — append the path and you’re reading from whichever layer your application needs.

FAQ