hyperliquid 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9976736621e86406eb3de9e8e4827b59d1c96c86aac1efcff2ee700afa78429
-  data.tar.gz: 79c0a9f8587b1af017f02539e2c35b27e7311ba7e00328c0147db636483aed28
+  metadata.gz: f6baba398ac6a839785cea71c83f96b7a7e339f200604288f9920f25b5a49ed0
+  data.tar.gz: 0b1961c8b84802e88730421516d27b58e5e14bb055ac190a82e2c0881c692333
 SHA512:
-  metadata.gz: 89e3b1c854bdb152494abc51ed5f7a3dcfe3c354226d7d92ed994ef8f99d9d5fabcf91d81ddedb18bf083bcc9f3cc4952578b2bfe1d95cc2d8c35b359eb392b1
-  data.tar.gz: c8fd08574cfa29c927bd5c848ca5bd578914bc82150af2ab0305c38ea84785b22f4f92bed0ca07e49f86f31c8dde089fd83c47e73c58678c807a0dacf5dc9b75
+  metadata.gz: a7f8886eede6df8fcde833b490733def438945d115c4d3664d397c037d97c5e785e13793885e984baeaf696f156f1f59f614c8f5d0f384e47cbc7d1b1d85708e
+  data.tar.gz: 518cdc5f65b6fd3de3c15a96bf6e67049af1c5935e9a67a9e56b01d45d43984506d9e30804ec01a9723fe2ff9e1306b2ee32bbb1959dfead2a4f6b036c2c2d49

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
+## [1.2.0] - 2026-04-27
+
+### New Info endpoints
+
+- HIP-2 borrow/lend: `Info#borrow_lend_user_state`, `Info#borrow_lend_reserve_state`, `Info#all_borrow_lend_reserve_states`, `Info#user_borrow_lend_interest`
+- Perp metadata: `Info#perp_annotation`, `Info#perp_concise_annotations`, `Info#perp_categories`, `Info#outcome_meta`, `Info#aligned_quote_token_info`
+- Builders / perp dexs: `Info#approved_builders`, `Info#all_perp_metas`, `Info#perp_dex_status`
+- TWAP / web / sub-accounts: `Info#user_twap_slice_fills_by_time`, `Info#web_data2`, `Info#sub_accounts2`, `Info#twap_history`
+- Margin / vaults: `Info#margin_table`, `Info#leading_vaults`
+- Validator / network: `Info#validator_l1_votes`, `Info#gossip_root_ips`, `Info#legal_check`
+
+### New Exchange actions
+
+- `Exchange#user_set_abstraction(user:, abstraction:)` — user-signed `userSetAbstraction` (new `USER_SET_ABSTRACTION_TYPES` EIP-712 schema)
+- `Exchange#agent_set_abstraction(abstraction:, vault_address:)` — L1 `agentSetAbstraction`
+- `Exchange#gossip_priority_bid(slot_id:, ip:, max_gas:, vault_address:)` — L1 `gossipPriorityBid`
+- `Exchange#convert_to_multi_sig_user(authorized_users:, threshold:)` — user-signed action (new `CONVERT_TO_MULTI_SIG_USER_TYPES` EIP-712 schema)
+- `Exchange#expires_after=` — writer to set the global L1 expiration timestamp for subsequent actions
+- `Exchange#use_big_blocks(enable:)` — `evmUserModify` action
+- `Exchange#noop(nonce: nil, vault_address: nil)` — L1 noop, useful for burning a specific nonce slot
+
 ## [1.1.0] - 2026-04-24
 
 ### New Info endpoints

data/CLAUDE.md

@@ -1,6 +1,97 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to AI coding agents working with this repository. It is the canonical source of truth — keep it in sync as the SDK evolves.
 
