hyperliquid 0.7.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67b19ec4599a62be35288947fdc8ce2a98c6a0f012f4bdb055a58bd9e4a37849
-  data.tar.gz: 58470f99ebf59a1ba95936816c887210d5937240c55ea1b6e85f7d68b0d82a37
+  metadata.gz: 1e1cb7c8ae1c1b83ab34eaba6f6bf9ce34b620ca1af4500912d62e54d75a95ab
+  data.tar.gz: 9d026ad803f2fe0d2983c3dd242ee5d901cf56677e7c32cf756b5da38eb39c68
 SHA512:
-  metadata.gz: fe341138c6085166b2ddd6e87fd7458554e178c4361e9ad16ed7ab1d239333c821dc0556d7f86d9080ec2002c3c36f26b3f32282acc2b6ccc010b85f83c83abe
-  data.tar.gz: caaefe028d2a4727c01daeea7241290af00c8676d73c2371ce360279f4dc0c18337c1daa398ab968416ee2516f02d08882b0556d91b5e5e78d318bfbd2d7531f
+  metadata.gz: 99a8f5cf7847c9236f3b4b48cfb83734ecb6ae8b7679d8d5cc1aef003b1a510df3edefdf9f6481d7bdb4ff7d22546549247b9aa17771e95d58307eb93bdd0448
+  data.tar.gz: d649b243e0aab4ae25ffcd3c452878cce1be94dd86dde1aeb151b9478bba1c42fe534ec485f4ddd896e0f358b705d4b063180b26e23fcf7d09d42a9f71ffbc64

data/.rubocop.yml

@@ -5,6 +5,7 @@ AllCops:
   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
@@ -30,10 +31,11 @@ Metrics/ParameterLists:
   Exclude:
     - 'lib/hyperliquid/exchange.rb'
 
-# Allow higher complexity for order type conversion logic
+# Allow higher complexity for order type conversion logic and WS message handling
 Metrics/CyclomaticComplexity:
   Exclude:
     - 'lib/hyperliquid/exchange.rb'
+    - 'lib/hyperliquid/ws/client.rb'
 
 Metrics/PerceivedComplexity:
   Exclude:

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
+## [1.0.1] - 2026-02-03
+
+- Minor refactors to reduce method complexity
+
+## [1.0.0] - 2026-02-03
+
+### WebSocket Support
+
+- Add real-time WebSocket client (`Hyperliquid::WS::Client`) with managed connection
+  - Three-thread architecture: read thread, dispatch thread, ping thread
+  - Automatic reconnection with exponential backoff (1s, 2s, 4s, ..., 30s cap)
+  - Heartbeat ping every 50 seconds to keep connection alive
+  - Bounded message queue (1024) with overflow detection
+  - Lifecycle callbacks: `on(:open)`, `on(:close)`, `on(:error)`
+
+- Add 9 WebSocket subscription channels
+  - `allMids` — mid prices for all coins
+  - `l2Book` — level 2 order book updates
+  - `trades` — trade feed for a coin
+  - `bbo` — best bid/offer for a coin
+  - `candle` — candlestick updates
+  - `orderUpdates` — order status changes for a user
+  - `userEvents` — all events for a user (fills, liquidations, etc.)
+  - `userFills` — fill updates for a user
+  - `userFundings` — funding payments for a user
+
+### HIP-3 Support
+
+- Add HIP-3 DEX abstraction Exchange actions
+  - `user_dex_abstraction` — enable/disable DEX abstraction for automatic collateral transfers (user-signed)
+  - `agent_enable_dex_abstraction` — enable DEX abstraction via agent (L1 action, enable only)
+- Add full HIP-3 trading support
+  - Lazy loading of HIP-3 dex asset metadata when trading prefixed coins (e.g., `xyz:GOLD`)
+  - Correct HIP-3 asset ID calculation: `100000 + perp_dex_index * 10000 + index_in_meta`
+  - `market_order` and `market_close` automatically use dex-specific price endpoints
+- Add `dex:` parameter to `all_mids` Info endpoint for HIP-3 perp dex prices
+
+### Info API
+
+- Add 3 more Info endpoints
+  - `extra_agents` — get authorized agent addresses for a user
+  - `user_to_multi_sig_signers` — get multi-sig signer mappings for a user
+  - `user_dex_abstraction` — get dex abstraction config for a user
+
 ## [0.7.0] - 2026-01-30
 
 - Add agent, builder & delegation actions to Exchange API

