hyperliquid 0.5.0 → 0.6.0

data/scripts/test_02_spot_limit_order.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 2: Spot Limit Order (Place and Cancel)
+# Place a limit buy well below market, then cancel it.
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 2: Spot Limit Order (Place and Cancel)')
+
+spot_coin = 'PURR/USDC'
+spot_size = 5
+
+mids = sdk.info.all_mids
+spot_price = mids[spot_coin]&.to_f
+
+if spot_price&.positive?
+  limit_price = (spot_price * 0.50).round(2)
+  puts "#{spot_coin} mid: $#{spot_price}"
+  puts "Limit price: $#{limit_price} (50% below mid - won't fill)"
+  puts "Size: #{spot_size} PURR"
+  puts
+
+  puts 'Placing limit BUY order...'
+  result = sdk.exchange.order(
+    coin: spot_coin,
+    is_buy: true,
+    size: spot_size,
+    limit_px: limit_price,
+    order_type: { limit: { tif: 'Gtc' } },
+    reduce_only: false
+  )
+  oid = check_result(result, 'Limit order')
+
+  if oid.is_a?(Integer)
+    wait_with_countdown(WAIT_SECONDS, 'Order resting. Waiting before cancel...')
+
+    puts "Canceling order #{oid}..."
+    result = sdk.exchange.cancel(coin: spot_coin, oid: oid)
+    check_result(result, 'Cancel')
+  end
+else
+  puts red("SKIPPED: Could not get #{spot_coin} price")
+end
+
+test_passed('Test 2 Spot Limit Order')
+

