hyperliquid 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6baba398ac6a839785cea71c83f96b7a7e339f200604288f9920f25b5a49ed0
-  data.tar.gz: 0b1961c8b84802e88730421516d27b58e5e14bb055ac190a82e2c0881c692333
+  metadata.gz: c7969eed04a0b822b7be2c29c3ab57f97f077eaf8ed245bc48cb4916fd6b5836
+  data.tar.gz: d37e1acbf31a1e26454071ede7c83fcccf842bf9524835def63a652e77fff1af
 SHA512:
-  metadata.gz: a7f8886eede6df8fcde833b490733def438945d115c4d3664d397c037d97c5e785e13793885e984baeaf696f156f1f59f614c8f5d0f384e47cbc7d1b1d85708e
-  data.tar.gz: 518cdc5f65b6fd3de3c15a96bf6e67049af1c5935e9a67a9e56b01d45d43984506d9e30804ec01a9723fe2ff9e1306b2ee32bbb1959dfead2a4f6b036c2c2d49
+  metadata.gz: 1a7bc66c9acd82975bb1e5929d2f4b77469c5e52b3c9824f7ce5306ad642c1e065531d6f4c20134cdab85c350b2f694736c5a414ee6e7a564d35abc658ed1074
+  data.tar.gz: 9898cba2cbf564dff73f950a29423dd5f42ab2fddf62458418d365546893dabdc5f3ddf159f1af31c7e6254ff02aeaa1a77ca0c63f6198931ee291319daaab82

data/.ruby-version

