View Source Hyperliquid.Transport.Rpc (hyperliquid v0.2.2)

JSON-RPC transport for Hyperliquid EVM.

Provides low-level JSON-RPC communication with the Hyperliquid EVM RPC endpoint. Supports all standard Ethereum JSON-RPC methods plus Hyperliquid-specific methods.

Usage 

# Use default RPC endpoint from config
{:ok, block_number} = Rpc.call("eth_blockNumber", [])

# Use a named RPC endpoint from the registry
{:ok, block_number} = Rpc.call("eth_blockNumber", [], rpc_name: :alchemy)

# Use custom RPC endpoint (direct URL override)
{:ok, block_number} = Rpc.call("eth_blockNumber", [], rpc_url: "https://custom-rpc.xyz")

# Batch requests
{:ok, results} = Rpc.batch([
  {"eth_blockNumber", []},
  {"eth_chainId", []}
])

Configuration

The RPC transport uses Hyperliquid.Config for default URL configuration:

  • Config.rpc_base/0 - Base URL for RPC requests (defaults to official Hyperliquid RPC)

You can override the RPC URL per-request using the :rpc_url option.

Summary

Types

batch_result()
rpc_opts()
rpc_result()

Functions

batch(requests, opts \\ [])

Make a batch of JSON-RPC calls.

batch!(requests, opts \\ [])

Make a batch of JSON-RPC calls. Raises on error.

call(method, params \\ [], opts \\ [])

Make a JSON-RPC call.

call!(method, params \\ [], opts \\ [])

Make a JSON-RPC call. Raises on error.

get_rpc_url(opts \\ [])

Get the current RPC URL being used.

ping(opts \\ [])

Check if the RPC endpoint is reachable.

ping!(opts \\ [])

Check if the RPC endpoint is reachable. Raises on error.

subscribe(subscription_type, params \\ [], opts \\ [])

Subscribe to events via WebSocket (if supported).

subscribe!(subscription_type, params \\ [], opts \\ [])

Subscribe to events via WebSocket. Raises on error.

unsubscribe(subscription_id, opts \\ [])

Unsubscribe from events.

unsubscribe!(subscription_id, opts \\ [])

Unsubscribe from events. Raises on error.

Types

Link to this type

batch_result()

View Source 
@type batch_result() :: {:ok, [any()]} | {:error, Hyperliquid.Error.t()}
Link to this type

rpc_opts()

View Source 
@type rpc_opts() :: [
  rpc_url: String.t(),
  rpc_name: atom() | String.t(),
  timeout: non_neg_integer(),
  recv_timeout: non_neg_integer()
]
Link to this type

rpc_result()

View Source 
@type rpc_result() :: {:ok, any()} | {:error, Hyperliquid.Error.t()}

Functions

Link to this function

batch(requests, opts \\ [])

View Source 
@spec batch([{String.t(), list()}], rpc_opts()) :: batch_result()

Make a batch of JSON-RPC calls.

Parameters

  • requests: List of {method, params} tuples
  • opts: Optional configuration (same as call/3)

Returns

  • {:ok, results} - List of results in same order as requests
  • {:error, %Error{}} - Error with details

Examples 

{:ok, [block_number, chain_id]} = Rpc.batch([
  {"eth_blockNumber", []},
  {"eth_chainId", []}
])
Link to this function

batch!(requests, opts \\ [])

View Source 
@spec batch!([{String.t(), list()}], rpc_opts()) :: [any()]

Make a batch of JSON-RPC calls. Raises on error.

Link to this function

call(method, params \\ [], opts \\ [])

View Source 
@spec call(String.t(), list(), rpc_opts()) :: rpc_result()

Make a JSON-RPC call.

Parameters

  • method: RPC method name (e.g., "eth_blockNumber")
  • params: List of parameters for the method
  • opts: Optional configuration
    • :rpc_url - Override default RPC URL (highest priority)
    • :rpc_name - Use a named RPC from the registry (e.g., :alchemy, :quicknode)
    • :timeout - Request timeout in ms
    • :recv_timeout - Receive timeout in ms

Returns

  • {:ok, result} - RPC result
  • {:error, %Error{}} - Error with details

Examples 

{:ok, "0x1234"} = Rpc.call("eth_blockNumber", [])

{:ok, balance} = Rpc.call("eth_getBalance", ["0x...", "latest"])

{:ok, block} = Rpc.call("eth_getBlockByNumber", ["0x1", true],
  rpc_name: :alchemy
)

{:ok, block} = Rpc.call("eth_getBlockByNumber", ["0x1", true],
  rpc_url: "https://custom-rpc.xyz"
)
Link to this function

call!(method, params \\ [], opts \\ [])

View Source 
@spec call!(String.t(), list(), rpc_opts()) :: any()

Make a JSON-RPC call. Raises on error.

Link to this function

get_rpc_url(opts \\ [])

View Source 
@spec get_rpc_url(rpc_opts()) :: String.t()

Get the current RPC URL being used.

Parameters

  • opts: Optional configuration with :rpc_url override

Returns

  • String with the RPC URL
Link to this function

ping(opts \\ [])

View Source 
@spec ping(rpc_opts()) :: {:ok, boolean()} | {:error, Hyperliquid.Error.t()}

Check if the RPC endpoint is reachable.

Parameters

  • opts: Optional configuration

Returns

  • {:ok, true} - Endpoint is reachable
  • {:error, %Error{}} - Error with details
Link to this function

ping!(opts \\ [])

View Source 
@spec ping!(rpc_opts()) :: boolean()

Check if the RPC endpoint is reachable. Raises on error.

Link to this function

subscribe(subscription_type, params \\ [], opts \\ [])

View Source 
@spec subscribe(String.t(), list(), rpc_opts()) :: rpc_result()

Subscribe to events via WebSocket (if supported).

Note: This requires a WebSocket connection to the RPC endpoint. Not all RPC endpoints support subscriptions.

Parameters

  • subscription_type: Type of subscription (e.g., "newHeads", "logs")
  • params: Optional parameters for the subscription
  • opts: Optional configuration

Returns

  • {:ok, subscription_id} - Subscription ID
  • {:error, %Error{}} - Error with details
Link to this function

subscribe!(subscription_type, params \\ [], opts \\ [])

View Source 
@spec subscribe!(String.t(), list(), rpc_opts()) :: any()

Subscribe to events via WebSocket. Raises on error.

Link to this function

unsubscribe(subscription_id, opts \\ [])

View Source 
@spec unsubscribe(String.t(), rpc_opts()) :: rpc_result()

Unsubscribe from events.

Parameters

  • subscription_id: ID returned from subscribe
  • opts: Optional configuration

Returns

  • {:ok, true} - Successfully unsubscribed
  • {:error, %Error{}} - Error with details
Link to this function

unsubscribe!(subscription_id, opts \\ [])

View Source 
@spec unsubscribe!(String.t(), rpc_opts()) :: any()

Unsubscribe from events. Raises on error.