hyperliquid 0.6.0 → 1.0.0

data/lib/hyperliquid/ws/client.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+require 'ws_lite'
+require 'json'
+
+module Hyperliquid
+  module WS
+    # Managed WebSocket client for subscribing to real-time data channels
+    class Client
+      attr_reader :dropped_message_count
+
+      def initialize(testnet: false, max_queue_size: Constants::WS_MAX_QUEUE_SIZE, reconnect: true)
+        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
+
+        @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 connect
+        @closing = false
+        @reconnect_attempts = 0
+        establish_connection
+        start_dispatch_thread
+        start_ping_thread
+        self
+      end
+
+      def subscribe(subscription, &callback)
+        raise ArgumentError, 'Block required for subscribe' unless block_given?
+
+        identifier = subscription_identifier(subscription)
+        sub_id = nil
+
+        @mutex.synchronize do
+          sub_id = @next_id
+          @next_id += 1
+
+          @subscriptions[identifier] ||= []
+          @subscriptions[identifier] << { id: sub_id, callback: callback }
+          @subscription_msgs[sub_id] = { subscription: subscription, identifier: identifier }
+        end
+
+        if @connected
+          send_subscribe(subscription)
+        else
+          @mutex.synchronize { @pending_subscriptions << subscription }
+          connect unless @ws
+        end
+
+        sub_id
+      end
+
+      def unsubscribe(subscription_id)
+        sub_msg = nil
+        should_send = false
+
+        @mutex.synchronize do
+          sub_msg = @subscription_msgs.delete(subscription_id)
+          return unless sub_msg
+
+          identifier = sub_msg[:identifier]
+          callbacks = @subscriptions[identifier]
+          return unless callbacks
+
+          callbacks.reject! { |entry| entry[:id] == subscription_id }
+
+          if callbacks.empty?
+            @subscriptions.delete(identifier)
+            should_send = true
+          end
+        end
+
+        send_unsubscribe(sub_msg[:subscription]) if should_send && @connected
+      end
+
+      def close
+        @closing = true
+        @connected = false
+
+        @ping_thread&.kill
+        @ping_thread = nil
+
+        @queue&.close if @queue.respond_to?(:close)
+        @dispatch_thread&.join(5)
+        @dispatch_thread = nil
+
+        @ws&.close
+        @ws = nil
+      end
+
+      def connected?
+        @connected
+      end
+
+      def on(event, &callback)
+        @lifecycle_callbacks[event] = callback
+      end
+
+      private
+
+      def establish_connection
+        client = self
+        url = @url
+        @connection_id += 1
+        active_id = @connection_id
+
+        @ws = ::WSLite.connect(url) do |ws|
+          ws.on :open do
+            next if client.send(:stale_connection?, active_id)
+
+            client.send(:handle_open)
+          end
+
+          ws.on :message do |msg|
+            next if client.send(:stale_connection?, active_id)
+
+            client.send(:handle_message, msg.data)
+          end
+
+          ws.on :error do |e|
+            next if client.send(:stale_connection?, active_id)
+
+            client.send(:handle_error, e)
+          end
+
+          ws.on :close do |e|
+            next if client.send(:stale_connection?, active_id)
+
+            client.send(:handle_close, e)
+          end
+        end
+      end
+
+      def stale_connection?(id)
+        id != @connection_id
+      end
+
+      def handle_open
+        @connected = true
+        @reconnect_attempts = 0
+        flush_pending_subscriptions
+        replay_subscriptions
+        @lifecycle_callbacks[:open]&.call
+      end
+
+      def handle_message(raw)
+        return if raw.nil? || raw.empty?
+
+        return if raw.start_with?('Websocket connection established')
+
+        data = parse_json(raw)
+        return unless data
+
+        channel = data['channel']
+        return if channel == 'pong'
+        return unless channel
+
+        identifier = compute_identifier(channel, data['data'])
+        return unless identifier
+
+        enqueue_message(identifier, data['data'])
+      end
+
+      def handle_error(error)
+        @lifecycle_callbacks[:error]&.call(error)
+      end
+
+      def handle_close(_event)
+        was_connected = @connected
+        @connected = false
+        @lifecycle_callbacks[:close]&.call
+
+        attempt_reconnect if was_connected && !@closing && @reconnect_enabled
+      end
+
+      def parse_json(raw)
+        JSON.parse(raw)
+      rescue JSON::ParserError => e
+        warn "[Hyperliquid::WS] Failed to parse message: #{e.message}"
+        nil
+      end
+
+      def compute_identifier(channel, data)
+        case channel
+        when 'l2Book'        then "l2Book:#{data['coin'].downcase}"
+        when 'trades'        then data.is_a?(Array) && data[0] ? "trades:#{data[0]['coin'].downcase}" : nil
+        when 'bbo'           then "bbo:#{data['coin'].downcase}"
+        when 'candle'        then "candle:#{data['s'].downcase}:#{data['i']}"
+        when 'allMids'       then 'allMids'
+        when 'orderUpdates'  then 'orderUpdates'
+        when 'userEvents'    then "userEvents:#{data['user'].downcase}"
+        when 'userFills'     then "userFills:#{data['user'].downcase}"
+        when 'userFundings'  then "userFundings:#{data['user'].downcase}"
+        end
+      end
+
+      def subscription_identifier(subscription)
+        type = sub_field(subscription, 'type')
+        case type
+        when 'l2Book'        then "l2Book:#{sub_field(subscription, 'coin').downcase}"
+        when 'trades'        then "trades:#{sub_field(subscription, 'coin').downcase}"
+        when 'bbo'           then "bbo:#{sub_field(subscription, 'coin').downcase}"
+        when 'candle'
+          "candle:#{sub_field(subscription, 'coin').downcase}:#{sub_field(subscription, 'interval')}"
+        when 'allMids'       then 'allMids'
+        when 'orderUpdates'  then 'orderUpdates'
+        when 'userEvents'    then "userEvents:#{sub_field(subscription, 'user').downcase}"
+        when 'userFills'     then "userFills:#{sub_field(subscription, 'user').downcase}"
+        when 'userFundings'  then "userFundings:#{sub_field(subscription, 'user').downcase}"
+        else
+          raise Hyperliquid::WebSocketError, "Unsupported subscription type: #{type}"
+        end
+      end
+
+      def sub_field(subscription, key)
+        subscription[key.to_sym] || subscription[key]
+      end
+
+      def enqueue_message(identifier, data)
+        @mutex.synchronize do
+          if @queue.size >= @max_queue_size
+            @dropped_message_count += 1
+            if @dropped_message_count == 1 || (@dropped_message_count % 100).zero?
+              warn "[Hyperliquid::WS] Queue full (#{@max_queue_size}). " \
+                   "Dropped #{@dropped_message_count} message(s). Callbacks may be too slow."
+            end
+            return
+          end
+        end
+        @queue.push({ identifier: identifier, data: data })
+      end
+
+      def start_dispatch_thread
+        @dispatch_thread = Thread.new do
+          loop do
+            msg = begin
+              @queue.pop
+            rescue ClosedQueueError
+              break
+            end
+            break if msg.nil?
+
+            callbacks = @mutex.synchronize { @subscriptions[msg[:identifier]]&.dup }
+            next unless callbacks
+
+            callbacks.each do |entry|
+              entry[:callback].call(msg[:data])
+            rescue StandardError => e
+              warn "[Hyperliquid::WS] Callback error: #{e.message}"
+            end
+          end
+        end
+        @dispatch_thread.name = 'hl-ws-dispatch'
+      end
+
+      def start_ping_thread
+        @ping_thread = Thread.new do
+          loop do
+            sleep Constants::WS_PING_INTERVAL
+            break if @closing
+
+            send_json({ method: 'ping' }) if @connected
+          end
+        end
+        @ping_thread.name = 'hl-ws-ping'
+        @ping_thread.report_on_exception = false
+      end
+
+      def flush_pending_subscriptions
+        pending = @mutex.synchronize do
+          subs = @pending_subscriptions.dup
+          @pending_subscriptions.clear
+          subs
+        end
+
+        pending.each { |sub| send_subscribe(sub) }
+      end
+
+      def send_subscribe(subscription)
+        send_json({ method: 'subscribe', subscription: subscription })
+      end
+
+      def send_unsubscribe(subscription)
+        send_json({ method: 'unsubscribe', subscription: subscription })
+      end
+
+      def send_json(hash)
+        @ws&.send(JSON.generate(hash))
+      rescue StandardError => e
+        warn "[Hyperliquid::WS] Send error: #{e.message}"
+      end
+
+      def attempt_reconnect
+        Thread.new do
+          loop do
+            break if @closing
+
+            delay = [2**@reconnect_attempts, 30].min
+            @reconnect_attempts += 1
+            sleep delay
+
+            break if @closing
+
+            begin
+              establish_connection
+              break
+            rescue StandardError => e
+              warn "[Hyperliquid::WS] Reconnect failed: #{e.message}"
+            end
+          end
+        end
+      end
+
+      def replay_subscriptions
+        subs = @mutex.synchronize do
+          @subscription_msgs.values.map { |v| v[:subscription] }.uniq
+        end
+        subs.each { |sub| send_subscribe(sub) }
+      end
+    end
+  end
+end