@@ -1 +1 @@
-3.4.8
+3.4.9

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
+## [1.4.0] - 2026-05-05
+
+### New Exchange actions
+
+- `Exchange#send_to_evm_with_data(destination:, token:, amount:, data:, ...)` — user-signed; transfers Core assets to HyperEVM with arbitrary calldata for `ICoreReceiveWithData` contracts. Adds `SEND_TO_EVM_WITH_DATA_TYPES` (first user-signed action using `bytes`). Includes signature-parity regression specs against captured `eth_account` fixtures to lock down eth gem's `bytes` handling.
+- `Exchange#agent_send_asset(...)` — agent-signed counterpart to `send_asset` (destination must equal the agent's principal).
+- `Exchange#hip3_liquidator_transfer(dex:, usdc:, to_dex:)` — deposit/withdraw to an HIP-3 DEX backstop in 1e-6 quote-token units.
+- `Exchange#borrow_lend(token:, action:, amount:, is_isolated:)` — HIP-2 supply/withdraw/repay/borrow (L1 action). Companion to the four HIP-2 info methods. `amount` is nullable for full-position ops.
+- `Exchange#sub_account_modify(sub_account_user:, name:)` — rename a sub-account (L1 action).
+- `Exchange#link_staking_user(staking_user:, ...)` — link staking + trading accounts for fee discount (user-signed EIP-712). Adds `LINK_STAKING_USER_TYPES`.
+
+## [1.3.0] - 2026-04-30
+
+### New transport
+
+- Explorer RPC connection (`rpc.hyperliquid.xyz` / `rpc.hyperliquid-testnet.xyz`, endpoint `/explorer`). `Client` gains optional `explorer_base_url:` and `target: :explorer` routing, with a lazily-built second Faraday connection sharing the default retry/timeout config. The SDK wires this up automatically based on `testnet:`.
+- New `Hyperliquid::ConfigurationError` raised when `target: :explorer` is used on a client constructed without an explorer URL.
+
+### New Info endpoints
+
+- `Info#tx_details(hash)` — explorer `txDetails` lookup
+- `Info#user_details(user)` — explorer `userDetails` lookup
+
+### New Exchange actions
+
+- `Exchange#claim_rewards` — L1 `claimRewards`
+- `Exchange#set_display_name(display_name:)` — L1 `setDisplayName` (max 20 chars; `""` clears)
+- `Exchange#register_referrer(code:)` — L1 `registerReferrer`
+- `Exchange#top_up_isolated_only_margin(coin:, leverage:, vault_address:)` — L1 `topUpIsolatedOnlyMargin`
+- `Exchange#vault_modify(vault_address:, allow_deposits:, always_close_on_withdraw:)` — L1 `vaultModify`
+- `Exchange#vault_distribute(vault_address:, usd:)` — L1 `vaultDistribute`
+
 ## [1.2.0] - 2026-04-27
 
 ### New Info endpoints

data/CLAUDE.md

@@ -50,6 +50,7 @@ Hyperliquid.new(...)
 
 - **Info path**: method builds `{ type: 'someType', ... }` body → `Client` POSTs to `/info` → parsed JSON returned.
 - **Exchange path**: method builds action payload → `Signer` generates EIP-712 signature over msgpack-encoded action → `Client` POSTs signed payload to `/exchange` → parsed JSON returned.
+- **Explorer RPC path** (`tx_details`, `user_details`): a separate base URL (`rpc.hyperliquid.xyz` / `rpc.hyperliquid-testnet.xyz`) with endpoint `/explorer`. `Client` holds a second Faraday connection for this, built lazily on first use; methods opt in via `client.post(EXPLORER_ENDPOINT, body, target: :explorer)`. The SDK wires this up automatically based on `testnet:`. Calling `target: :explorer` on a `Client` constructed without `explorer_base_url:` raises `ConfigurationError`. Don't add a public connection accessor — `target:` is the contract.
 - **WebSocket path**: `WS::Client` manages a persistent WSS connection with subscription tracking, automatic reconnection (exp backoff, 30s cap), 50s ping keepalive, and a bounded message queue (1024, drops oldest on overflow). Subscriptions are identified by a canonical key and dispatched via callbacks on a dedicated thread.
 
 ### Signing (Python SDK Parity)
@@ -62,6 +63,8 @@ The signing chain in `lib/hyperliquid/signing/` must exactly match the official
 
 Any change to signing must maintain parity with the Python SDK or transactions will be rejected by the exchange.
 
+User-signed actions (`usd_send`, `withdraw_from_bridge`, `send_to_evm_with_data`, etc.) use direct EIP-712 typed-data signing with the `HyperliquidSignTransaction` domain (chain ID 421614) — not the phantom-agent flow. Each has a typed-data spec in `Signing::EIP712`. The `eth` gem's typed-data signer handles primitive types (`string`, `uint*`, `address`, `bool`) and dynamic `bytes` correctly — `send_to_evm_with_data` was the first to use `bytes`, and its spec includes a fixture-based signature parity test against `eth_account` to lock that in. When adding new user-signed actions with non-string types, add a similar fixture to catch eth-gem regressions.
+
 ### Numeric Conversion
 
 - **`float_to_wire`** (in Exchange): converts to string with 8-decimal precision, validates rounding tolerance (`1e-12`), normalizes trailing zeros. No scientific notation.

data/lib/hyperliquid/client.rb

@@ -21,17 +21,24 @@ module Hyperliquid
     }.freeze
 
     # Initialize a new HTTP client
-    # @param base_url [String] The base URL for the API
+    # @param base_url [String] The base URL for the default API (info/exchange)
     # @param timeout [Integer] Request timeout in seconds (default: Constants::DEFAULT_TIMEOUT)
     # @param retry_enabled [Boolean] Whether to enable retry logic (default: false)
-    def initialize(base_url:, timeout: Constants::DEFAULT_TIMEOUT, retry_enabled: false)
+    # @param explorer_base_url [String, nil] Optional base URL for the explorer RPC (used by
+    #   tx_details / user_details). When nil, calls with target: :explorer raise ConfigurationError.
+    def initialize(base_url:, timeout: Constants::DEFAULT_TIMEOUT, retry_enabled: false,
+                   explorer_base_url: nil)
       @retry_enabled = retry_enabled
