hyperliquid 0.3.0 → 0.4.1

data/docs/EXAMPLES.md

@@ -0,0 +1,342 @@
+# Examples
+
+## Info API
+
+### General Info
+
+```ruby
+# Retrieve mids for all coins
+mids = sdk.info.all_mids
+# => { "BTC" => "50000", "ETH" => "3000", ... }
+
+user_address = "0x..."
+
+# Retrieve a user's open orders
+orders = sdk.info.open_orders(user_address)
+# => [{ "coin" => "BTC", "sz" => "0.1", "px" => "50000", "side" => "A" }]
+
+# Retrieve a user's open orders with additional frontend info
+frontend_orders = sdk.info.frontend_open_orders(user_address)
+# => [{ "coin" => "BTC", "isTrigger" => false, ... }]
+
+# Retrieve a user's fills
+fills = sdk.info.user_fills(user_address)
+# => [{ "coin" => "BTC", "sz" => "0.1", "px" => "50000", "side" => "A", "time" => 1234567890 }]
+
+# Retrieve a user's fills by time
+start_time_ms = 1_700_000_000_000
+end_time_ms = start_time_ms + 86_400_000
+fills_by_time = sdk.info.user_fills_by_time(user_address, start_time_ms, end_time_ms)
+# => [{ "coin" => "ETH", "px" => "3000", "time" => start_time_ms }, ...]
+
+# Query user rate limits
+rate_limit = sdk.info.user_rate_limit(user_address)
+# => { "nRequestsUsed" => 100, "nRequestsCap" => 10000 }
+
+# Query order status by oid
+order_id = 12345
+status_by_oid = sdk.info.order_status(user_address, order_id)
+# => { "status" => "filled", ... }
+
+# Query order status by cloid
+cloid = "client-order-id-123"
+status_by_cloid = sdk.info.order_status_by_cloid(user_address, cloid)
+# => { "status" => "cancelled", ... }
+
+# L2 order book snapshot
+book = sdk.info.l2_book("BTC")
+# => { "coin" => "BTC", "levels" => [[asks], [bids]], "time" => ... }
+
+# Candle snapshot
+candles = sdk.info.candles_snapshot("BTC", "1h", start_time_ms, end_time_ms)
+# => [{ "t" => ..., "o" => "50000", "h" => "51000", "l" => "49000", "c" => "50500", "v" => "100" }]
+
+# Check builder fee approval
+builder_address = "0x..."
+fee_approval = sdk.info.max_builder_fee(user_address, builder_address)
+# => { "approved" => true, ... }
+
+# Retrieve a user's historical orders
+hist_orders = sdk.info.historical_orders(user_address)
+# => [{ "oid" => 123, "coin" => "BTC", ... }]
+hist_orders_ranged = sdk.info.historical_orders(user_address, start_time_ms, end_time_ms)
+# => []
+
+# Retrieve a user's TWAP slice fills
+twap_fills = sdk.info.user_twap_slice_fills(user_address)
+# => [{ "sliceId" => 1, "coin" => "ETH", "sz" => "1.0" }, ...]
+twap_fills_ranged = sdk.info.user_twap_slice_fills(user_address, start_time_ms, end_time_ms)
+# => []
+
+# Retrieve a user's subaccounts
+subaccounts = sdk.info.user_subaccounts(user_address)
+# => ["0x1111...", ...]
+
+# Retrieve details for a vault
+vault_addr = "0x..."
+vault = sdk.info.vault_details(vault_addr)
+# => { "vaultAddress" => vault_addr, ... }
+vault_with_user = sdk.info.vault_details(vault_addr, user_address)
+# => { "vaultAddress" => vault_addr, "user" => user_address, ... }
+
+# Retrieve a user's vault deposits
+vault_deposits = sdk.info.user_vault_equities(user_address)
+# => [{ "vaultAddress" => "0x...", "equity" => "123.45" }, ...]
+
+# Query a user's role
+role = sdk.info.user_role(user_address)
+# => { "role" => "tradingUser" }
+
+# Query a user's portfolio
+portfolio = sdk.info.portfolio(user_address)
+# => [["day", { "pnlHistory" => [...], "vlm" => "0.0" }], ...]
+
+# Query a user's referral information
+referral = sdk.info.referral(user_address)
+# => { "referredBy" => { "referrer" => "0x..." }, ... }
+
+# Query a user's fees
+fees = sdk.info.user_fees(user_address)
+# => { "userAddRate" => "0.0001", "feeSchedule" => { ... } }
+
+# Query a user's staking delegations
+delegations = sdk.info.delegations(user_address)
+# => [{ "validator" => "0x...", "amount" => "100.0" }, ...]
+
+# Query a user's staking summary
+summary = sdk.info.delegator_summary(user_address)
+# => { "delegated" => "12060.16529862", ... }
+
+# Query a user's staking history
+history = sdk.info.delegator_history(user_address)
+# => [{ "time" => 1_736_726_400_073, "delta" => { ... } }, ...]
+
+# Query a user's staking rewards
+rewards = sdk.info.delegator_rewards(user_address)
+# => [{ "time" => 1_736_726_400_073, "source" => "delegation", "totalAmount" => "0.123" }, ...]
+```
+
+**Note:** `l2_book` and `candles_snapshot` work for both Perpetuals and Spot. For spot, use `"{BASE}/USDC"` when available (e.g., `"PURR/USDC"`). Otherwise, use the index alias `"@{index}"` from `spot_meta["universe"]`.
+
+### Perpetuals
+
+```ruby
+# Retrieve all perpetual DEXs
+perp_dexs = sdk.info.perp_dexs
+# => [nil, { "name" => "test", "full_name" => "test dex", ... }]
+
+# Retrieve perpetuals metadata (optionally for a specific perp dex)
+meta = sdk.info.meta
+# => { "universe" => [...] }
+meta = sdk.info.meta(dex: "perp-dex-name")
+# => { "universe" => [...] }
+
+# Retrieve perpetuals asset contexts (includes mark price, current funding, open interest, etc.)
+meta_ctxs = sdk.info.meta_and_asset_ctxs
+# => { "universe" => [...], "assetCtxs" => [...] }
+
+# Retrieve user's perpetuals account summary (optionally for a specific perp dex)
+state = sdk.info.user_state(user_address)
+# => { "assetPositions" => [...], "marginSummary" => {...} }
+state = sdk.info.user_state(user_address, dex: "perp-dex-name")
+# => { "assetPositions" => [...], "marginSummary" => {...} }
+
+# Retrieve a user's funding history or non-funding ledger updates (optional end_time)
+funding = sdk.info.user_funding(user_address, start_time)
+# => [{ "delta" => { "type" => "funding", ... }, "time" => ... }]
+funding = sdk.info.user_funding(user_address, start_time, end_time)
+# => [{ "delta" => { "type" => "funding", ... }, "time" => ... }]
+
+# Retrieve historical funding rates
+hist = sdk.info.funding_history("ETH", start_time)
+# => [{ "coin" => "ETH", "fundingRate" => "...", "time" => ... }]
+
+# Retrieve predicted funding rates for different venues
+pred = sdk.info.predicted_fundings
+# => [["AVAX", [["HlPerp", { "fundingRate" => "0.0000125", "nextFundingTime" => ... }], ...]], ...]
+
+# Query perps at open interest caps
+oi_capped = sdk.info.perps_at_open_interest_cap
+# => ["BADGER", "CANTO", ...]
+
+# Retrieve information about the Perp Deploy Auction
+auction = sdk.info.perp_deploy_auction_status
+# => { "startTimeSeconds" => ..., "durationSeconds" => ..., "startGas" => "500.0", ... }
+
+# Retrieve User's Active Asset Data
+aad = sdk.info.active_asset_data(user_address, "APT")
+# => { "user" => user_address, "coin" => "APT", "leverage" => { "type" => "cross", "value" => 3 }, ... }
+
+# Retrieve Builder-Deployed Perp Market Limits
+limits = sdk.info.perp_dex_limits("builder-dex")
+# => { "totalOiCap" => "10000000.0", "oiSzCapPerPerp" => "...", ... }
+```
+
+### Spot
+
+```ruby
+# Retrieve spot metadata
+spot_meta = sdk.info.spot_meta
+# => { "tokens" => [...], "universe" => [...] }
+
+# Retrieve spot asset contexts
+spot_meta_ctxs = sdk.info.spot_meta_and_asset_ctxs
+# => [ { "tokens" => [...], "universe" => [...] }, [ { "midPx" => "...", ... } ] ]
+
+# Retrieve a user's token balances
+balances = sdk.info.spot_balances(user_address)
+# => { "balances" => [{ "coin" => "USDC", "token" => 0, "total" => "..." }, ...] }
+
+# Retrieve information about the Spot Deploy Auction
+deploy_state = sdk.info.spot_deploy_state(user_address)
+# => { "states" => [...], "gasAuction" => { ... } }
+
+# Retrieve information about the Spot Pair Deploy Auction
+pair_status = sdk.info.spot_pair_deploy_auction_status
+# => { "startTimeSeconds" => ..., "durationSeconds" => ..., "startGas" => "...", ... }
+
+# Retrieve information about a token by onchain id in 34-character hexadecimal format
+details = sdk.info.token_details("0x00000000000000000000000000000000")
+# => { "name" => "TEST", "maxSupply" => "...", "midPx" => "...", ... }
+```
+
+## Exchange API (Trading)
+
+### Basic Orders
+
+```ruby
+# Initialize SDK with private key for trading
+sdk = Hyperliquid.new(
+  testnet: true,
+  private_key: ENV['HYPERLIQUID_PRIVATE_KEY']
+)
+
+# Get wallet address
+address = sdk.exchange.address
+# => "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
+
+# Place a limit buy order
+result = sdk.exchange.order(
+  coin: 'BTC',
+  is_buy: true,
+  size: '0.01',
+  limit_px: '95000',
+  order_type: { limit: { tif: 'Gtc' } }  # Good-til-canceled (default)
+)
+# => { "status" => "ok", "response" => { "type" => "order", "data" => { "statuses" => [...] } } }
+
+# Place a limit sell order with client order ID
+cloid = Hyperliquid::Cloid.from_int(123)  # Or Cloid.random
+result = sdk.exchange.order(
+  coin: 'ETH',
+  is_buy: false,
+  size: '0.5',
+  limit_px: '3500',
+  cloid: cloid
+)
+
+# Place a market order (IoC with slippage)
+result = sdk.exchange.market_order(
+  coin: 'BTC',
+  is_buy: true,
+  size: '0.01',
+  slippage: 0.03  # 3% slippage tolerance (default: 5%)
+)
+
+# Place multiple orders at once
+orders = [
+  { coin: 'BTC', is_buy: true, size: '0.01', limit_px: '94000' },
+  { coin: 'BTC', is_buy: false, size: '0.01', limit_px: '96000' }
+]
+result = sdk.exchange.bulk_orders(orders: orders)
+```
+
+### Canceling Orders
+
+```ruby
+# Cancel an order by order ID
+oid = result.dig('response', 'data', 'statuses', 0, 'resting', 'oid')
+sdk.exchange.cancel(coin: 'BTC', oid: oid)
+
+# Cancel an order by client order ID
+sdk.exchange.cancel_by_cloid(coin: 'ETH', cloid: cloid)
+
+# Cancel multiple orders by order ID
+cancels = [
+  { coin: 'BTC', oid: 12345 },
+  { coin: 'ETH', oid: 12346 }
+]
+sdk.exchange.bulk_cancel(cancels: cancels)
+
+# Cancel multiple orders by client order ID
+cloid_cancels = [
+  { coin: 'BTC', cloid: Hyperliquid::Cloid.from_int(1) },
+  { coin: 'ETH', cloid: Hyperliquid::Cloid.from_int(2) }
+]
+sdk.exchange.bulk_cancel_by_cloid(cancels: cloid_cancels)
+```
+
+### Vault Trading
+
+```ruby
+# Vault trading (trade on behalf of a vault)
+vault_address = '0x...'
+sdk.exchange.order(
+  coin: 'BTC',
+  is_buy: true,
+  size: '1.0',
+  limit_px: '95000',
+  vault_address: vault_address
+)
+```
+
+### Trigger Orders (Stop Loss / Take Profit)
+
+```ruby
+# Stop loss: Sell when price drops to trigger level
+sdk.exchange.order(
+  coin: 'BTC',
+  is_buy: false,
+  size: '0.1',
+  limit_px: '89900',
+  order_type: {
+    trigger: {
+      trigger_px: 90_000,
+      is_market: true,  # Execute as market order when triggered
+      tpsl: 'sl'        # Stop loss
+    }
+  }
+)
+
+# Take profit: Sell when price rises to trigger level
+sdk.exchange.order(
+  coin: 'BTC',
+  is_buy: false,
+  size: '0.1',
+  limit_px: '100100',
+  order_type: {
+    trigger: {
+      trigger_px: 100_000,
+      is_market: false,  # Execute as limit order when triggered
+      tpsl: 'tp'         # Take profit
+    }
+  }
+)
+```
+
+### Client Order IDs (Cloid)
+
+```ruby
+# Create from integer (zero-padded to 16 bytes)
+cloid = Hyperliquid::Cloid.from_int(42)
+# => "0x0000000000000000000000000000002a"
+
+# Create from hex string
+cloid = Hyperliquid::Cloid.from_str('0x1234567890abcdef1234567890abcdef')
+
+# Create from UUID
+cloid = Hyperliquid::Cloid.from_uuid('550e8400-e29b-41d4-a716-446655440000')
+
+# Generate random
+cloid = Hyperliquid::Cloid.random
+```