data/lib/hyperliquid.rb

@@ -9,6 +9,7 @@ require_relative 'hyperliquid/cloid'
 require_relative 'hyperliquid/signing/eip712'
 require_relative 'hyperliquid/signing/signer'
 require_relative 'hyperliquid/exchange'
+require_relative 'hyperliquid/ws/client'
 
 # Ruby SDK for Hyperliquid API
 # Provides access to Hyperliquid's decentralized exchange API
@@ -34,7 +35,7 @@ module Hyperliquid
 
   # Main SDK class
   class SDK
-    attr_reader :info, :exchange
+    attr_reader :info, :exchange, :ws
 
     # Initialize the SDK
     # @param testnet [Boolean] Whether to use testnet (default: false for mainnet)
@@ -50,6 +51,7 @@ module Hyperliquid
       @info = Info.new(client)
       @testnet = testnet
       @exchange = nil
+      @ws = WS::Client.new(testnet: testnet)
 
       return unless private_key
 
@@ -58,6 +60,7 @@ module Hyperliquid
         client: client,
         signer: signer,
         info: @info,
+        testnet: testnet,
         expires_after: expires_after
       )
     end

data/scripts/test_03_perp_market_roundtrip.rb

@@ -1,49 +1,55 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Test 3: Perp Market Roundtrip (BTC Long)
-# Open a long BTC position, then close it.
+# Test 3: Perp Market Roundtrip (Long)
+# Open a long perp position, then close it.
 
 require_relative 'test_helpers'
 
 sdk = build_sdk