-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)**.
+## Overview
+
+Ruby SDK 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.
+
+Version is the single source of truth in `lib/hyperliquid/version.rb`; required Ruby version is in the gemspec.
+
+## 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)
+
+Integration scripts live in `scripts/` as standalone files (`test_NN_<name>.rb`). They require a real testnet private key and hit the live testnet API.
+
+```bash
+HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_all.rb              # all 14
+HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_automated.rb        # CI-friendly subset
+HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_08_usd_class_transfer.rb  # single
+```
+
+`test_automated.rb` is the unattended runner — same as `test_all.rb` but excludes scripts that require manual testnet preconditions (e.g. `test_09_sub_account_lifecycle` needs $100k traded volume; `test_12_staking` needs HYPE balance). Some included tests (e.g. `test_08`, `test_11`) are also coded to skip-with-warning when known testnet preconditions aren't met, so the suite stays green on a stable wallet.
+
+`test_integration.rb` at the project root is a thin convenience wrapper.
+
+## Architecture
+
+### Request Flow
+
+All three API surfaces are reached 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 (exp backoff, 30s cap), 50s ping keepalive, and a bounded message queue (1024, 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 by the exchange.
+
+### 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.
+
+### HIP-3 (Builder-Deployed Perps)
+
+Many Info methods accept a `dex:` kwarg (e.g. `meta(dex: 'foo')`, `user_state(user, dex: 'foo')`) to query a builder-deployed perp dex rather than the canonical perp market. `Info#perp_dexs` enumerates available dexes; `Info#perp_dex_limits(dex)` returns per-dex risk parameters.
+
+### Testing
+
+- **Unit tests** (`spec/`): RSpec + WebMock. WebMock resets between tests. Monkey-patching disabled. Test files mirror `lib/` structure. No live HTTP calls in unit tests.
+- **Integration tests** (`scripts/`): run against testnet with a real private key. Each script is self-contained. Helpers (separators, status dumping, retry-on-oracle-bounce) live in `scripts/test_helpers.rb`.
+- **`dump_status` / `check_result` helpers** in `test_helpers.rb` must guard against `result['response']` *itself* being a String for transfer-style actions (`usdClassTransfer`, `approveBuilderFee`) — not just `result['response']['data']`. This was a real bug fixed in 1.1.0; preserve the guards if refactoring those helpers.
+
+### 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.
+
+Predicate methods follow Ruby style (`vip?`, `connected?`, `testnet?`) — not `is_vip` / `is_connected`. RuboCop's `Naming/PredicateName` enforces this.
+
+### CI
+
+GitHub Actions (`.github/workflows/main.yml`): runs `bundle exec rake` (tests + lint) on the Ruby matrix defined in that workflow, for pushes to `main` and on all PRs. The release workflow creates GitHub releases from `CHANGELOG.md` on version tags.
+
+## Release Flow
+
+Releases happen from `main`. Day-to-day work lands on `dev`, then `dev` is merged into `main` and tagged at release time. `CHANGELOG.md` follows Keep-a-Changelog conventions; `lib/hyperliquid/version.rb` is the single source of version truth (gemspec reads it). Tags push automatically trigger the GitHub release workflow.
+
+## Additional Docs
+
+Detailed API reference, examples, WebSocket guide, configuration, and error handling in `docs/` (`API.md`, `EXAMPLES.md`, `WS.md`, `CONFIGURATION.md`, `ERRORS.md`, `DEVELOPMENT.md`).

data/lib/hyperliquid/exchange.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'bigdecimal'
+require 'json'
 
 module Hyperliquid
   # Exchange API client for write operations (orders, cancels, etc.)
@@ -675,6 +676,123 @@ module Hyperliquid
       post_action(action, signature, nonce, vault_address)
     end
 
+    # Set the agent abstraction mode (L1 action `agentSetAbstraction`).
+    # @param abstraction [String] One of 'u' (unified), 'p' (portfolio margin), 'i' (isolated/disabled)
+    # @param vault_address [String, nil] Vault address if acting on behalf of a vault
+    # @return [Hash] Exchange response
+    def agent_set_abstraction(abstraction:, vault_address: nil)
+      nonce = timestamp_ms
+      action = { type: 'agentSetAbstraction', abstraction: abstraction }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        vault_address: vault_address,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, vault_address)
+    end
+
+    # Set the abstraction mode for a user (`userSetAbstraction` user-signed action).
+    # The `user` address is lowercased to match the Python SDK and protocol expectations.
+    # @param user [String] Wallet address whose abstraction is being set
+    # @param abstraction [String] One of 'u' (unified), 'p' (portfolio margin), 'i' (isolated/disabled)
+    # @return [Hash] Exchange response
+    def user_set_abstraction(user:, abstraction:)
+      nonce = timestamp_ms
+      user_lower = user.downcase
+      action = {
+        type: 'userSetAbstraction',
+        signatureChainId: '0x66eee',
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
+        user: user_lower,
+        abstraction: abstraction,
+        nonce: nonce
+      }
+      signature = @signer.sign_user_signed_action(
+        { user: user_lower, abstraction: abstraction, nonce: nonce },
+        'HyperliquidTransaction:UserSetAbstraction',
+        Signing::EIP712::USER_SET_ABSTRACTION_TYPES
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # Update the global expiration timestamp applied to subsequent L1 actions.
+    # `expires_after` is not supported on user-signed actions (e.g. `usd_send`,
+    # `withdraw_from_bridge`) and must be nil for those calls to succeed.
+    # @param value [Integer, nil] Unix timestamp in milliseconds, or nil to clear
+    attr_writer :expires_after
+
+    # Toggle EVM big-blocks mode for this account (`evmUserModify` L1 action).
+    # When enabled, EVM transactions from this account are routed to big blocks.
+    # @param enable [Boolean] True to enable big blocks, false to disable
+    # @return [Hash] Exchange response
+    def use_big_blocks(enable:)
+      nonce = timestamp_ms
+      action = { type: 'evmUserModify', usingBigBlocks: enable }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
+    # No-op L1 action — useful for burning a specific nonce slot without side effects.
+    # @param nonce [Integer, nil] Nonce to consume (defaults to current timestamp_ms)
+    # @param vault_address [String, nil] Vault address if acting on behalf of a vault
+    # @return [Hash] Exchange response
+    def noop(nonce: nil, vault_address: nil)
+      nonce ||= timestamp_ms
+      action = { type: 'noop' }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        vault_address: vault_address,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, vault_address)
+    end
+
+    # Submit a priority-bid gossip message (L1 action `gossipPriorityBid`).
+    # Used by validators / priority bidders to gossip a bid for a given slot.
+    # @param slot_id [Integer] Slot identifier the bid applies to
+    # @param ip [String] Bidder IP address (string form expected by the protocol)
+    # @param max_gas [Integer] Maximum gas the bidder is willing to pay
+    # @param vault_address [String, nil] Vault address if acting on behalf of a vault
+    # @return [Hash] Exchange response
+    def gossip_priority_bid(slot_id:, ip:, max_gas:, vault_address: nil)
+      nonce = timestamp_ms
+      action = { type: 'gossipPriorityBid', slotId: slot_id, ip: ip, maxGas: max_gas }
+      signature = @signer.sign_l1_action(
+        action, nonce,
+        vault_address: vault_address,
+        expires_after: @expires_after
+      )
+      post_action(action, signature, nonce, vault_address)
+    end
+
+    # Convert this account into a multi-sig user (`convertToMultiSigUser` user-signed action).
+    # The set of authorized signers and the threshold are JSON-encoded into the action's
+    # `signers` field as required by the Hyperliquid protocol.
+    # @param authorized_users [Array<String>] Authorized signer addresses; sorted before signing
+    # @param threshold [Integer] Number of signatures required to authorize an action
+    # @return [Hash] Exchange response
+    def convert_to_multi_sig_user(authorized_users:, threshold:)
+      nonce = timestamp_ms
+      sorted_users = authorized_users.sort
+      signers_json = JSON.generate({ authorizedUsers: sorted_users, threshold: threshold })
+      action = {
+        type: 'convertToMultiSigUser',
+        signatureChainId: '0x66eee',
+        hyperliquidChain: Signing::EIP712.hyperliquid_chain(testnet: @testnet),
+        signers: signers_json,
+        nonce: nonce
+      }
+      signature = @signer.sign_user_signed_action(
+        { signers: signers_json, nonce: nonce },
+        'HyperliquidTransaction:ConvertToMultiSigUser',
+        Signing::EIP712::CONVERT_TO_MULTI_SIG_USER_TYPES
+      )
+      post_action(action, signature, nonce, nil)
+    end
+
     # Clear the asset metadata cache
     # Call this if metadata has been updated
     def reload_metadata!

