hyperliquid 0.7.0 → 1.0.1

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

@@ -42,6 +42,7 @@ when 'deposit'
     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
@@ -53,6 +54,7 @@ when 'withdraw'
       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})")

data/scripts/test_11_builder_fee.rb

@@ -16,6 +16,7 @@ perp_coin = 'BTC'
 # Step 1: Approve builder fee
 puts "Approving builder fee for #{builder_address} (max #{max_fee_rate})..."
 result = sdk.exchange.approve_builder_fee(builder: builder_address, max_fee_rate: max_fee_rate)
+dump_status(result)
 api_error?(result) || puts(green('Builder fee approved'))
 puts
 

data/scripts/test_12_staking.rb

@@ -50,6 +50,7 @@ when 'delegate'
     wei: delegate_amount,
     is_undelegate: false
   )
+  dump_status(result)
   api_error?(result) || puts(green('Delegation successful!'))
 when 'undelegate'
   puts "Undelegating 0.1 HYPE from #{validator}..."
@@ -58,6 +59,7 @@ when 'undelegate'
     wei: delegate_amount,
     is_undelegate: true
   )
+  dump_status(result)
   api_error?(result) || puts(green('Undelegation successful!'))
 else
   puts 'Pass "delegate" or "undelegate" as an argument to perform an action.'

data/scripts/test_13_ws_l2_book.rb

@@ -0,0 +1,83 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 13: WebSocket l2Book Subscription
+#
+# Subscribes to ETH perp l2Book on testnet, prints 3 updates
+# with top-of-book (best bid/ask), then cleanly disconnects.
+#
+# No private key required (read-only WebSocket).
+#
+# Usage:
+#   ruby scripts/test_13_ws_l2_book.rb
+
+require_relative '../lib/hyperliquid'
+
+def green(text)
+  "\e[32m#{text}\e[0m"
+end
+
+def red(text)
+  "\e[31m#{text}\e[0m"
+end
+
+puts
+puts '=' * 60
+puts 'TEST 13: WebSocket l2Book Subscription'
+puts '=' * 60
+puts
+puts 'Network: Testnet'
+puts 'Subscribing to ETH l2Book (3 updates, then disconnect)'
+puts
+
+sdk = Hyperliquid.new(testnet: true)
+updates = []
+mutex = Mutex.new
+done = ConditionVariable.new
+
+sdk.ws.on(:open) { puts 'WebSocket connected.' }
+sdk.ws.on(:error) { |e| puts red("WebSocket error: #{e}") }
+
+sdk.ws.subscribe({ type: 'l2Book', coin: 'ETH' }) do |data|
+  mutex.synchronize do
+    next if updates.length >= 3
+
+    levels = data['levels']
+    bids = levels&.dig(0) || []
+    asks = levels&.dig(1) || []
+    best_bid = bids.first
+    best_ask = asks.first
+
+    update_num = updates.length + 1
+    puts "Update #{update_num}/3:"
+    puts "  Best bid: #{best_bid ? "#{best_bid['px']} (#{best_bid['sz']})" : 'n/a'}"
+    puts "  Best ask: #{best_ask ? "#{best_ask['px']} (#{best_ask['sz']})" : 'n/a'}"
+    puts "  Bid levels: #{bids.length}, Ask levels: #{asks.length}"
+    puts
+
+    updates << data
+    done.signal if updates.length >= 3
+  end
+end
+
+# Wait for 3 updates or timeout after 30 seconds
+success = false
+mutex.synchronize do
+  deadline = Time.now + 30
+  while updates.length < 3 && Time.now < deadline
+    remaining = deadline - Time.now
+    break if remaining <= 0
+
+    done.wait(mutex, remaining)
+  end
+  success = updates.length >= 3
+end
+
+sdk.ws.close
+
+if success
+  puts green('Test 13 WebSocket l2Book passed!')
+else
+  puts red("Test 13 FAILED: only received #{updates.length}/3 updates within 30s")
+  exit 1
+end