data/example.rb

@@ -5,54 +5,157 @@ require_relative 'lib/hyperliquid'
 
 # Example usage of the Hyperliquid Ruby SDK
 
+puts 'Hyperliquid Ruby SDK v0.4.0 - API Examples'
+puts '=' * 50
+
+# =============================================================================
+# INFO API (Read-only, no authentication required)
+# =============================================================================
+
 # Create a new SDK instance (defaults to mainnet)
 sdk = Hyperliquid.new
 
-puts 'Hyperliquid Ruby SDK v0.1 - Info API Examples'
-puts '=' * 50
+puts "\n--- INFO API EXAMPLES ---\n"
 
 # Example 1: Get all market mid prices
 begin
-  puts "\n1. Getting all market mid prices..."
+  puts '1. Getting all market mid prices...'
   mids = sdk.info.all_mids
-  puts "Found #{mids.length} markets" if mids.is_a?(Hash)
+  puts "   Found #{mids.length} markets" if mids.is_a?(Hash)
+  puts "   BTC mid: #{mids['BTC']}" if mids['BTC']
 rescue Hyperliquid::Error => e
-  puts "Error getting market mids: #{e.message}"
+  puts "   Error: #{e.message}"
 end
 
-# Example 2: Get metadata for all assets
+# Example 2: Get metadata for all perpetual assets
 begin
