hyperliquid 0.6.0 → 1.0.0

data/lib/hyperliquid/exchange.rb

@@ -16,11 +16,13 @@ module Hyperliquid
     # @param client [Hyperliquid::Client] HTTP client
     # @param signer [Hyperliquid::Signing::Signer] EIP-712 signer
     # @param info [Hyperliquid::Info] Info API client for metadata
+    # @param testnet [Boolean] Whether targeting testnet (default: false)
     # @param expires_after [Integer, nil] Optional global expiration timestamp
-    def initialize(client:, signer:, info:, expires_after: nil)
+    def initialize(client:, signer:, info:, testnet: false, expires_after: nil)
       @client = client
       @signer = signer
       @info = info
+      @testnet = testnet
       @expires_after = expires_after
       @asset_cache = nil
     end
@@ -40,9 +42,10 @@ module Hyperliquid
     # @param reduce_only [Boolean] Reduce-only flag (default: false)
     # @param cloid [Cloid, String, nil] Client order ID (optional)
     # @param vault_address [String, nil] Vault address for vault trading (optional)
+    # @param builder [Hash, nil] Builder fee config { b: "0xaddress", f: fee_in_tenths_of_bp } (optional)
     # @return [Hash] Order response
     def order(coin:, is_buy:, size:, limit_px:, order_type: { limit: { tif: 'Gtc' } },
-              reduce_only: false, cloid: nil, vault_address: nil)
+              reduce_only: false, cloid: nil, vault_address: nil, builder: nil)
       nonce = timestamp_ms
 
       order_wire = build_order_wire(
@@ -60,6 +63,7 @@ module Hyperliquid
         orders: [order_wire],
         grouping: 'na'
       }
+      action[:builder] = normalize_builder(builder) if builder
 
       signature = @signer.sign_l1_action(
         action, nonce,
@@ -74,8 +78,9 @@ module Hyperliquid
     #   :coin, :is_buy, :size, :limit_px, :order_type, :reduce_only, :cloid
     # @param grouping [String] Order grouping ("na", "normalTpsl", "positionTpsl")
     # @param vault_address [String, nil] Vault address for vault trading (optional)
+    # @param builder [Hash, nil] Builder fee config { b: "0xaddress", f: fee_in_tenths_of_bp } (optional)
     # @return [Hash] Bulk order response
-    def bulk_orders(orders:, grouping: 'na', vault_address: nil)
+    def bulk_orders(orders:, grouping: 'na', vault_address: nil, builder: nil)
       nonce = timestamp_ms
 
       order_wires = orders.map do |o|
@@ -95,6 +100,7 @@ module Hyperliquid
         orders: order_wires,
         grouping: grouping
       }
+      action[:builder] = normalize_builder(builder) if builder
 
       signature = @signer.sign_l1_action(
         action, nonce,
@@ -110,10 +116,12 @@ module Hyperliquid
     # @param size [String, Numeric] Order size
     # @param slippage [Float] Slippage tolerance (default: 0.05 = 5%)
     # @param vault_address [String, nil] Vault address for vault trading (optional)
+    # @param builder [Hash, nil] Builder fee config { b: "0xaddress", f: fee_in_tenths_of_bp } (optional)
     # @return [Hash] Order response
-    def market_order(coin:, is_buy:, size:, slippage: DEFAULT_SLIPPAGE, vault_address: nil)
-      # Get current mid price
-      mids = @info.all_mids
+    def market_order(coin:, is_buy:, size:, slippage: DEFAULT_SLIPPAGE, vault_address: nil, builder: nil)
+      # Get current mid price (use dex-specific endpoint for HIP-3 assets)
+      dex_prefix = extract_dex_prefix(coin)
+      mids = dex_prefix ? @info.all_mids(dex: dex_prefix) : @info.all_mids
       mid = mids[coin]&.to_f
       raise ArgumentError, "Unknown asset or no price available: #{coin}" unless mid&.positive?
 
@@ -126,7 +134,8 @@ module Hyperliquid
         size: size,
         limit_px: slippage_price,
         order_type: { limit: { tif: 'Ioc' } },
-        vault_address: vault_address
+        vault_address: vault_address,
+        builder: builder
       )
     end
 
