hyperliquid 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4e2d29336f0e921d82f0f7a154676a102a228fd5aa4811b85db890802330865
-  data.tar.gz: ff28b26c30bd14549def4e1f5adb3193ab812cc4527da50109dd17d5bc333816
+  metadata.gz: 67b19ec4599a62be35288947fdc8ce2a98c6a0f012f4bdb055a58bd9e4a37849
+  data.tar.gz: 58470f99ebf59a1ba95936816c887210d5937240c55ea1b6e85f7d68b0d82a37
 SHA512:
-  metadata.gz: d19f8ddf0b9d7cb16a7791a2d7117725929e956c05a46a27b11cc9b27bb051f0c4d7b1cfc1053e3683a9577ceaacbd96ebd3b06a3541d527f9c0437e5de067b1
-  data.tar.gz: 8a590a96b1e14b8178e3d628cb8e498d718e0a41963dad0671ead93c06df3d389e2fe2c3082d2a27965eb0adf46370e1508f8a9b0cb2e002444c225e39d8aa79
+  metadata.gz: fe341138c6085166b2ddd6e87fd7458554e178c4361e9ad16ed7ab1d239333c821dc0556d7f86d9080ec2002c3c36f26b3f32282acc2b6ccc010b85f83c83abe
+  data.tar.gz: caaefe028d2a4727c01daeea7241290af00c8676d73c2371ce360279f4dc0c18337c1daa398ab968416ee2516f02d08882b0556d91b5e5e78d318bfbd2d7531f

data/.rubocop.yml

@@ -4,6 +4,7 @@ AllCops:
   SuggestExtensions: false
   Exclude:
     - 'test_*.rb'  # Exclude ad-hoc integration test scripts
+    - 'scripts/**/*'  # Exclude integration test scripts
     - 'vendor/**/*'  # Exclude vendored gems (CI bundles here)
 
 # Allow longer methods for complex logic

data/CHANGELOG.md

@@ -1,8 +1,30 @@
 ## [Ruby Hyperliquid SDK Changelog]
 
+## [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
+  - USD transfers: `usd_send`, `usd_class_transfer`, `withdraw_from_bridge`
+  - Spot transfers: `spot_send`, `send_asset`
+  - Sub-accounts: `create_sub_account`, `sub_account_transfer`, `sub_account_spot_transfer`
+  - Vaults: `vault_transfer`
+  - Referrals: `set_referrer`
+- Add user-signed action signing (`sign_user_signed_action`) for EIP-712 typed data with `HyperliquidSignTransaction` domain
+- Add Python SDK parity test vectors for `usd_send`, `withdraw_from_bridge`, `create_sub_account`, and `sub_account_transfer`
+- Reorganize integration tests into individual scripts under `scripts/` for easier debugging
+
 ## [0.5.0] - 2026-01-28
 
-- Add core trading features to Exchange API (Tier 1 parity with Python SDK)
+- Add core trading features to Exchange API
   - Order modification: `modify_order`, `batch_modify`
   - Position management: `update_leverage`, `update_isolated_margin`, `market_close`
   - Dead man's switch: `schedule_cancel`

data/CLAUDE.md

@@ -45,16 +45,15 @@ ruby example.rb
 
 ### Integration Testing (Testnet)
 ```bash
-# Run the testnet integration test (requires private key)
+# Run all integration tests (requires private key)
 # Get testnet funds from: https://app.hyperliquid-testnet.xyz
-HYPERLIQUID_PRIVATE_KEY=0x... ruby test_integration.rb
+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
 ```
 
-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)
+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

data/docs/API.md

@@ -84,11 +84,32 @@ Read-only methods for querying market data and user information.
 - `update_leverage(coin:, leverage:, is_cross:, ...)` - Set cross or isolated leverage for a coin
 - `update_isolated_margin(coin:, amount:, ...)` - Add or remove isolated margin for a position
 
+### Transfers & Account Management
+
+- `usd_send(amount:, destination:)` - Transfer USDC to another address
+- `spot_send(amount:, destination:, token:)` - Transfer a spot token to another address
+- `usd_class_transfer(amount:, to_perp:)` - Move USDC between perp and spot accounts
+- `withdraw_from_bridge(amount:, destination:)` - Withdraw USDC via the bridge
+- `send_asset(destination:, source_dex:, destination_dex:, token:, amount:)` - Move assets between DEX instances
+- `create_sub_account(name:)` - Create a sub-account
+- `sub_account_transfer(sub_account_user:, is_deposit:, usd:)` - Transfer USDC to/from a sub-account
+- `sub_account_spot_transfer(sub_account_user:, is_deposit:, token:, amount:)` - Transfer spot tokens to/from a sub-account
+- `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
+
 ### Other
 
 - `address` - Get the wallet address associated with the private key
 
-All exchange methods support an optional `vault_address:` parameter for vault trading.
+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
 

data/docs/DEVELOPMENT.md

@@ -11,13 +11,42 @@ bin/setup
 ## Running Tests
 
 ```bash