data/README.md

@@ -6,7 +6,7 @@
 
 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.
+Full-featured SDK with Info API (market data), Exchange API (trading), real-time WebSocket streaming, and HIP-3 builder-deployed perpetuals support.
 
 ## Installation
 
@@ -54,6 +54,7 @@ exchange = trading_sdk.exchange
 
 - [API Reference](docs/API.md) - Complete list of available methods
 - [Examples](docs/EXAMPLES.md) - Code examples for Info and Exchange APIs
+- [Web Sockets](docs/WS.md) - Web Sockets implementation
 - [Configuration](docs/CONFIGURATION.md) - SDK configuration options
 - [Error Handling](docs/ERRORS.md) - Error types and handling
 - [Development](docs/DEVELOPMENT.md) - Contributing and running tests

data/docs/API.md

@@ -6,8 +6,8 @@ Read-only methods for querying market data and user information.
 
 ### General Info
 
-- `all_mids()` - Retrieve mids for all coins
-- `open_orders(user)` - Retrieve a user's open orders
+- `all_mids(dex: nil)` - Retrieve mids for all coins (optional dex for HIP-3 perp dexs; spot mids only included with default dex)
+- `open_orders(user, dex: nil)` - Retrieve a user's open orders (optional dex for HIP-3)
 - `frontend_open_orders(user, dex: nil)` - Retrieve a user's open orders with additional frontend info
 - `user_fills(user)` - Retrieve a user's fills
 - `user_fills_by_time(user, start_time, end_time = nil)` - Retrieve a user's fills by time (optional end time)
@@ -30,6 +30,9 @@ Read-only methods for querying market data and user information.
 - `delegator_summary(user)` - Query a user's staking summary
 - `delegator_history(user)` - Query a user's staking history
 - `delegator_rewards(user)` - Query a user's staking rewards
+- `extra_agents(user)` - Get authorized agent addresses for a user
+- `user_to_multi_sig_signers(user)` - Get multi-sig signer mappings for a user
+- `user_dex_abstraction(user)` - Get dex abstraction config for a user
 
 ### Perpetuals Methods
 
@@ -103,6 +106,13 @@ Read-only methods for querying market data and user information.
 - `approve_builder_fee(builder:, max_fee_rate:)` - Approve a builder fee rate for a builder address
 - `token_delegate(validator:, wei:, is_undelegate:)` - Delegate or undelegate HYPE tokens to a validator
 
+### HIP-3 DEX Abstraction
+
+HIP-3 DEX abstraction allows automatic collateral transfers when trading on builder-deployed perpetual DEXs.
+
+- `user_dex_abstraction(enabled:, user: nil)` - Enable or disable DEX abstraction for an account (user-signed)
+- `agent_enable_dex_abstraction(vault_address: nil)` - Enable DEX abstraction via agent (L1 action, enable only)
+
 ### Other
 
 - `address` - Get the wallet address associated with the private key
@@ -134,3 +144,51 @@ Factory methods:
 - `Hyperliquid::Cloid.from_str(s)` - Create from hex string
 - `Hyperliquid::Cloid.from_uuid(uuid)` - Create from UUID
 - `Hyperliquid::Cloid.random` - Generate random