@@ -342,10 +351,12 @@ module Hyperliquid
     # @param slippage [Float] Slippage tolerance (default: 5%)
     # @param cloid [Cloid, String, nil] Client order ID (optional)
     # @param vault_address [String, nil] Vault address for vault trading (optional)
+    # @param builder [Hash, nil] Builder fee config { b: "0xaddress", f: fee_in_tenths_of_bp } (optional)
     # @return [Hash] Order response
-    def market_close(coin:, size: nil, slippage: DEFAULT_SLIPPAGE, cloid: nil, vault_address: nil)
+    def market_close(coin:, size: nil, slippage: DEFAULT_SLIPPAGE, cloid: nil, vault_address: nil, builder: nil)
       address = vault_address || @signer.address
-      state = @info.user_state(address)
+      dex_prefix = extract_dex_prefix(coin)
+      state = dex_prefix ? @info.user_state(address, dex: dex_prefix) : @info.user_state(address)
 
       position = state['assetPositions']&.find do |pos|
         pos.dig('position', 'coin') == coin
@@ -356,7 +367,7 @@ module Hyperliquid
       is_buy = szi.negative?
       close_size = size || szi.abs
 
-      mids = @info.all_mids
+      mids = dex_prefix ? @info.all_mids(dex: dex_prefix) : @info.all_mids
       mid = mids[coin]&.to_f
       raise ArgumentError, "Unknown asset or no price available: #{coin}" unless mid&.positive?
 
@@ -370,7 +381,8 @@ module Hyperliquid
         order_type: { limit: { tif: 'Ioc' } },
         reduce_only: true,
         cloid: cloid,
-        vault_address: vault_address
+        vault_address: vault_address,
+        builder: builder
       )
     end
 
@@ -383,7 +395,7 @@ module Hyperliquid
       action = {
         type: 'usdSend',
         signatureChainId: '0x66eee',
-        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @signer.instance_variable_get(:@testnet)),
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
         destination: destination,
         amount: amount.to_s,
         time: nonce
@@ -406,7 +418,7 @@ module Hyperliquid
       action = {
         type: 'spotSend',
         signatureChainId: '0x66eee',
-        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @signer.instance_variable_get(:@testnet)),
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
         destination: destination,
         token: token,
         amount: amount.to_s,
@@ -429,7 +441,7 @@ module Hyperliquid
       action = {
         type: 'usdClassTransfer',
         signatureChainId: '0x66eee',
-        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @signer.instance_variable_get(:@testnet)),
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
         amount: amount.to_s,
         toPerp: to_perp,
         nonce: nonce
@@ -451,7 +463,7 @@ module Hyperliquid
       action = {
         type: 'withdraw3',
         signatureChainId: '0x66eee',
-        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @signer.instance_variable_get(:@testnet)),
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
         destination: destination,
         amount: amount.to_s,
         time: nonce
@@ -476,7 +488,7 @@ module Hyperliquid
       action = {
         type: 'sendAsset',
         signatureChainId: '0x66eee',
-        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @signer.instance_variable_get(:@testnet)),
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
         destination: destination,
         sourceDex: source_dex,
         destinationDex: destination_dex,
@@ -569,6 +581,116 @@ module Hyperliquid
       post_action(action, signature, nonce, nil)
     end
 
