hyperliquid 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c9ed1fef8ad29ab90cbc1ba13a6dc7ceed9267ff98ec97ed6748f71e1ff8289
-  data.tar.gz: 10268ae8868d6b46a1a91a853c80f5009b7586d8bed449488ec1db2923a6a3ad
+  metadata.gz: 749f15d29e4a3e03829a031352be5c151c83d178ef5b7ac4a03e4e6741d2c097
+  data.tar.gz: 558db42547ec4f1a615b31e45730e868b84ee4a0641d56c3103257c8ff546707
 SHA512:
-  metadata.gz: ab9e06936e8a3417d074f9102463d309c5c7527f945a6165a592ff57124772ce946248b9d6582a281071fc0520fd42136bce3a00cf62e60af02fc1cd3e1ecaaa
-  data.tar.gz: 665b93a26551b493309a14aa29d4a795d5e701a54bd55ba66bbbaa3fc20cc30eca6b98224e0bd3bfc538ab87884479918a95fccf49eece876347b61d4914b850
+  metadata.gz: 78163c112fb337a68f453fdca4d9ead9cd219e5919dd5d4c39697dde9d104d28ca32e37a3075e34eced886cc685845fb128b3b7196e418ab80db806ce28cb388
+  data.tar.gz: cb5a6f2bd65e4b31235a200c970355dc20eb5050c74c334d03ee6bee694c0550680c02a86001ed2003cbd53eb1edac30d0c9747af3af6628ffcc37a5a893938f

data/.rubocop.yml

@@ -1,10 +1,11 @@
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 3.4.3
+  TargetRubyVersion: 3.3
   SuggestExtensions: false
   Exclude:
     - 'test_*.rb'  # Exclude ad-hoc integration test scripts
     - 'scripts/**/*'  # Exclude integration test scripts
+    - 'local/**/*'  # Exclude local test scripts
     - 'vendor/**/*'  # Exclude vendored gems (CI bundles here)
 
 # Allow longer methods for complex logic

data/.ruby-version

@@ -1 +1 @@
-3.4.3
+3.4.8

data/AGENTS.md

