hyperliquid 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5ac9afd372d7362c7d984fa21d21ef3822a2b3a2beebeb2067f088055be2b7b
-  data.tar.gz: b45bb221a66d07fa76d5f53375c24aef11f55a421cf0f33c038c53cbf49b797e
+  metadata.gz: 789cad57e75566edeaeb09a8437763d716caa6978c8a2ed9322623eb223c40a7
+  data.tar.gz: f2e68884aedf2f33cf4b66d811e02fe1f3fdaf4e1b77793b29b64b52934773ad
 SHA512:
-  metadata.gz: d55505a3ebf3595363542005aa5b6e3400678b22bd6689ffb38318f4f8450362d1e3ae2a8041a877dab82d1343f28bc48ba61f6a50a02dd81fbd2989bcad2660
-  data.tar.gz: 17e7a2df87f5f30b3ce79f6767ba5da9a95d097990b2b990ddc7d71bee2600c15630c3b3f96bcf350a151479eebd8520eb38f74949bad2e9fc6026a23d740d80
+  metadata.gz: 271fd73adff54d249d4ca2bf2b9f16aacdba8519ea0891e36b2315781019e231ddc158e2a0caeb401d2b43c3cf34f5cee68a0f1c15b183f41f2a1363a98af05b
+  data.tar.gz: 8b0c7fe1e353bdd6aa01d745708c0dfd7b3909bd95185c88ce9cd7fa93204535cccea04f47ad22d786f068c6e3f2cee77a69ce81df6aa1615e700743248e35fa

data/.rubocop.yml

@@ -1,6 +1,10 @@
 AllCops:
   NewCops: enable
   TargetRubyVersion: 3.4.3
+  SuggestExtensions: false
+  Exclude:
+    - 'test_*.rb'  # Exclude ad-hoc integration test scripts
+    - 'vendor/**/*'  # Exclude vendored gems (CI bundles here)
 
 # Allow longer methods for complex logic
 Metrics/MethodLength:
@@ -14,7 +18,22 @@ Metrics/AbcSize:
 Metrics/ClassLength:
   Enabled: false
 
-# Allow longer blocks in specs - this is normal for tests
+# Allow longer blocks in specs and gemspec - this is normal for tests and gem configs
 Metrics/BlockLength:
   Exclude:
-    - 'spec/**/*'
+    - 'spec/**/*'
+    - '*.gemspec'
+
+# Exchange API methods require many parameters
+Metrics/ParameterLists:
+  Exclude:
+    - 'lib/hyperliquid/exchange.rb'
+
+# Allow higher complexity for order type conversion logic
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'lib/hyperliquid/exchange.rb'
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'lib/hyperliquid/exchange.rb'

data/CHANGELOG.md

@@ -1,13 +1,33 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
-## [0.1.0] - 2025-08-21
+## [0.4.0] - 2025-01-27
 
-- Initial release which includes info endpoints for market and user perps data
+- Add Exchange API for authenticated write operations (trading)
+  - Order placement: `order`, `bulk_orders`, `market_order`
+  - Order cancellation: `cancel`, `cancel_by_cloid`, `bulk_cancel`, `bulk_cancel_by_cloid`
+  - Trigger orders (stop loss / take profit) support
+  - Vault trading support via optional `vault_address` parameter
+  - Order expiration support via `expires_after` parameter
+- Add EIP-712 signing infrastructure matching official Python SDK
+  - Phantom agent signing scheme
+  - Full parity with Python SDK signature generation
+- Add new dependencies: `eth` (~> 0.5), `msgpack` (~> 1.7)
+- SDK now accepts optional `private_key` and `expires_after` parameters
 
-## [0.1.1] - 2025-09-23
+## [0.3.0] - 2025-09-24
 
-- Fixed retry logic, make retry logic disabled by default
+- Full parity with all Hyperliquid Info APIs
+  - All Info APIs implemented
+  - Code, tests, and docs reflect structure of official Hyperliquid API documentation
 
 ## [0.2.0] - 2025-09-24
 
 - Add info endpoints for user spot data
+
+## [0.1.1] - 2025-09-23
+
+- Fixed retry logic, make retry logic disabled by default
+
+## [0.1.0] - 2025-08-21
+
+- Initial release which includes info endpoints for market and user perps data

data/CLAUDE.md