-      @connection = build_connection(base_url, timeout)
+      @timeout = timeout
+      @explorer_base_url = explorer_base_url
+      @connection = build_connection(base_url)
+      @explorer_connection = nil
     end
 
     # Make a POST request to the API
     # @param endpoint [String] The API endpoint to make the request to
     # @param body [Hash] The request body as a hash (default: {})
+    # @param target [Symbol] Which connection to use; :default (info/exchange) or :explorer (RPC)
     # @return [Hash, String] The parsed JSON response or raw response body
     # @raise [NetworkError] When connection fails
     # @raise [TimeoutError] When request times out
@@ -41,8 +48,10 @@ module Hyperliquid
     # @raise [RateLimitError] When API returns 429 status
     # @raise [ServerError] When API returns 5xx status
     # @raise [ClientError] When API returns unexpected status
-    def post(endpoint, body = {})
-      response = @connection.post(endpoint) do |req|
+    # @raise [ConfigurationError] When target: :explorer is requested but no explorer_base_url was configured
+    def post(endpoint, body = {}, target: :default)
+      connection = connection_for(target)
+      response = connection.post(endpoint) do |req|
         req.headers['Content-Type'] = 'application/json'
         req.body = body.to_json unless body.empty?
       end
@@ -60,9 +69,24 @@ module Hyperliquid
 
     private
 
-    def build_connection(base_url, timeout)
+    def connection_for(target)
+      case target
+      when :default
+        @connection
+      when :explorer
+        unless @explorer_base_url
+          raise ConfigurationError,
+                'Explorer RPC URL not configured; pass explorer_base_url: when constructing the Client'
+        end
+        @explorer_connection ||= build_connection(@explorer_base_url)
+      else
+        raise ArgumentError, "Unknown post target: #{target.inspect} (expected :default or :explorer)"
+      end
+    end
+
+    def build_connection(base_url)
       Faraday.new(url: base_url) do |conn|
-        conn.options.timeout = timeout
+        conn.options.timeout = @timeout
         conn.options.read_timeout = Constants::DEFAULT_READ_TIMEOUT
         conn.request :retry, DEFAULT_RETRY_OPTIONS if @retry_enabled
       end

data/lib/hyperliquid/constants.rb

@@ -7,9 +7,14 @@ module Hyperliquid
     MAINNET_API_URL = 'https://api.hyperliquid.xyz'
     TESTNET_API_URL = 'https://api.hyperliquid-testnet.xyz'
 
+    # Explorer RPC URLs (used by Info#tx_details and Info#user_details)
+    MAINNET_RPC_URL = 'https://rpc.hyperliquid.xyz'
+    TESTNET_RPC_URL = 'https://rpc.hyperliquid-testnet.xyz'
+
     # API endpoints
     INFO_ENDPOINT = '/info'
     EXCHANGE_ENDPOINT = '/exchange'
+    EXPLORER_ENDPOINT = '/explorer'
 
     # WebSocket
     WS_ENDPOINT = '/ws'

data/lib/hyperliquid/errors.rb

@@ -38,4 +38,8 @@ module Hyperliquid
 
   # Error for WebSocket issues
   class WebSocketError < Error; end
+
+  # Error for SDK configuration issues (e.g. calling an explorer-only method
+  # on a Client that wasn't configured with an explorer_base_url)
+  class ConfigurationError < Error; end
 end

data/lib/hyperliquid/exchange.rb

@@ -793,6 +793,266 @@ module Hyperliquid
       post_action(action, signature, nonce, nil)
     end
 