@@ -0,0 +1,83 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents working with this repository.
+
+## Overview
+
+Ruby SDK (v1.0.1) for the Hyperliquid decentralized exchange API. Three API surfaces: **Info** (read-only market data), **Exchange** (authenticated trading), and **WebSocket** (real-time streaming). Built on Faraday for HTTP, the `eth` gem for EIP-712 signing, `msgpack` for action serialization, and `ws_lite` for WebSocket connections.
+
+**Ruby**: >= 3.3.0 (CI tests 3.3, 3.4)
+
+## Commands
+
+```bash
+bin/setup                  # install dependencies
+rake                       # run tests + linting (CI default)
+rake spec                  # tests only
+rake rubocop               # linting only
+bundle exec rspec spec/hyperliquid/cloid_spec.rb       # single file
+bundle exec rspec spec/hyperliquid/cloid_spec.rb:62    # single test by line
+bin/console                # IRB with SDK loaded
+ruby example.rb            # example usage script
+```
+
+### Integration Tests (Testnet)
+```bash
+HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_all.rb              # all
+HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_08_usd_class_transfer.rb  # single
+```
+Integration tests live in `scripts/` as standalone files. `test_integration.rb` at project root is a convenience wrapper.
+
+## Architecture
+
+### Request Flow
+
+The SDK has three parallel API surfaces, all routed through `Hyperliquid::SDK` (`lib/hyperliquid.rb`):
+
+```
+Hyperliquid.new(...)
+  ├── sdk.info     → Info       → Client → POST /info     (always available)
+  ├── sdk.exchange → Exchange   → Client → POST /exchange  (requires private_key)
+  └── sdk.ws       → WS::Client → WSS /ws                 (real-time streaming)
+```
+
+**Info path**: Method builds `{ type: 'someType' }` body → `Client` POSTs to `/info` → parsed JSON returned.
+
+**Exchange path**: Method builds action payload → `Signer` generates EIP-712 signature over msgpack-encoded action → `Client` POSTs signed payload to `/exchange` → parsed JSON returned.
+
+**WebSocket path**: `WS::Client` manages a persistent WSS connection with subscription tracking, automatic reconnection, ping keepalive (50s), and a bounded message queue (1024 max, drops oldest on overflow). Subscriptions are identified by a canonical key and dispatched via callbacks on a dedicated thread.
+
+### Signing (Python SDK Parity)
+
+The signing chain in `lib/hyperliquid/signing/` must exactly match the official Python SDK:
+
+1. **Action hash**: `keccak256(msgpack(action) + nonce(8B big-endian) + vault_flag + [vault_addr] + [expires_flag + expires_after])`
+2. **Phantom agent**: `{ source: 'a'|'b', connectionId: action_hash }` (a=mainnet, b=testnet)
+3. **EIP-712 signature** over phantom agent with Exchange domain (chain ID 1337)
+
+Any change to signing must maintain parity with the Python SDK or transactions will be rejected.
+
+### Numeric Conversion
+
+**float_to_wire** (in Exchange): Converts to string with 8 decimal precision, validates rounding tolerance (1e-12), normalizes trailing zeros. No scientific notation.
+
+**Market order pricing** (_slippage_price): Apply slippage (default 5%) to mid price → round to 5 significant figures → round to `(6 for perp, 8 for spot) - szDecimals` decimal places.
+
+**Spot vs Perp**: Assets with index >= 10,000 are spot (`SPOT_ASSET_THRESHOLD` in Exchange). This affects decimal place calculations.
+
+### Testing
+
+- **Unit tests** (`spec/`): RSpec + WebMock. WebMock resets between tests. Monkey-patching disabled. Test files mirror `lib/` structure.
+- **Integration tests** (`scripts/`): Run against testnet with a real private key. Each script is self-contained.
+
+### Code Style
+
+RuboCop targets Ruby 3.3. Key relaxations: methods up to 50 lines, no class length limit (Info/Exchange are large by design), no block length limit in specs, no parameter list limit in Exchange. `scripts/`, `test_*.rb`, `local/`, and `vendor/` are excluded from linting.
+
+### CI
+
+GitHub Actions (`.github/workflows/main.yml`): runs `bundle exec rake` (tests + lint) on Ruby 3.3 and 3.4 for pushes to main and all PRs. Release workflow creates GitHub releases from CHANGELOG.md on version tags.
+
+## Additional Docs
+
+Detailed API reference, examples, WebSocket guide, configuration, and error handling in `docs/`.

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
+## [1.0.2] - 2026-02-05
+
+- Lower minimum Ruby requirement to 3.3 and align RuboCop target
+- Expand CI matrix to Ruby 3.3, 3.4, and 4.0
+- Bump `ws_lite` dependency to `~> 1.0.1`
+
+## [1.0.1] - 2026-02-03
+
+- Minor refactors to reduce method complexity
+
 ## [1.0.0] - 2026-02-03
 
 ### WebSocket Support

data/CLAUDE.md