data/scripts/test_14_ws_candle.rb

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 14: WebSocket candle Subscription
+#
+# Subscribes to ETH 1m candles on testnet, prints 3 updates
+# with OHLCV data, then cleanly disconnects.
+#
+# No private key required (read-only WebSocket).
+#
+# Usage:
+#   ruby scripts/test_14_ws_candle.rb
+
+require_relative '../lib/hyperliquid'
+
+def green(text)
+  "\e[32m#{text}\e[0m"
+end
+
+def red(text)
+  "\e[31m#{text}\e[0m"
+end
+
+puts
+puts '=' * 60
+puts 'TEST 14: WebSocket candle Subscription'
+puts '=' * 60
+puts
+puts 'Network: Testnet'
+puts 'Subscribing to ETH 1m candles (3 updates, then disconnect)'
+puts
+
+sdk = Hyperliquid.new(testnet: true)
+updates = []
+mutex = Mutex.new
+done = ConditionVariable.new
+
+sdk.ws.on(:open) { puts 'WebSocket connected.' }
+sdk.ws.on(:error) { |e| puts red("WebSocket error: #{e}") }
+
+sdk.ws.subscribe({ type: 'candle', coin: 'ETH', interval: '1m' }) do |data|
+  mutex.synchronize do
+    next if updates.length >= 3
+
+    update_num = updates.length + 1
+    puts "Update #{update_num}/3:"
+    puts "  Symbol:   #{data['s']}"
+    puts "  Interval: #{data['i']}"
+    puts "  Open:     #{data['o']}"
+    puts "  High:     #{data['h']}"
+    puts "  Low:      #{data['l']}"
+    puts "  Close:    #{data['c']}"
+    puts "  Volume:   #{data['v']}"
+    puts
+
+    updates << data
+    done.signal if updates.length >= 3
+  end
+end
+
+# Wait for 3 updates or timeout after 90 seconds (candles can be slow)
+success = false
+mutex.synchronize do
+  deadline = Time.now + 90
+  while updates.length < 3 && Time.now < deadline
+    remaining = deadline - Time.now
+    break if remaining <= 0
+
+    done.wait(mutex, remaining)
+  end
+  success = updates.length >= 3
+end
+
+sdk.ws.close
+
+if success
+  puts green('Test 14 WebSocket candle passed!')
+else
+  puts red("Test 14 FAILED: only received #{updates.length}/3 updates within 90s")
+  exit 1
+end

data/scripts/test_all.rb

@@ -30,7 +30,9 @@ SCRIPTS = [
   'test_09_sub_account_lifecycle.rb',
   'test_10_vault.rb',
   'test_11_builder_fee.rb',
-  'test_12_staking.rb'
+  'test_12_staking.rb',
+  'test_13_ws_l2_book.rb',
+  'test_14_ws_candle.rb'
 ].freeze
 
 def green(text)

data/scripts/test_helpers.rb

@@ -5,7 +5,9 @@ require 'json'
 
 WAIT_SECONDS = 3
 SPOT_SLIPPAGE = 0.40  # 40% for illiquid testnet spot markets
-PERP_SLIPPAGE = 0.05  # 5% for perp markets
+PERP_SLIPPAGE = 0.15
+ORACLE_RETRY_ATTEMPTS = 3
+ORACLE_SLIPPAGE_INCREMENT = 0.10  # Increase slippage by 10% on each retry
 
 def green(text)
   "\e[32m#{text}\e[0m"
@@ -43,7 +45,19 @@ def api_error?(result)
   true
 end
 
+# Extract and display the status from an API response
+def dump_status(result)
+  return unless result.is_a?(Hash)
+
+  status = result.dig('response', 'data', 'statuses', 0)
+  return unless status
+
+  puts "  API status: #{status.inspect}"
+end
+
 def check_result(result, operation)
+  dump_status(result)
+
   return false if api_error?(result)
 
   status = result.dig('response', 'data', 'statuses', 0)
@@ -98,3 +112,119 @@ def build_sdk
 
   sdk
 end