+    # Claim accrued referral-program rewards (`claimRewards` L1 action).
+    # @return [Hash] Exchange response
+    def claim_rewards
+      nonce = timestamp_ms
+      action = { type: 'claimRewards' }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Set the leaderboard display name (`setDisplayName` L1 action).
+    # Pass an empty string to remove the existing display name.
+    # @param display_name [String] Display name (max 20 characters)
+    # @return [Hash] Exchange response
+    def set_display_name(display_name:)
+      nonce = timestamp_ms
+      action = { type: 'setDisplayName', displayName: display_name }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Register a new referral code for this account (`registerReferrer` L1 action).
+    # Distinct from `set_referrer`, which records a referrer the account was referred *by*.
+    # @param code [String] Referral code to create (1–20 characters)
+    # @return [Hash] Exchange response
+    def register_referrer(code:)
+      nonce = timestamp_ms
+      action = { type: 'registerReferrer', code: code }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Top up isolated margin to target a specific leverage (`topUpIsolatedOnlyMargin` L1 action).
+    # @param coin [String] Asset symbol (perps only)
+    # @param leverage [String, Numeric] Target leverage (sent as float string per protocol)
+    # @param vault_address [String, nil] Vault address if acting on behalf of a vault
+    # @return [Hash] Exchange response
+    def top_up_isolated_only_margin(coin:, leverage:, vault_address: nil)
+      nonce = timestamp_ms
+      action = {
+        type: 'topUpIsolatedOnlyMargin',
+        asset: asset_index(coin),
+        leverage: leverage.to_s
+      }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        vault_address: vault_address,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, vault_address)
+    end
+
+    # Modify a vault's configuration (`vaultModify` L1 action).
+    # Only the vault leader may submit this. Either flag may be omitted (sent as null).
+    # @param vault_address [String] Vault address being modified
+    # @param allow_deposits [Boolean, nil] Allow follower deposits (nil = unchanged)
+    # @param always_close_on_withdraw [Boolean, nil] Always close positions on withdrawal (nil = unchanged)
+    # @return [Hash] Exchange response
+    def vault_modify(vault_address:, allow_deposits: nil, always_close_on_withdraw: nil)
+      nonce = timestamp_ms
+      action = {
+        type: 'vaultModify',
+        vaultAddress: vault_address,
+        allowDeposits: allow_deposits,
+        alwaysCloseOnWithdraw: always_close_on_withdraw
+      }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Distribute funds from a vault to followers (`vaultDistribute` L1 action).
+    # Only the vault leader may submit this. Pass `usd: 0` to close the vault.
+    # @param vault_address [String] Vault address
+    # @param usd [Numeric] USD amount to distribute (scaled to integer cents-of-cents internally)
+    # @return [Hash] Exchange response
+    def vault_distribute(vault_address:, usd:)
+      nonce = timestamp_ms
+      action = {
+        type: 'vaultDistribute',
+        vaultAddress: vault_address,
+        usd: float_to_usd_int(usd)
+      }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Borrow, lend, supply, or withdraw HIP-2 borrow/lend assets (`borrowLend` L1 action).
+    # Companion to the four HIP-2 info methods (`borrow_lend_user_state` etc.).
+    # @param operation [String] One of 'supply', 'withdraw', 'repay', 'borrow'
+    # @param token [Integer] HIP-2 token ID (e.g. 0 for USDC)
+    # @param amount [String, Numeric, nil] Amount to operate on; pass nil to use the full position
+    # @param vault_address [String, nil] Vault address if acting on behalf of a vault
+    # @return [Hash] Exchange response
+    def borrow_lend(operation:, token:, amount: nil, vault_address: nil)
+      nonce = timestamp_ms
+      action = {
+        type: 'borrowLend',
+        operation: operation,
+        token: token,
+        amount: amount&.to_s
+      }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        vault_address: vault_address,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, vault_address)
+    end
+
+    # Rename a sub-account (`subAccountModify` L1 action).
+    # @param sub_account_user [String] Sub-account wallet address to rename
+    # @param name [String] New sub-account name (1–16 characters)
+    # @return [Hash] Exchange response
+    def sub_account_modify(sub_account_user:, name:)
+      nonce = timestamp_ms
+      action = {
+        type: 'subAccountModify',
+        subAccountUser: sub_account_user,
+        name: name
+      }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Link a staking account to a trading account for fee-discount attribution
+    # (`linkStakingUser` user-signed action).
+    # The trading user initiates with `is_finalize: false`; the staking user finalizes
+    # the permanent link with `is_finalize: true`. The `user` field is the *other*
+    # account address in each direction.
+    # @param user [String] The counterpart account address (staking address when initiating, trading when finalizing)
+    # @param is_finalize [Boolean] False = trading user initiates, true = staking user finalizes
+    # @return [Hash] Exchange response
+    def link_staking_user(user:, is_finalize:)
+      nonce = timestamp_ms
+      action = {
+        type: 'linkStakingUser',
+        signatureChainId: '0x66eee',
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
+        user: user,
+        isFinalize: is_finalize,
+        nonce: nonce
+      }
+      signature = @signer.sign_user_signed_action(
+        { user: user, isFinalize: is_finalize, nonce: nonce },
+        'HyperliquidTransaction:LinkStakingUser',
+        Signing::EIP712::LINK_STAKING_USER_TYPES
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Move assets between DEX instances on behalf of an agent's principal
+    # (`agentSendAsset` L1 action). Unlike `send_asset` (which is user-signed),
+    # this is signed by an agent and the destination must equal the agent's
+    # principal address. `source_dex`/`destination_dex` accept "" (default USDC
+    # perp DEX) and "spot" (spot trading) per protocol convention.
+    # @param destination [String] Destination wallet address (must match the agent's principal)
+    # @param source_dex [String] Source DEX identifier
+    # @param destination_dex [String] Destination DEX identifier
+    # @param token [String] Token in "tokenName:tokenId" format
+    # @param amount [String, Numeric] Amount to send
+    # @param from_sub_account [String] Source sub-account address, or empty string for the principal
+    # @return [Hash] Exchange response
+    def agent_send_asset(destination:, source_dex:, destination_dex:, token:, amount:,
+                         from_sub_account: '')
+      nonce = timestamp_ms
+      action = {
+        type: 'agentSendAsset',
+        destination: destination,
+        sourceDex: source_dex,
+        destinationDex: destination_dex,
+        token: token,
+        amount: amount.to_s,
+        fromSubAccount: from_sub_account,
+        nonce: nonce
+      }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Deposit to or withdraw from an HIP-3 DEX's backstop liquidator
+    # (`hip3LiquidatorTransfer` L1 action). `ntl` is denominated in 1e-6 quote
+    # tokens and the protocol requires it to be a multiple of 1_000_000_000
+    # (i.e. $1,000 increments).
+    # @param dex [String] HIP-3 DEX identifier
+    # @param ntl [Integer] Notional amount in 1e-6 quote tokens (multiple of 1_000_000_000)
+    # @param is_deposit [Boolean] True to deposit into the backstop, false to withdraw
+    # @return [Hash] Exchange response
+    def hip3_liquidator_transfer(dex:, ntl:, is_deposit:)
+      nonce = timestamp_ms
+      action = { type: 'hip3LiquidatorTransfer', dex: dex, ntl: ntl, isDeposit: is_deposit }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Transfer an asset from Core to HyperEVM with an arbitrary calldata payload
+    # (`sendToEvmWithData` user-signed action). Intended for `ICoreReceiveWithData`
+    # contracts that react atomically to the deposit. `data` accepts a hex string
+    # ('0x' or '0x...'); the EIP-712 signer hashes it as `bytes`.
+    # `destination_recipient` is NOT lowercased — `address_encoding` may be
+    # 'base58' for non-EVM target chains, where lowercasing would corrupt the value.
+    # @param token [String] Token symbol (e.g. "USDC")
+    # @param amount [String, Numeric] Amount as UnsignedDecimal (NOT wei); coerced via to_s
+    # @param source_dex [String] Source DEX identifier (e.g. "spot")
+    # @param destination_recipient [String] Recipient address on the destination chain (hex or base58)
+    # @param address_encoding [String] One of 'hex' or 'base58'
+    # @param destination_chain_id [Integer] Target EVM chain id (e.g. 998 for HyperEVM testnet)
+    # @param gas_limit [Integer] Gas limit for the destination EVM call
+    # @param data [String] ABI calldata hex string ('0x' for empty payload)
+    # @return [Hash] Exchange response
+    def send_to_evm_with_data(token:, amount:, source_dex:, destination_recipient:,
+                              address_encoding:, destination_chain_id:, gas_limit:, data: '0x')
+      nonce = timestamp_ms
+      action = {
+        type: 'sendToEvmWithData',
+        signatureChainId: '0x66eee',
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
+        token: token,
+        amount: amount.to_s,
+        sourceDex: source_dex,
+        destinationRecipient: destination_recipient,
+        addressEncoding: address_encoding,
+        destinationChainId: destination_chain_id.to_i,
+        gasLimit: gas_limit.to_i,
+        data: data,
+        nonce: nonce
+      }
+      signature = @signer.sign_user_signed_action(
+        { token: token, amount: amount.to_s, sourceDex: source_dex,
+          destinationRecipient: destination_recipient, addressEncoding: address_encoding,
+          destinationChainId: destination_chain_id.to_i, gasLimit: gas_limit.to_i,
+          data: data, nonce: nonce },
+        'HyperliquidTransaction:SendToEvmWithData',
+        Signing::EIP712::SEND_TO_EVM_WITH_DATA_TYPES
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
     # Clear the asset metadata cache
     # Call this if metadata has been updated
     def reload_metadata!

data/lib/hyperliquid/info.rb

@@ -631,6 +631,32 @@ module Hyperliquid
       body[:endTime] = end_time if end_time
       @client.post(Constants::INFO_ENDPOINT, body)
     end
+
+    # ============================
+    # Info: Explorer RPC
+    # ============================
+    # The methods below are routed via a separate base URL (the explorer RPC) rather
+    # than the canonical /info endpoint. They require the Client to have been
+    # constructed with explorer_base_url:; the SDK does this automatically based on
+    # the testnet: flag.
+
+    # Retrieve transaction details by transaction hash
+    # @param hash [String] Transaction hash (66-char 0x-prefixed hex)
+    # @return [Hash] Hash with type ('txDetails') and tx (transaction details)
+    def tx_details(hash)
+      @client.post(Constants::EXPLORER_ENDPOINT, { type: 'txDetails', hash: hash }, target: :explorer)
+    end
+
+    # Retrieve a user's transaction history from the explorer
+    # @param user [String] Wallet address
+    # @return [Hash] Hash with type ('userDetails') and txs (Array of transaction details)
+    def user_details(user)
+      @client.post(
+        Constants::EXPLORER_ENDPOINT,
+        { type: 'userDetails', user: user.downcase },
+        target: :explorer
+      )
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/hyperliquid/signing/eip712.rb

@@ -121,6 +121,30 @@ module Hyperliquid
         ]
       }.freeze
 