@@ -2,200 +2,5 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Overview
-
-This is a Ruby SDK for the Hyperliquid decentralized exchange API. The current version (0.4.0) supports both **read operations** (Info API) and **authenticated write operations** (Exchange API) for trading.
-
-**Target Ruby Version**: 3.4.0+
-
-## Development Commands
-
-### Running Tests
-```bash
-# Run all tests
-rake spec
-
-# Run tests and linting together (default rake task)
-rake
-
-# Run a single test file
-bundle exec rspec spec/hyperliquid/cloid_spec.rb
-
-# Run a specific test by line number
-bundle exec rspec spec/hyperliquid/cloid_spec.rb:62
-```
-
-### Linting
-```bash
-# Run RuboCop linter
-rake rubocop
-```
-
-### Interactive Console
-```bash
-# Open an interactive console with the SDK loaded
-bin/console
-```
-
-### Example Script
-```bash
-# Run the example usage script
-ruby example.rb
-```
-
-### Integration Testing (Testnet)
-```bash
-# Run all integration tests (requires private key)
-# Get testnet funds from: https://app.hyperliquid-testnet.xyz
-HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_all.rb
-
-# Run a single integration test
-HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_08_usd_class_transfer.rb
-```
-
-Integration tests live in `scripts/` as individual files. Each can be run standalone for debugging. `test_integration.rb` at the project root is a convenience wrapper that runs them all.
-
-### Setup
-```bash
-# Install dependencies
-bin/setup
-```
-
-## Architecture
-
-### Core Components
-
-**Hyperliquid::SDK** (`lib/hyperliquid.rb`)
-- Main entry point created via `Hyperliquid.new(testnet:, timeout:, retry_enabled:, private_key:, expires_after:)`
-- Manages environment selection (mainnet vs testnet)
-- Exposes the `info` API client (always available)
-- Exposes the `exchange` API client (when `private_key` provided)
-
-**Hyperliquid::Client** (`lib/hyperliquid/client.rb`)
-- Low-level HTTP client built on Faraday
-- Handles all POST requests to the Hyperliquid API
-- Manages retry logic (disabled by default, opt-in via `retry_enabled: true`)
-- Converts HTTP errors into typed exceptions
-
-**Hyperliquid::Info** (`lib/hyperliquid/info.rb`)
-- High-level API client for all Info endpoints (read-only)
-- Organized into three sections:
-  1. **General Info**: Market data, user orders, fills, rate limits, portfolios, referrals, fees, staking
-  2. **Perpetuals**: Perp DEXs, metadata, user state, funding rates, open interest
-  3. **Spot**: Spot tokens, balances, deploy auctions, token details
-- All methods accept user wallet addresses and return parsed JSON responses
-
-**Hyperliquid::Exchange** (`lib/hyperliquid/exchange.rb`)
-- High-level API client for Exchange endpoints (authenticated write operations)
-- Order placement: `order`, `bulk_orders`, `market_order`
-- Order cancellation: `cancel`, `cancel_by_cloid`, `bulk_cancel`, `bulk_cancel_by_cloid`
-- Supports trigger orders (stop loss / take profit)
-- Supports vault trading via `vault_address` parameter
-- Caches asset metadata for efficient lookups
-
-**Hyperliquid::Signing::Signer** (`lib/hyperliquid/signing/signer.rb`)
-- EIP-712 signature generation using phantom agent scheme
-- Matches official Python SDK signing algorithm exactly
-- Supports vault address and expiration in signature
-
-**Hyperliquid::Signing::EIP712** (`lib/hyperliquid/signing/eip712.rb`)
-- EIP-712 domain and type definitions
-- L1 chain ID (1337) and source identifiers ('a' mainnet, 'b' testnet)
-
-**Hyperliquid::Cloid** (`lib/hyperliquid/cloid.rb`)
-- Type-safe client order ID class
-- Validates 16-byte hex format (0x + 32 hex characters)
-- Factory methods: `from_int`, `from_str`, `from_uuid`, `random`
-
-**Hyperliquid::Constants** (`lib/hyperliquid/constants.rb`)
-- API URLs for mainnet and testnet
-- Endpoint paths (`/info`, `/exchange`)
-- Default timeout values
-
-**Hyperliquid::Errors** (`lib/hyperliquid/errors.rb`)
-- Typed exception hierarchy for API errors
-- Base class: `Hyperliquid::Error`
-- Specific errors: `ClientError`, `ServerError`, `AuthenticationError`, `RateLimitError`, `BadRequestError`, `NotFoundError`, `TimeoutError`, `NetworkError`
-
-### API Request Pattern
-
-**Info API (read-only):**
-1. SDK method called (e.g., `sdk.info.all_mids`)
-2. Info class builds request body with `type` field (e.g., `{ type: 'allMids' }`)
-3. Client POSTs JSON body to `/info` endpoint
-4. Client parses response and handles errors
-5. Parsed JSON returned to caller
-
-**Exchange API (authenticated):**
-1. SDK method called (e.g., `sdk.exchange.order(...)`)
-2. Exchange class builds action payload with order/cancel details
-3. Signer generates EIP-712 signature over msgpack-encoded action
-4. Exchange POSTs signed payload to `/exchange` endpoint
-5. Client parses response and handles errors
-6. Parsed JSON returned to caller
-
-### Testing
-
-- Uses RSpec for testing
-- WebMock for HTTP mocking
-- Spec helper configures WebMock to reset between tests
-- Test files mirror source structure in `spec/`
-
-### Code Style
-
-RuboCop configuration (`.rubocop.yml`):
-- Targets Ruby 3.4.0+
-- Allows longer methods (max 50 lines) for complex logic
-- Disables class length checks (Info/Exchange classes implement many endpoints)
-- Excludes block length checks for specs
-- Enables NewCops by default
-
-## Key Implementation Details
-
-### Retry Logic
-- **Disabled by default** for predictable behavior in time-sensitive trading
-- When enabled: max 2 retries, 0.5s base interval, exponential backoff (2x), ±50% randomness
-- Retries on: connection failures, timeouts, 429 (rate limit), 5xx errors
-
-### API Endpoints
-- Info requests POST to `/info` endpoint
-- Exchange requests POST to `/exchange` endpoint
-- Request body includes `type` field indicating the operation
-
-### Time Parameters
-- All timestamps are in **milliseconds** (not seconds)
-- Methods with time ranges support optional `end_time` parameter
-- `expires_after` is an absolute timestamp in milliseconds
-
-### Signature Generation (Python SDK Parity)
-The signing implementation matches the official Python SDK exactly:
-- **Action hash**: `keccak256(msgpack(action) + nonce(8B BE) + vault_flag + [vault_addr] + [expires_flag + expires_after])`
-- **Phantom agent**: `{ source: 'a'|'b', connectionId: action_hash }`
-- **EIP-712 signature** over phantom agent with Exchange domain
-
-### Float to Wire Format
-Numeric values are converted to strings matching Python SDK `float_to_wire`:
-- 8 decimal precision
-- Rounding tolerance validation (1e-12)
-- Trailing zero normalization (no scientific notation)
-
-### Market Order Price Calculation
-Market orders use Python SDK `_slippage_price` algorithm:
-- Apply slippage to mid price
-- Round to 5 significant figures
-- Round to asset-specific decimal places: `(6 for perp, 8 for spot) - szDecimals`
-
-### Client Order IDs (Cloid)
-- Must be 16 bytes in hex format: `0x` + 32 hex characters
-- Use `Hyperliquid::Cloid` class for type safety and validation
-- Factory methods: `from_int(n)`, `from_str(s)`, `from_uuid(uuid)`, `random`
-
-## Development Workflow
-
-1. Make changes to library code in `lib/hyperliquid/`
-2. Add/update tests in `spec/`
-3. Run tests: `rake spec`
-4. Run linter: `rake rubocop`
-5. Test in console: `bin/console`
-6. Run example script: `ruby example.rb`
-
+AGENTS.md is the canonical source of truth; this file exists only as a Claude Code convenience entrypoint.
+For comprehensive architecture documentation and implementation details, see **[AGENTS.md](./AGENTS.md)**.

