hyperliquid 0.2.0 → 0.4.0

data/lib/hyperliquid/info.rb

@@ -7,6 +7,10 @@ module Hyperliquid
       @client = client
     end
 
+    # ============================
+    # Info
+    # ============================
+
     # Get all market mid prices
     # @return [Hash] Hash containing mid prices for all markets
     def all_mids
@@ -15,9 +19,22 @@ module Hyperliquid
 
     # Get a user's open orders
     # @param user [String] Wallet address
+    # @param dex [String, nil] Optional perp dex name
     # @return [Array] Array of open orders for the user
-    def open_orders(user)
-      @client.post(Constants::INFO_ENDPOINT, { type: 'openOrders', user: user })
+    def open_orders(user, dex: nil)
+      body = { type: 'openOrders', user: user }
+      body[:dex] = dex if dex
+      @client.post(Constants::INFO_ENDPOINT, body)
+    end
+
+    # Get a user's open orders with additional frontend info
+    # @param user [String] Wallet address
+    # @param dex [String, nil] Optional perp dex name
+    # @return [Array]
+    def frontend_open_orders(user, dex: nil)
+      body = { type: 'frontendOpenOrders', user: user }
+      body[:dex] = dex if dex
+      @client.post(Constants::INFO_ENDPOINT, body)
     end
 
     # Get a user's fill history
@@ -27,6 +44,24 @@ module Hyperliquid
       @client.post(Constants::INFO_ENDPOINT, { type: 'userFills', user: user })
     end
 
+    # Get a user's fills within a time range
+    # @param user [String] Wallet address
+    # @param start_time [Integer] Start timestamp in milliseconds
+    # @param end_time [Integer, nil] Optional end timestamp in milliseconds
+    # @return [Array]
+    def user_fills_by_time(user, start_time, end_time = nil)
+      body = { type: 'userFillsByTime', user: user, startTime: start_time }
+      body[:endTime] = end_time if end_time
+      @client.post(Constants::INFO_ENDPOINT, body)
+    end
+
+    # Query user rate limits and usage
+    # @param user [String] Wallet address
+    # @return [Hash]
+    def user_rate_limit(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'userRateLimit', user: user })
+    end
+
     # Get order status by order ID
     # @param user [String] Wallet address
     # @param oid [Integer] Order ID
@@ -35,23 +70,12 @@ module Hyperliquid
       @client.post(Constants::INFO_ENDPOINT, { type: 'orderStatus', user: user, oid: oid })
     end
 
-    # Get user's trading state
+    # Get order status by client order ID (cloid)
     # @param user [String] Wallet address
-    # @return [Hash] User's trading state including positions and balances
-    def user_state(user)
-      @client.post(Constants::INFO_ENDPOINT, { type: 'clearinghouseState', user: user })
-    end
-
-    # Get metadata for all assets
-    # @return [Hash] Metadata for all tradable assets
-    def meta
-      @client.post(Constants::INFO_ENDPOINT, { type: 'meta' })
-    end
-
-    # Get metadata for all assets including universe info
-    # @return [Hash] Extended metadata for all assets with universe information
-    def meta_and_asset_ctxs
-      @client.post(Constants::INFO_ENDPOINT, { type: 'metaAndAssetCtxs' })
+    # @param cloid [String] Client order ID
+    # @return [Hash] Order status information
+    def order_status_by_cloid(user, cloid)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'orderStatus', user: user, cloid: cloid })
     end
 
     # Get L2 order book for a coin
@@ -79,8 +103,221 @@ module Hyperliquid
                    })
     end
 