data/lib/hyperliquid/info.rb

@@ -134,6 +134,13 @@ module Hyperliquid
       @client.post(Constants::INFO_ENDPOINT, { type: 'maxBuilderFee', user: user, builder: builder })
     end
 
+    # Query approved builders for a user
+    # @param user [String] Wallet address
+    # @return [Array<String>] Array of approved builder addresses
+    def approved_builders(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'approvedBuilders', user: user })
+    end
+
     # Retrieve a user's historical orders
     # @param user [String] Wallet address
     # @param start_time [Integer, nil] Optional start timestamp in milliseconds
@@ -158,6 +165,20 @@ module Hyperliquid
       @client.post(Constants::INFO_ENDPOINT, body)
     end
 
+    # Retrieve a user's TWAP slice fills within a time range
+    # @param user [String] Wallet address
+    # @param start_time [Integer] Start timestamp in milliseconds
+    # @param end_time [Integer, nil] Optional end timestamp in milliseconds
+    # @param aggregate_by_time [Boolean, nil] If true, partial fills are aggregated when a
+    #   crossing order fills multiple resting orders
+    # @return [Array]
+    def user_twap_slice_fills_by_time(user, start_time, end_time = nil, aggregate_by_time: nil)
+      body = { type: 'userTwapSliceFillsByTime', user: user, startTime: start_time }
+      body[:endTime] = end_time if end_time
+      body[:aggregateByTime] = aggregate_by_time unless aggregate_by_time.nil?
+      @client.post(Constants::INFO_ENDPOINT, body)
+    end
+
     # Retrieve a user's subaccounts
     # @param user [String]
     # @return [Array]