data/lib/hyperliquid/exchange.rb

@@ -355,34 +355,18 @@ module Hyperliquid
     # @return [Hash] Order response
     def market_close(coin:, size: nil, slippage: DEFAULT_SLIPPAGE, cloid: nil, vault_address: nil, builder: nil)
       address = vault_address || @signer.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
-      end
+      position = find_position(coin, address)
       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 = 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?
-
-      slippage_price = calculate_slippage_price(coin, mid, is_buy, slippage)
+      slippage_price = calculate_slippage_price(coin, get_mid_price(coin), 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,
-        builder: builder
+        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, builder: builder
       )
     end
 
@@ -718,6 +702,23 @@ module Hyperliquid
       (Time.now.to_f * 1000).to_i
     end
 
+    # Find a position for a coin
+    def find_position(coin, address)
+      dex_prefix = extract_dex_prefix(coin)
+      state = dex_prefix ? @info.user_state(address, dex: dex_prefix) : @info.user_state(address)
+      state['assetPositions']&.find { |pos| pos.dig('position', 'coin') == coin }
+    end
+
+    # Get mid price for a coin
+    def get_mid_price(coin)
+      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?
+
+      mid
+    end
+
     # Get asset index for a coin symbol
     # @param coin [String] Asset symbol (supports HIP-3 prefixed names like "xyz:GOLD")
     # @return [Integer] Asset index
