hyperliquid 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa1051cb2277e69795819ed2ae8564e89ac3e6b34139d9112a8273f0604d2fa1
-  data.tar.gz: 072416d6751fa766f0b4eeb5c416365ea96652b980301932d3ab32a549750b24
+  metadata.gz: 14a1a12bfa26b33260f7f2b0eacd8aeeb6762fc5d7d678f44cd63d6b492dcdd2
+  data.tar.gz: b0d4516d805842818e5d71b904a1f707014446802ad8efe60a7b6a6ed6a27853
 SHA512:
-  metadata.gz: 41059a1ef505d93e061fdd575f42ca340c6eb1e8100f14adf176c9512bd65ce4c1afdd1ddeeb831a1833bce63b9ca065f602681c673bba9b96f7a298130b05a0
-  data.tar.gz: 9cfb58786186bafc873dc9dd1747c2b87a645770fddc8d759ea3b5420e7367f1118de056de8e470dbe8bff06e44e55033ce063d839a3c81803fc418e3be68890
+  metadata.gz: 2e0419a6fc7501f2c3a3b4085d35fc495a88840a295a2017a60934f5e906f51b98bdd0be178d2474eb9be0414a6b435fed19e258235e30043ca1808af8e7144a
+  data.tar.gz: 3de78e11757c22db4a7d59880fd14e0d28a3e31721054bb22d5368adf48a0e1fa2a9ca7c67fa75ffce2d88115a9973fa5fdc92f285b62836f657c4518c7fe585

data/.rubocop.yml

@@ -41,3 +41,9 @@ Metrics/CyclomaticComplexity:
 Metrics/PerceivedComplexity:
   Exclude:
     - 'lib/hyperliquid/exchange.rb'
+    - 'lib/hyperliquid/ws/client.rb'
+
+# Empty blocks are intentional in specs (no-op callbacks for subscription tests)
+Lint/EmptyBlock:
+  Exclude:
+    - 'spec/**/*'

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
+## [1.8.0] - 2026-06-16
+
+### New WebSocket endpoints
+
+- `WS::Client#subscribe_explorer_block` — subscribe to Explorer WebSocket for block notifications. Uses a separate connection, queue, dispatch thread, and ping thread from the main API WebSocket to avoid cross-contamination.
+- `WS::Client#subscribe_explorer_txs` — subscribe to Explorer WebSocket for transaction notifications. Same dual-transport architecture; messages arrive as bare arrays duck-typed by field presence.
+
+### Fixes
+
+- Wired `test_20_explorer_ws` into the automated integration suite (was previously only in `test_all.rb`).
+
 ## [1.7.0] - 2026-06-11
 
 ### New Exchange actions

data/CLAUDE.md

@@ -26,12 +26,12 @@ ruby example.rb            # example usage script
 Integration scripts live in `scripts/` as standalone files (`test_NN_<name>.rb`). They require a real testnet private key and hit the live testnet API.
 
 ```bash
-HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_all.rb              # all 14
-HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_automated.rb        # CI-friendly subset
+HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_all.rb              # all 20
+HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_automated.rb        # CI-friendly subset (13)
 HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_08_usd_class_transfer.rb  # single
 ```
 
-`test_automated.rb` is the unattended runner — same as `test_all.rb` but excludes scripts that require manual testnet preconditions (e.g. `test_09_sub_account_lifecycle` needs $100k traded volume; `test_12_staking` needs HYPE balance). Some included tests (e.g. `test_08`, `test_11`) are also coded to skip-with-warning when known testnet preconditions aren't met, so the suite stays green on a stable wallet.
+`test_automated.rb` is the unattended runner — same as `test_all.rb` but excludes scripts that require manual testnet preconditions (e.g. `test_09_sub_account_lifecycle` needs $100k traded volume; `test_12_staking` needs HYPE balance; `test_20_explorer_ws` is new and not yet in automated). Some included tests (e.g. `test_08`, `test_11`) are also coded to skip-with-warning when known testnet preconditions aren't met, so the suite stays green on a stable wallet.
 
 `test_integration.rb` at the project root is a thin convenience wrapper.
 