@@ -165,6 +186,15 @@ module Hyperliquid
       @client.post(Constants::INFO_ENDPOINT, { type: 'subaccounts', user: user })
     end
 
+    # Retrieve a user's V2 subaccounts (per-dex clearinghouse + spot state)
+    # @param user [String] Wallet address
+    # @return [Array<Hash>, nil] Array of entries with name, subAccountUser, master,
+    #   dexToClearinghouseState (array of [dex, state] tuples), and spotState; nil if
+    #   the user has no subaccounts
+    def sub_accounts2(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'subAccounts2', user: user })
+    end
+
     # Retrieve details for a vault
     # @param vault_address [String] Vault address
     # @param user [String, nil] Optional wallet address
@@ -316,6 +346,58 @@ module Hyperliquid
       @client.post(Constants::INFO_ENDPOINT, { type: 'maxMarketOrderNtls' })
     end
 
+    # Retrieve L1 governance votes cast by validators
+    # @return [Array] Array of entries with expireTime (ms since epoch), action (hash with
+    #   either `D` string or `C` array of strings), and votes (array of validator addresses)
+    def validator_l1_votes
+      @client.post(Constants::INFO_ENDPOINT, { type: 'validatorL1Votes' })
+    end
+
+    # Retrieve gossip root IPs
+    # @return [Array<String>] Array of dotted-quad IPv4 addresses
+    def gossip_root_ips
+      @client.post(Constants::INFO_ENDPOINT, { type: 'gossipRootIps' })
+    end
+
+    # Retrieve a user's legal verification status
+    # @param user [String] Wallet address
+    # @return [Hash] Keys: ipAllowed (Boolean), acceptedTerms (Boolean), userAllowed (Boolean)
+    def legal_check(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'legalCheck', user: user })
+    end
+
+    # Retrieve the margin requirements table for a given id
+    # @param id [Integer] Margin table id
+    # @return [Hash] Keys: description (String), marginTiers (Array of { lowerBound, maxLeverage })
+    def margin_table(id)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'marginTable', id: id })
+    end
+
+    # Retrieve the vaults a user is leading
+    # @param user [String] Wallet address
+    # @return [Array<Hash>] Array of { address (String), name (String) } entries
+    def leading_vaults(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'leadingVaults', user: user })
+    end
+
+    # Retrieve a user's TWAP order history
+    # @param user [String] Wallet address
+    # @return [Array<Hash>] Array of entries with time (Integer, sec since epoch), state (Hash),
+    #   status (Hash with `status` and optional `description`), and optional twapId (Integer)
+    def twap_history(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'twapHistory', user: user })
+    end
+
+    # Retrieve comprehensive user and market data in a single response
+    # @param user [String] Wallet address
+    # @return [Hash] Aggregated payload containing keys including clearinghouseState,
+    #   leadingVaults, totalVaultEquity, openOrders, agentAddress, agentValidUntil, cumLedger,
+    #   meta, assetCtxs, serverTime, isVault, user, twapStates, spotState, spotAssetCtxs,
+    #   optOutOfSpotDusting, perpsAtOpenInterestCap
+    def web_data2(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'webData2', user: user })
+    end
+
     # ============================
     # Info: Perpetuals
     # ============================