+    # Check builder fee approval
+    # @param user [String] Wallet address
+    # @param builder [String] Builder address
+    # @return [Hash]
+    def max_builder_fee(user, builder)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'maxBuilderFee', user: user, builder: builder })
+    end
+
+    # Retrieve a user's historical orders
+    # @param user [String] Wallet address
+    # @param start_time [Integer, nil] Optional start timestamp in milliseconds
+    # @param end_time [Integer, nil] Optional end timestamp in milliseconds
+    # @return [Array]
+    def historical_orders(user, start_time = nil, end_time = nil)
+      body = { type: 'historicalOrders', user: user }
+      body[:startTime] = start_time if start_time
+      body[:endTime] = end_time if end_time
+      @client.post(Constants::INFO_ENDPOINT, body)
+    end
+
+    # Retrieve a user's TWAP slice fills
+    # @param user [String] Wallet address
+    # @param start_time [Integer, nil] Optional start timestamp in milliseconds
+    # @param end_time [Integer, nil] Optional end timestamp in milliseconds
+    # @return [Array]
+    def user_twap_slice_fills(user, start_time = nil, end_time = nil)
+      body = { type: 'userTwapSliceFills', user: user }
+      body[:startTime] = start_time if start_time
+      body[:endTime] = end_time if end_time
+      @client.post(Constants::INFO_ENDPOINT, body)
+    end
+
+    # Retrieve a user's subaccounts
+    # @param user [String]
+    # @return [Array]
+    def user_subaccounts(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'subaccounts', user: user })
+    end
+
+    # Retrieve details for a vault
+    # @param vault_address [String] Vault address
+    # @param user [String, nil] Optional wallet address
+    # @return [Hash]
+    def vault_details(vault_address, user = nil)
+      body = { type: 'vaultDetails', vaultAddress: vault_address }
+      body[:user] = user if user
+      @client.post(Constants::INFO_ENDPOINT, body)
+    end
+
+    # Retrieve a user's vault deposits
+    # @param user [String] Wallet address
+    # @return [Array]
+    def user_vault_equities(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'userVaultEquities', user: user })
+    end
+
+    # Query a user's role
+    # @param user [String]
+    # @return [Hash]
+    def user_role(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'userRole', user: user })
+    end
+
+    # Query a user's portfolio time series
+    # @param user [String]
+    # @return [Array]
+    def portfolio(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'portfolio', user: user })
+    end
+
+    # Query a user's referral information
+    # @param user [String]
+    # @return [Hash]
+    def referral(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'referral', user: user })
+    end
+
+    # Query a user's effective fee rates and schedule
+    # @param user [String]
+    # @return [Hash]
+    def user_fees(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'userFees', user: user })
+    end
+
+    # Query a user's staking delegations
+    # @param user [String]
+    # @return [Array]
+    def delegations(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'delegations', user: user })
+    end
+
+    # Query a user's staking summary
+    # @param user [String]
+    # @return [Hash]
+    def delegator_summary(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'delegatorSummary', user: user })
+    end
+
+    # Query a user's staking history
+    # @param user [String]
+    # @return [Array]
+    def delegator_history(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'delegatorHistory', user: user })
+    end
+
+    # Query a user's staking rewards
+    # @param user [String]
+    # @return [Array]
+    def delegator_rewards(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'delegatorRewards', user: user })
+    end
+
+    # ============================
+    # Info: Perpetuals
+    # ============================
+
+    # Retrieve all perpetual dexs
+    # @return [Array]
+    def perp_dexs
+      @client.post(Constants::INFO_ENDPOINT, { type: 'perpDexs' })
+    end
+
+    # Get metadata for all assets
+    # @return [Hash] Metadata for all tradable assets
+    # @param dex [String, nil] Optional perp dex name (defaults to first perp dex when not provided)
+    def meta(dex: nil)
+      body = { type: 'meta' }
+      body[:dex] = dex if dex
+      @client.post(Constants::INFO_ENDPOINT, body)
+    end
+
+    # Get metadata for all assets including universe info
+    # @return [Hash] Extended metadata for all assets with universe information
+    def meta_and_asset_ctxs
+      @client.post(Constants::INFO_ENDPOINT, { type: 'metaAndAssetCtxs' })
+    end
+
+    # Get user's trading state
+    # @param user [String] Wallet address
+    # @param dex [String, nil] Optional perp dex name
+    # @return [Hash] User's trading state including positions and balances
+    def user_state(user, dex: nil)
+      body = { type: 'clearinghouseState', user: user }
+      body[:dex] = dex if dex
+      @client.post(Constants::INFO_ENDPOINT, body)
+    end
+
+    # Retrieve predicted funding rates for different venues
+    # @return [Array]
+    def predicted_fundings
+      @client.post(Constants::INFO_ENDPOINT, { type: 'predictedFundings' })
+    end
+
+    # Query perps at open interest caps
+    # @return [Array]
+    def perps_at_open_interest_cap
+      @client.post(Constants::INFO_ENDPOINT, { type: 'perpsAtOpenInterestCap' })
+    end
+
+    # Retrieve information about the Perp Deploy Auction
+    # @return [Hash]
+    def perp_deploy_auction_status
+      @client.post(Constants::INFO_ENDPOINT, { type: 'perpDeployAuctionStatus' })
+    end
+
+    # Retrieve User's Active Asset Data
+    # @param user [String]
+    # @param coin [String]
+    # @return [Hash]
+    def active_asset_data(user, coin)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'activeAssetData', user: user, coin: coin })
+    end
+
+    # Retrieve Builder-Deployed Perp Market Limits
+    # @param dex [String]
+    # @return [Hash]
+    def perp_dex_limits(dex)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'perpDexLimits', dex: dex })
+    end
+
+    # Retrieve a user's funding history
+    # @param user [String]
+    # @param start_time [Integer]
+    # @param end_time [Integer, nil]
+    # @return [Array]
+    def user_funding(user, start_time, end_time = nil)
+      body = { type: 'userFunding', user: user, startTime: start_time }
+      body[:endTime] = end_time if end_time
+      @client.post(Constants::INFO_ENDPOINT, body)
+    end
+
+    # Retrieve a user's non-funding ledger updates
+    # @param user [String]
+    # @param start_time [Integer]
+    # @param end_time [Integer, nil]
+    # @return [Array]
+    def user_non_funding_ledger_updates(user, start_time, end_time = nil)
+      body = { type: 'userNonFundingLedgerUpdates', user: user, startTime: start_time }
+      body[:endTime] = end_time if end_time
+      @client.post(Constants::INFO_ENDPOINT, body)
+    end
+
+    # Retrieve historical funding rates
+    # @param coin [String]
+    # @param start_time [Integer]
+    # @param end_time [Integer, nil]
+    # @return [Array]
+    def funding_history(coin, start_time, end_time = nil)
+      body = { type: 'fundingHistory', coin: coin, startTime: start_time }
+      body[:endTime] = end_time if end_time
+      @client.post(Constants::INFO_ENDPOINT, body)
+    end
+
     # ============================
