hyperliquid 1.9.0 → 2.0.0

data/scripts/test_14_ws_candle.rb

@@ -1,81 +0,0 @@
-#!/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_15_explorer.rb

@@ -1,71 +0,0 @@
-#!/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_16_send_to_evm_with_data.rb

@@ -1,79 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Test 16: sendToEvmWithData (user-signed exchange action)
-#
-# Mirrors the TS SDK's `tests/api/exchange/sendToEvmWithData.test.ts`:
-#   1. Top up spot USDC by 2 (via usd_class_transfer perp -> spot).
-#   2. Submit one real sendToEvmWithData action sending 1 USDC to 0x...01
-#      on HyperEVM testnet (chain 998) with empty calldata.
-#   3. Assert response is { status: 'ok', response: { type: 'default' } }.
-#
-# This funds-moving test sends 1 testnet USDC to 0x...01 (effectively burned —
-# no contract is there to redirect it). Same bar the TS SDK uses for its own
-# test suite.
-#
-# Skips with a warning if the wallet is on unified account (usd_class_transfer
-# is disabled in that mode and the top-up cannot run).
-#
-# Usage:
-#   HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_16_send_to_evm_with_data.rb
-
-require_relative 'test_helpers'
-
-sdk = build_sdk
-separator('TEST 16: sendToEvmWithData')
-
-abstraction = sdk.info.user_abstraction(sdk.exchange.address)
-if abstraction == 'unifiedAccount'
-  puts "SKIPPED: Wallet has unified account active (abstraction=#{abstraction.inspect})."
-  puts '  usd_class_transfer top-up step is disabled by the exchange when balances are unified.'
-  test_passed('Test 16 sendToEvmWithData')
-  exit 0
-end
-
-puts 'Topping up spot USDC by $2 (perp -> spot)...'
-top_up = sdk.exchange.usd_class_transfer(amount: '2', to_perp: false)
-dump_status(top_up)
-if api_error?(top_up)
-  puts red('Top-up failed; aborting before sendToEvmWithData.')
-  test_passed('Test 16 sendToEvmWithData')
-  exit 1
-end
-puts green('Top-up successful.')
-puts
-
-wait_with_countdown(WAIT_SECONDS, 'Waiting before sendToEvmWithData...')
-
-puts 'Sending 1 USDC to 0x...01 on HyperEVM testnet (chain 998) with empty calldata...'
-result = sdk.exchange.send_to_evm_with_data(
-  token: 'USDC',
-  amount: '1',
-  source_dex: 'spot',
-  destination_recipient: '0x0000000000000000000000000000000000000001',
-  address_encoding: 'hex',
-  destination_chain_id: 998,
-  gas_limit: 200_000,
-  data: '0x'
-)
-
-if api_error?(result)
-  puts red("sendToEvmWithData FAILED: #{result.inspect}")
-  test_passed('Test 16 sendToEvmWithData')
-  exit 1
-end
-
-unless result.is_a?(Hash) && result['status'] == 'ok'
-  $test_failed = true
-  puts red("Unexpected status: #{result.inspect}")
-end
-
-response_type = result.dig('response', 'type')
-unless response_type == 'default'
-  $test_failed = true
-  puts red("Expected response.type 'default', got: #{response_type.inspect}")
-end
-
-puts green("sendToEvmWithData OK: status=ok, response.type=#{response_type}") unless $test_failed
-
-test_passed('Test 16 sendToEvmWithData')

data/scripts/test_17_create_vault.rb