@@ -341,6 +423,12 @@ module Hyperliquid
       @client.post(Constants::INFO_ENDPOINT, { type: 'metaAndAssetCtxs' })
     end
 
+    # Get trading metadata for all perpetual dexs
+    # @return [Array<Hash>] Array of meta payloads (one per dex), each with universe and other fields
+    def all_perp_metas
+      @client.post(Constants::INFO_ENDPOINT, { type: 'allPerpMetas' })
+    end
+
     # Get user's trading state
     # @param user [String] Wallet address
     # @param dex [String, nil] Optional perp dex name
@@ -384,6 +472,42 @@ module Hyperliquid
       @client.post(Constants::INFO_ENDPOINT, { type: 'perpDexLimits', dex: dex })
     end
 
+    # Retrieve perp DEX status (e.g. total net deposit) for a builder-deployed dex
+    # @param dex [String] Perp dex name; the empty string represents the first perp dex
+    # @return [Hash] Keys: totalNetDeposit (String)
+    def perp_dex_status(dex)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'perpDexStatus', dex: dex })
+    end
+
+    # Retrieve perpetual asset categories
+    # @return [Array<Array(String, String)>] Array of [coin, category] tuples
+    def perp_categories
+      @client.post(Constants::INFO_ENDPOINT, { type: 'perpCategories' })
+    end
+
+    # Retrieve perp annotation for a single perpetual asset
+    # @param coin [String] Coin symbol (e.g., "BTC")
+    # @return [Hash, nil] Hash with category, description, and optional displayName/keywords;
+    #   nil if no annotation exists for the coin
+    def perp_annotation(coin)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'perpAnnotation', coin: coin })
+    end
+
+    # Retrieve concise annotations for all perpetual assets
+    # @return [Array<Array>] Array of [coin (String), annotation (Hash)] tuples; each
+    #   annotation has category and optional displayName/keywords
+    def perp_concise_annotations
+      @client.post(Constants::INFO_ENDPOINT, { type: 'perpConciseAnnotations' })
+    end
+
+    # Retrieve prediction market outcome metadata
+    # @return [Hash] Hash with outcomes (each with outcome, name, description, sideSpecs)
+    #   and questions (each with question, name, description, fallbackOutcome,
+    #   namedOutcomes, settledNamedOutcomes)
+    def outcome_meta
+      @client.post(Constants::INFO_ENDPOINT, { type: 'outcomeMeta' })
+    end
+
     # Retrieve a user's funding history
     # @param user [String]
     # @param start_time [Integer]
@@ -459,6 +583,54 @@ module Hyperliquid
     def token_details(token_id)
       @client.post(Constants::INFO_ENDPOINT, { type: 'tokenDetails', tokenId: token_id })
     end
+
+    # Get supply, rate, and pending payment information for an aligned quote token
+    # @param token [Integer] Token index
+    # @return [Hash] Hash with isAligned, firstAlignedTime, evmMintedSupply,
+    #   dailyAmountOwed (array of [date, amount] tuples), predictedRate
+    def aligned_quote_token_info(token)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'alignedQuoteTokenInfo', token: token })
+    end
+
+    # ============================
+    # Info: Borrow/Lend (HIP-2)
+    # ============================
+
+    # Retrieve a user's borrow/lend state across tokens
+    # @param user [String] Wallet address
+    # @return [Hash] Hash with tokenToState (array of [tokenId, state] tuples; state has
+    #   borrow {basis, value} and supply {basis, value}), health, healthFactor
+    def borrow_lend_user_state(user)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'borrowLendUserState', user: user })
+    end
+
+    # Retrieve borrow/lend reserve state for a single token
+    # @param token [Integer] Token index
+    # @return [Hash] Hash with borrowYearlyRate, supplyYearlyRate, balance, utilization,
+    #   oraclePx, ltv, totalSupplied, totalBorrowed
+    def borrow_lend_reserve_state(token)
+      @client.post(Constants::INFO_ENDPOINT, { type: 'borrowLendReserveState', token: token })
+    end
+
+    # Retrieve borrow/lend reserve states for all tokens
+    # @return [Array<Array>] Array of [reserveId (Integer), state (Hash)] tuples; each
+    #   state has borrowYearlyRate, supplyYearlyRate, balance, utilization, oraclePx,
+    #   ltv, totalSupplied, totalBorrowed
+    def all_borrow_lend_reserve_states
+      @client.post(Constants::INFO_ENDPOINT, { type: 'allBorrowLendReserveStates' })
+    end
+
+    # Retrieve a user's borrow/lend interest accrual history
+    # @param user [String] Wallet address
+    # @param start_time [Integer] Start timestamp in milliseconds
+    # @param end_time [Integer, nil] Optional end timestamp in milliseconds
+    # @return [Array<Hash>] Array of {time, token, borrow, supply} entries; borrow and
+    #   supply are decimal-string interest amounts
+    def user_borrow_lend_interest(user, start_time, end_time = nil)
+      body = { type: 'userBorrowLendInterest', user: user, startTime: start_time }
+      body[:endTime] = end_time if end_time
+      @client.post(Constants::INFO_ENDPOINT, body)
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/hyperliquid/signing/eip712.rb