-    # Spot-specific info endpoints
+    # Info: Spot
     # ============================
 
     # Get spot metadata
@@ -122,4 +359,5 @@ module Hyperliquid
       @client.post(Constants::INFO_ENDPOINT, { type: 'tokenDetails', tokenId: token_id })
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/hyperliquid/signing/eip712.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Hyperliquid
+  module Signing
+    # EIP-712 domain and type definitions for Hyperliquid
+    # These values are defined by the Hyperliquid protocol and must match exactly
+    class EIP712
+      # Hyperliquid L1 chain ID (same for mainnet and testnet)
+      L1_CHAIN_ID = 1337
+
+      # Source identifier for phantom agent
+      MAINNET_SOURCE = 'a'
+      TESTNET_SOURCE = 'b'
+
+      class << self
+        # Domain for L1 actions (orders, cancels, leverage, etc.)
+        # @return [Hash] EIP-712 domain configuration
+        def l1_action_domain
+          {
+            name: 'Exchange',
+            version: '1',
+            chainId: L1_CHAIN_ID,
+            verifyingContract: '0x0000000000000000000000000000000000000000'
+          }
+        end
+
+        # EIP-712 domain type definition
+        # @return [Array<Hash>] Domain type fields
+        def domain_type
+          [
+            { name: :name, type: 'string' },
+            { name: :version, type: 'string' },
+            { name: :chainId, type: 'uint256' },
+            { name: :verifyingContract, type: 'address' }
+          ]
+        end
+
+        # Agent type for phantom agent signing
+        # @return [Array<Hash>] Agent type fields
+        def agent_type
+          [
+            { name: :source, type: 'string' },
+            { name: :connectionId, type: 'bytes32' }
+          ]
+        end
+
+        # Get source identifier for phantom agent
+        # @param testnet [Boolean] Whether testnet
+        # @return [String] Source identifier ('a' for mainnet, 'b' for testnet)
+        def source(testnet:)
+          testnet ? TESTNET_SOURCE : MAINNET_SOURCE
+        end
+      end
+    end
+  end
+end