@@ -1,73 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Test 17: createVault (L1 exchange action)
-#
-# Creates a new vault with the calling wallet as leader, using a $100 testnet
-# USDC seed (server-enforced minimum). On success, prints the new vault address
-# from response.data.
-#
-# WARNING: This is a real testnet action. The $100 seed is locked into the
-# created vault per Hyperliquid's vault lockup rules. Run intentionally —
-# do NOT wire into test_automated.rb.
-#
-# Skips with a warning if the wallet has < $100 perp USDC available.
-#
-# Usage:
-#   HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_17_create_vault.rb
-
-require_relative 'test_helpers'
-
-sdk = build_sdk
-separator('TEST 17: createVault')
-
-state = sdk.info.user_state(sdk.exchange.address)
-withdrawable = state['withdrawable'].to_f
-puts "Wallet:       #{sdk.exchange.address}"
-puts "Withdrawable: $#{format('%.2f', withdrawable)}"
-puts
-
-if withdrawable < 100
-  puts red("SKIPPED: Need >= $100 perp USDC to seed a vault (have $#{format('%.2f', withdrawable)}).")
-  test_passed('Test 17 createVault')
-  exit 0
-end
-
-vault_name = "AgentVault#{Time.now.to_i}"
-vault_description = 'Vault created by hyperliquid-run integration test (test_17).'
-
-puts "Creating vault \"#{vault_name}\" with $100 seed..."
-result = sdk.exchange.create_vault(
-  name: vault_name,
-  description: vault_description,
-  initial_usd: 100
-)
-
-if api_error?(result)
-  puts red("createVault FAILED: #{result.inspect}")
-  test_passed('Test 17 createVault')
-  exit 1
-end
-
-unless result.is_a?(Hash) && result['status'] == 'ok'
-  $test_failed = true
-  puts red("Unexpected status: #{result.inspect}")
-end
-
-response_type = result.dig('response', 'type')
-unless response_type == 'createVault'
-  $test_failed = true
-  puts red("Expected response.type 'createVault', got: #{response_type.inspect}")
-end
-
-vault_address = result.dig('response', 'data')
-unless vault_address.is_a?(String) && vault_address.start_with?('0x') && vault_address.length == 42
-  $test_failed = true
-  puts red("Expected response.data to be a 0x-prefixed 40-hex-char vault address, got: #{vault_address.inspect}")
-end
-
-unless $test_failed
-  puts green("createVault OK: status=ok, response.type=#{response_type}, vault=#{vault_address}")
-end
-
-test_passed('Test 17 createVault')

data/scripts/test_18_user_portfolio_margin.rb

@@ -1,72 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Test 18: userPortfolioMargin (user-signed exchange action)
-#
-# Toggles cross-portfolio-margin mode for the calling wallet. Sends two actions:
-# enable, then disable, leaving the wallet in its original state.
-#
-# WARNING: Toggling portfolio margin alters margining math on existing perp positions.
-# Run only on a wallet without significant open exposure on testnet.
-#
-# Usage:
-#   HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_18_user_portfolio_margin.rb
-
-require_relative 'test_helpers'
-
-sdk = build_sdk
-separator('TEST 18: userPortfolioMargin')
-
-user = sdk.exchange.address
-puts "Wallet: #{user}"
-puts
-
-puts 'Enabling portfolio margin...'
-result = sdk.exchange.user_portfolio_margin(user: user, enabled: true)
-
-# The protocol enforces a $10k account value or $5m volume threshold for portfolio
-# margin eligibility. The agent testnet wallet typically meets neither, so this
-# precondition failure is not an SDK bug — downgrade to warning and exit cleanly,
-# matching the test_08 / test_11 pattern.
-if result.is_a?(Hash) && result['status'] == 'err' &&
-   result['response'].to_s.include?('Portfolio margin requires')
-  puts red("WARNING: #{result['response']}")
-  puts '  Skipping — this is a testnet precondition, not an SDK failure.'
-  puts '  The action correctly serialized and signed (server returned a structured'
-  puts '  rejection, not a signing error).'
-  test_passed('Test 18 user_portfolio_margin')
-  exit 0
-end
-
-if api_error?(result)
-  puts red("user_portfolio_margin (enable) FAILED: #{result.inspect}")
-  test_passed('Test 18 user_portfolio_margin')
-  exit 1
-end
-
-unless result.is_a?(Hash) && result['status'] == 'ok' && result.dig('response', 'type') == 'default'
-  $test_failed = true
-  puts red("Unexpected enable response: #{result.inspect}")
-end
-
-puts green("Enable OK: #{result.inspect}") unless $test_failed
-
-wait_with_countdown(WAIT_SECONDS, 'Settling before toggle back...')
-
-puts 'Disabling portfolio margin...'
-result = sdk.exchange.user_portfolio_margin(user: user, enabled: false)
-
-if api_error?(result)
-  puts red("user_portfolio_margin (disable) FAILED: #{result.inspect}")
-  test_passed('Test 18 user_portfolio_margin')
-  exit 1
-end
-
-unless result.is_a?(Hash) && result['status'] == 'ok' && result.dig('response', 'type') == 'default'
-  $test_failed = true
-  puts red("Unexpected disable response: #{result.inspect}")
-end
-
-puts green("Disable OK: #{result.inspect}") unless $test_failed
-
-test_passed('Test 18 user_portfolio_margin')

data/scripts/test_19_spot_user.rb