+
+# Check if result has "Price too far from oracle" error
+def oracle_error?(result)
+  return false unless result.is_a?(Hash)
+
+  if result['status'] == 'err' && result['response'].to_s.include?('Price too far from oracle')
+    return true
+  end
+
+  status = result.dig('response', 'data', 'statuses', 0)
+  status.is_a?(Hash) && status['error'].to_s.include?('Price too far from oracle')
+end
+
+# Execute a market order with retry logic for oracle errors
+def market_order_with_retry(sdk, coin:, is_buy:, size:, base_slippage:)
+  slippage = base_slippage
+
+  ORACLE_RETRY_ATTEMPTS.times do |attempt|
+    result = sdk.exchange.market_order(
+      coin: coin,
+      is_buy: is_buy,
+      size: size,
+      slippage: slippage
+    )
+
+    unless oracle_error?(result)
+      return result
+    end
+
+    if attempt < ORACLE_RETRY_ATTEMPTS - 1
+      slippage += ORACLE_SLIPPAGE_INCREMENT
+      puts red("Oracle price error. Retrying with #{(slippage * 100).to_i}% slippage (attempt #{attempt + 2}/#{ORACLE_RETRY_ATTEMPTS})...")
+      sleep 1
+    else
+      return result
+    end
+  end
+end
+
+# Get position for a coin, returns nil if no position
+def get_position(sdk, coin)
+  state = sdk.info.user_state(sdk.exchange.address)
+  positions = state['assetPositions'] || []
+  positions.find { |p| p.dig('position', 'coin') == coin }
+end
+
+# Check for open position and prompt user to clean up
+# Returns true if test should continue, false if should skip
+def check_position_and_prompt(sdk, coin, timeout: 10)
+  position = get_position(sdk, coin)
+  return true unless position
+
+  size = position.dig('position', 'szi').to_f
+  return true if size.zero?
+
+  puts red("WARNING: Open #{coin} position detected (size: #{size})")
+  puts "This test requires no open #{coin} position."
+  puts
+  puts "Options:"
+  puts "  [c] Close the position and continue"
+  puts "  [s] Skip this test"
+  puts
+  print "Choice (auto-skip in #{timeout}s): "
+  $stdout.flush
+
+  # Non-blocking read with timeout
+  require 'io/wait'
+  choice = nil
+  start = Time.now
+  loop do
+    if $stdin.ready?
+      choice = $stdin.gets&.strip&.downcase
+      break
+    end
+    elapsed = Time.now - start
+    remaining = (timeout - elapsed).ceil
+    if elapsed >= timeout
+      puts
+      puts "No response, skipping test..."
+      return false
+    end
+    print "\rChoice (auto-skip in #{remaining}s): "
+    $stdout.flush
+    sleep 0.5
+  end
+
+  case choice
+  when 'c'
+    puts "Closing #{coin} position..."
+    result = sdk.exchange.market_close(coin: coin, slippage: PERP_SLIPPAGE + 0.20)
+    dump_status(result)
+    if api_error?(result)
+      puts red("Failed to close position. Skipping test.")
+      return false
+    end
+    puts green("Position closed. Waiting for settlement...")
+
+    # Wait and verify position is actually closed
+    5.times do |i|
+      sleep 2
+      position = get_position(sdk, coin)
+      remaining = position&.dig('position', 'szi').to_f.abs
+      if remaining < 0.000001
+        puts green("Position fully settled.")
+        return true
+      end
+      puts "  Still settling... (#{remaining} remaining)"
+    end
+
+    puts red("Position did not fully close. Skipping test.")
+    false
+  else
+    puts "Skipping test."
+    false
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperliquid
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 1.0.1
 platform: ruby
 authors:
 - carter2099
@@ -65,6 +65,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: ws_lite
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
 description: A Ruby SDK for interacting with Hyperliquid's decentralized exchange
   API
 email:
@@ -88,6 +102,7 @@ files:
 - docs/DEVELOPMENT.md
 - docs/ERRORS.md
 - docs/EXAMPLES.md
+- docs/WS.md
 - example.rb
 - lib/hyperliquid.rb
 - lib/hyperliquid/client.rb
@@ -99,6 +114,7 @@ files:
 - lib/hyperliquid/signing/eip712.rb
 - lib/hyperliquid/signing/signer.rb
 - lib/hyperliquid/version.rb
+- lib/hyperliquid/ws/client.rb
 - scripts/test_01_spot_market_roundtrip.rb
 - scripts/test_02_spot_limit_order.rb
 - scripts/test_03_perp_market_roundtrip.rb
@@ -111,6 +127,8 @@ files:
 - scripts/test_10_vault.rb
 - scripts/test_11_builder_fee.rb
 - scripts/test_12_staking.rb
+- scripts/test_13_ws_l2_book.rb
+- scripts/test_14_ws_candle.rb
 - scripts/test_all.rb
 - scripts/test_helpers.rb
 - sig/hyperliquid.rbs