+
+## WebSocket
+
+Real-time data streaming via WebSocket. No private key required.
+
+### Connection
+
+- `ws.connect` - Connect to the WebSocket server (also called automatically on first `subscribe`)
+- `ws.connected?` - Check if the WebSocket is connected
+- `ws.close` - Disconnect and stop all background threads
+
+### Subscriptions
+
+- `ws.subscribe(subscription, &callback)` - Subscribe to a channel. Returns a subscription ID.
+- `ws.unsubscribe(id)` - Unsubscribe by subscription ID. Sends unsubscribe to server when the last callback for a channel is removed.
+
+### Lifecycle Events
+
+- `ws.on(:open, &callback)` - Called when connection is established
+- `ws.on(:close, &callback)` - Called when connection is closed
+- `ws.on(:error, &callback)` - Called on connection error
+
+### Monitoring
+
+- `ws.dropped_message_count` - Number of messages dropped due to a full internal queue (callbacks too slow)
+
+### Available Channels
+
+| Channel | Subscription | Description |
+|---------|-------------|-------------|
+| `allMids` | `{ type: 'allMids' }` | Mid prices for all coins |
+| `l2Book` | `{ type: 'l2Book', coin: 'ETH' }` | Level 2 order book updates |
+| `trades` | `{ type: 'trades', coin: 'ETH' }` | Trade feed for a coin |
+| `bbo` | `{ type: 'bbo', coin: 'ETH' }` | Best bid/offer for a coin |
+| `candle` | `{ type: 'candle', coin: 'ETH', interval: '1m' }` | Candlestick updates |
+| `orderUpdates` | `{ type: 'orderUpdates', user: '0x...' }` | Order status changes for a user |
+| `userEvents` | `{ type: 'userEvents', user: '0x...' }` | All events for a user (fills, liquidations, etc.) |
+| `userFills` | `{ type: 'userFills', user: '0x...' }` | Fill updates for a user |
+| `userFundings` | `{ type: 'userFundings', user: '0x...' }` | Funding payments for a user |
+
+Candle intervals: `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `8h`, `12h`, `1d`, `3d`, `1w`, `1M`
+
+### Configuration
+
+`Hyperliquid::WS::Client.new` accepts:
+- `testnet:` (Boolean, default: false) - Use testnet WebSocket endpoint
+- `max_queue_size:` (Integer, default: 1024) - Max messages buffered before dropping
+- `reconnect:` (Boolean, default: true) - Auto-reconnect on unexpected disconnect

data/docs/EXAMPLES.md

@@ -9,12 +9,20 @@
 mids = sdk.info.all_mids
 # => { "BTC" => "50000", "ETH" => "3000", ... }
 
+# Retrieve mids for a HIP-3 perp dex (e.g., xyz)
+hip3_mids = sdk.info.all_mids(dex: 'xyz')
+# => { "xyz:GOLD" => "2500", "xyz:SILVER" => "30", ... }
+
 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 on a HIP-3 dex
+hip3_orders = sdk.info.open_orders(user_address, dex: 'xyz')
+# => [{ "coin" => "xyz:GOLD", "sz" => "1.0", ... }]
+
 # Retrieve a user's open orders with additional frontend info
 frontend_orders = sdk.info.frontend_open_orders(user_address)
 # => [{ "coin" => "BTC", "isTrigger" => false, ... }]
@@ -114,6 +122,18 @@ history = sdk.info.delegator_history(user_address)
 # Query a user's staking rewards
 rewards = sdk.info.delegator_rewards(user_address)
 # => [{ "time" => 1_736_726_400_073, "source" => "delegation", "totalAmount" => "0.123" }, ...]
+
+# Get authorized agent addresses for a user
+agents = sdk.info.extra_agents(user_address)
+# => [{ "address" => "0x...", "name" => "agent1" }, ...]
+
+# Get multi-sig signer mappings for a user
+signers = sdk.info.user_to_multi_sig_signers(user_address)
+# => { "signers" => ["0x...", "0x..."], "threshold" => 2 }
+
+# Get dex abstraction config for a user
+dex_abstraction = sdk.info.user_dex_abstraction(user_address)
+# => { "enabled" => true }
 ```
 
 **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"]`.