+    # Authorize an agent wallet to trade on behalf of this account
+    # @param agent_address [String] Agent's Ethereum address
+    # @param agent_name [String, nil] Optional agent name (omitted from action if nil)
+    # @return [Hash] Approve agent response
+    def approve_agent(agent_address:, agent_name: nil)
+      nonce = timestamp_ms
+      action = {
+        type: 'approveAgent',
+        signatureChainId: '0x66eee',
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
+        agentAddress: agent_address,
+        nonce: nonce
+      }
+      # agentName is always included in the signed message (empty string if nil),
+      # but only included in the posted action if a name was provided (matches Python SDK)
+      action[:agentName] = agent_name if agent_name
+      signature = @signer.sign_user_signed_action(
+        { agentAddress: agent_address, agentName: agent_name || '', nonce: nonce },
+        'HyperliquidTransaction:ApproveAgent',
+        Signing::EIP712::APPROVE_AGENT_TYPES
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Approve a builder fee rate for a builder address
+    # Users must approve a builder before orders with that builder can be placed.
+    # @param builder [String] Builder's Ethereum address
+    # @param max_fee_rate [String] Maximum fee rate (e.g., "0.01%" for 1 basis point)
+    # @return [Hash] Approve builder fee response
+    def approve_builder_fee(builder:, max_fee_rate:)
+      nonce = timestamp_ms
+      action = {
+        type: 'approveBuilderFee',
+        signatureChainId: '0x66eee',
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
+        maxFeeRate: max_fee_rate,
+        builder: builder,
+        nonce: nonce
+      }
+      signature = @signer.sign_user_signed_action(
+        { maxFeeRate: max_fee_rate, builder: builder, nonce: nonce },
+        'HyperliquidTransaction:ApproveBuilderFee',
+        Signing::EIP712::APPROVE_BUILDER_FEE_TYPES
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Delegate or undelegate HYPE tokens to a validator
+    # @param validator [String] Validator's Ethereum address
+    # @param wei [Integer] Amount as float * 1e8 (e.g., 1 HYPE = 100_000_000)
+    # @param is_undelegate [Boolean] True to undelegate, false to delegate
+    # @return [Hash] Token delegate response
+    def token_delegate(validator:, wei:, is_undelegate:)
+      nonce = timestamp_ms
+      action = {
+        type: 'tokenDelegate',
+        signatureChainId: '0x66eee',
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
+        validator: validator,
+        wei: wei,
+        isUndelegate: is_undelegate,
+        nonce: nonce
+      }
+      signature = @signer.sign_user_signed_action(
+        { validator: validator, wei: wei, isUndelegate: is_undelegate, nonce: nonce },
+        'HyperliquidTransaction:TokenDelegate',
+        Signing::EIP712::TOKEN_DELEGATE_TYPES
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Enable or disable HIP-3 DEX abstraction for automatic collateral transfers
+    # When enabled, collateral is automatically transferred to HIP-3 dexes when trading
+    # @param enabled [Boolean] True to enable, false to disable DEX abstraction
+    # @param user [String, nil] User address (defaults to signer address)
+    # @return [Hash] User DEX abstraction response
+    def user_dex_abstraction(enabled:, user: nil)
+      nonce = timestamp_ms
+      user_address = user || @signer.address
+      action = {
+        type: 'userDexAbstraction',
+        signatureChainId: '0x66eee',
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
+        user: user_address,
+        enabled: enabled,
+        nonce: nonce
+      }
+      signature = @signer.sign_user_signed_action(
+        { user: user_address, enabled: enabled, nonce: nonce },
+        'HyperliquidTransaction:UserDexAbstraction',
+        Signing::EIP712::USER_DEX_ABSTRACTION_TYPES
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Enable HIP-3 DEX abstraction via agent (L1 action, enable only)
+    # This allows agents to enable DEX abstraction for the account they're trading on behalf of
+    # @param vault_address [String, nil] Vault address if trading on behalf of a vault
+    # @return [Hash] Agent enable DEX abstraction response
+    def agent_enable_dex_abstraction(vault_address: nil)
+      nonce = timestamp_ms
+      action = { type: 'agentEnableDexAbstraction' }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        vault_address: vault_address,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, vault_address)
+    end
+
     # Clear the asset metadata cache
     # Call this if metadata has been updated
     def reload_metadata!
@@ -597,26 +719,54 @@ module Hyperliquid
     end
 
     # Get asset index for a coin symbol
-    # @param coin [String] Asset symbol
+    # @param coin [String] Asset symbol (supports HIP-3 prefixed names like "xyz:GOLD")
     # @return [Integer] Asset index
     def asset_index(coin)
       load_asset_cache unless @asset_cache
+
+      # If not found and has a dex prefix (e.g., "xyz:GOLD"), try loading that dex
+      unless @asset_cache[:indices][coin]
+        dex_prefix = extract_dex_prefix(coin)
+        load_hip3_dex_cache(dex_prefix) if dex_prefix && !@loaded_dexes&.include?(dex_prefix)
+      end
+
       @asset_cache[:indices][coin] || raise(ArgumentError, "Unknown asset: #{coin}")
     end
 
     # Get asset metadata for a coin symbol
-    # @param coin [String] Asset symbol
+    # @param coin [String] Asset symbol (supports HIP-3 prefixed names like "xyz:GOLD")
     # @return [Hash] Asset metadata with :sz_decimals and :is_spot
     def asset_metadata(coin)
       load_asset_cache unless @asset_cache
+
+      # If not found and has a dex prefix, try loading that dex
+      unless @asset_cache[:metadata][coin]
+        dex_prefix = extract_dex_prefix(coin)
+        load_hip3_dex_cache(dex_prefix) if dex_prefix && !@loaded_dexes&.include?(dex_prefix)
+      end
+
       @asset_cache[:metadata][coin] || raise(ArgumentError, "Unknown asset: #{coin}")
     end
 
+    # Extract dex prefix from a coin name (e.g., "xyz:GOLD" -> "xyz")
+    # @param coin [String] Coin name
+    # @return [String, nil] Dex prefix or nil if no prefix
+    def extract_dex_prefix(coin)
+      return nil unless coin.include?(':')
+
+      prefix = coin.split(':').first
+      # Spot pairs like "PURR/USDC" don't count as dex prefixes
+      return nil if prefix.include?('/')
+
+      prefix
+    end
+
     # Load asset metadata from Info API (perps and spot)
     def load_asset_cache
       @asset_cache = { indices: {}, metadata: {} }
+      @loaded_dexes = Set.new
 
-      # Load perpetual assets
+      # Load perpetual assets from default dex
       meta = @info.meta
       meta['universe'].each_with_index do |asset, index|
         name = asset['name']
@@ -640,6 +790,33 @@ module Hyperliquid
       end
     end
 
+    # Load asset metadata for a HIP-3 dex
+    # HIP-3 asset IDs use formula: 100000 + perp_dex_index * 10000 + index_in_meta
+    # @param dex [String] Dex name (e.g., "xyz")
+    def load_hip3_dex_cache(dex)
+      return if @loaded_dexes.include?(dex)
+
+      @loaded_dexes.add(dex)
+
+      # Get perp_dex_index from perp_dexs list (position in array)
+      perp_dexs = @info.perp_dexs
+      perp_dex_index = perp_dexs.index { |d| d && d['name'] == dex }
+      return unless perp_dex_index
+
+      meta = @info.meta(dex: dex)
+      meta['universe']&.each_with_index do |asset, index|
+        name = asset['name']
+        # HIP-3 asset ID: 100000 + perp_dex_index * 10000 + index_in_meta
+        hip3_asset_id = 100_000 + (perp_dex_index * 10_000) + index
+        @asset_cache[:indices][name] = hip3_asset_id
+        @asset_cache[:metadata][name] = {
+          sz_decimals: asset['szDecimals'],
+          is_spot: false,
+          dex: dex
+        }
+      end
+    end
+
     # Convert float to wire format (string representation)
     # Maintains parity with official Python SDK
     # - 8 decimal precision
@@ -745,6 +922,13 @@ module Hyperliquid
       end
     end
 
+    # Normalize builder fee config for inclusion in action payload
+    # @param builder [Hash] Builder config with :b (address) and :f (fee)
+    # @return [Hash] Normalized builder config with lowercased address
+    def normalize_builder(builder)
+      { b: builder[:b].downcase, f: builder[:f] }
+    end
+
     # Convert order type to wire format
     # @param order_type [Hash] Order type configuration
     # @return [Hash] Wire format order type

data/lib/hyperliquid/info.rb

@@ -12,9 +12,12 @@ module Hyperliquid
     # ============================
 
     # Get all market mid prices
+    # @param dex [String, nil] Optional perp dex name (defaults to first perp dex; spot mids only included with first perp dex)
     # @return [Hash] Hash containing mid prices for all markets
-    def all_mids
-      @client.post(Constants::INFO_ENDPOINT, { type: 'allMids' })
+    def all_mids(dex: nil)
+      body = { type: 'allMids' }
+      body[:dex] = dex if dex
+      @client.post(Constants::INFO_ENDPOINT, body)
     end
 
     # Get a user's open orders
@@ -215,6 +218,27 @@ module Hyperliquid
       @client.post(Constants::INFO_ENDPOINT, { type: 'delegatorRewards', user: user })
     end
 
+    # Get authorized agent addresses for a user
+    # @param user [String] Wallet address
+    # @return [Array] Array of authorized agent addresses
+    def extra_agents(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'extraAgents', user: user })
+    end
+
+    # Get multi-sig signer mappings for a user
+    # @param user [String] Multi-sig wallet address
+    # @return [Hash] Multi-sig signer information
+    def user_to_multi_sig_signers(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'userToMultiSigSigners', user: user })
+    end
+
+    # Get dex abstraction config for a user
+    # @param user [String] Wallet address
+    # @return [Hash] Dex abstraction configuration
+    def user_dex_abstraction(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'userDexAbstraction', user: user })
+    end
+
     # ============================
     # Info: Perpetuals
     # ============================