-  puts "\n2. Getting asset metadata..."
+  puts "\n2. Getting perpetual asset metadata..."
   meta = sdk.info.meta
-  puts 'Got metadata for universe' if meta.is_a?(Hash)
+  universe = meta['universe'] || []
+  puts "   Found #{universe.length} perpetual assets"
+  puts "   First asset: #{universe.first['name']}" if universe.any?
+rescue Hyperliquid::Error => e
+  puts "   Error: #{e.message}"
+end
+
+# Example 3: Get L2 order book
+begin
+  puts "\n3. Getting L2 order book for BTC..."
+  book = sdk.info.l2_book('BTC')
+  levels = book['levels'] || []
+  puts "   Bid levels: #{levels[0]&.length || 0}, Ask levels: #{levels[1]&.length || 0}"
 rescue Hyperliquid::Error => e
-  puts "Error getting metadata: #{e.message}"
+  puts "   Error: #{e.message}"
 end
 
-# Example 3: Use testnet
-puts "\n3. Using testnet..."
+# Example 4: Get spot metadata
+begin
+  puts "\n4. Getting spot asset metadata..."
+  spot_meta = sdk.info.spot_meta
+  tokens = spot_meta['tokens'] || []
+  puts "   Found #{tokens.length} spot tokens"
+rescue Hyperliquid::Error => e
+  puts "   Error: #{e.message}"
+end
+
+# Example 5: Use testnet
+puts "\n5. Creating testnet SDK..."
 testnet_sdk = Hyperliquid.new(testnet: true)
