hyperliquid 1.7.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa1051cb2277e69795819ed2ae8564e89ac3e6b34139d9112a8273f0604d2fa1
-  data.tar.gz: 072416d6751fa766f0b4eeb5c416365ea96652b980301932d3ab32a549750b24
+  metadata.gz: 9a6d420027ac68a2d2959293fd9735798e80ad39f484dd2f43f1f808d5964944
+  data.tar.gz: 89c4e1688d7a5ac9d4cba3a214de798ec333161a0d6053abeac5d6d4da4916f3
 SHA512:
-  metadata.gz: 41059a1ef505d93e061fdd575f42ca340c6eb1e8100f14adf176c9512bd65ce4c1afdd1ddeeb831a1833bce63b9ca065f602681c673bba9b96f7a298130b05a0
-  data.tar.gz: 9cfb58786186bafc873dc9dd1747c2b87a645770fddc8d759ea3b5420e7367f1118de056de8e470dbe8bff06e44e55033ce063d839a3c81803fc418e3be68890
+  metadata.gz: 7ca76a9847766153f734661dd91f9d62bb1c87e2c43aacb4dd63e20904a1f3ddff505b4e8f92eb80b0bf6624e584560c121a901e2a1865617062b0e1cc1963c4
+  data.tar.gz: 43d32462a0350f7f733f50cd1190b6acfde8647b141665998bf5e1fb6f6b3fc24c348ba04dbb6ca35d3aef8e8bce0770445ab44991e65d566c58a9ce01c928c3

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/.ruby-version