+      LINK_STAKING_USER_TYPES = {
+        'HyperliquidTransaction:LinkStakingUser': [
+          { name: :hyperliquidChain, type: 'string' },
+          { name: :user, type: 'address' },
+          { name: :isFinalize, type: 'bool' },
+          { name: :nonce, type: 'uint64' }
+        ]
+      }.freeze
+
+      SEND_TO_EVM_WITH_DATA_TYPES = {
+        'HyperliquidTransaction:SendToEvmWithData': [
+          { name: :hyperliquidChain,     type: 'string' },
+          { name: :token,                type: 'string' },
+          { name: :amount,               type: 'string' },
+          { name: :sourceDex,            type: 'string' },
+          { name: :destinationRecipient, type: 'string' },
+          { name: :addressEncoding,      type: 'string' },
+          { name: :destinationChainId,   type: 'uint32' },
+          { name: :gasLimit,             type: 'uint64' },
+          { name: :data,                 type: 'bytes'  },
+          { name: :nonce,                type: 'uint64' }
+        ]
+      }.freeze
+
       class << self
         # Domain for L1 actions (orders, cancels, leverage, etc.)
         # @return [Hash] EIP-712 domain configuration

data/lib/hyperliquid/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hyperliquid
-  VERSION = '1.2.0'
+  VERSION = '1.4.0'
 end