data/lib/hyperliquid/signing/signer.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'eth'
+require 'msgpack'
+
+module Hyperliquid
+  module Signing
+    # EIP-712 signature generation for Hyperliquid exchange operations
+    # Implements the phantom agent signing scheme used by Hyperliquid
+    class Signer
+      # Initialize a new signer
+      # @param private_key [String] Ethereum private key (hex string with or without 0x prefix)
+      # @param testnet [Boolean] Whether to sign for testnet (default: false)
+      def initialize(private_key:, testnet: false)
+        @testnet = testnet
+        @key = Eth::Key.new(priv: normalize_private_key(private_key))
+      end
+
+      # Get the wallet address
+      # @return [String] Checksummed Ethereum address
+      def address
+        @key.address.to_s
+      end
+
+      # Sign an L1 action (orders, cancels, leverage updates, etc.)
+      # @param action [Hash] The action payload to sign
+      # @param nonce [Integer] Timestamp in milliseconds
+      # @param vault_address [String, nil] Optional vault address for vault trading
+      # @param expires_after [Integer, nil] Optional expiration timestamp in milliseconds
+      # @return [Hash] Signature with :r, :s, :v components
+      def sign_l1_action(action, nonce, vault_address: nil, expires_after: nil)
+        phantom_agent = construct_phantom_agent(action, nonce, vault_address, expires_after)
+
+        typed_data = {
+          types: {
+            EIP712Domain: EIP712.domain_type,
+            Agent: EIP712.agent_type
+          },
+          primaryType: 'Agent',
+          domain: EIP712.l1_action_domain,
+          message: phantom_agent
+        }
+
+        sign_typed_data(typed_data)
+      end
+
+      private
+
+      # Normalize private key format
+      # @param key [String] Private key with or without 0x prefix
+      # @return [String] Private key with 0x prefix
+      def normalize_private_key(key)
+        key.start_with?('0x') ? key : "0x#{key}"
+      end
+
+      # Construct the phantom agent for signing
+      # Maintains parity with Python SDK
+      # @param action [Hash] Action payload
+      # @param nonce [Integer] Nonce timestamp
+      # @param vault_address [String, nil] Optional vault address
+      # @param expires_after [Integer, nil] Optional expiration timestamp
+      # @return [Hash] Phantom agent with source and connectionId
+      def construct_phantom_agent(action, nonce, vault_address, expires_after)
+        # Compute action hash
+        # Maintains parity with Python SDK
+        # data = msgpack(action) + nonce(8 bytes BE) + vault_flag + [vault_addr] + [expires_flag + expires_after]
+        # - Note: expires_flag is only included if expires_after exists. A bit odd but that's what the
+        #     Python SDK does.
+        data = action.to_msgpack
+        data += [nonce].pack('Q>') # 8-byte big-endian uint64
+
+        if vault_address.nil?
+          data += "\x00" # no vault flag
+        else
+          data += "\x01" # has vault flag
+          data += address_to_bytes(vault_address.downcase)
+        end
+
+        unless expires_after.nil?
+          data += "\x00" # expiration flag
+          data += [expires_after].pack('Q>') # 8-byte big-endian uint64
+        end
+
+        connection_id = Eth::Util.keccak256(data)
+
+        {
+          source: EIP712.source(testnet: @testnet),
+          connectionId: bin_to_hex(connection_id)
+        }
+      end
+
+      # Convert hex address to 20-byte binary
+      # @param address [String] Ethereum address with 0x prefix
+      # @return [String] 20-byte binary representation
+      def address_to_bytes(address)
+        [address.sub(/\A0x/i, '')].pack('H*')
+      end
+
+      # Sign EIP-712 typed data using eth gem's built-in method
+      # @param typed_data [Hash] Complete EIP-712 structure
+      # @return [Hash] Signature components :r, :s, :v
+      def sign_typed_data(typed_data)
+        signature = @key.sign_typed_data(typed_data)
+
+        # Parse signature hex string into components
+        # Format: r (64 hex chars) + s (64 hex chars) + v (2 hex chars)
+        {
+          r: "0x#{signature[0, 64]}",
+          s: "0x#{signature[64, 64]}",
+          v: signature[128, 2].to_i(16)
+        }
+      end
+
+      # Convert binary data to hex string with 0x prefix
+      # @param bin [String] Binary data
+      # @return [String] Hex string with 0x prefix
+      def bin_to_hex(bin)
+        "0x#{bin.unpack1('H*')}"
+      end
+    end
+  end
+end

