hyperliquid 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 184e215d2d80056cb19bd6a20b273134d9997979d160d154318c5e155cdf02bb
-  data.tar.gz: 1f2bd8b08ef2e99e3732bd7775eeb70fe00ad7c2f4210312d07d237d28e670ed
+  metadata.gz: e4e2d29336f0e921d82f0f7a154676a102a228fd5aa4811b85db890802330865
+  data.tar.gz: ff28b26c30bd14549def4e1f5adb3193ab812cc4527da50109dd17d5bc333816
 SHA512:
-  metadata.gz: 1b8645b6f40ae9163343fbc6d7d5c814417643469d75ac320073546243d601055c26f92e1ecb272baf9d839dc4b983b19d56be01cc2bcf4709de9f0e6bf81116
-  data.tar.gz: 462b64553e8ee0939bf0284b0647ec602f9be2f3b2389144e64188813cf52d1bca1daf3feb233eab1167fb1337bda7028208acc38398e55a6279e2593ab26181
+  metadata.gz: d19f8ddf0b9d7cb16a7791a2d7117725929e956c05a46a27b11cc9b27bb051f0c4d7b1cfc1053e3683a9577ceaacbd96ebd3b06a3541d527f9c0437e5de067b1
+  data.tar.gz: 8a590a96b1e14b8178e3d628cb8e498d718e0a41963dad0671ead93c06df3d389e2fe2c3082d2a27965eb0adf46370e1508f8a9b0cb2e002444c225e39d8aa79

data/CHANGELOG.md

@@ -1,6 +1,16 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
-## [0.4.1] - 2025-01-28
+## [0.5.0] - 2026-01-28
+
+- Add core trading features to Exchange API (Tier 1 parity with Python SDK)
+  - Order modification: `modify_order`, `batch_modify`
+  - Position management: `update_leverage`, `update_isolated_margin`, `market_close`
+  - Dead man's switch: `schedule_cancel`
+- Add `market_close` helper for closing positions at market price with auto-detection of size and direction
+- Add integration tests for leverage updates, order modification, and market close
+- Add GitHub Release workflow (`.github/workflows/release.yml`)
+
+## [0.4.1] - 2026-01-28
 
 - Reorganize documentation for improved readability
   - Streamline README with basic setup and links to detailed docs
@@ -10,7 +20,7 @@
   - Add `docs/ERRORS.md` with error handling guide
   - Add `docs/DEVELOPMENT.md` with setup and testing instructions
 
-## [0.4.0] - 2025-01-27
+## [0.4.0] - 2026-01-27
 
 - Add Exchange API for authenticated write operations (trading)
   - Order placement: `order`, `bulk_orders`, `market_order`

data/README.md

@@ -1,5 +1,9 @@
 # Hyperliquid Ruby SDK
 
