hyperliquid 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6baba398ac6a839785cea71c83f96b7a7e339f200604288f9920f25b5a49ed0
-  data.tar.gz: 0b1961c8b84802e88730421516d27b58e5e14bb055ac190a82e2c0881c692333
+  metadata.gz: 3bb8af9ff28e902372f37910705473b980d432cf4a04485dbe5999e7fa6edc7e
+  data.tar.gz: e7176efc9fd95c1662b36ec7b8f5536192d8ce3e41624f9b341eca5e79de079a
 SHA512:
-  metadata.gz: a7f8886eede6df8fcde833b490733def438945d115c4d3664d397c037d97c5e785e13793885e984baeaf696f156f1f59f614c8f5d0f384e47cbc7d1b1d85708e
-  data.tar.gz: 518cdc5f65b6fd3de3c15a96bf6e67049af1c5935e9a67a9e56b01d45d43984506d9e30804ec01a9723fe2ff9e1306b2ee32bbb1959dfead2a4f6b036c2c2d49
+  metadata.gz: 79d01ffef7d490e185e191285dab90adcd339b03c8f2936ab8eaccb1fba6bc832a76aa49e2cee3db354608a5ce53e92afda6c6efec5d8b2cafc0c1e9a51f7b44
+  data.tar.gz: c313423aab3b257d81b7447c840502025f1a92cf857064c614678be2022b533ce7e85a89bedf0aaedd371c5781425962ee48b8f8c9ac7be98f3940b08c756510

data/.ruby-version

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

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
+## [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)

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,106 @@ 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
+
     # 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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hyperliquid
-  VERSION = '1.2.0'
+  VERSION = '1.3.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_all.rb

@@ -32,7 +32,8 @@ 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'
 ].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.3.0
 platform: ruby
 authors:
 - carter2099
@@ -129,6 +129,7 @@ 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_all.rb
 - scripts/test_automated.rb
 - scripts/test_helpers.rb