@@ -0,0 +1,202 @@
+# CLAUDE.md
+
+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 the testnet integration test (requires private key)
+# Get testnet funds from: https://app.hyperliquid-testnet.xyz
+HYPERLIQUID_PRIVATE_KEY=0x... ruby test_integration.rb
+```
+
+The integration test executes real trades on testnet:
+1. Spot market roundtrip (buy/sell PURR/USDC)
+2. Spot limit order (place and cancel)
+3. Perp market roundtrip (long/close BTC)
+4. Perp limit order (place short, cancel)
+
+### 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`
+

data/README.md

@@ -2,7 +2,7 @@
 
 A Ruby SDK for interacting with the Hyperliquid decentralized exchange API.
 
-The latest version is v0.2.0 - a read-only implementation focusing on the Info API endpoints for market data, user information, and order book data.
+The SDK supports both read operations (Info API) and authenticated write operations (Exchange API) for trading.
 
 ## Installation
 
@@ -27,14 +27,23 @@ Or install it yourself as:
 ```ruby
 require 'hyperliquid'
 
-# Create SDK instance (mainnet by default)
+# Create SDK instance for read-only operations (mainnet by default)
 sdk = Hyperliquid.new
 
 # Or use testnet
 testnet_sdk = Hyperliquid.new(testnet: true)
 
-# Access the Info API
+# Access the Info API (read operations)
 info = sdk.info
+
+# For trading operations, provide a private key
+trading_sdk = Hyperliquid.new(
+  testnet: true,
+  private_key: ENV['HYPERLIQUID_PRIVATE_KEY']
+)
+
+# Access the Exchange API (write operations)
+exchange = trading_sdk.exchange
 ```
 
 ### Supported APIs
@@ -287,6 +296,155 @@ details = sdk.info.token_details("0x00000000000000000000000000000000")
 # => { "name" => "TEST", "maxSupply" => "...", "midPx" => "...", ... }
 ```
 
+#### Exchange Methods (Trading)
+
+**Note:** Exchange methods require initializing the SDK with a `private_key`.
+
+- `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
+- `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
+- `address` - Get the wallet address associated with the private key
+
+All exchange methods support an optional `vault_address:` parameter for vault trading.
+
+##### Examples: Exchange (Trading)
+
+```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)
+
+# 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 (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
+)
+```
+
+**Order Types:**
+- `{ limit: { tif: 'Gtc' } }` - Good-til-canceled (default)
+- `{ limit: { tif: 'Ioc' } }` - Immediate-or-cancel
+- `{ limit: { tif: 'Alo' } }` - Add-liquidity-only (post-only)
+
+**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
+```
+
 ### Configuration
 
 ```ruby
@@ -296,12 +454,31 @@ sdk = Hyperliquid.new(timeout: 60)
 # Enable retry logic for handling transient failures (default: disabled)
 sdk = Hyperliquid.new(retry_enabled: true)
 
+# Enable trading with a private key
+sdk = Hyperliquid.new(private_key: ENV['HYPERLIQUID_PRIVATE_KEY'])
+
+# Set global order expiration (orders expire after this timestamp)
+expires_at_ms = (Time.now.to_f * 1000).to_i + 30_000  # 30 seconds from now
+sdk = Hyperliquid.new(
+  private_key: ENV['HYPERLIQUID_PRIVATE_KEY'],
+  expires_after: expires_at_ms
+)
+
 # Combine multiple configuration options
-sdk = Hyperliquid.new(testnet: true, timeout: 60, retry_enabled: true)
+sdk = Hyperliquid.new(
+  testnet: true,
+  timeout: 60,
+  retry_enabled: true,
+  private_key: ENV['HYPERLIQUID_PRIVATE_KEY'],
+  expires_after: expires_at_ms
+)
 
 # Check which environment you're using
 sdk.testnet?  # => false
 sdk.base_url  # => "https://api.hyperliquid.xyz"
+
+# Check if exchange is available (private_key was provided)
+sdk.exchange  # => nil if no private_key, Hyperliquid::Exchange instance otherwise
 ```
 
 #### Retry Configuration
@@ -380,11 +557,11 @@ rake rubocop
 
 ## Roadmap
 
-The latest version implements read-only Info API support. Future versions will include:
+The SDK now supports both Info API (read) and Exchange API (trading). Future versions will include:
 
-- Trading API (place orders, cancel orders, etc.)
 - WebSocket support for real-time data
-- Advanced trading features
+- Additional exchange operations (leverage, margin adjustments, transfers)
+- Advanced trading features (TWAP, etc.)
 
 ## Contributing