data/lib/hyperliquid.rb

@@ -46,7 +46,13 @@ module Hyperliquid
     def initialize(testnet: false, timeout: Constants::DEFAULT_TIMEOUT, retry_enabled: false,
                    private_key: nil, expires_after: nil)
       base_url = testnet ? Constants::TESTNET_API_URL : Constants::MAINNET_API_URL
-      client = Client.new(base_url: base_url, timeout: timeout, retry_enabled: retry_enabled)
+      explorer_base_url = testnet ? Constants::TESTNET_RPC_URL : Constants::MAINNET_RPC_URL
+      client = Client.new(
+        base_url: base_url,
+        timeout: timeout,
+        retry_enabled: retry_enabled,
+        explorer_base_url: explorer_base_url
+      )
 
       @info = Info.new(client)
       @testnet = testnet

data/scripts/test_15_explorer.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 15: Explorer RPC (tx_details + user_details)
+#
+# Calls the explorer RPC for the wallet's recent transactions:
+#   1. user_details(wallet_address)  -> list of recent txs
+#   2. tx_details(first tx hash)     -> full details of one tx
+#
+# Requires HYPERLIQUID_PRIVATE_KEY (used to derive wallet address; no signing).
+# A wallet with no testnet activity at all will produce a soft warning rather
+# than fail — explorer testnet endpoint occasionally has its own state quirks.
+#
+# Usage:
+#   HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_15_explorer.rb
+
+require_relative 'test_helpers'
+
+separator('TEST 15: Explorer RPC (tx_details + user_details)')
+
+sdk = build_sdk
+
+begin
+  user_details_resp = sdk.info.user_details(sdk.exchange.address)
+rescue Hyperliquid::Error => e
+  puts red("user_details FAILED: #{e.class}: #{e.message}")
+  exit 1
+end
+
+unless user_details_resp.is_a?(Hash) && user_details_resp['type'] == 'userDetails'
+  puts red("user_details: unexpected response shape: #{user_details_resp.inspect}")
+  exit 1
+end
+
+txs = user_details_resp['txs'] || []
+puts green("user_details OK: #{txs.length} txs returned")
+
+if txs.empty?
+  puts 'No txs on this wallet — skipping tx_details lookup.'
+  test_passed('Test 15 explorer RPC')
+  exit 0
+end
+
+first_hash = txs.first['hash']
+unless first_hash.is_a?(String) && first_hash.start_with?('0x')
+  puts red("First tx hash missing or malformed: #{first_hash.inspect}")
+  exit 1
+end
+
+puts "Looking up tx_details for #{first_hash}..."
+begin
+  tx_resp = sdk.info.tx_details(first_hash)
+rescue Hyperliquid::Error => e
+  puts red("tx_details FAILED: #{e.class}: #{e.message}")
+  exit 1
+end
+
+unless tx_resp.is_a?(Hash) && tx_resp['type'] == 'txDetails'
+  puts red("tx_details: unexpected response shape: #{tx_resp.inspect}")
+  exit 1
+end
+
+tx = tx_resp['tx']
+unless tx.is_a?(Hash) && tx['hash'] == first_hash
+  puts red("tx_details: hash mismatch or missing tx: #{tx.inspect}")
+  exit 1
+end
+
+puts green("tx_details OK: action=#{tx.dig('action', 'type')} time=#{tx['time']}")
+
+test_passed('Test 15 explorer RPC')