-# Run all tests
+# Run all unit tests
 rake spec
 
-# Run tests and linting together (default)
+# Run unit tests and linting together (default)
 rake
 ```
 
+### Integration Testing (Testnet)
+
+Integration tests live in `scripts/` and execute real trades on testnet. No real funds are at risk. Get testnet funds from https://app.hyperliquid-testnet.xyz.
+
+```bash
+# Run all integration tests
+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
+```
+
+The convenience wrapper `ruby test_integration.rb` also runs all tests.
+
+Available test scripts:
+
+| Script | Description |
+|--------|-------------|
+| `test_01_spot_market_roundtrip.rb` | Buy/sell PURR/USDC at market |
+| `test_02_spot_limit_order.rb` | Place and cancel a spot limit order |
+| `test_03_perp_market_roundtrip.rb` | Long/close BTC at market |
+| `test_04_perp_limit_order.rb` | Place and cancel a perp short |
+| `test_05_update_leverage.rb` | Set cross, isolated, and reset leverage |
+| `test_06_modify_order.rb` | Place, modify, and cancel an order |
+| `test_07_market_close.rb` | Open a position and close via `market_close` |
+| `test_08_usd_class_transfer.rb` | Transfer USDC between perp and spot |
+| `test_09_sub_account_lifecycle.rb` | Create sub-account, deposit, withdraw |
+| `test_10_vault_transfer.rb` | Deposit/withdraw to a vault |
+
 ## Linting
 
 ```bash
@@ -37,18 +66,3 @@ This opens an interactive prompt with the SDK loaded for experimentation.
 ```bash
 ruby example.rb
 ```
-
-## Integration Testing (Testnet)
-
-For real trading tests on testnet:
-
-```bash
-# 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)

data/docs/EXAMPLES.md

@@ -388,6 +388,153 @@ sdk.exchange.order(
 )
 ```
 
+### Transfers & Account Management
+
+```ruby
+# Transfer USDC to another address
+sdk.exchange.usd_send(
+  amount: '100',
+  destination: '0x...'
+)
+
+# Transfer a spot token to another address
+sdk.exchange.spot_send(
+  amount: '50',
+  destination: '0x...',
+  token: 'PURR'
+)
+
+# Move USDC between perp and spot accounts
+sdk.exchange.usd_class_transfer(amount: '100', to_perp: false)   # perp -> spot
+sdk.exchange.usd_class_transfer(amount: '100', to_perp: true)    # spot -> perp
+
+# Withdraw USDC via the bridge
+sdk.exchange.withdraw_from_bridge(
+  amount: '100',
+  destination: '0x...'
+)
+
+# Move assets between DEX instances
+sdk.exchange.send_asset(
+  destination: '0x...',
+  source_dex: 'dex1',
+  destination_dex: 'dex2',
+  token: 'USDC',
+  amount: '100'
+)
+```
+
+### Sub-Account Management
+
+```ruby
+# Create a sub-account
+result = sdk.exchange.create_sub_account(name: 'my-sub-account')
+sub_address = result.dig('response', 'data', 'subAccountUser')
+
+# Deposit USDC into a sub-account
+sdk.exchange.sub_account_transfer(
+  sub_account_user: sub_address,
+  is_deposit: true,
+  usd: 100
+)
+
+# Withdraw USDC from a sub-account
+sdk.exchange.sub_account_transfer(
+  sub_account_user: sub_address,
+  is_deposit: false,
+  usd: 50
+)
+
+# Transfer spot tokens to a sub-account
+sdk.exchange.sub_account_spot_transfer(
+  sub_account_user: sub_address,
+  is_deposit: true,
+  token: 'PURR',
+  amount: '10'
+)
+```
+
+### Vault Operations
+
+```ruby
+# Deposit USDC into a vault
+sdk.exchange.vault_transfer(
+  vault_address: '0x...',
+  is_deposit: true,
+  usd: 100
+)
+
+# Withdraw USDC from a vault
+sdk.exchange.vault_transfer(
+  vault_address: '0x...',
+  is_deposit: false,
+  usd: 50
+)
+```
+
+### Referral
+
+```ruby
+# Set a referral code
+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
+)
+```
+
 ### Client Order IDs (Cloid)
 
 ```ruby