@@ -766,30 +767,27 @@ module Hyperliquid
       @asset_cache = { indices: {}, metadata: {} }
       @loaded_dexes = Set.new
 
-      # Load perpetual assets from default dex
-      meta = @info.meta
-      meta['universe'].each_with_index do |asset, index|
-        name = asset['name']
-        @asset_cache[:indices][name] = index
-        @asset_cache[:metadata][name] = {
-          sz_decimals: asset['szDecimals'],
-          is_spot: false
-        }
+      load_perp_assets
+      load_spot_assets
+    end
+
+    def load_perp_assets
+      @info.meta['universe'].each_with_index do |asset, index|
+        cache_asset(asset['name'], index, asset['szDecimals'], is_spot: false)
       end
+    end
 
-      # Load spot assets (index starts at SPOT_ASSET_THRESHOLD)
-      spot_meta = @info.spot_meta
-      spot_meta['universe'].each_with_index do |pair, index|
-        name = pair['name']
-        spot_index = index + SPOT_ASSET_THRESHOLD
-        @asset_cache[:indices][name] = spot_index
-        @asset_cache[:metadata][name] = {
-          sz_decimals: pair['szDecimals'] || 0,
-          is_spot: true
-        }
+    def load_spot_assets
+      @info.spot_meta['universe'].each_with_index do |pair, index|
+        cache_asset(pair['name'], index + SPOT_ASSET_THRESHOLD, pair['szDecimals'] || 0, is_spot: true)
       end
     end
 
+    def cache_asset(name, index, sz_decimals, is_spot:, dex: nil)
+      @asset_cache[:indices][name] = index
+      @asset_cache[:metadata][name] = { sz_decimals: sz_decimals, is_spot: is_spot, dex: dex }.compact
+    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")
@@ -803,17 +801,9 @@ module Hyperliquid
       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
+      @info.meta(dex: dex)['universe']&.each_with_index do |asset, index|
         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
-        }
+        cache_asset(asset['name'], hip3_asset_id, asset['szDecimals'], is_spot: false, dex: dex)
       end
     end
 

data/lib/hyperliquid/info.rb

@@ -12,7 +12,8 @@ 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)
+    # @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(dex: nil)
       body = { type: 'allMids' }

data/lib/hyperliquid/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperliquid
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - carter2099
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: 1.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: 1.0.1
 description: A Ruby SDK for interacting with Hyperliquid's decentralized exchange
   API
 email:
@@ -90,6 +90,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- AGENTS.md
 - CHANGELOG.md
 - CLAUDE.md
 - CODE_OF_CONDUCT.md
@@ -148,14 +149,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.4.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby SDK for Hyperliquid API
 test_files: []