hyperliquid 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e1cb7c8ae1c1b83ab34eaba6f6bf9ce34b620ca1af4500912d62e54d75a95ab
-  data.tar.gz: 9d026ad803f2fe0d2983c3dd242ee5d901cf56677e7c32cf756b5da38eb39c68
+  metadata.gz: 749f15d29e4a3e03829a031352be5c151c83d178ef5b7ac4a03e4e6741d2c097
+  data.tar.gz: 558db42547ec4f1a615b31e45730e868b84ee4a0641d56c3103257c8ff546707
 SHA512:
-  metadata.gz: 99a8f5cf7847c9236f3b4b48cfb83734ecb6ae8b7679d8d5cc1aef003b1a510df3edefdf9f6481d7bdb4ff7d22546549247b9aa17771e95d58307eb93bdd0448
-  data.tar.gz: d649b243e0aab4ae25ffcd3c452878cce1be94dd86dde1aeb151b9478bba1c42fe534ec485f4ddd896e0f358b705d4b063180b26e23fcf7d09d42a9f71ffbc64
+  metadata.gz: 78163c112fb337a68f453fdca4d9ead9cd219e5919dd5d4c39697dde9d104d28ca32e37a3075e34eced886cc685845fb128b3b7196e418ab80db806ce28cb388
+  data.tar.gz: cb5a6f2bd65e4b31235a200c970355dc20eb5050c74c334d03ee6bee694c0550680c02a86001ed2003cbd53eb1edac30d0c9747af3af6628ffcc37a5a893938f

data/.rubocop.yml

@@ -1,6 +1,6 @@
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 3.4.3
+  TargetRubyVersion: 3.3
   SuggestExtensions: false
   Exclude:
     - 'test_*.rb'  # Exclude ad-hoc integration test scripts

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,11 @@
 ## [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

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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperliquid
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  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: []