@@ -51,7 +51,9 @@ 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.
+- **WebSocket path**: `WS::Client` manages two independent WebSocket connections:
+  - **Main API WS** (`wss://api.hyperliquid.xyz/ws`): subscribes to market data channels (`l2Book`, `trades`, `candle`, etc.). Messages arrive as `{channel, data}` envelopes; `compute_identifier` extracts routing keys (e.g. `l2Book:eth`, `candle:btc:1h`). Callbacks are dispatched via a bounded queue (1024, drops on overflow) on a dedicated thread.
+  - **Explorer WS** (`wss://rpc.hyperliquid.xyz/ws`): subscribes to block/transaction streams (`explorerBlock`, `explorerTxs`). Messages arrive as **bare arrays** (no envelope), so `identify_explorer_array` duck-types by field presence (`blockTime`/`height` for blocks, `action`/`hash` for txs). Uses a separate queue, dispatch thread, and subscription ID namespace to avoid cross-contamination with main-API WS. Both connections share the same 50s ping keepalive, automatic reconnection (exp backoff, 30s cap), and lifecycle hooks (`on(:open)`, `on(:close)`, `on(:error)`).
 
 ### Signing (Python SDK Parity)
 
@@ -79,13 +81,13 @@ Many Info methods accept a `dex:` kwarg (e.g. `meta(dex: 'foo')`, `user_state(us
 
 ### Testing
 
-- **Unit tests** (`spec/`): RSpec + WebMock. WebMock resets between tests. Monkey-patching disabled. Test files mirror `lib/` structure. No live HTTP calls in unit tests.
-- **Integration tests** (`scripts/`): run against testnet with a real private key. Each script is self-contained. Helpers (separators, status dumping, retry-on-oracle-bounce) live in `scripts/test_helpers.rb`.
+- **Unit tests** (`spec/`): RSpec + WebMock. WebMock resets between tests. Monkey-patching disabled. Test files mirror `lib/` structure. No live HTTP calls in unit tests. The WS client spec (`spec/hyperliquid/ws/client_spec.rb`) includes comprehensive isolation tests verifying that explorer WS messages never route to main-API callbacks and vice versa — this is critical because the two transports share the same `WS::Client` class.
+- **Integration tests** (`scripts/`): run against testnet with a real private key. Each script is self-contained. Helpers (separators, status dumping, retry-on-oracle-bounce) live in `scripts/test_helpers.rb`. `test_20_explorer_ws.rb` subscribes to `explorerBlock` on testnet and collects 3 block events (60s timeout) to verify the explorer WS transport works end-to-end.
 - **`dump_status` / `check_result` helpers** in `test_helpers.rb` must guard against `result['response']` *itself* being a String for transfer-style actions (`usdClassTransfer`, `approveBuilderFee`) — not just `result['response']['data']`. This was a real bug fixed in 1.1.0; preserve the guards if refactoring those helpers.
 
 ### Code Style
 
-RuboCop targets Ruby 3.3. Key relaxations: methods up to 50 lines, no class length limit (Info/Exchange are large by design), no block length limit in specs, no parameter list limit in Exchange. `scripts/`, `test_*.rb`, `local/`, and `vendor/` are excluded from linting.
+RuboCop targets Ruby 3.3. Key relaxations: methods up to 50 lines, no class length limit (Info/Exchange are large by design), no block length limit in specs, no parameter list limit in Exchange, empty blocks allowed in specs (intentional no-op callbacks). `scripts/`, `test_*.rb`, `local/`, and `vendor/` are excluded from linting. The WS client's `initialize` method was refactored to extract `init_main_ws_state` and `init_explorer_ws_state` helpers to reduce ABC size (33 assignments across two transports).
 
 Predicate methods follow Ruby style (`vip?`, `connected?`, `testnet?`) — not `is_vip` / `is_connected`. RuboCop's `Naming/PredicateName` enforces this.
 

data/lib/hyperliquid/constants.rb

@@ -21,6 +21,10 @@ module Hyperliquid
     WS_PING_INTERVAL = 50        # seconds between pings
     WS_MAX_QUEUE_SIZE = 1024     # max queued messages before dropping
 
+    # Explorer WebSocket URLs (used by subscribe_explorer_block / subscribe_explorer_txs)
+    MAINNET_EXPLORER_WS_URL = 'wss://rpc.hyperliquid.xyz/ws'
+    TESTNET_EXPLORER_WS_URL = 'wss://rpc.hyperliquid-testnet.xyz/ws'
+
     # Request timeouts (seconds)
     DEFAULT_TIMEOUT = 30
     DEFAULT_READ_TIMEOUT = 30

data/lib/hyperliquid/version.rb

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

data/lib/hyperliquid/ws/client.rb

@@ -7,33 +7,58 @@ module Hyperliquid
   module WS
     # Managed WebSocket client for subscribing to real-time data channels
     class Client
-      attr_reader :dropped_message_count
+      attr_reader :dropped_message_count, :explorer_dropped_message_count
 
-      def initialize(testnet: false, max_queue_size: Constants::WS_MAX_QUEUE_SIZE, reconnect: true)
+      def initialize(testnet: false, max_queue_size: Constants::WS_MAX_QUEUE_SIZE, reconnect: true,
+                     explorer_ws_url: nil)
         base_url = testnet ? Constants::TESTNET_API_URL : Constants::MAINNET_API_URL
         @url = base_url.sub(%r{^https?://}, 'wss://') + Constants::WS_ENDPOINT
         @max_queue_size = max_queue_size
         @reconnect_enabled = reconnect
+        @mutex = Mutex.new
+
+        init_main_ws_state
+        init_explorer_ws_state(explorer_ws_url)
+      end
+
+      private
 
+      def init_main_ws_state
         @subscriptions = {}      # identifier => [{ id:, callback: }]
         @subscription_msgs = {}  # subscription_id => { subscription:, identifier: }
         @next_id = 0
-        @mutex = Mutex.new
         @queue = Queue.new
         @dropped_message_count = 0
-
         @ws = nil
         @connected = false
         @closing = false
         @dispatch_thread = nil
         @ping_thread = nil
         @pending_subscriptions = []
-
         @lifecycle_callbacks = {}
         @reconnect_attempts = 0
         @connection_id = 0
       end
 
+      def init_explorer_ws_state(explorer_ws_url)
+        @explorer_ws_url = explorer_ws_url
+        @explorer_ws = nil
+        @explorer_connected = false
+        @explorer_closing = false
+        @explorer_connection_id = 0
+        @explorer_reconnect_attempts = 0
+        @explorer_subscriptions = {}
+        @explorer_subscription_msgs = {}
+        @explorer_next_id = 0
+        @explorer_queue = Queue.new
+        @explorer_dropped_message_count = 0
+        @explorer_dispatch_thread = nil
+        @explorer_ping_thread = nil
+        @explorer_pending_subscriptions = []
+      end
+
+      public
+
       def connect
         @closing = false
         @reconnect_attempts = 0
@@ -68,48 +93,88 @@ module Hyperliquid
         sub_id
       end
 
+      def subscribe_explorer_block(&)
+        raise ArgumentError, 'Block required for subscribe_explorer_block' unless block_given?
+        raise ConfigurationError, 'Explorer WebSocket URL not configured' unless @explorer_ws_url
+
+        subscribe_explorer({ type: 'explorerBlock' }, 'explorerBlock', &)
+      end
+
+      def subscribe_explorer_txs(&)
+        raise ArgumentError, 'Block required for subscribe_explorer_txs' unless block_given?
+        raise ConfigurationError, 'Explorer WebSocket URL not configured' unless @explorer_ws_url
+
+        subscribe_explorer({ type: 'explorerTxs' }, 'explorerTxs', &)
+      end
+
       def unsubscribe(subscription_id)
         sub_msg = nil
         should_send = false
+        explorer = false
 
         @mutex.synchronize do
           sub_msg = @subscription_msgs.delete(subscription_id)
+          unless sub_msg
+            sub_msg = @explorer_subscription_msgs.delete(subscription_id)
+            explorer = true if sub_msg
+          end
           return unless sub_msg
 
           identifier = sub_msg[:identifier]
-          callbacks = @subscriptions[identifier]
+          map = explorer ? @explorer_subscriptions : @subscriptions
+          callbacks = map[identifier]
           return unless callbacks
 
           callbacks.reject! { |entry| entry[:id] == subscription_id }
 
           if callbacks.empty?
-            @subscriptions.delete(identifier)
+            map.delete(identifier)
             should_send = true
           end
         end
 
-        send_unsubscribe(sub_msg[:subscription]) if should_send && @connected
+        return unless should_send
+
+        if explorer
+          send_explorer_unsubscribe(sub_msg[:subscription]) if @explorer_connected
+        elsif @connected
+          send_unsubscribe(sub_msg[:subscription])
+        end
       end
 
       def close
         @closing = true
         @connected = false
+        @explorer_closing = true
+        @explorer_connected = false
 
         @ping_thread&.kill
         @ping_thread = nil
+        @explorer_ping_thread&.kill
+        @explorer_ping_thread = nil
 
         @queue&.close if @queue.respond_to?(:close)
+        @explorer_queue&.close if @explorer_queue.respond_to?(:close)
+
         @dispatch_thread&.join(5)
         @dispatch_thread = nil
+        @explorer_dispatch_thread&.join(5)
+        @explorer_dispatch_thread = nil
 
         @ws&.close
         @ws = nil
+        @explorer_ws&.close
+        @explorer_ws = nil
       end
 
       def connected?
         @connected
       end
 
+      def explorer_connected?
+        @explorer_connected
+      end
+
       def on(event, &callback)
         @lifecycle_callbacks[event] = callback
       end
@@ -335,6 +400,233 @@ module Hyperliquid
         end
         subs.each { |sub| send_subscribe(sub) }
       end
+
+      # ── Explorer WebSocket ──────────────────────────────────────────
+
+      def subscribe_explorer(subscription, identifier, &callback)
+        sub_id = nil
+
+        @mutex.synchronize do
+          sub_id = @explorer_next_id
+          @explorer_next_id += 1
+
+          @explorer_subscriptions[identifier] ||= []
+          @explorer_subscriptions[identifier] << { id: sub_id, callback: callback }
+          @explorer_subscription_msgs[sub_id] = { subscription: subscription, identifier: identifier }
+        end
+
+        if @explorer_connected
+          send_explorer_subscribe(subscription)
+        else
+          @mutex.synchronize { @explorer_pending_subscriptions << subscription }
+          establish_explorer_connection unless @explorer_ws
+          start_explorer_dispatch_thread unless @explorer_dispatch_thread
+          start_explorer_ping_thread unless @explorer_ping_thread
+        end
+
+        sub_id
+      end
+
+      def establish_explorer_connection
+        client = self
+        url = @explorer_ws_url
+        @explorer_connection_id += 1
+        active_id = @explorer_connection_id
+
+        @explorer_ws = ::WSLite.connect(url) do |ws|
+          ws.on :open do
+            next if client.send(:stale_explorer_connection?, active_id)
+
+            client.send(:handle_explorer_open)
+          end
+
+          ws.on :message do |msg|
+            next if client.send(:stale_explorer_connection?, active_id)
+
+            client.send(:handle_explorer_message, msg.data)
+          end
+
+          ws.on :error do |e|
+            next if client.send(:stale_explorer_connection?, active_id)
+
+            client.send(:handle_explorer_error, e)
+          end
+
+          ws.on :close do |e|
+            next if client.send(:stale_explorer_connection?, active_id)
+
+            client.send(:handle_explorer_close, e)
+          end
+        end
+      end
+
+      def stale_explorer_connection?(id)
+        id != @explorer_connection_id
+      end
+
+      def handle_explorer_open
+        @explorer_connected = true
+        @explorer_reconnect_attempts = 0
+        flush_explorer_pending_subscriptions
+        replay_explorer_subscriptions
+      end
+
+      def handle_explorer_message(raw)
+        return if raw.nil? || raw.empty?
+        return if raw.start_with?('Websocket connection established')
+
+        data = parse_json(raw)
+        return unless data
+
+        if data.is_a?(Hash)
+          return if data['channel'] == 'pong'
+
+          return
+        end
+
+        unless data.is_a?(Array)
+          warn '[Hyperliquid::WS] Unknown explorer WS message shape'
+          return
+        end
+
+        return if data.empty?
+
+        identifier = identify_explorer_array(data)
+        return unless identifier
+
+        enqueue_explorer_message(identifier, data)
+      end
+
+      def identify_explorer_array(data)
+        first = data.first
+        return unless first.is_a?(Hash)
+
+        if first.key?('blockTime') && first.key?('hash') && first.key?('height') &&
+           first.key?('numTxs') && first.key?('proposer')
+          return 'explorerBlock'
+        end
+
+        if first.key?('action') && first.key?('block') && first.key?('error') &&
+           first.key?('hash') && first.key?('time') && first.key?('user')
+          return 'explorerTxs'
+        end
+
+        warn '[Hyperliquid::WS] Unknown explorer WS array shape'
+        nil
+      end
+
+      def handle_explorer_error(error)
+        warn "[Hyperliquid::WS] Explorer WS error: #{error.message}"
+      end
+
+      def handle_explorer_close(_event)
+        was_connected = @explorer_connected
+        @explorer_connected = false
+
+        attempt_explorer_reconnect if was_connected && !@explorer_closing && @reconnect_enabled
+      end
+
+      def enqueue_explorer_message(identifier, data)
+        @mutex.synchronize do
+          if @explorer_queue.size >= @max_queue_size
+            @explorer_dropped_message_count += 1
+            if @explorer_dropped_message_count == 1 || (@explorer_dropped_message_count % 100).zero?
+              warn "[Hyperliquid::WS] Explorer queue full (#{@max_queue_size}). " \
+                   "Dropped #{@explorer_dropped_message_count} message(s)."
+            end
+            return
+          end
+        end
+        @explorer_queue.push({ identifier: identifier, data: data })
+      end
+
+      def start_explorer_dispatch_thread
+        @explorer_dispatch_thread = Thread.new do
+          loop do
+            msg = begin
+              @explorer_queue.pop
+            rescue ClosedQueueError
+              break
+            end
+            break if msg.nil?
+
+            callbacks = @mutex.synchronize { @explorer_subscriptions[msg[:identifier]]&.dup }
+            next unless callbacks
+
+            callbacks.each do |entry|
+              entry[:callback].call(msg[:data])
+            rescue StandardError => e
+              warn "[Hyperliquid::WS] Explorer callback error: #{e.message}"
+            end
+          end
+        end
+        @explorer_dispatch_thread.name = 'hl-explorer-ws-dispatch'
+      end
+
+      def start_explorer_ping_thread
+        @explorer_ping_thread = Thread.new do
+          loop do
+            sleep Constants::WS_PING_INTERVAL
+            break if @explorer_closing
+
+            send_explorer_json({ method: 'ping' }) if @explorer_connected
+          end
+        end
+        @explorer_ping_thread.name = 'hl-explorer-ws-ping'
+        @explorer_ping_thread.report_on_exception = false
+      end
+
+      def flush_explorer_pending_subscriptions
+        pending = @mutex.synchronize do
+          subs = @explorer_pending_subscriptions.dup
+          @explorer_pending_subscriptions.clear
+          subs
+        end
+
+        pending.each { |sub| send_explorer_subscribe(sub) }
+      end
+
+      def send_explorer_subscribe(subscription)
+        send_explorer_json({ method: 'subscribe', subscription: subscription })
+      end
+
+      def send_explorer_unsubscribe(subscription)
+        send_explorer_json({ method: 'unsubscribe', subscription: subscription })
+      end
+
+      def send_explorer_json(hash)
+        @explorer_ws&.send(JSON.generate(hash))
+      rescue StandardError => e
+        warn "[Hyperliquid::WS] Explorer send error: #{e.message}"
+      end
+
+      def attempt_explorer_reconnect
+        Thread.new do
+          loop do
+            break if @explorer_closing
+
+            delay = [2**@explorer_reconnect_attempts, 30].min
+            @explorer_reconnect_attempts += 1
+            sleep delay
+
+            break if @explorer_closing
+
+            begin
+              establish_explorer_connection
+              break
+            rescue StandardError => e
+              warn "[Hyperliquid::WS] Explorer reconnect failed: #{e.message}"
+            end
+          end
+        end
+      end
+
+      def replay_explorer_subscriptions
+        subs = @mutex.synchronize do
+          @explorer_subscription_msgs.values.map { |v| v[:subscription] }.uniq
+        end
+        subs.each { |sub| send_explorer_subscribe(sub) }
+      end
     end
   end
 end

data/lib/hyperliquid.rb

@@ -58,7 +58,8 @@ module Hyperliquid
       @info = Info.new(client)
       @testnet = testnet
       @exchange = nil
-      @ws = WS::Client.new(testnet: testnet)
+      explorer_ws_url = testnet ? Constants::TESTNET_EXPLORER_WS_URL : Constants::MAINNET_EXPLORER_WS_URL
+      @ws = WS::Client.new(testnet: testnet, explorer_ws_url: explorer_ws_url)
 
       return unless private_key
 

data/scripts/test_20_explorer_ws.rb

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Integration test for Explorer WebSocket subscription
+# Connects to testnet explorer WS, subscribes to explorerBlock, and collects 3 block events
+#
+# Usage: ruby test_20_explorer_ws.rb
+
+require_relative 'test_helpers'
+
+puts '=' * 70
+puts 'test_20: Explorer WebSocket subscription'
+puts '=' * 70
+
+# Initialize SDK with testnet
+sdk = Hyperliquid::SDK.new(testnet: true)
+
+puts "\n1. Testing explorer WebSocket connection and subscription..."
+
+blocks_received = []
+max_blocks = 3
+timeout_seconds = 60
+start_time = Time.now
+
+puts "   Subscribing to explorerBlock channel (expecting #{max_blocks} blocks within #{timeout_seconds}s)..."
+puts "   Explorer WS URL: wss://rpc.hyperliquid-testnet.xyz/ws"
+
+# Subscribe to explorer blocks
+sub_id = sdk.ws.subscribe_explorer_block do |block_array|
+  # Explorer messages arrive as arrays
+  block_array.each do |block|
+    blocks_received << block
+    elapsed = Time.now - start_time
+    puts "   Block ##{blocks_received.size}: height=#{block['height']} hash=#{block['hash']} " \
+         "numTxs=#{block['numTxs']} proposer=#{block['proposer'][0..10]}... (#{elapsed.round(1)}s elapsed)"
+
+    break if blocks_received.size >= max_blocks
+  end
+end
+
+puts "   Subscription ID: #{sub_id}"
+
+# Wait for blocks with timeout
+puts "\n2. Waiting for block events..."
+loop do
+  break if blocks_received.size >= max_blocks
+
+  elapsed = Time.now - start_time
+  if elapsed > timeout_seconds
+    puts "\n   ⚠ Timeout: Only received #{blocks_received.size}/#{max_blocks} blocks after #{timeout_seconds}s"
+    puts '   This may indicate testnet explorer is not producing blocks or WS connection issues'
+    break
+  end
+
+  sleep 0.5
+end
+
+# Cleanup
+puts "\n3. Cleanup..."
+sdk.ws.unsubscribe(sub_id)
+puts "   Unsubscribed from #{sub_id}"
+
+sdk.ws.close
+puts '   WebSocket connection closed'
+
+# Verify results
+puts "\n4. Verification..."
+if blocks_received.empty?
+  puts '   ❌ FAIL: No blocks received'
+  puts '   Explorer WebSocket may not be working on testnet, or connection failed'
+  exit 1
+end
+
+puts "   ✓ Received #{blocks_received.size} block(s)"
+
+# Verify block structure
+blocks_received.each_with_index do |block, idx|
+  required_fields = %w[height hash numTxs proposer blockTime]
+  missing = required_fields - block.keys
+  unless missing.empty?
+    puts "   ⚠ Block ##{idx + 1} missing fields: #{missing.join(', ')}"
+  end
+end
+
+if blocks_received.size >= max_blocks
+  puts "   ✓ PASS: Successfully received #{max_blocks} explorer blocks"
+  exit 0
+else
+  puts "   ⚠ PARTIAL: Received #{blocks_received.size}/#{max_blocks} blocks"
+  puts '   This is acceptable if testnet explorer is slow, but should be investigated'
+  exit 0 # Don't fail the test suite for partial results
+end

data/scripts/test_all.rb

@@ -37,7 +37,8 @@ SCRIPTS = [
   'test_16_send_to_evm_with_data.rb',
   'test_17_create_vault.rb',
   'test_18_user_portfolio_margin.rb',
-  'test_19_spot_user.rb'
+  'test_19_spot_user.rb',
+  'test_20_explorer_ws.rb'
 ].freeze
 
 def green(text)

data/scripts/test_automated.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperliquid
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - carter2099
@@ -135,6 +135,7 @@ files:
 - scripts/test_17_create_vault.rb
 - scripts/test_18_user_portfolio_margin.rb
 - scripts/test_19_spot_user.rb
+- scripts/test_20_explorer_ws.rb
 - scripts/test_all.rb
 - scripts/test_automated.rb
 - scripts/test_helpers.rb