@@ -1,55 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Test 19: spotUser (L1 exchange action)
-#
-# Toggles spot-dusting opt-out for the calling wallet. Sends two actions:
-# opt_out: true, then opt_out: false, leaving the wallet in its original state
-# (spot dusting opted-in by default).
-#
-# Usage:
-#   HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_19_spot_user.rb
-
-require_relative 'test_helpers'
-
-sdk = build_sdk
-separator('TEST 19: spotUser (spot-dusting opt-out)')
-
-puts "Wallet: #{sdk.exchange.address}"
-puts
-
-puts 'Opting out of spot dusting...'
-result = sdk.exchange.spot_user(opt_out: true)
-
-if api_error?(result)
-  puts red("spot_user (opt_out: true) FAILED: #{result.inspect}")
-  test_passed('Test 19 spot_user')
-  exit 1
-end
-
-unless result.is_a?(Hash) && result['status'] == 'ok' && result.dig('response', 'type') == 'default'
-  $test_failed = true
-  puts red("Unexpected opt-out response: #{result.inspect}")
-end
-
-puts green("Opt-out OK: #{result.inspect}") unless $test_failed
-
-wait_with_countdown(WAIT_SECONDS, 'Settling before toggle back...')
-
-puts 'Opting back in to spot dusting...'
-result = sdk.exchange.spot_user(opt_out: false)
-
-if api_error?(result)
-  puts red("spot_user (opt_out: false) FAILED: #{result.inspect}")
-  test_passed('Test 19 spot_user')
-  exit 1
-end
-
-unless result.is_a?(Hash) && result['status'] == 'ok' && result.dig('response', 'type') == 'default'
-  $test_failed = true
-  puts red("Unexpected opt-in response: #{result.inspect}")
-end
-
-puts green("Opt-in OK: #{result.inspect}") unless $test_failed
-
-test_passed('Test 19 spot_user')

data/scripts/test_20_explorer_ws.rb

@@ -1,92 +0,0 @@
-#!/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

@@ -1,96 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Hyperliquid Ruby SDK - Testnet Integration Tests (Runner)
-#
-# Runs all integration test scripts in order.
-# Each script can also be run individually for debugging.
-#
-# Prerequisites:
-#   - Testnet wallet with USDC balance
-#   - Get testnet funds from: https://app.hyperliquid-testnet.xyz
-#
-# Usage:
-#   HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_all.rb
-#
-# Run a single test:
-#   HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_08_usd_class_transfer.rb
-#
-# Note: These scripts execute real trades on testnet. No real funds are at risk.
-
-SCRIPTS = [
-  'test_01_spot_market_roundtrip.rb',
-  'test_02_spot_limit_order.rb',
-  'test_03_perp_market_roundtrip.rb',
-  'test_04_perp_limit_order.rb',
-  'test_05_update_leverage.rb',
-  'test_06_modify_order.rb',
-  'test_07_market_close.rb',
-  'test_08_usd_class_transfer.rb',
-  'test_09_sub_account_lifecycle.rb',
-  'test_10_vault.rb',
-  'test_11_builder_fee.rb',
-  'test_12_staking.rb',
-  'test_13_ws_l2_book.rb',
-  'test_14_ws_candle.rb',
-  'test_15_explorer.rb',
-  '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_20_explorer_ws.rb'
-].freeze
-
-def green(text)
-  "\e[32m#{text}\e[0m"
-end
-
-def red(text)
-  "\e[31m#{text}\e[0m"
-end
-
-unless ENV['HYPERLIQUID_PRIVATE_KEY']
-  puts red('Error: Set HYPERLIQUID_PRIVATE_KEY environment variable')
-  puts 'Usage: HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_all.rb'
-  exit 1
-end
-
-scripts_dir = __dir__
-passed = []
-failed = []
-
-SCRIPTS.each do |script|
-  path = File.join(scripts_dir, script)
-  puts
-  puts '#' * 60
-  puts "# Running: #{script}"
-  puts '#' * 60
-
-  success = system(RbConfig.ruby, path)
-
-  if success
-    passed << script
-  else
-    failed << script
-    puts red("!!! #{script} exited with error !!!")
-  end
-end
-
-puts
-puts '=' * 60
-puts 'INTEGRATION TEST SUMMARY'
-puts '=' * 60
-puts
-puts "Passed: #{passed.length}/#{SCRIPTS.length}"
-passed.each { |s| puts green("  [PASS] #{s}") }
-if failed.any?
-  puts
-  puts "Failed: #{failed.length}/#{SCRIPTS.length}"
-  failed.each { |s| puts red("  [FAIL] #{s}") }
-end
-puts
-puts 'Check your testnet wallet for trade history:'
-puts 'https://app.hyperliquid-testnet.xyz'
-puts
-
-exit(failed.empty? ? 0 : 1)