-puts "Testnet SDK created, base URL: #{testnet_sdk.base_url}"
+puts "   Testnet base URL: #{testnet_sdk.base_url}"
 
-# Example 4: User-specific endpoints (requires valid wallet address)
-wallet_address = "0x#{'0' * 40}" # Example placeholder address
+# Example 6: User-specific endpoints (requires valid wallet address)
+wallet_address = "0x#{'0' * 40}" # Placeholder address
 
 begin
-  puts "\n4. Getting open orders for wallet #{wallet_address[0..10]}..."
-  orders = sdk.info.open_orders(wallet_address)
-  puts "Open orders: #{orders}"
+  puts "\n6. Getting user state for #{wallet_address[0..13]}..."
+  state = sdk.info.user_state(wallet_address)
+  puts "   Account value: #{state.dig('marginSummary', 'accountValue') || 'N/A'}"
 rescue Hyperliquid::Error => e
-  puts "Error getting open orders: #{e.message}"
+  puts "   Error: #{e.message}"
 end
 
+# =============================================================================
+# EXCHANGE API (Authenticated, requires private key)
+# =============================================================================
+
+puts "\n--- EXCHANGE API EXAMPLES ---\n"
+puts "(These examples are commented out to prevent accidental execution)\n"
+
+# To use the Exchange API, create an SDK with your private key:
+#
+#   sdk = Hyperliquid.new(
+#     testnet: true,  # Use testnet for testing!
+#     private_key: ENV['HYPERLIQUID_PRIVATE_KEY']
+#   )
+#
+# Your wallet address:
+#   puts sdk.exchange.address
+#
+# Place a limit order:
+#   result = sdk.exchange.order(
+#     coin: 'BTC',
+#     is_buy: true,
+#     size: 0.001,
+#     limit_px: 50000.0,
+#     order_type: { limit: { tif: 'Gtc' } },
+#     reduce_only: false
+#   )
+#
+# Place a market order (uses slippage):
+#   result = sdk.exchange.market_order(
+#     coin: 'BTC',
+#     is_buy: true,
+#     size: 0.001,
+#     slippage: 0.01  # 1% slippage
+#   )
+#
+# Place a stop loss order:
+#   result = sdk.exchange.order(
+#     coin: 'BTC',
+#     is_buy: false,
+#     size: 0.001,
+#     limit_px: 48000.0,
+#     order_type: {
+#       trigger: {
+#         trigger_px: 49000.0,
+#         is_market: false,
+#         tpsl: 'sl'
+#       }
+#     },
+#     reduce_only: true
+#   )
+#
+# Cancel an order by OID:
+#   result = sdk.exchange.cancel(coin: 'BTC', oid: 123456789)
+#
+# Cancel an order by client order ID:
+#   result = sdk.exchange.cancel_by_cloid(coin: 'BTC', cloid: '0x...')
+#
+# Bulk cancel multiple orders:
+#   result = sdk.exchange.bulk_cancel([
+#     { coin: 'BTC', oid: 123 },
+#     { coin: 'ETH', oid: 456 }
+#   ])
+#
+# Use client order IDs for tracking:
+#   cloid = Hyperliquid::Cloid.random
+#   result = sdk.exchange.order(
+#     coin: 'BTC',
+#     is_buy: true,
+#     size: 0.001,
+#     limit_px: 50000.0,
+#     cloid: cloid
+#   )
+#   puts "Order placed with cloid: #{cloid}"
+#
+# Trade on behalf of a vault:
+#   result = sdk.exchange.order(
+#     coin: 'BTC',
+#     is_buy: true,
+#     size: 0.001,
+#     limit_px: 50000.0,
+#     vault_address: '0x...'
+#   )
+
+puts 'See commented code above for Exchange API usage patterns.'
 puts "\nSDK examples completed!"
