hyperliquid 0.5.0 → 0.7.0

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.rb

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

data/scripts/test_11_builder_fee.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 11: Builder Fee (Approve + Order with Builder)
+# Approve a builder fee, then place an order with builder param, then cancel.
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 11: Builder Fee (Approve + Order with Builder)')
+
+builder_address = '0x250F311Ae04D3CEA03443C76340069eD26C47D7D'
+max_fee_rate = '0.01%'
+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)
+api_error?(result) || puts(green('Builder fee approved'))
+puts
+
+wait_with_countdown(WAIT_SECONDS, 'Waiting before placing order with builder...')
+
+# Step 2: Verify approval via Info API
+puts 'Checking builder fee approval...'
+approval = sdk.info.max_builder_fee(sdk.exchange.address, builder_address)
+puts "Max builder fee: #{approval.inspect}"
+puts
+
+# Step 3: Place order with builder param
+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 "Builder: #{builder_address} (fee: 10 = 1bp)"
+  puts
+
+  puts 'Placing limit SELL order with builder fee...'
+  result = sdk.exchange.order(
+    coin: perp_coin,
+    is_buy: false,
+    size: perp_size,
+    limit_px: limit_price,
+    order_type: { limit: { tif: 'Gtc' } },
+    builder: { b: builder_address, f: 10 }
+  )
+  oid = check_result(result, 'Limit short with builder')
+
+  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 11 Builder Fee')

data/scripts/test_12_staking.rb

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Test 12: Staking Status / Delegate / Undelegate
+#
+# Default:  Show staking summary and delegations
+# Options:  ruby test_12_staking.rb delegate
+#           ruby test_12_staking.rb undelegate
+
+require_relative 'test_helpers'
+
+sdk = build_sdk
+separator('TEST 12: Staking Status / Delegate / Undelegate')
+
+validator = '0x946bf3135c7d15e4462b510f74b6e304aabb5b21'
+action = ARGV[0] # nil, "delegate", or "undelegate"
+delegate_amount = 10_000_000 # 0.1 HYPE (wei = float * 1e8)
+
+puts "Validator: #{validator}"
+puts
+
+# Show staking summary
+summary = sdk.info.delegator_summary(sdk.exchange.address)
+puts "Staking summary:"
+puts "  Delegated:      #{summary['delegated']}" if summary['delegated']
+puts "  Undelegatable:  #{summary['undelegatable']}" if summary['undelegatable']
+puts "  Total pending:  #{summary['totalPending']}" if summary['totalPending']
+puts "  N delegations:  #{summary['nDelegations']}" if summary['nDelegations']
+puts
+
+# Show delegations for this validator
+delegations = sdk.info.delegations(sdk.exchange.address)
+validator_delegation = delegations&.find { |d| d['validator']&.downcase == validator.downcase }
+
+if validator_delegation
+  puts "Delegation to #{validator}:"
+  puts "  Amount:    #{validator_delegation['amount']}"
+  lockup = validator_delegation['lockedUntilTimestamp']
+  puts "  Locked until: #{Time.at(lockup / 1000.0).utc}" if lockup
+else
+  puts "No active delegation to #{validator}."
+end
+puts
+
+case action
+when 'delegate'
+  puts "Delegating 0.1 HYPE to #{validator}..."
+  result = sdk.exchange.token_delegate(
+    validator: validator,
+    wei: delegate_amount,
+    is_undelegate: false
+  )
+  api_error?(result) || puts(green('Delegation successful!'))
+when 'undelegate'
+  puts "Undelegating 0.1 HYPE from #{validator}..."
+  result = sdk.exchange.token_delegate(
+    validator: validator,
+    wei: delegate_amount,
+    is_undelegate: true
+  )
+  api_error?(result) || puts(green('Undelegation successful!'))
+else
+  puts 'Pass "delegate" or "undelegate" as an argument to perform an action.'
+  puts '  ruby scripts/test_12_staking.rb delegate'
+  puts '  ruby scripts/test_12_staking.rb undelegate'
+end
+
+test_passed('Test 12 Staking')

data/scripts/test_all.rb

@@ -0,0 +1,88 @@
+#!/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'
+].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)