@@ -535,6 +555,177 @@ sdk.exchange.token_delegate(
 )
 ```
 
+### HIP-3 DEX Abstraction
+
+HIP-3 DEX abstraction allows automatic collateral transfers when trading on builder-deployed perpetual DEXs.
+
+```ruby
+# Enable DEX abstraction for your account (user-signed action)
+sdk.exchange.user_dex_abstraction(enabled: true)
+
+# Disable DEX abstraction
+sdk.exchange.user_dex_abstraction(enabled: false)
+
+# Enable for a specific user address
+sdk.exchange.user_dex_abstraction(enabled: true, user: '0x...')
+
+# Enable DEX abstraction via agent (L1 action, enable only)
+# Use this when trading as an agent on behalf of another account
+sdk.exchange.agent_enable_dex_abstraction
+
+# Enable DEX abstraction for a vault via agent
+sdk.exchange.agent_enable_dex_abstraction(vault_address: '0x...')
+
+# Check current DEX abstraction status
+status = sdk.info.user_dex_abstraction(sdk.exchange.address)
+# => { "enabled" => true }
+```
+
+## WebSocket
+
+### l2Book (Order Book)
+
+```ruby
+sdk = Hyperliquid.new(testnet: true)
+
+sdk.ws.on(:open) { puts 'Connected!' }
+
+sub_id = sdk.ws.subscribe({ type: 'l2Book', coin: 'ETH' }) do |data|
+  levels = data['levels']
+  best_bid = levels[0]&.first
+  best_ask = levels[1]&.first
+  puts "ETH  bid=#{best_bid['px']}  ask=#{best_ask['px']}"
+end
+
+sleep 10
+sdk.ws.unsubscribe(sub_id)
+sdk.ws.close
+```
+
+### allMids (Mid Prices)
+
+```ruby
+sdk = Hyperliquid.new(testnet: true)
+
+sdk.ws.subscribe({ type: 'allMids' }) do |data|
+  puts "BTC mid: #{data['mids']['BTC']}"
+  puts "ETH mid: #{data['mids']['ETH']}"
+end
+
+sleep 10
+sdk.ws.close
+```
+
+### trades
+
+```ruby
+sdk = Hyperliquid.new(testnet: true)
+
+sdk.ws.subscribe({ type: 'trades', coin: 'ETH' }) do |trades|
+  trades.each do |t|
+    side = t['side'] == 'B' ? 'BUY' : 'SELL'
+    puts "#{side} #{t['sz']} ETH @ #{t['px']}"
+  end
+end
+
+sleep 30
+sdk.ws.close
+```
+
+### bbo (Best Bid/Offer)
+
+```ruby
+sdk = Hyperliquid.new(testnet: true)
+
+sdk.ws.subscribe({ type: 'bbo', coin: 'BTC' }) do |data|
+  puts "BTC  bid=#{data['bid']}  ask=#{data['ask']}"
+end
+
+sleep 10
+sdk.ws.close
+```
+
+### candle (Candlesticks)
+
+```ruby
+sdk = Hyperliquid.new(testnet: true)
+
+sdk.ws.subscribe({ type: 'candle', coin: 'ETH', interval: '1m' }) do |data|
+  puts "ETH 1m candle  o=#{data['o']} h=#{data['h']} l=#{data['l']} c=#{data['c']}"
+end
+
+sleep 120
+sdk.ws.close
+```
+
+### User Channels
+
+```ruby
+sdk = Hyperliquid.new(testnet: true, private_key: ENV['HYPERLIQUID_PRIVATE_KEY'])
+user = sdk.exchange.address
+
+# Order status changes
+sdk.ws.subscribe({ type: 'orderUpdates', user: user }) do |updates|
+  updates.each { |u| puts "Order #{u['order']['oid']}: #{u['status']}" }
+end
+
+# Fill notifications
+sdk.ws.subscribe({ type: 'userFills', user: user }) do |data|
+  data['fills'].each { |f| puts "Fill: #{f['sz']} #{f['coin']} @ #{f['px']}" }
+end
+
+# Funding payments
+sdk.ws.subscribe({ type: 'userFundings', user: user }) do |data|
+  puts "Funding update for #{data['user']}"
+end
+
+# All user events (fills, liquidations, etc.)
+sdk.ws.subscribe({ type: 'userEvents', user: user }) do |data|
+  puts "User event received"
+end
+
+sleep 60
+sdk.ws.close
+```
+
+### Multiple Subscriptions
+
+```ruby
+sdk = Hyperliquid.new(testnet: true)
+
+sdk.ws.subscribe({ type: 'l2Book', coin: 'ETH' }) do |data|
+  puts "ETH book: #{data['levels'][0]&.first&.dig('px')}"
+end
+
+sdk.ws.subscribe({ type: 'l2Book', coin: 'BTC' }) do |data|
+  puts "BTC book: #{data['levels'][0]&.first&.dig('px')}"
+end
+
+sdk.ws.subscribe({ type: 'trades', coin: 'ETH' }) do |trades|
+  puts "ETH trade: #{trades.first['px']}" if trades.any?
+end
+
+sleep 10
+sdk.ws.close
+```
+
+### Handling Reconnection
+
+```ruby
+sdk = Hyperliquid.new(testnet: true)
+
+sdk.ws.on(:open) { puts 'Connected (or reconnected)!' }
+sdk.ws.on(:close) { puts 'Connection lost. Reconnecting...' }
+
+# Subscriptions are automatically replayed on reconnect
+sdk.ws.subscribe({ type: 'l2Book', coin: 'ETH' }) do |data|
+  puts "ETH: #{data['levels'][0]&.first&.dig('px')}"
+end
+
+sleep 300
+sdk.ws.close
+```
+
 ### Client Order IDs (Cloid)
 
 ```ruby