-puts "\nAvailable Info methods:"
-puts '- all_mids() - Get all market mid prices'
-puts "- open_orders(user) - Get user's open orders"
-puts "- user_fills(user) - Get user's fill history"
-puts '- order_status(user, oid) - Get order status'
-puts "- user_state(user) - Get user's trading state"
-puts '- meta() - Get asset metadata'
-puts '- meta_and_asset_ctxs() - Get extended asset metadata'
-puts '- l2_book(coin) - Get L2 order book'
-puts '- candles_snapshot(coin, interval, start_time, end_time) - Get candlestick data'

data/lib/hyperliquid/cloid.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Hyperliquid
+  # Client Order ID for tracking orders
+  # Must be a 16-byte hex string in format: 0x + 32 hex characters
+  class Cloid
+    # Initialize a new Cloid from a raw hex string
+    # @param raw_cloid [String] Hex string in format 0x + 32 hex characters
+    # @raise [ArgumentError] If format is invalid
+    def initialize(raw_cloid)
+      @raw_cloid = raw_cloid.downcase
+      validate!
+    end
+
+    # Get the raw hex string representation
+    # @return [String] The raw cloid string
+    def to_raw
+      @raw_cloid
+    end
+
+    # String representation
+    # @return [String] The raw cloid string
+    def to_s
+      @raw_cloid
+    end
+
+    # Inspect representation
+    # @return [String] The raw cloid string
+    def inspect
+      @raw_cloid
+    end
+
+    # Equality check
+    # @param other [Cloid, String] Another Cloid or string to compare
+    # @return [Boolean] True if equal
+    def ==(other)
+      case other
+      when Cloid
+        @raw_cloid == other.to_raw
+      when String
+        @raw_cloid == other.downcase
+      else
+        false
+      end
+    end
+
+    alias eql? ==
+
+    # Hash for use in Hash keys
+    # @return [Integer] Hash value
+    def hash
+      @raw_cloid.hash
+    end
+
+    class << self
+      # Create a Cloid from an integer
+      # @param value [Integer] Integer value (0 to 2^128-1)
+      # @return [Cloid] New Cloid instance
+      # @raise [ArgumentError] If value is out of range
+      def from_int(value)
+        raise ArgumentError, 'cloid integer must be non-negative' if value.negative?
+        raise ArgumentError, 'cloid integer must be less than 2^128' if value >= 2**128
+
+        new(format('0x%032x', value))
+      end
+
+      # Create a Cloid from a hex string
+      # @param value [String] Hex string in format 0x + 32 hex characters
+      # @return [Cloid] New Cloid instance
+      def from_str(value)
+        new(value)
+      end
+
+      # Generate a random Cloid
+      # @return [Cloid] New random Cloid instance
+      def random
+        from_int(SecureRandom.random_number(2**128))
+      end
+
+      # Create a Cloid from a UUID string
+      # @param uuid [String] UUID string (with or without dashes)
+      # @return [Cloid] New Cloid instance
+      def from_uuid(uuid)
+        hex = uuid.delete('-').downcase
+        raise ArgumentError, 'UUID must be 32 hex characters' unless hex.match?(/\A[0-9a-f]{32}\z/)
+
+        new("0x#{hex}")
+      end
+    end
+
+    private
+
+    def validate!
+      return if @raw_cloid.match?(/\A0x[0-9a-f]{32}\z/)
+
+      raise ArgumentError,
+            "cloid must be '0x' followed by 32 hex characters (16 bytes). Got: #{@raw_cloid.inspect}"
+    end
+  end
+end

data/lib/hyperliquid/constants.rb

@@ -9,6 +9,7 @@ module Hyperliquid
 
     # API endpoints
     INFO_ENDPOINT = '/info'
+    EXCHANGE_ENDPOINT = '/exchange'
 
     # Request timeouts (seconds)
     DEFAULT_TIMEOUT = 30