hyperliquid 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 324ff762cbf5edcea7fc532f853b7295ffcd34476f6273fdef4e03bcc0f9eaee
-  data.tar.gz: 98b1b88b378bb8ae010301c656c833282cd406822fa0c8a7d6c134911b0f2cce
+  metadata.gz: 7c9ed1fef8ad29ab90cbc1ba13a6dc7ceed9267ff98ec97ed6748f71e1ff8289
+  data.tar.gz: 10268ae8868d6b46a1a91a853c80f5009b7586d8bed449488ec1db2923a6a3ad
 SHA512:
-  metadata.gz: fe9e447e5500312f98e8f8e602071372847963daacfd51475e92d4db5a7bc988546e4cf106479a9c899bcecf113612c2aa9ebe0dd50a5384bd438bb0d6429865
-  data.tar.gz: 7cd7d2e048c4bf25e128dd7fd41814621bd95305d613199cb4c41abdf1901fdc4c665635000112aafeb7c395dbf01dae81cba74042557d86643c6ac169e3d201
+  metadata.gz: ab9e06936e8a3417d074f9102463d309c5c7527f945a6165a592ff57124772ce946248b9d6582a281071fc0520fd42136bce3a00cf62e60af02fc1cd3e1ecaaa
+  data.tar.gz: 665b93a26551b493309a14aa29d4a795d5e701a54bd55ba66bbbaa3fc20cc30eca6b98224e0bd3bfc538ab87884479918a95fccf49eece876347b61d4914b850

data/.rubocop.yml

@@ -30,10 +30,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,55 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
+## [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
+  - `approve_agent` — authorize an agent wallet to trade on behalf of the account
+  - `approve_builder_fee` — approve a builder fee rate for a builder address
+  - `token_delegate` — delegate or undelegate HYPE tokens to a validator
+- Add builder fee support on order placement
+  - Optional `builder:` parameter on `order`, `bulk_orders`, `market_order`, `market_close`
+- Add EIP-712 type definitions for `ApproveAgent`, `ApproveBuilderFee`, and `TokenDelegate`
+
 ## [0.6.0] - 2026-01-28
 
 - Add transfers and account management 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
 
@@ -97,12 +100,27 @@ Read-only methods for querying market data and user information.
 - `vault_transfer(vault_address:, is_deposit:, usd:)` - Deposit or withdraw USDC to/from a vault
 - `set_referrer(code:)` - Set referral code
 
+### Agent & Builder
+
+- `approve_agent(agent_address:, agent_name:)` - Authorize an agent wallet to trade on behalf of this account
+- `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
 
 Order placement and management methods support an optional `vault_address:` parameter for vault trading.
 
+Order placement methods (`order`, `bulk_orders`, `market_order`, `market_close`) support an optional `builder:` parameter for builder fee integration. The builder is a Hash with `:b` (builder address) and `:f` (fee in tenths of a basis point).
+
 ### Order Types
 
 - `{ limit: { tif: 'Gtc' } }` - Good-til-canceled (default)
@@ -126,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"]`.
@@ -479,6 +499,233 @@ sdk.exchange.vault_transfer(
 sdk.exchange.set_referrer(code: 'MY_REFERRAL_CODE')
 ```
 
+### Agent, Builder & Delegation
+
+```ruby
+# Authorize an agent wallet to trade on your behalf
+agent_key = Eth::Key.new
+result = sdk.exchange.approve_agent(
+  agent_address: agent_key.address.to_s,
+  agent_name: 'my-trading-bot'       # optional
+)
+
+# Approve a builder fee (required before placing orders with that builder)
+sdk.exchange.approve_builder_fee(
+  builder: '0x250F311Ae04D3CEA03443C76340069eD26C47D7D',
+  max_fee_rate: '0.01%'   # 1 basis point
+)
+
+# Place an order with a builder fee
+sdk.exchange.order(
+  coin: 'BTC',
+  is_buy: true,
+  size: '0.01',
+  limit_px: '95000',
+  builder: { b: '0x250F311Ae04D3CEA03443C76340069eD26C47D7D', f: 10 }  # f=10 means 1bp
+)
+
+# Builder works with all order methods
+sdk.exchange.bulk_orders(
+  orders: [
+    { coin: 'BTC', is_buy: true, size: '0.01', limit_px: '94000' },
+    { coin: 'BTC', is_buy: false, size: '0.01', limit_px: '96000' }
+  ],
+  builder: { b: '0x250F311Ae04D3CEA03443C76340069eD26C47D7D', f: 10 }
+)
+
+sdk.exchange.market_order(
+  coin: 'BTC',
+  is_buy: true,
+  size: '0.01',
+  builder: { b: '0x250F311Ae04D3CEA03443C76340069eD26C47D7D', f: 10 }
+)
+
+# Delegate HYPE tokens to a validator (wei = float * 1e8)
+sdk.exchange.token_delegate(
+  validator: '0x...',
+  wei: 100_000_000,  # 1 HYPE
+  is_undelegate: false
+)
+
+# Undelegate HYPE tokens
+sdk.exchange.token_delegate(
+  validator: '0x...',
+  wei: 10_000_000,   # 0.1 HYPE
+  is_undelegate: true
+)
+```
+
+### 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