data/lib/hyperliquid/signing/eip712.rb

@@ -67,6 +67,43 @@ module Hyperliquid
         ]
       }.freeze
 
+      APPROVE_AGENT_TYPES = {
+        'HyperliquidTransaction:ApproveAgent': [
+          { name: :hyperliquidChain, type: 'string' },
+          { name: :agentAddress, type: 'address' },
+          { name: :agentName, type: 'string' },
+          { name: :nonce, type: 'uint64' }
+        ]
+      }.freeze
+
+      APPROVE_BUILDER_FEE_TYPES = {
+        'HyperliquidTransaction:ApproveBuilderFee': [
+          { name: :hyperliquidChain, type: 'string' },
+          { name: :maxFeeRate, type: 'string' },
+          { name: :builder, type: 'address' },
+          { name: :nonce, type: 'uint64' }
+        ]
+      }.freeze
+
+      TOKEN_DELEGATE_TYPES = {
+        'HyperliquidTransaction:TokenDelegate': [
+          { name: :hyperliquidChain, type: 'string' },
+          { name: :validator, type: 'address' },
+          { name: :wei, type: 'uint64' },
+          { name: :isUndelegate, type: 'bool' },
+          { name: :nonce, type: 'uint64' }
+        ]
+      }.freeze
+
+      USER_DEX_ABSTRACTION_TYPES = {
+        'HyperliquidTransaction:UserDexAbstraction': [
+          { name: :hyperliquidChain, type: 'string' },
+          { name: :user, type: 'address' },
+          { name: :enabled, type: 'bool' },
+          { name: :nonce, type: 'uint64' }
+        ]
+      }.freeze
+
       class << self
         # Domain for L1 actions (orders, cancels, leverage, etc.)
         # @return [Hash] EIP-712 domain configuration

data/lib/hyperliquid/signing/signer.rb

@@ -22,6 +22,12 @@ module Hyperliquid
         @key.address.to_s
       end
 
+      # Whether the signer targets testnet
+      # @return [Boolean]
+      def testnet?
+        @testnet
+      end
+
       # Sign an L1 action (orders, cancels, leverage updates, etc.)
       # @param action [Hash] The action payload to sign
       # @param nonce [Integer] Timestamp in milliseconds

data/lib/hyperliquid/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hyperliquid
-  VERSION = '0.6.0'
+  VERSION = '1.0.0'
 end