-separator('TEST 3: Perp Market Roundtrip (BTC Long)')
+perp_coin = 'ETH'
+separator("TEST 3: Perp Market Roundtrip (#{perp_coin} Long)")
 
-perp_coin = 'BTC'
 mids = sdk.info.all_mids
-btc_price = mids[perp_coin]&.to_f
+perp_coin_price = mids[perp_coin]&.to_f
 
-if btc_price&.positive?
+if perp_coin_price&.positive?
   meta = sdk.info.meta
-  btc_meta = meta['universe'].find { |a| a['name'] == perp_coin }
-  sz_decimals = btc_meta['szDecimals']
+  perp_coin_meta = meta['universe'].find { |a| a['name'] == perp_coin }
+  sz_decimals = perp_coin_meta['szDecimals']
 
-  perp_size = (20.0 / btc_price).ceil(sz_decimals)
+  perp_size = (20.0 / perp_coin_price).ceil(sz_decimals)
 
-  puts "#{perp_coin} mid: $#{btc_price.round(2)}"
-  puts "Size: #{perp_size} BTC (~$#{(perp_size * btc_price).round(2)})"
-  puts "Slippage: #{(PERP_SLIPPAGE * 100).to_i}%"
+  puts "#{perp_coin} mid: $#{perp_coin_price.round(2)}"
+  puts "Size: #{perp_size} #{perp_coin} (~$#{(perp_size * perp_coin_price).round(2)})"
+  puts "Slippage: #{(PERP_SLIPPAGE * 100).to_i}% (with retry up to #{((PERP_SLIPPAGE + ORACLE_SLIPPAGE_INCREMENT * (ORACLE_RETRY_ATTEMPTS - 1)) * 100).to_i}%)"
   puts
 
   puts 'Opening LONG position (market buy)...'