data/lib/hyperliquid/version.rb

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

data/lib/hyperliquid.rb

@@ -5,33 +5,61 @@ require_relative 'hyperliquid/constants'
 require_relative 'hyperliquid/errors'
 require_relative 'hyperliquid/client'
 require_relative 'hyperliquid/info'
+require_relative 'hyperliquid/cloid'
+require_relative 'hyperliquid/signing/eip712'
+require_relative 'hyperliquid/signing/signer'
+require_relative 'hyperliquid/exchange'
 
 # Ruby SDK for Hyperliquid API
-# Provides read-only access to Hyperliquid's decentralized exchange API
+# Provides access to Hyperliquid's decentralized exchange API
+# including both read (Info) and write (Exchange) operations
 module Hyperliquid
   # Create a new SDK instance
   # @param testnet [Boolean] Whether to use testnet (default: false for mainnet)
   # @param timeout [Integer] Request timeout in seconds (default: 30)
   # @param retry_enabled [Boolean] Whether to enable retry logic (default: false)
+  # @param private_key [String, nil] Ethereum private key for exchange operations (optional)
+  # @param expires_after [Integer, nil] Global order expiration timestamp in ms (optional)
   # @return [Hyperliquid::SDK] A new SDK instance
-  def self.new(testnet: false, timeout: Constants::DEFAULT_TIMEOUT, retry_enabled: false)
-    SDK.new(testnet: testnet, timeout: timeout, retry_enabled: retry_enabled)
+  def self.new(testnet: false, timeout: Constants::DEFAULT_TIMEOUT, retry_enabled: false,
+               private_key: nil, expires_after: nil)
+    SDK.new(
+      testnet: testnet,
+      timeout: timeout,
+      retry_enabled: retry_enabled,
+      private_key: private_key,
+      expires_after: expires_after
+    )
   end
 
   # Main SDK class
   class SDK
-    attr_reader :info
+    attr_reader :info, :exchange
 
     # Initialize the SDK
     # @param testnet [Boolean] Whether to use testnet (default: false for mainnet)
     # @param timeout [Integer] Request timeout in seconds
     # @param retry_enabled [Boolean] Whether to enable retry logic (default: false)
-    def initialize(testnet: false, timeout: Constants::DEFAULT_TIMEOUT, retry_enabled: false)
+    # @param private_key [String, nil] Ethereum private key for exchange operations (optional)
+    # @param expires_after [Integer, nil] Global order expiration timestamp in ms (optional)
+    def initialize(testnet: false, timeout: Constants::DEFAULT_TIMEOUT, retry_enabled: false,
+                   private_key: nil, expires_after: nil)
       base_url = testnet ? Constants::TESTNET_API_URL : Constants::MAINNET_API_URL
       client = Client.new(base_url: base_url, timeout: timeout, retry_enabled: retry_enabled)
 
       @info = Info.new(client)
       @testnet = testnet
+      @exchange = nil
+
+      return unless private_key
+
+      signer = Signing::Signer.new(private_key: private_key, testnet: testnet)
+      @exchange = Exchange.new(
+        client: client,
+        signer: signer,
+        info: @info,
+        expires_after: expires_after
+      )
     end
 
     # Check if using testnet