data/scripts/test_16_send_to_evm_with_data.rb

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 16: sendToEvmWithData (user-signed exchange action)
+#
+# Mirrors the TS SDK's `tests/api/exchange/sendToEvmWithData.test.ts`:
+#   1. Top up spot USDC by 2 (via usd_class_transfer perp -> spot).
+#   2. Submit one real sendToEvmWithData action sending 1 USDC to 0x...01
+#      on HyperEVM testnet (chain 998) with empty calldata.
+#   3. Assert response is { status: 'ok', response: { type: 'default' } }.
+#
+# This funds-moving test sends 1 testnet USDC to 0x...01 (effectively burned —
+# no contract is there to redirect it). Same bar the TS SDK uses for its own
+# test suite.
+#
+# Skips with a warning if the wallet is on unified account (usd_class_transfer
+# is disabled in that mode and the top-up cannot run).
+#
+# Usage:
+#   HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_16_send_to_evm_with_data.rb
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 16: sendToEvmWithData')
+
+abstraction = sdk.info.user_abstraction(sdk.exchange.address)
+if abstraction == 'unifiedAccount'
+  puts "SKIPPED: Wallet has unified account active (abstraction=#{abstraction.inspect})."
+  puts '  usd_class_transfer top-up step is disabled by the exchange when balances are unified.'
+  test_passed('Test 16 sendToEvmWithData')
+  exit 0
+end
+
+puts 'Topping up spot USDC by $2 (perp -> spot)...'
+top_up = sdk.exchange.usd_class_transfer(amount: '2', to_perp: false)
+dump_status(top_up)
+if api_error?(top_up)
+  puts red('Top-up failed; aborting before sendToEvmWithData.')
+  test_passed('Test 16 sendToEvmWithData')
+  exit 1
+end
+puts green('Top-up successful.')
+puts
+
+wait_with_countdown(WAIT_SECONDS, 'Waiting before sendToEvmWithData...')
+
+puts 'Sending 1 USDC to 0x...01 on HyperEVM testnet (chain 998) with empty calldata...'
+result = sdk.exchange.send_to_evm_with_data(
+  token: 'USDC',
+  amount: '1',
+  source_dex: 'spot',
+  destination_recipient: '0x0000000000000000000000000000000000000001',
+  address_encoding: 'hex',
+  destination_chain_id: 998,
+  gas_limit: 200_000,
+  data: '0x'
+)
+
+if api_error?(result)
+  puts red("sendToEvmWithData FAILED: #{result.inspect}")
+  test_passed('Test 16 sendToEvmWithData')
+  exit 1
+end
+
+unless result.is_a?(Hash) && result['status'] == 'ok'
+  $test_failed = true
+  puts red("Unexpected status: #{result.inspect}")
+end
+
+response_type = result.dig('response', 'type')
+unless response_type == 'default'
+  $test_failed = true
+  puts red("Expected response.type 'default', got: #{response_type.inspect}")
+end
+
+puts green("sendToEvmWithData OK: status=ok, response.type=#{response_type}") unless $test_failed
+
+test_passed('Test 16 sendToEvmWithData')

data/scripts/test_all.rb

@@ -32,7 +32,9 @@ SCRIPTS = [
   'test_11_builder_fee.rb',
   'test_12_staking.rb',
   'test_13_ws_l2_book.rb',
-  'test_14_ws_candle.rb'
+  'test_14_ws_candle.rb',
+  'test_15_explorer.rb',
+  'test_16_send_to_evm_with_data.rb'
 ].freeze
 
 def green(text)

data/scripts/test_automated.rb

@@ -22,7 +22,8 @@ SCRIPTS = [
   'test_10_vault.rb',
   'test_11_builder_fee.rb',
   'test_13_ws_l2_book.rb',
-  'test_14_ws_candle.rb'
+  'test_14_ws_candle.rb',
+  'test_15_explorer.rb'
 ].freeze
 
 def green(text)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperliquid
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - carter2099
@@ -129,6 +129,8 @@ files:
 - scripts/test_12_staking.rb
 - scripts/test_13_ws_l2_book.rb
 - scripts/test_14_ws_candle.rb
+- scripts/test_15_explorer.rb
+- scripts/test_16_send_to_evm_with_data.rb
 - scripts/test_all.rb
 - scripts/test_automated.rb
 - scripts/test_helpers.rb