@@ -104,6 +104,23 @@ module Hyperliquid
         ]
       }.freeze
 
+      CONVERT_TO_MULTI_SIG_USER_TYPES = {
+        'HyperliquidTransaction:ConvertToMultiSigUser': [
+          { name: :hyperliquidChain, type: 'string' },
+          { name: :signers, type: 'string' },
+          { name: :nonce, type: 'uint64' }
+        ]
+      }.freeze
+
+      USER_SET_ABSTRACTION_TYPES = {
+        'HyperliquidTransaction:UserSetAbstraction': [
+          { name: :hyperliquidChain, type: 'string' },
+          { name: :user, type: 'address' },
+          { name: :abstraction, type: 'string' },
+          { name: :nonce, type: 'uint64' }
+        ]
+      }.freeze
+
       class << self
         # Domain for L1 actions (orders, cancels, leverage, etc.)
         # @return [Hash] EIP-712 domain configuration

data/lib/hyperliquid/version.rb

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

data/scripts/test_08_usd_class_transfer.rb

@@ -9,6 +9,17 @@ require_relative 'test_helpers'
 sdk = build_sdk
 separator('TEST 8: USD Class Transfer (Perp <-> Spot)')
 
+# Unified-account wallets cannot use usdClassTransfer — perp and spot balances
+# are merged, so the action is disabled at the exchange layer. Detect this up
+# front and skip rather than hitting a predictable "Action disabled" failure.
+abstraction = sdk.info.user_abstraction(sdk.exchange.address)
+if abstraction == 'unifiedAccount'
+  puts "SKIPPED: Wallet has unified account active (abstraction=#{abstraction.inspect})."
+  puts '  usdClassTransfer is disabled by the exchange when perp/spot balances are unified.'
+  test_passed('Test 8 USD Class Transfer')
+  exit 0
+end
+
 puts 'Transferring $10 from perp to spot...'
 result = sdk.exchange.usd_class_transfer(amount: '10', to_perp: false)
 dump_status(result)

data/scripts/test_11_builder_fee.rb

@@ -14,10 +14,20 @@ max_fee_rate = '0.01%'
 perp_coin = 'BTC'
 
 # Step 1: Approve builder fee
+# On testnet, the builder may not meet the exchange's minimum balance for approval.
+# That precondition failure is not an SDK bug — we downgrade it to a warning and
+# continue, since the order-with-builder-fee flow (the thing we actually ship)
+# can still be exercised if a prior approval is in place.
 puts "Approving builder fee for #{builder_address} (max #{max_fee_rate})..."
 result = sdk.exchange.approve_builder_fee(builder: builder_address, max_fee_rate: max_fee_rate)
-dump_status(result)
-api_error?(result) || puts(green('Builder fee approved'))
+if result.is_a?(Hash) && result['status'] == 'err' &&
+   result['response'].to_s.include?('insufficient balance')
+  puts red("WARNING: #{result['response']}")
+  puts '  Continuing — this is a testnet precondition, not an SDK failure.'
+else
+  dump_status(result)
+  api_error?(result) || puts(green('Builder fee approved'))
+end
 puts
 
 wait_with_countdown(WAIT_SECONDS, 'Waiting before placing order with builder...')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperliquid
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - carter2099
@@ -90,7 +90,6 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
-- AGENTS.md
 - CHANGELOG.md
 - CLAUDE.md
 - CODE_OF_CONDUCT.md

data/AGENTS.md

@@ -1,83 +0,0 @@
-# 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/`.