data/docs/WS.md

@@ -0,0 +1,49 @@
+# WebSocket Implementation
+
+## Architecture
+
+`Hyperliquid::WS::Client` is a managed WebSocket client backed by three background threads:
+
+```
+WS Read Thread ──> Bounded Queue (1024) ──> Dispatch Thread ──> User Callbacks
+Ping Thread (every 50s)
+```
+
+- **Read thread** (`ws_lite`): receives frames, parses JSON, pushes onto the queue. Never blocks on user code.
+- **Dispatch thread** (`hl-ws-dispatch`): pops messages from the queue and invokes matching callbacks in order. If a callback is slow, only this thread blocks.
+- **Ping thread** (`hl-ws-ping`): sends `{"method":"ping"}` every 50 seconds to keep the connection alive.
+
+## Message Flow
+
+1. Raw frame arrives on the read thread.
+2. Non-JSON messages (e.g. `"Websocket connection established."`) and `pong` responses are discarded.
+3. A channel identifier is computed from the message (e.g. `l2Book:eth`).
+4. The message is pushed onto the bounded `Queue`. If the queue is full, the message is dropped and a warning is emitted.
+5. The dispatch thread pops the message, looks up callbacks by identifier, and calls each one.
+
+## Subscription Routing
+
+Subscriptions are keyed by an identifier string derived from the channel type and its parameters:
+
+| Channel        | Identifier format                  | Example             |
+|----------------|------------------------------------|---------------------|
+| `allMids`      | `allMids`                          | `allMids`           |
+| `l2Book`       | `l2Book:<coin>`                    | `l2Book:eth`        |
+| `candle`       | `candle:<coin>:<interval>`         | `candle:eth:1h`     |
+| `userEvents`   | `userEvents:<user>`                | `userEvents:0xabc`  |
+
+Multiple callbacks can be registered for the same identifier. The server unsubscribe message is only sent when the last callback for an identifier is removed.
+
+## Queue Overflow
+
+The internal queue is bounded (default 1024 messages). When full, new messages are dropped (oldest retained). Warnings print on the 1st drop and every 100th drop. Monitor via `dropped_message_count`.
+
+## Reconnection
+
+On unexpected disconnect (when `reconnect: true`, the default), the client spawns a thread that retries with exponential backoff: 1s, 2s, 4s, ..., capped at 30s. On reconnect, all active subscriptions are replayed automatically.
+
+## Thread Safety
+
+- `@subscriptions` and `@pending_subscriptions` are protected by a `Mutex` as they are accessed across the three threads.
+- Ruby's `Queue` is inherently thread-safe.
+- Callbacks are invoked serially on the dispatch thread (never concurrently).

data/lib/hyperliquid/constants.rb

@@ -11,6 +11,11 @@ module Hyperliquid
     INFO_ENDPOINT = '/info'
     EXCHANGE_ENDPOINT = '/exchange'
 
+    # WebSocket
+    WS_ENDPOINT = '/ws'
+    WS_PING_INTERVAL = 50        # seconds between pings
+    WS_MAX_QUEUE_SIZE = 1024     # max queued messages before dropping
+
     # Request timeouts (seconds)
     DEFAULT_TIMEOUT = 30
     DEFAULT_READ_TIMEOUT = 30

data/lib/hyperliquid/errors.rb

@@ -35,4 +35,7 @@ module Hyperliquid
 
   # Error for network connectivity issues
   class NetworkError < Error; end
+
+  # Error for WebSocket issues
+  class WebSocketError < Error; end
 end