hyperliquid 0.3.0 → 0.4.0

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

data/test_integration.rb

@@ -0,0 +1,255 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Hyperliquid Ruby SDK - Testnet Integration Test
+#
+# This script tests the Exchange API against the live testnet:
+#   1. Spot market roundtrip (buy PURR, sell PURR)
+#   2. Spot limit order (place and cancel)
+#   3. Perp market roundtrip (long BTC, close position)
+#   4. Perp limit order (place short, cancel)
+#
+# Prerequisites:
+#   - Testnet wallet with USDC balance
+#   - Get testnet funds from: https://app.hyperliquid-testnet.xyz
+#
+# Usage:
+#   HYPERLIQUID_PRIVATE_KEY=0x... ruby test_integration.rb
+#
+# Note: This script executes real trades on testnet. No real funds are at risk.
+
+require_relative 'lib/hyperliquid'
+require 'json'
+
+WAIT_SECONDS = 10
+SPOT_SLIPPAGE = 0.40  # 40% for illiquid testnet spot markets
+PERP_SLIPPAGE = 0.05  # 5% for perp markets
+
+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 check_result(result, operation)
+  status = result.dig('response', 'data', 'statuses', 0)
+
+  if status.is_a?(Hash) && status['error']
+    puts "FAILED: #{status['error']}"
+    return false
+  end
+
+  if status.is_a?(Hash) && status['resting']
+    puts "Order resting with OID: #{status['resting']['oid']}"
+    return status['resting']['oid']
+  end
+
+  if status == 'success' || (status.is_a?(Hash) && status['filled'])
+    puts "#{operation} successful!"
+    return true
+  end
+
+  puts "Result: #{status.inspect}"
+  true
+end
+
+# --- Main Script ---
+
+private_key = ENV['HYPERLIQUID_PRIVATE_KEY']
+unless private_key
+  puts 'Error: Set HYPERLIQUID_PRIVATE_KEY environment variable'
+  puts 'Usage: HYPERLIQUID_PRIVATE_KEY=0x... ruby test_integration.rb'
+  exit 1
+end
+
+sdk = Hyperliquid.new(
+  testnet: true,
+  private_key: private_key
+)
+
+puts 'Hyperliquid Ruby SDK - Testnet Integration Test'
+puts '=' * 60
+puts "Wallet: #{sdk.exchange.address}"
+puts 'Network: Testnet'
+puts "Testnet UI: https://app.hyperliquid-testnet.xyz"
+
+# ============================================================
+# TEST 1: Spot Market Roundtrip (PURR/USDC)
+# ============================================================
+separator('TEST 1: Spot Market Roundtrip (PURR/USDC)')
+
+spot_coin = 'PURR/USDC'
+spot_size = 5  # PURR has 0 decimals
+
+mids = sdk.info.all_mids
+spot_price = mids[spot_coin]&.to_f
+
+if spot_price&.positive?
+  puts "#{spot_coin} mid: $#{spot_price}"
+  puts "Size: #{spot_size} PURR (~$#{(spot_size * spot_price).round(2)})"
+  puts "Slippage: #{(SPOT_SLIPPAGE * 100).to_i}%"
+  puts
+
+  # Buy
+  puts 'Placing market BUY...'
+  result = sdk.exchange.market_order(
+    coin: spot_coin,
+    is_buy: true,
+    size: spot_size,
+    slippage: SPOT_SLIPPAGE
+  )
+  check_result(result, 'Buy')
+
+  wait_with_countdown(WAIT_SECONDS, 'Waiting before sell...')
+
+  # Sell
+  puts 'Placing market SELL...'
+  result = sdk.exchange.market_order(
+    coin: spot_coin,
+    is_buy: false,
+    size: spot_size,
+    slippage: SPOT_SLIPPAGE
+  )
+  check_result(result, 'Sell')
+else
+  puts "SKIPPED: Could not get #{spot_coin} price"
+end
+
+# ============================================================
+# TEST 2: Spot Limit Order (Place and Cancel)
+# ============================================================
+separator('TEST 2: Spot Limit Order (Place and Cancel)')
+
+if spot_price&.positive?
+  # Place limit buy well below market (won't fill)
+  limit_price = (spot_price * 0.50).round(2)  # 50% below mid
+  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 "SKIPPED: Could not get #{spot_coin} price"
+end
+
+# ============================================================
+# TEST 3: Perp Market Roundtrip (BTC Long)
+# ============================================================
+separator('TEST 3: Perp Market Roundtrip (BTC Long)')
+
+perp_coin = 'BTC'
+btc_price = mids[perp_coin]&.to_f
+
+if btc_price&.positive?
+  # Get BTC metadata for size precision
+  meta = sdk.info.meta
+  btc_meta = meta['universe'].find { |a| a['name'] == perp_coin }
+  sz_decimals = btc_meta['szDecimals']
+
+  # Calculate size for ~$20 notional
+  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
+
+  # Open long
+  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...')
+
+  # Close long (sell to 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 "SKIPPED: Could not get #{perp_coin} price"
+end
+
+# ============================================================
+# TEST 4: Perp Limit Order (Short, then Cancel)
+# ============================================================
+separator('TEST 4: Perp Limit Order (Short, then Cancel)')
+
+if btc_price&.positive?
+  # Place limit sell well above market (won't fill)
+  limit_price = (btc_price * 1.50).round(0).to_i  # 50% above mid, whole number tick
+  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 "SKIPPED: Could not get #{perp_coin} price"
+end
+
+# ============================================================
+# Summary
+# ============================================================
+separator('INTEGRATION TEST COMPLETE')
+puts 'All tests executed. Check your testnet wallet for trade history:'
+puts 'https://app.hyperliquid-testnet.xyz'
+puts

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperliquid
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - carter2099
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: eth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -37,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: msgpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
 description: A Ruby SDK for interacting with Hyperliquid's decentralized exchange
   API
 email:
@@ -49,6 +77,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
@@ -56,11 +85,16 @@ files:
 - example.rb
 - lib/hyperliquid.rb
 - lib/hyperliquid/client.rb
+- lib/hyperliquid/cloid.rb
 - lib/hyperliquid/constants.rb
 - lib/hyperliquid/errors.rb
+- lib/hyperliquid/exchange.rb
 - lib/hyperliquid/info.rb
+- lib/hyperliquid/signing/eip712.rb
+- lib/hyperliquid/signing/signer.rb
 - lib/hyperliquid/version.rb
 - sig/hyperliquid.rbs
+- test_integration.rb
 homepage: https://github.com/carter2099/hyperliquid
 licenses:
 - MIT