+[![Gem Version](https://badge.fury.io/rb/hyperliquid.svg)](https://rubygems.org/gems/hyperliquid)
+[![Downloads](https://img.shields.io/gem/dt/hyperliquid.svg)](https://rubygems.org/gems/hyperliquid)
+[![CI](https://github.com/carter2099/hyperliquid/actions/workflows/main.yml/badge.svg)](https://github.com/carter2099/hyperliquid/actions)
+
 A Ruby SDK for interacting with the Hyperliquid decentralized exchange API.
 
 The SDK supports both read operations (Info API) and authenticated write operations (Exchange API) for trading.
@@ -54,14 +58,6 @@ exchange = trading_sdk.exchange
 - [Error Handling](docs/ERRORS.md) - Error types and handling
 - [Development](docs/DEVELOPMENT.md) - Contributing and running tests
 
-## Roadmap
-
-The SDK now supports both Info API (read) and Exchange API (trading). Future versions will include:
-
-- WebSocket support for real-time data
-- Additional exchange operations (leverage, margin adjustments, transfers)
-- Advanced trading features (TWAP, etc.)
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/carter2099/hyperliquid.

data/SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+## For Issues in Hyperliquid
+
+If you have discovered a vulnerability or security issue related to the Hyperliquid service (e.g., buffer overflow, SQL
+injection, cross-site scripting, etc.), please refer to the
+[Hyperliquid Security Policy](https://github.com/hyperliquid-dex/hyperliquid-python-sdk/blob/master/SECURITY.md).

data/docs/API.md

@@ -59,13 +59,33 @@ Read-only methods for querying market data and user information.
 
 **Note:** Exchange methods require initializing the SDK with a `private_key`.
 
+### Order Placement
+
 - `order(coin:, is_buy:, size:, limit_px:, ...)` - Place a single limit order
 - `bulk_orders(orders:, grouping:, ...)` - Place multiple orders in a batch
 - `market_order(coin:, is_buy:, size:, slippage:, ...)` - Place a market order with slippage
+
+### Order Modification
+
+- `modify_order(oid:, coin:, is_buy:, size:, limit_px:, ...)` - Modify an existing order by oid or cloid
+- `batch_modify(modifies:, ...)` - Modify multiple orders at once
+
+### Order Cancellation
+
 - `cancel(coin:, oid:, ...)` - Cancel an order by order ID
 - `cancel_by_cloid(coin:, cloid:, ...)` - Cancel an order by client order ID
 - `bulk_cancel(cancels:, ...)` - Cancel multiple orders by order ID
 - `bulk_cancel_by_cloid(cancels:, ...)` - Cancel multiple orders by client order ID
+- `schedule_cancel(time:, ...)` - Auto-cancel all orders at a given time
+
+### Position Management
+
+- `market_close(coin:, size:, slippage:, ...)` - Close a position at market price (auto-detects position size)
+- `update_leverage(coin:, leverage:, is_cross:, ...)` - Set cross or isolated leverage for a coin
+- `update_isolated_margin(coin:, amount:, ...)` - Add or remove isolated margin for a position
+
+### Other
+
 - `address` - Get the wallet address associated with the private key
 
 All exchange methods support an optional `vault_address:` parameter for vault trading.

data/docs/EXAMPLES.md

@@ -276,6 +276,70 @@ cloid_cancels = [
 sdk.exchange.bulk_cancel_by_cloid(cancels: cloid_cancels)
 ```
 
+### Modifying Orders
+
+```ruby
+# Modify an existing order by order ID
+oid = result.dig('response', 'data', 'statuses', 0, 'resting', 'oid')
+sdk.exchange.modify_order(
+  oid: oid,
+  coin: 'BTC',
+  is_buy: true,
+  size: '0.02',
+  limit_px: '96000'
+)
+
+# Modify an order by client order ID
+cloid = Hyperliquid::Cloid.from_int(123)
+sdk.exchange.modify_order(
+  oid: cloid,
+  coin: 'BTC',
+  is_buy: true,
+  size: '0.02',
+  limit_px: '96000'
+)
+
+# Modify multiple orders at once
+modifies = [
+  { oid: 12345, coin: 'BTC', is_buy: true, size: '0.01', limit_px: '95000' },
+  { oid: 12346, coin: 'ETH', is_buy: false, size: '0.5', limit_px: '3200' }
+]
+sdk.exchange.batch_modify(modifies: modifies)
+```
+
+### Position Management
+
+```ruby
+# Set cross leverage (default)
+sdk.exchange.update_leverage(coin: 'BTC', leverage: 5)
+
+# Set isolated leverage
+sdk.exchange.update_leverage(coin: 'BTC', leverage: 10, is_cross: false)
+
+# Add isolated margin to a position (positive amount)
+sdk.exchange.update_isolated_margin(coin: 'BTC', amount: 100.0)
+
+# Remove isolated margin from a position (negative amount)
+sdk.exchange.update_isolated_margin(coin: 'BTC', amount: -50.0)
+
+# Close an entire position at market price (auto-detects size and direction)
+sdk.exchange.market_close(coin: 'BTC')
+
+# Close a partial position with custom slippage
+sdk.exchange.market_close(coin: 'BTC', size: 0.01, slippage: 0.03)
+```
+
+### Schedule Cancel
+
+```ruby
+# Schedule auto-cancel of all orders at a specific time
+cancel_time = (Time.now.to_f * 1000).to_i + 60_000  # 60 seconds from now
+sdk.exchange.schedule_cancel(time: cancel_time)
+
+# Activate schedule cancel without specifying a time (server default)
+sdk.exchange.schedule_cancel
+```
+
 ### Vault Trading
 
 ```ruby

data/lib/hyperliquid/exchange.rb

@@ -213,6 +213,167 @@ module Hyperliquid
       post_action(action, signature, nonce, vault_address)
     end
 
+    # Modify a single existing order
+    # @param oid [Integer, Cloid, String] Order ID or client order ID to modify
+    # @param coin [String] Asset symbol (e.g., "BTC")
+    # @param is_buy [Boolean] True for buy, false for sell
+    # @param size [String, Numeric] New order size
+    # @param limit_px [String, Numeric] New limit price
+    # @param order_type [Hash] Order type config (default: { limit: { tif: "Gtc" } })
+    # @param reduce_only [Boolean] Reduce-only flag (default: false)
+    # @param cloid [Cloid, String, nil] Client order ID for the modified order (optional)
+    # @param vault_address [String, nil] Vault address for vault trading (optional)
+    # @return [Hash] Modify response
+    def modify_order(oid:, coin:, is_buy:, size:, limit_px:,
+                     order_type: { limit: { tif: 'Gtc' } },
+                     reduce_only: false, cloid: nil, vault_address: nil)
+      batch_modify(
+        modifies: [{
+          oid: oid, coin: coin, is_buy: is_buy, size: size,
+          limit_px: limit_px, order_type: order_type,
+          reduce_only: reduce_only, cloid: cloid
+        }],
+        vault_address: vault_address
+      )
+    end
+
+    # Modify multiple orders at once
+    # @param modifies [Array<Hash>] Array of modify hashes with keys:
+    #   :oid, :coin, :is_buy, :size, :limit_px, :order_type, :reduce_only, :cloid
+    # @param vault_address [String, nil] Vault address for vault trading (optional)
+    # @return [Hash] Batch modify response
+    def batch_modify(modifies:, vault_address: nil)
+      nonce = timestamp_ms
+
+      modify_wires = modifies.map do |m|
+        order_wire = build_order_wire(
+          coin: m[:coin],
+          is_buy: m[:is_buy],
+          size: m[:size],
+          limit_px: m[:limit_px],
+          order_type: m[:order_type] || { limit: { tif: 'Gtc' } },
+          reduce_only: m[:reduce_only] || false,
+          cloid: m[:cloid]
+        )
+        { oid: normalize_oid(m[:oid]), order: order_wire }
+      end
+
+      action = {
+        type: 'batchModify',
+        modifies: modify_wires
+      }
+
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        vault_address: vault_address,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, vault_address)
+    end
+
+    # Set cross or isolated leverage for a coin
+    # @param coin [String] Asset symbol (perps only)
+    # @param leverage [Integer] Leverage value
+    # @param is_cross [Boolean] True for cross margin, false for isolated (default: true)
+    # @param vault_address [String, nil] Vault address for vault trading (optional)
+    # @return [Hash] Leverage update response
+    def update_leverage(coin:, leverage:, is_cross: true, vault_address: nil)
+      nonce = timestamp_ms
+
+      action = {
+        type: 'updateLeverage',
+        asset: asset_index(coin),
+        isCross: is_cross,
+        leverage: leverage
+      }
+
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        vault_address: vault_address,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, vault_address)
+    end
+
+    # Add or remove isolated margin for a position
+    # @param coin [String] Asset symbol (perps only)
+    # @param amount [Numeric] Amount in USD (positive to add, negative to remove)
+    # @param vault_address [String, nil] Vault address for vault trading (optional)
+    # @return [Hash] Margin update response
+    def update_isolated_margin(coin:, amount:, vault_address: nil)
+      nonce = timestamp_ms
+
+      action = {
+        type: 'updateIsolatedMargin',
+        asset: asset_index(coin),
+        isBuy: true,
+        ntli: float_to_usd_int(amount)
+      }
+
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        vault_address: vault_address,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, vault_address)
+    end
+
+    # Schedule automatic cancellation of all orders
+    # @param time [Integer, nil] UTC timestamp in milliseconds to cancel at (nil to activate with server default)
+    # @param vault_address [String, nil] Vault address for vault trading (optional)
+    # @return [Hash] Schedule cancel response
+    def schedule_cancel(time: nil, vault_address: nil)
+      nonce = timestamp_ms
+
+      action = { type: 'scheduleCancel' }
+      action[:time] = time if time
+
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        vault_address: vault_address,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, vault_address)
+    end
+
+    # Close a position at market price
+    # @param coin [String] Asset symbol (perps only)
+    # @param size [Numeric, nil] Size to close (nil = close entire position)
+    # @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)
+    # @return [Hash] Order response
+    def market_close(coin:, size: nil, slippage: DEFAULT_SLIPPAGE, cloid: nil, vault_address: nil)
+      address = vault_address || @signer.address
+      state = @info.user_state(address)
+
+      position = state['assetPositions']&.find do |pos|
+        pos.dig('position', 'coin') == coin
+      end
+      raise ArgumentError, "No open position found for #{coin}" unless position
+
+      szi = position.dig('position', 'szi').to_f
+      is_buy = szi.negative?
+      close_size = size || szi.abs
+
+      mids = @info.all_mids
+      mid = mids[coin]&.to_f
+      raise ArgumentError, "Unknown asset or no price available: #{coin}" unless mid&.positive?
+
+      slippage_price = calculate_slippage_price(coin, mid, is_buy, slippage)
+
+      order(
+        coin: coin,
+        is_buy: is_buy,
+        size: close_size,
+        limit_px: slippage_price,
+        order_type: { limit: { tif: 'Ioc' } },
+        reduce_only: true,
+        cloid: cloid,
+        vault_address: vault_address
+      )
+    end
+
     # Clear the asset metadata cache
     # Call this if metadata has been updated
     def reload_metadata!
@@ -345,6 +506,29 @@ module Hyperliquid
       format("%.#{decimal_places}f", rounded)
     end
 
+    # Normalize an order ID to the correct wire format
+    # @param oid [Integer, Cloid, String] Order ID or client order ID
+    # @return [Integer, String] Normalized order ID
+    def normalize_oid(oid)
+      case oid
+      when Integer then oid
+      when Cloid then oid.to_raw
+      when String then normalize_cloid(oid)
+      else raise ArgumentError, "oid must be Integer, Cloid, or String. Got: #{oid.class}"
+      end
+    end
+
+    # Convert a float USD amount to an integer (scaled by 10^6)
+    # @param value [Numeric] USD amount
+    # @return [Integer] Scaled integer value
+    def float_to_usd_int(value)
+      scaled = value.to_f * 1_000_000
+      rounded = scaled.round
+      raise ArgumentError, "float_to_usd_int causes rounding: #{value}" if (rounded - scaled).abs >= 1e-3
+
+      rounded
+    end
+
     # Convert cloid to raw string format
     # @param cloid [Cloid, String, nil] Client order ID
     # @return [String, nil] Raw cloid string

data/lib/hyperliquid/version.rb

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

data/test_integration.rb

@@ -246,6 +246,127 @@ else
   puts "SKIPPED: Could not get #{perp_coin} price"
 end
 
+# ============================================================
+# TEST 5: Update Leverage (BTC)
+# ============================================================
+separator('TEST 5: Update Leverage (BTC)')
+
+if btc_price&.positive?
+  puts 'Setting BTC to 5x cross leverage...'
+  result = sdk.exchange.update_leverage(coin: perp_coin, leverage: 5, is_cross: true)
+  puts "Result: #{result.inspect}"
+  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)
+  puts "Result: #{result.inspect}"
+  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)
+  puts "Result: #{result.inspect}"
+else
+  puts "SKIPPED: Could not get #{perp_coin} price"
+end
+
+# ============================================================
+# TEST 6: Modify Order (BTC)
+# ============================================================
+separator('TEST 6: Modify Order (BTC)')
+
+if btc_price&.positive?
+  # Place limit buy well below market (won't fill)
+  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
+    )
+    puts "Modify result: #{result.inspect}"
+    puts
+
+    # Extract new oid from modify result if available
+    new_status = result.dig('response', 'data', 'statuses', 0)
+    new_oid = if new_status.is_a?(Hash) && new_status['resting']
+                new_status['resting']['oid']
+              else
+                oid
+              end
+
+    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 "SKIPPED: Could not get #{perp_coin} price"
+end
+
+# ============================================================
+# TEST 7: Market Close (BTC)
+# ============================================================
+separator('TEST 7: Market Close (BTC)')
+
+if btc_price&.positive?
+  perp_size = (20.0 / btc_price).ceil(sz_decimals)
+
+  puts "#{perp_coin} mid: $#{btc_price.round(2)}"
+  puts "Size: #{perp_size} BTC"
+  puts
+
+  # Open a small long position
+  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...')
+
+  # Close using market_close (auto-detect size)
+  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 "SKIPPED: Could not get #{perp_coin} price"
+end
+
 # ============================================================
 # Summary
 # ============================================================

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperliquid
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - carter2099
@@ -82,6 +82,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- SECURITY.md
 - docs/API.md
 - docs/CONFIGURATION.md
 - docs/DEVELOPMENT.md