-  result = sdk.exchange.market_order(
+  result = market_order_with_retry(
+    sdk,
     coin: perp_coin,
     is_buy: true,
     size: perp_size,
-    slippage: PERP_SLIPPAGE
+    base_slippage: PERP_SLIPPAGE
   )
-  check_result(result, 'Long open')
-
-  wait_with_countdown(WAIT_SECONDS, 'Position open. Waiting before close...')
-
-  puts 'Closing LONG position (market sell)...'
-  result = sdk.exchange.market_order(
-    coin: perp_coin,
-    is_buy: false,
-    size: perp_size,
-    slippage: PERP_SLIPPAGE
-  )
-  check_result(result, 'Long close')
+  open_success = check_result(result, 'Long open')
+
+  if open_success
+    wait_with_countdown(WAIT_SECONDS, 'Position open. Waiting before close...')
+
+    puts 'Closing LONG position (market sell)...'
+    result = market_order_with_retry(
+      sdk,
+      coin: perp_coin,
+      is_buy: false,
+      size: perp_size,
+      base_slippage: PERP_SLIPPAGE
+    )
+    check_result(result, 'Long close')
+  else
+    puts red('Skipping close - position was not opened')
+  end
 else
   puts red("SKIPPED: Could not get #{perp_coin} price")
 end

data/scripts/test_05_update_leverage.rb

@@ -3,6 +3,7 @@
 
 # Test 5: Update Leverage (BTC)
 # Set cross, isolated, then reset leverage.
+# Requires no open BTC position (cannot switch leverage type with open position).
 
 require_relative 'test_helpers'
 
@@ -14,8 +15,16 @@ mids = sdk.info.all_mids
 btc_price = mids[perp_coin]&.to_f
 
 if btc_price&.positive?
+  # Check for open position - cannot switch leverage type with open position
+  unless check_position_and_prompt(sdk, perp_coin, timeout: 10)
+    puts
+    puts green('Test 5 Update Leverage skipped (open position).')
+    exit 0
+  end
+
   puts 'Setting BTC to 5x cross leverage...'
   result = sdk.exchange.update_leverage(coin: perp_coin, leverage: 5, is_cross: true)
+  dump_status(result)
   api_error?(result) || puts(green('5x cross leverage set'))
   puts
 
@@ -23,6 +32,7 @@ if btc_price&.positive?
 
   puts 'Setting BTC to 3x isolated leverage...'
   result = sdk.exchange.update_leverage(coin: perp_coin, leverage: 3, is_cross: false)
+  dump_status(result)
   api_error?(result) || puts(green('3x isolated leverage set'))
   puts
 
@@ -30,6 +40,7 @@ if btc_price&.positive?
 
   puts 'Resetting BTC to 1x cross leverage...'
   result = sdk.exchange.update_leverage(coin: perp_coin, leverage: 1, is_cross: true)
+  dump_status(result)
   api_error?(result) || puts(green('1x cross leverage set'))
 else
   puts red("SKIPPED: Could not get #{perp_coin} price")

data/scripts/test_07_market_close.rb

@@ -1,46 +1,52 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Test 7: Market Close (BTC)
+# Test 7: Market Close (PERP)
 # Open a long position, then close it using market_close (auto-detect size).
 
 require_relative 'test_helpers'
 
 sdk = build_sdk
-separator('TEST 7: Market Close (BTC)')
+perp_coin = 'ETH'
+separator("TEST 7: Market Close (#{perp_coin})")
 
-perp_coin = 'BTC'
 mids = sdk.info.all_mids
-btc_price = mids[perp_coin]&.to_f
+perp_coin_price = mids[perp_coin]&.to_f
 
-if btc_price&.positive?
+if perp_coin_price&.positive?
   meta = sdk.info.meta
-  btc_meta = meta['universe'].find { |a| a['name'] == perp_coin }
-  sz_decimals = btc_meta['szDecimals']
+  perp_coin_meta = meta['universe'].find { |a| a['name'] == perp_coin }
+  sz_decimals = perp_coin_meta['szDecimals']
 
-  perp_size = (20.0 / btc_price).ceil(sz_decimals)
+  perp_size = (20.0 / perp_coin_price).ceil(sz_decimals)
 
-  puts "#{perp_coin} mid: $#{btc_price.round(2)}"
-  puts "Size: #{perp_size} BTC"
+  puts "#{perp_coin} mid: $#{perp_coin_price.round(2)}"
+  puts "Size: #{perp_size} #{perp_coin}"
+  puts "Slippage: #{(PERP_SLIPPAGE * 100).to_i}% (with retry up to #{((PERP_SLIPPAGE + ORACLE_SLIPPAGE_INCREMENT * (ORACLE_RETRY_ATTEMPTS - 1)) * 100).to_i}%)"
   puts
 
   puts 'Opening LONG position (market buy)...'
-  result = sdk.exchange.market_order(
+  result = market_order_with_retry(
+    sdk,
     coin: perp_coin,
     is_buy: true,
     size: perp_size,
-    slippage: PERP_SLIPPAGE
+    base_slippage: PERP_SLIPPAGE
   )
-  check_result(result, 'Long open')
-
-  wait_with_countdown(WAIT_SECONDS, 'Position open. Waiting before market_close...')
-
-  puts 'Closing position using market_close (auto-detect size)...'
-  result = sdk.exchange.market_close(
-    coin: perp_coin,
-    slippage: PERP_SLIPPAGE
-  )
-  check_result(result, 'Market close')
+  open_success = check_result(result, 'Long open')
+
+  if open_success
+    wait_with_countdown(WAIT_SECONDS, 'Position open. Waiting before market_close...')
+
+    puts 'Closing position using market_close (auto-detect size)...'
+    result = sdk.exchange.market_close(
+      coin: perp_coin,
+      slippage: PERP_SLIPPAGE + ORACLE_SLIPPAGE_INCREMENT  # Use higher slippage for close
+    )
+    check_result(result, 'Market close')
+  else
+    puts red('Skipping market_close - position was not opened')
+  end
 else
   puts red("SKIPPED: Could not get #{perp_coin} price")
 end

data/scripts/test_08_usd_class_transfer.rb

@@ -11,6 +11,7 @@ separator('TEST 8: USD Class Transfer (Perp <-> Spot)')
 
 puts 'Transferring $10 from perp to spot...'
 result = sdk.exchange.usd_class_transfer(amount: '10', to_perp: false)
+dump_status(result)
 api_error?(result) || puts(green('Transfer to spot successful!'))
 puts
 
@@ -18,6 +19,7 @@ wait_with_countdown(WAIT_SECONDS, 'Waiting before transferring back...')
 
 puts 'Transferring $10 from spot to perp...'
 result = sdk.exchange.usd_class_transfer(amount: '10', to_perp: true)
+dump_status(result)
 api_error?(result) || puts(green('Transfer to perp successful!'))
 
 test_passed('Test 8 USD Class Transfer')

data/scripts/test_10_vault.rb

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 10: Vault Status / Deposit / Withdraw
+#
+# Default:  Show vault status (equity, entry date, unlock date)
+# Options:  ruby test_10_vault_transfer.rb deposit
+#           ruby test_10_vault_transfer.rb withdraw
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 10: Vault Status / Deposit / Withdraw')
+
+vault_addr = '0xa15099a30bbf2e68942d6f4c43d70d04faeab0a0'
+action = ARGV[0] # nil, "deposit", or "withdraw"
+
+puts "Vault: #{vault_addr}"
+puts
+
+vault = sdk.info.vault_details(vault_addr, sdk.exchange.address)
+follower = vault['followerState']
+
+if follower
+  equity = follower['vaultEquity']
+  entry_time = follower['vaultEntryTime']
+  lockup_until = follower['lockupUntil']
+
+  puts "Vault equity:  $#{equity}"
+  puts "Entry date:    #{Time.at(entry_time / 1000.0).utc}" if entry_time
+  puts "Unlock date:   #{Time.at(lockup_until / 1000.0).utc}" if lockup_until
+else
+  puts 'No position in this vault.'
+end
+puts
+
+case action
+when 'deposit'
+  puts 'Depositing $10 to vault...'
+  result = sdk.exchange.vault_transfer(
+    vault_address: vault_addr,
+    is_deposit: true,
+    usd: 10
+  )
+  dump_status(result)
+  api_error?(result) || puts(green('Vault deposit successful!'))
+when 'withdraw'
+  equity_f = follower&.dig('vaultEquity')&.to_f || 0
+  if equity_f > 1
+    withdraw_amount = equity_f.floor
+    puts "Withdrawing $#{withdraw_amount} from vault..."
+    result = sdk.exchange.vault_transfer(
+      vault_address: vault_addr,
+      is_deposit: false,
+      usd: withdraw_amount
+    )
+    dump_status(result)
+    api_error?(result) || puts(green('Vault withdrawal successful!'))
+  else
+    puts red("Insufficient vault equity to withdraw ($#{equity_f})")
+  end
+else
+  puts 'Pass "deposit" or "withdraw" as an argument to perform a transfer.'
+  puts '  ruby scripts/test_10_vault_transfer.rb deposit'
+  puts '  ruby scripts/test_10_vault_transfer.rb withdraw'
+end
+
+test_passed('Test 10 Vault Status')