data/scripts/test_03_perp_market_roundtrip.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 3: Perp Market Roundtrip (BTC Long)
+# Open a long BTC position, then close it.
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 3: Perp Market Roundtrip (BTC Long)')
+
+perp_coin = 'BTC'
+mids = sdk.info.all_mids
+btc_price = mids[perp_coin]&.to_f
+
+if btc_price&.positive?
+  meta = sdk.info.meta
+  btc_meta = meta['universe'].find { |a| a['name'] == perp_coin }
+  sz_decimals = btc_meta['szDecimals']
+
+  perp_size = (20.0 / btc_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
+
+  puts 'Opening LONG position (market buy)...'
+  result = sdk.exchange.market_order(
+    coin: perp_coin,
+    is_buy: true,
+    size: perp_size,
+    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')
+else
+  puts red("SKIPPED: Could not get #{perp_coin} price")
+end
+
+test_passed('Test 3 Perp Market Roundtrip')
+

data/scripts/test_04_perp_limit_order.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 4: Perp Limit Order (Short, then Cancel)
+# Place a limit sell well above market, then cancel it.
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 4: Perp Limit Order (Short, then Cancel)')
+
+perp_coin = 'BTC'
+mids = sdk.info.all_mids
+btc_price = mids[perp_coin]&.to_f
+
+if btc_price&.positive?
+  meta = sdk.info.meta
+  btc_meta = meta['universe'].find { |a| a['name'] == perp_coin }
+  sz_decimals = btc_meta['szDecimals']
+
+  limit_price = (btc_price * 1.50).round(0).to_i
+  perp_size = (20.0 / btc_price).ceil(sz_decimals)
+
+  puts "#{perp_coin} mid: $#{btc_price.round(2)}"
+  puts "Limit price: $#{limit_price} (50% above mid - won't fill)"
+  puts "Size: #{perp_size} BTC"
+  puts
+
+  puts 'Placing limit SELL order (short)...'
+  result = sdk.exchange.order(
+    coin: perp_coin,
+    is_buy: false,
+    size: perp_size,
+    limit_px: limit_price,
+    order_type: { limit: { tif: 'Gtc' } },
+    reduce_only: false
+  )
+  oid = check_result(result, 'Limit short')
+
+  if oid.is_a?(Integer)
+    wait_with_countdown(WAIT_SECONDS, 'Order resting. Waiting before cancel...')
+
+    puts "Canceling order #{oid}..."
+    result = sdk.exchange.cancel(coin: perp_coin, oid: oid)
+    check_result(result, 'Cancel')
+  end
+else
+  puts red("SKIPPED: Could not get #{perp_coin} price")
+end
+
+test_passed('Test 4 Perp Limit Order')
+

data/scripts/test_05_update_leverage.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 5: Update Leverage (BTC)
+# Set cross, isolated, then reset leverage.
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 5: Update Leverage (BTC)')
+
+perp_coin = 'BTC'
+mids = sdk.info.all_mids
+btc_price = mids[perp_coin]&.to_f
+
+if btc_price&.positive?
+  puts 'Setting BTC to 5x cross leverage...'
+  result = sdk.exchange.update_leverage(coin: perp_coin, leverage: 5, is_cross: true)
+  api_error?(result) || puts(green('5x cross leverage set'))
+  puts
+
+  wait_with_countdown(WAIT_SECONDS, 'Waiting before next leverage update...')
+
+  puts 'Setting BTC to 3x isolated leverage...'
+  result = sdk.exchange.update_leverage(coin: perp_coin, leverage: 3, is_cross: false)
+  api_error?(result) || puts(green('3x isolated leverage set'))
+  puts
+
+  wait_with_countdown(WAIT_SECONDS, 'Waiting before resetting leverage...')
+
+  puts 'Resetting BTC to 1x cross leverage...'
+  result = sdk.exchange.update_leverage(coin: perp_coin, leverage: 1, is_cross: true)
+  api_error?(result) || puts(green('1x cross leverage set'))
+else
+  puts red("SKIPPED: Could not get #{perp_coin} price")
+end
+
+test_passed('Test 5 Update Leverage')
+

data/scripts/test_06_modify_order.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 6: Modify Order (BTC)
+# Place a limit buy, modify its price, then cancel.
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 6: Modify Order (BTC)')
+
+perp_coin = 'BTC'
+mids = sdk.info.all_mids
+btc_price = mids[perp_coin]&.to_f
+
+if btc_price&.positive?
+  meta = sdk.info.meta
+  btc_meta = meta['universe'].find { |a| a['name'] == perp_coin }
+  sz_decimals = btc_meta['szDecimals']
+
+  original_price = (btc_price * 0.50).round(0).to_i
+  modified_price = (btc_price * 0.51).round(0).to_i
+  perp_size = (20.0 / btc_price).ceil(sz_decimals)
+
+  puts "#{perp_coin} mid: $#{btc_price.round(2)}"
+  puts "Original limit: $#{original_price} (50% below mid)"
+  puts "Modified limit: $#{modified_price} (49% below mid)"
+  puts "Size: #{perp_size} BTC"
+  puts
+
+  puts 'Placing limit BUY order...'
+  result = sdk.exchange.order(
+    coin: perp_coin,
+    is_buy: true,
+    size: perp_size,
+    limit_px: original_price,
+    order_type: { limit: { tif: 'Gtc' } }
+  )
+  oid = check_result(result, 'Limit buy')
+
+  if oid.is_a?(Integer)
+    wait_with_countdown(WAIT_SECONDS, 'Order resting. Waiting before modify...')
+
+    puts "Modifying order #{oid} (price: $#{original_price} -> $#{modified_price})..."
+    result = sdk.exchange.modify_order(
+      oid: oid,
+      coin: perp_coin,
+      is_buy: true,
+      size: perp_size,
+      limit_px: modified_price
+    )
+    new_oid = check_result(result, 'Modify')
+    new_oid = oid unless new_oid.is_a?(Integer)
+    puts
+
+    wait_with_countdown(WAIT_SECONDS, 'Waiting before cancel...')
+
+    puts "Canceling modified order #{new_oid}..."
+    result = sdk.exchange.cancel(coin: perp_coin, oid: new_oid)
+    check_result(result, 'Cancel')
+  end
+else
+  puts red("SKIPPED: Could not get #{perp_coin} price")
+end
+
+test_passed('Test 6 Modify Order')
+

data/scripts/test_07_market_close.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 7: Market Close (BTC)
+# 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 = 'BTC'
+mids = sdk.info.all_mids
+btc_price = mids[perp_coin]&.to_f
+
+if btc_price&.positive?
+  meta = sdk.info.meta
+  btc_meta = meta['universe'].find { |a| a['name'] == perp_coin }
+  sz_decimals = btc_meta['szDecimals']
+
+  perp_size = (20.0 / btc_price).ceil(sz_decimals)
+
+  puts "#{perp_coin} mid: $#{btc_price.round(2)}"
+  puts "Size: #{perp_size} BTC"
+  puts
+
+  puts 'Opening LONG position (market buy)...'
+  result = sdk.exchange.market_order(
+    coin: perp_coin,
+    is_buy: true,
+    size: perp_size,
+    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')
+else
+  puts red("SKIPPED: Could not get #{perp_coin} price")
+end
+
+test_passed('Test 7 Market Close')
+

data/scripts/test_08_usd_class_transfer.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 8: USD Class Transfer (Perp <-> Spot)
+# Transfer $10 from perp to spot, then back.
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+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)
+api_error?(result) || puts(green('Transfer to spot successful!'))
+puts
+
+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)
+api_error?(result) || puts(green('Transfer to perp successful!'))
+
+test_passed('Test 8 USD Class Transfer')

data/scripts/test_09_sub_account_lifecycle.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 9: Sub Account Lifecycle
+# Create a sub-account, deposit $10, then withdraw $10.
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 9: Sub Account Lifecycle')
+
+puts 'Creating sub-account "ruby-sdk-test"...'
+result = sdk.exchange.create_sub_account(name: 'ruby-sdk-test')
+
+if api_error?(result)
+  exit 1
+end
+
+puts green('Sub-account created!')
+puts
+
+sub_account_address = result.dig('response', 'data', 'subAccountUser')
+if sub_account_address
+  puts "Sub-account address: #{sub_account_address}"
+  puts
+
+  wait_with_countdown(WAIT_SECONDS, 'Waiting before deposit...')
+
+  puts 'Depositing $10 to sub-account...'
+  result = sdk.exchange.sub_account_transfer(
+    sub_account_user: sub_account_address,
+    is_deposit: true,
+    usd: 10
+  )
+  api_error?(result) || puts(green('Deposit successful!'))
+  puts
+
+  wait_with_countdown(WAIT_SECONDS, 'Waiting before withdrawal...')
+
+  puts 'Withdrawing $10 from sub-account...'
+  result = sdk.exchange.sub_account_transfer(
+    sub_account_user: sub_account_address,
+    is_deposit: false,
+    usd: 10
+  )
+  api_error?(result) || puts(green('Withdrawal successful!'))
+else
+  puts red('SKIPPED: Could not extract sub-account address from response')
+end
+
+test_passed('Test 9 Sub Account Lifecycle')

data/scripts/test_10_vault_transfer.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 10: Vault Deposit/Withdraw
+# Check vault equity and either deposit or withdraw.
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 10: Vault Deposit/Withdraw')
+
+vault_addr = '0xa15099a30bbf2e68942d6f4c43d70d04faeab0a0'
+puts "Vault: #{vault_addr}"
+puts
+
+vault = sdk.info.vault_details(vault_addr, sdk.exchange.address)
+user_vault_equity = vault.dig('portfolio', 0, 1, 'accountValue')&.to_f || 0
+puts "User equity in vault: $#{user_vault_equity}"
+puts
+
+if user_vault_equity > 1
+  withdraw_amount = user_vault_equity.floor
+  puts "Withdrawing $#{withdraw_amount} from vault..."
+  result = sdk.exchange.vault_transfer(
+    vault_address: vault_addr,
+    is_deposit: false,
+    usd: withdraw_amount
+  )
+  api_error?(result) || puts(green('Vault withdrawal successful!'))
+else
+  puts "User has $#{user_vault_equity} in vault (insufficient to withdraw)"
+  puts 'Depositing $10 to vault...'
+  result = sdk.exchange.vault_transfer(
+    vault_address: vault_addr,
+    is_deposit: true,
+    usd: 10
+  )
+  api_error?(result) || puts(green('Vault deposit successful!'))
+end
+
+test_passed('Test 10 Vault Deposit/Withdraw')

data/scripts/test_all.rb

@@ -0,0 +1,86 @@
+#!/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_transfer.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)

data/scripts/test_helpers.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative '../lib/hyperliquid'
+require 'json'
+
+WAIT_SECONDS = 3
+SPOT_SLIPPAGE = 0.40  # 40% for illiquid testnet spot markets
+PERP_SLIPPAGE = 0.05  # 5% for perp markets
+
+def green(text)
+  "\e[32m#{text}\e[0m"
+end
+
+def red(text)
+  "\e[31m#{text}\e[0m"
+end
+
+$test_failed = false
+
+def separator(title)
+  puts
+  puts '=' * 60
+  puts title
+  puts '=' * 60
+  puts
+end
+
+def wait_with_countdown(seconds, message)
+  puts message
+  seconds.downto(1) do |i|
+    print "\r  #{i} seconds remaining...  "
+    sleep 1
+  end
+  puts "\r  Done!                      "
+  puts
+end
+
+def api_error?(result)
+  return false unless result.is_a?(Hash) && result['status'] == 'err'
+
+  $test_failed = true
+  puts red("FAILED: #{result['response']}")
+  true
+end
+
+def check_result(result, operation)
+  return false if api_error?(result)
+
+  status = result.dig('response', 'data', 'statuses', 0)
+
+  if status.is_a?(Hash) && status['error']
+    $test_failed = true
+    puts red("FAILED: #{status['error']}")
+    return false
+  end
+
+  if status.is_a?(Hash) && status['resting']
+    puts green("Order resting with OID: #{status['resting']['oid']}")
+    return status['resting']['oid']
+  end
+
+  if status == 'success' || (status.is_a?(Hash) && status['filled'])
+    puts green("#{operation} successful!")
+    return true
+  end
+
+  puts "Result: #{status.inspect}"
+  true
+end
+
+def test_passed(name)
+  puts
+  if $test_failed
+    puts red("#{name} FAILED!")
+    exit 1
+  else
+    puts green("#{name} passed!")
+  end
+end
+
+def build_sdk
+  private_key = ENV['HYPERLIQUID_PRIVATE_KEY']
+  unless private_key
+    puts red('Error: Set HYPERLIQUID_PRIVATE_KEY environment variable')
+    puts 'Usage: HYPERLIQUID_PRIVATE_KEY=0x... ruby <script>'
+    exit 1
+  end
+
+  sdk = Hyperliquid.new(
+    testnet: true,
+    private_key: private_key
+  )
+
+  puts "Wallet: #{sdk.exchange.address}"
+  puts 'Network: Testnet'
+  puts "Testnet UI: https://app.hyperliquid-testnet.xyz"
+  puts
+
+  sdk
+end