@@ -1 +1 @@
-3.4.9
+3.4.10

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
+## [1.9.0] - 2026-08-31
+
+### New Exchange actions
+
+- `Exchange#activate_outcome_deployer(is_deactivate:)` activates or deactivates a HIP-4 outcome deployer.
+
+### New Info methods
+
+- `Info#outcome_templates` retrieves HIP-4 prediction-market deployer templates.
+- `Info#usdc_routing` retrieves the active USDC deposit and withdrawal routing configuration.
+
+### Extended API support
+
+- Added fast-cancel support to `Exchange#cancel`, `Exchange#cancel_by_cloid`, and `l2Book` WebSocket subscriptions.
+- Added always-place support to individual `Exchange#modify_order` and `Exchange#batch_modify` entries.
+- Added optional sub-account routing to `Exchange#usd_class_transfer`.
+- Added optional trigger and stop-price details to `Exchange#twap_order`.
+- Added optional destination routing to `Exchange#reserve_request_weight`.
+- Added optional DEX selection to `Info#margin_table`.
+
+### Tooling
+
+- Added weekly Dependabot checks for Bundler and GitHub Actions dependencies.
+- Updated the repository Ruby version to 3.4.10.
+
+## [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,8 +26,8 @@ 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 (14)
 HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_08_usd_class_transfer.rb  # single
 ```
 
@@ -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,19 +81,19 @@ 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.
 
 ### CI
 
-GitHub Actions (`.github/workflows/main.yml`): runs `bundle exec rake` (tests + lint) on the Ruby matrix defined in that workflow, for pushes to `main` and on all PRs. The release workflow creates GitHub releases from `CHANGELOG.md` on version tags.
+GitHub Actions (`.github/workflows/main.yml`): runs `bundle exec rake` (tests + lint) on the Ruby matrix defined in that workflow, for pushes to `main` and on all PRs. The release workflow creates GitHub releases from `CHANGELOG.md` on version tags. Dependabot checks Bundler and GitHub Actions dependencies weekly with a 14-day default cooldown; Bundler major updates use a 30-day cooldown.
 
 ## Release Flow
 

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/exchange.rb

@@ -144,13 +144,17 @@ module Hyperliquid
     # @param coin [String] Asset symbol
     # @param oid [Integer] Order ID
     # @param vault_address [String, nil] Vault address for vault trading (optional)
+    # @param fast [Boolean, nil] Whether to use fast cancel (optional)
     # @return [Hash] Cancel response
-    def cancel(coin:, oid:, vault_address: nil)
+    def cancel(coin:, oid:, vault_address: nil, fast: nil)
       nonce = timestamp_ms
 
+      cancel_entry = { a: asset_index(coin), o: oid }
+      cancel_entry[:f] = true if fast
+
       action = {
         type: 'cancel',
-        cancels: [{ a: asset_index(coin), o: oid }]
+        cancels: [cancel_entry]
       }
 
       signature = @signer.sign_l1_action(
@@ -165,14 +169,18 @@ module Hyperliquid
     # @param coin [String] Asset symbol
     # @param cloid [Cloid, String] Client order ID
     # @param vault_address [String, nil] Vault address for vault trading (optional)
+    # @param fast [Boolean, nil] Whether to use fast cancel (optional)
     # @return [Hash] Cancel response
-    def cancel_by_cloid(coin:, cloid:, vault_address: nil)
+    def cancel_by_cloid(coin:, cloid:, vault_address: nil, fast: nil)
       nonce = timestamp_ms
       cloid_raw = normalize_cloid(cloid)
 
+      cancel_entry = { asset: asset_index(coin), cloid: cloid_raw }
+      cancel_entry[:f] = true if fast
+
       action = {
         type: 'cancelByCloid',
-        cancels: [{ asset: asset_index(coin), cloid: cloid_raw }]
+        cancels: [cancel_entry]
       }
 
       signature = @signer.sign_l1_action(
@@ -233,15 +241,17 @@ module Hyperliquid
     # @param reduce_only [Boolean] Reduce-only flag (default: false)
     # @param cloid [Cloid, String, nil] Client order ID for the modified order (optional)
     # @param vault_address [String, nil] Vault address for vault trading (optional)
+    # @param always_place [Boolean, nil] Always place the order even if cancel fails (optional)
     # @return [Hash] Modify response
     def modify_order(oid:, coin:, is_buy:, size:, limit_px:,
                      order_type: { limit: { tif: 'Gtc' } },
-                     reduce_only: false, cloid: nil, vault_address: nil)
+                     reduce_only: false, cloid: nil, vault_address: nil, always_place: nil)
       batch_modify(
         modifies: [{
           oid: oid, coin: coin, is_buy: is_buy, size: size,
           limit_px: limit_px, order_type: order_type,
-          reduce_only: reduce_only, cloid: cloid
+          reduce_only: reduce_only, cloid: cloid,
+          always_place: always_place
         }],
         vault_address: vault_address
       )
@@ -249,7 +259,7 @@ module Hyperliquid
 
     # Modify multiple orders at once
     # @param modifies [Array<Hash>] Array of modify hashes with keys:
-    #   :oid, :coin, :is_buy, :size, :limit_px, :order_type, :reduce_only, :cloid
+    #   :oid, :coin, :is_buy, :size, :limit_px, :order_type, :reduce_only, :cloid, :always_place
     # @param vault_address [String, nil] Vault address for vault trading (optional)
     # @return [Hash] Batch modify response
     def batch_modify(modifies:, vault_address: nil)
@@ -265,7 +275,9 @@ module Hyperliquid
           reduce_only: m[:reduce_only] || false,
           cloid: m[:cloid]
         )
-        { oid: normalize_oid(m[:oid]), order: order_wire }
+        entry = { oid: normalize_oid(m[:oid]), order: order_wire }
+        entry[:a] = true if m[:always_place]
+        entry
       end
 
       action = {
@@ -420,19 +432,25 @@ module Hyperliquid
     # Move USDC between perp and spot accounts
     # @param amount [String, Numeric] Amount to transfer
     # @param to_perp [Boolean] True to move to perp, false to move to spot
+    # @param sub_account [String, nil] Optional sub-account address (0x-prefixed hex).
+    #   When provided, the transfer targets the sub-account rather than the
+    #   master account; the suffix ` subaccount:<address>` is appended to the
+    #   signed amount string (mirrors TS SDK v0.33.1's amount union shape).
     # @return [Hash] Transfer response
-    def usd_class_transfer(amount:, to_perp:)
+    def usd_class_transfer(amount:, to_perp:, sub_account: nil)
       nonce = timestamp_ms
+      amount_str = amount.to_s
+      amount_str = "#{amount_str} subaccount:#{sub_account}" if sub_account
       action = {
         type: 'usdClassTransfer',
         signatureChainId: '0x66eee',
         hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
-        amount: amount.to_s,
+        amount: amount_str,
         toPerp: to_perp,
         nonce: nonce
       }
       signature = @signer.sign_user_signed_action(
-        { amount: amount.to_s, toPerp: to_perp, nonce: nonce },
+        { amount: amount_str, toPerp: to_perp, nonce: nonce },
         'HyperliquidTransaction:UsdClassTransfer',
         Signing::EIP712::USD_CLASS_TRANSFER_TYPES
       )
@@ -1211,8 +1229,9 @@ module Hyperliquid
     # @param minutes [Integer] TWAP duration in minutes (5..1440)
     # @param randomize [Boolean] Randomize order timing
     # @param vault_address [String, nil] Vault address if acting on behalf of a vault
+    # @param details [Hash, nil] Optional trigger/stop price config: { t: { p:, a: } | nil, s: <UnsignedDecimal> | nil }
     # @return [Hash] Exchange response — on success `response.data.status.running.twapId`
-    def twap_order(coin:, is_buy:, size:, reduce_only:, minutes:, randomize:, vault_address: nil)
+    def twap_order(coin:, is_buy:, size:, reduce_only:, minutes:, randomize:, vault_address: nil, details: nil)
       nonce = timestamp_ms
       action = {
         type: 'twapOrder',
@@ -1225,6 +1244,7 @@ module Hyperliquid
           t: randomize
         }
       }
+      action[:details] = details unless details.nil?
       signature = @signer.sign_l1_action(
         action, nonce,
         vault_address: vault_address,
@@ -1251,10 +1271,12 @@ module Hyperliquid
 
     # Reserve additional rate-limited actions for a fee (`reserveRequestWeight` L1 action).
     # @param weight [Integer] Amount of request weight to reserve
+    # @param destination [String, nil] Address of an existing user to reserve the weight for; nil omits the field
     # @return [Hash] Exchange response
-    def reserve_request_weight(weight:)
+    def reserve_request_weight(weight:, destination: nil)
       nonce = timestamp_ms
       action = { type: 'reserveRequestWeight', weight: weight }
+      action[:destination] = destination unless destination.nil?
       signature = @signer.sign_l1_action(
         action, nonce,
         expires_after: @expires_after
@@ -1338,6 +1360,20 @@ module Hyperliquid
       post_action(action, signature, nonce, nil)
     end
 
+    # Activate or deactivate the signer as an outcome deployer
+    # (`activateOutcomeDeployer` L1 action, HIP-4).
+    # @param is_deactivate [Boolean] True to deactivate, false to activate
+    # @return [Hash] Exchange response
+    def activate_outcome_deployer(is_deactivate:)
+      nonce = timestamp_ms
+      action = { type: 'activateOutcomeDeployer', isDeactivate: is_deactivate }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
     # Finalize the link between a HyperCore spot token and an ERC-20 contract on
     # HyperEVM (`finalizeEvmContract` L1 action). `input` selects the verification method
     # and is passed through verbatim — accepts a Hash `{ create: { nonce: <int> } }` for an

data/lib/hyperliquid/info.rb

@@ -375,9 +375,12 @@ module Hyperliquid
 
     # Retrieve the margin requirements table for a given id
     # @param id [Integer] Margin table id
+    # @param dex [String, nil] DEX name (empty string for main dex); nil omits the field
     # @return [Hash] Keys: description (String), marginTiers (Array of { lowerBound, maxLeverage })
-    def margin_table(id)
-      @client.post(Constants::INFO_ENDPOINT, { type: 'marginTable', id: id })
+    def margin_table(id, dex: nil)
+      body = { type: 'marginTable', id: id }
+      body[:dex] = dex unless dex.nil?
+      @client.post(Constants::INFO_ENDPOINT, body)
     end
 
     # Retrieve the vaults a user is leading
@@ -522,6 +525,20 @@ module Hyperliquid
       @client.post(Constants::INFO_ENDPOINT, { type: 'settledOutcome', outcome: outcome.to_i })
     end
 
+    # Retrieve outcome templates for HIP-4 prediction market deployers
+    # @return [Array<Hash>] Array of templates, each with id, role (standaloneOutcome
+    #   with sideNames), name, description (both with {keyword} placeholders), and
+    #   keywords (array of [name, type] where type is "dateTime", "date", "string", or "hlPerp")
+    def outcome_templates
+      @client.post(Constants::INFO_ENDPOINT, { type: 'outcomeTemplates' })
+    end
+
+    # Retrieve USDC transfer routing configuration
+    # @return [Hash] Hash with depositRoute and withdrawalRoute, each "bridge" or "cctp"
+    def usdc_routing
+      @client.post(Constants::INFO_ENDPOINT, { type: 'usdcRouting' })
+    end
+
     # Retrieve a user's funding history
     # @param user [String]
     # @param start_time [Integer]

data/lib/hyperliquid/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hyperliquid
-  VERSION = '1.7.0'
+  VERSION = '1.9.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.9.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