hyperliquid 1.9.2 → 2.0.0

data/docs/CONFIGURATION.md

@@ -3,10 +3,11 @@
 ## Basic Options
 
 ```ruby
-# Custom timeout (default: 30 seconds)
+# Custom timeout in seconds (default: 30), applied separately to connecting,
+# sending the request and waiting for the response
 sdk = Hyperliquid.new(timeout: 60)
 
-# Enable retry logic for handling transient failures (default: disabled)
+# Retry transient failures of read requests (default: disabled; /exchange is never retried)
 sdk = Hyperliquid.new(retry_enabled: true)
 
 # Enable trading with a private key
@@ -36,18 +37,31 @@ sdk.base_url  # => "https://api.hyperliquid.xyz"
 sdk.exchange  # => nil if no private_key, Hyperliquid::Exchange instance otherwise
 ```
 
+## Timeout
+
+`timeout:` (seconds, default 30) is used for every phase of a request: opening the connection, writing the request and reading the response. Each phase can take up to that long, so a slow response raises `Hyperliquid::TimeoutError` once no data has arrived for `timeout` seconds.
+
 ## Retry Configuration
 
-By default, retry logic is **disabled** for predictable API behavior. When enabled, the SDK will automatically retry requests that fail due to:
+Retries are **disabled** by default. With `retry_enabled: true`, only read requests are retried:
+
+- `POST /info`: every `sdk.info` method except `tx_details` and `user_details`
+- `POST /explorer` on the RPC host: `sdk.info.tx_details` and `sdk.info.user_details`
+
+**`POST /exchange` is never retried**, whatever the failure. Resending a signed action could execute it twice (for example, place the same order twice), so a failed exchange request always raises after exactly one attempt. Check the result (for example with `open_orders` or `order_status`) before you send the action again.
 
-- Network connectivity issues (connection failed, timeouts)
-- Server errors (5xx status codes)
-- Rate limiting (429 status codes)
+A read request is retried when:
+
+- the response status is 429, 502, 503 or 504
+- the connection fails (`Faraday::ConnectionFailed`) or times out (`Faraday::TimeoutError`)
+
+Other statuses (400, 401, 404, 500, …) are not retried and raise their error class immediately.
 
 **Retry Settings:**
-- Maximum retries: 2
-- Base interval: 0.5 seconds
-- Backoff factor: 2x (exponential backoff)
-- Randomness: ±50% to prevent thundering herd
+- Maximum retries: 2 (at most 3 attempts per read request)
+- Wait before retry *n*: 0.5 s × 2^(n−1), plus a random 0–0.25 s (0.5–0.75 s, then 1.0–1.25 s)
+- A `Retry-After` or `RateLimit-Reset` response header that asks for a longer wait is honoured
+
+When the last attempt still fails, the SDK raises the same error a single failure would raise (`RateLimitError` for 429, `ServerError` for 5xx, `NetworkError` or `TimeoutError` for network failures).
 
-**Note:** Retries are disabled by default to avoid unexpected delays in time-sensitive trading applications. Enable only when you want automatic handling of transient failures.
+**Note:** Retries are disabled by default to avoid unexpected delays in time-sensitive trading applications. Enable them only if you want transient read failures handled automatically.

data/docs/DEVELOPMENT.md

@@ -11,46 +11,124 @@ bin/setup
 ## Running Tests
 
 ```bash
-# Run all unit tests
+# Default gate (what CI runs): unit tests, RuboCop, and Lint+Security on scripts/ and example.rb
+rake
+
+# Unit tests only (random order; reproduce a failure with its printed seed)
 rake spec
+bundle exec rspec --seed 1234
 
-# Run unit tests and linting together (default)
-rake
+# Default gate again inside a fresh clone of HEAD with a frozen bundle (run after committing)
+rake verify
+
+# Exit 0 and print DOCS_ONLY=yes iff every uncommitted change is docs-only
+rake verify:docs_only
+
+# Regenerate the Python-SDK parity fixtures and diff them against spec/fixtures/parity (python3 + network)
+rake parity:check
+
+# Run the Ruby 3.3 CI leg locally
+RBENV_VERSION=3.3.12 bundle exec rake
 ```
 
+A change is done when `rake` is green, `rake verify` is green on the commit, and `rake integration` reports `INTEGRATION GATE: PASS`. You can skip `rake integration` only when `rake verify:docs_only` prints `DOCS_ONLY=yes`. Unit and lint failures are never waived. See `CLAUDE.md` → Verification.
+
 ### 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 the integration gate (exits 2 when HYPERLIQUID_PRIVATE_KEY is unset)
+HYPERLIQUID_PRIVATE_KEY=0x... rake integration
+
+# Same runner without rake
+HYPERLIQUID_PRIVATE_KEY=0x... ruby -rbundler/setup scripts/test_all.rb
 
 # Run a single integration test
-HYPERLIQUID_PRIVATE_KEY=0x... ruby scripts/test_08_usd_class_transfer.rb
+HYPERLIQUID_PRIVATE_KEY=0x... ruby -rbundler/setup scripts/test_08_usd_class_transfer.rb
+
+# Read-only wallet precondition check (the runner's pre-flight and post-flight)
+HYPERLIQUID_PRIVATE_KEY=0x... ruby -rbundler/setup scripts/testnet_wallet_check.rb --assert
+
+# Switch to standard abstraction and rebalance (manual only, never from a runner)
+HYPERLIQUID_PRIVATE_KEY=0x... ruby -rbundler/setup scripts/testnet_wallet_check.rb --fix
+```
+
+`scripts/test_all.rb` is the only runner.
+- **Discovery.** It runs every `scripts/test_[0-9][0-9]_*.rb` it finds by glob, in sorted order, so a new script is picked up automatically. Deliberate exclusions go in its `OPT_OUT` hash, with a reason.
+- **Lock.** It holds a `flock` on `tmp/integration.lock`, so only one gate runs at a time.
+- **Wallet checks.** It runs `testnet_wallet_check.rb --assert` before the first script and after the last. A violation fails the gate as `precondition` or `leak`.
+- **Process.** Each script runs under `ruby -rbundler/setup`, against the locked gems, in its own process group. The private key is redacted from the output.
+- **Timeouts.** Each script has a timeout of `HL_SCRIPT_TIMEOUT` seconds (default 300) and is then killed (TIMEOUT). The whole run has a budget of `HL_GATE_BUDGET` seconds (default 2400); scripts left when it runs out are NOT_RUN.
+
+Each script reports its result through its exit code:
+
+| Status | Exit | Meaning | Blocks the gate |
+|--------|------|---------|-----------------|
+| PASS | 0 | Verified (for a rejection wire check: the pinned rejection arrived) | no |
+| FAIL | 1 (or any other unlisted code) | Something is wrong | yes |
+| INCONCLUSIVE | 75 | The environment gave no evidence either way | no (yes with `HL_GATE_STRICT=1`) |
+| SKIPPED | 77 | The script deliberately tested nothing | no (yes with `HL_GATE_STRICT=1`) |
+| GUARDED | 78 | Wallet/testnet state forced a weaker check that still proves signing | no (yes with `HL_GATE_STRICT=1`) |
+| TIMEOUT | — | Exceeded `HL_SCRIPT_TIMEOUT` and was killed | yes |
+| NOT_RUN | — | `HL_GATE_BUDGET` ran out before the script started | yes |
+
+The runner's last stdout line is always:
+
+```text
+INTEGRATION GATE: PASS|FAIL total=N pass=a guarded=b skipped=c inconclusive=d fail=e timeout=f not_run=g
 ```
 
-The convenience wrapper `ruby test_integration.rb` also runs all tests.
+A JSON summary with per-script status, exit code, duration and `RESULT` line goes to `HL_GATE_SUMMARY`, default `tmp/integration-summary.json`. Report every INCONCLUSIVE, SKIPPED and GUARDED script by name.
+
+Every script is safe to run unattended in its default mode, and a new script must be too: read-only, or rejection-only with a fail-closed guard. Destructive or locking variants are opt-in CLI args on individual scripts and are never run by the runner:
+
+```bash
+ruby -rbundler/setup scripts/test_10_vault.rb deposit|withdraw            # move $10 into / out of the test vault
+ruby -rbundler/setup scripts/test_12_staking.rb delegate|undelegate       # 0.1 HYPE, 1-day delegation lockup
+ruby -rbundler/setup scripts/test_16_send_to_evm_with_data.rb live        # burns 1 testnet USDC
+ruby -rbundler/setup scripts/test_17_create_vault.rb live                 # locks $100 in a new vault
+```
 
-Available test scripts:
+Available test scripts (every `scripts/test_NN_*.rb` has exactly one row here; `spec/call_surface_spec.rb` enforces it):
 
 | 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_02_spot_limit_order.rb` | Place a resting spot limit buy below market and cancel it |
 | `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_04_perp_limit_order.rb` | Place a resting perp limit short above market and cancel it |
+| `test_05_update_leverage.rb` | Set cross, isolated, and reset BTC leverage (requires no BTC position or orders) |
 | `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 |
+| `test_08_usd_class_transfer.rb` | Transfer USDC perp → spot → perp (GUARDED rejection wire check on a unified wallet) |
+| `test_09_sub_account_lifecycle.rb` | Create (or reuse) a sub-account, deposit, withdraw (volume-gate rejection is a wire check) |
+| `test_10_vault.rb` | Vault status (`deposit`/`withdraw` opt-in) |
+| `test_11_builder_fee.rb` | Approve a builder fee, place an order with a builder, cancel (GUARDED if the builder is ineligible) |
+| `test_12_staking.rb` | Staking status and undelegate rejection wire check (`delegate`/`undelegate` opt-in) |
+| `test_13_ws_l2_book.rb` | WebSocket `l2Book` subscription (top of book; no key) |
+| `test_14_ws_candle.rb` | WebSocket `candle` subscriptions with coin/interval routing checks (INCONCLUSIVE when testnet ETH has no trades) |
+| `test_15_explorer.rb` | Explorer RPC `user_details` and `tx_details` (SKIPPED when the wallet has no txs) |
+| `test_16_send_to_evm_with_data.rb` | Send USDC to HyperEVM with calldata (default: rejection wire check; `live` sends 1 USDC) |
+| `test_17_create_vault.rb` | Create a vault (default: rejection wire check; `live` seeds a real vault with $100) |
+| `test_18_user_portfolio_margin.rb` | Portfolio-margin toggle (rejection wire check; restores the original mode) |
+| `test_19_spot_user.rb` | Opt out of then back into spot dusting |
+| `test_20_explorer_ws.rb` | Explorer WebSocket block stream (3 blocks; INCONCLUSIVE on 1–2) |
+| `test_21_ws_channel_parity.rb` | Subscribe to the parity WS channels (read-only) and check each delivers its own user/dex/coin |
+| `test_22_outcome_deploy.rb` | HIP-4 outcome deployer actions (structured-rejection wire check) |
+| `test_23_ws_fast_asset_ctxs.rb` | Subscribe to the compressed `fastAssetCtxs` channel (read-only) and check the decoded snapshot + deltas |
+| `test_24_perp_deploy_wire.rb` | Send `perpDeploy` actions to a nonexistent dex; expect a structured rejection (proves signing) |
+| `test_25_hip3_star.rb` | Read `user_star_state`; send a HIP-3* `star` action to a live star dex; expect a structured rejection (proves signing; SKIPPED when no star dex exists) |
+| `test_26_spot_deploy_rejection.rb` | spotDeploy structured-rejection wire check on token 0 with a throwaway-key control (no state change) |
+| `test_27_validator_actions.rb` | Validator-operator actions (`validator_l1_stream`, `c_signer_*`, `c_validator_change_profile`, `c_validator_unregister`) — rejection-only wire check behind a fail-closed non-validator safety guard; `c_validator_register` is never sent |
+
+Each rejection wire check (`test_09`, `test_12`, `test_16`–`test_18`, `test_22`, `test_24`–`test_27`) also sends the same call with a never-funded throwaway key. It passes only when the wallet's rejection differs from that control's "does not exist" / "must deposit" rejection, which proves the server recovered this wallet as the signer.
 
 ## Linting
 
 ```bash
-rake rubocop
+rake rubocop           # lib/, spec/, config files
+rake rubocop:scripts   # Lint + Security departments only, on scripts/ and example.rb
 ```
 
 ## Interactive Console

data/docs/ERRORS.md

@@ -36,3 +36,5 @@ end
 | `Hyperliquid::RateLimitError` | 429 errors |
 | `Hyperliquid::NetworkError` | Connection issues |
 | `Hyperliquid::TimeoutError` | Request timeouts |
+| `Hyperliquid::WebSocketError` | Unsupported WebSocket subscription type |
+| `Hyperliquid::ConfigurationError` | Missing configuration, e.g. explorer endpoint not set |

data/docs/EXAMPLES.md

@@ -134,6 +134,20 @@ signers = sdk.info.user_to_multi_sig_signers(user_address)
 # Get dex abstraction config for a user
 dex_abstraction = sdk.info.user_dex_abstraction(user_address)
 # => { "enabled" => true }
+
+# Fills in a time range, newest first, with partial fills of one crossing order merged
+fills = sdk.info.user_fills_by_time(user_address, start_time_ms, nil, aggregate_by_time: true, reversed: true)
+
+# Recent trades and a block by height
+sdk.info.recent_trades('BTC')
+sdk.info.block_details(123_456)
+
+# Vaults created in the last 2 hours, and vaults a user leads
+sdk.info.vault_summaries
+sdk.info.leading_vaults(user_address)
+
+# Margin table (dex: '' is the main dex)
+sdk.info.margin_table(1, dex: '')
 ```
 
 **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"]`.
@@ -183,6 +197,29 @@ oi_capped = sdk.info.perps_at_open_interest_cap
 auction = sdk.info.perp_deploy_auction_status
 # => { "startTimeSeconds" => ..., "durationSeconds" => ..., "startGas" => "500.0", ... }
 
+# Deploy a HIP-3 perp dex (deployer wallet only; mirrors the Python SDK's examples/perp_deploy.py).
+# The first registration on a new dex passes `schema:` and pays the deploy-auction gas.
+# `auction` comes from perp_deploy_auction_status above; `max_gas: nil` bids its currentGas.
+sdk.exchange.perp_deploy_register_asset2(
+  dex: "test", coin: "test:TEST0", sz_decimals: 2, oracle_px: "10.0", margin_table_id: 10,
+  margin_mode: "noCross",
+  max_gas: 1_000_000_000_000, # native-token wei: 10k HYPE
+  schema: { full_name: "test dex", collateral_token: 0, oracle_updater: sdk.exchange.address }
+)
+# => { "status" => "ok", "response" => { "type" => "default" } }
+
+# Push oracle prices (at most once every 2.5s); coins are full "dex:COIN" names.
+# A real oracle updater runs this continuously.
+3.times do
+  sdk.exchange.perp_deploy_set_oracle(
+    dex: "test",
+    oracle_pxs: { "test:TEST0" => "12.0" },
+    all_mark_pxs: [{ "test:TEST0" => "12.1" }],
+    external_perp_pxs: { "test:TEST0" => "12.0" }
+  )
+  sleep 3
+end
+
 # Retrieve User's Active Asset Data
 aad = sdk.info.active_asset_data(user_address, "APT")
 # => { "user" => user_address, "coin" => "APT", "leverage" => { "type" => "cross", "value" => 3 }, ... }
@@ -220,6 +257,31 @@ details = sdk.info.token_details("0x00000000000000000000000000000000")
 # => { "name" => "TEST", "maxSupply" => "...", "midPx" => "...", ... }
 ```
 
+### HIP-2 Borrow/Lend
+
+```ruby
+sdk.info.all_borrow_lend_reserve_states
+sdk.info.borrow_lend_reserve_state(0)               # token index 0 = USDC
+sdk.info.borrow_lend_user_state(user_address)
+sdk.info.user_borrow_lend_interest(user_address, start_time_ms)
+```
+
+### HIP-4 Outcomes
+
+```ruby
+sdk.info.outcome_meta
+sdk.info.outcome_templates
+sdk.info.settled_outcome(outcome: 5)                # nil until settled
+```
+
+### Explorer RPC
+
+```ruby
+# Routed to rpc.hyperliquid.xyz/explorer (rpc.hyperliquid-testnet.xyz with testnet: true)
+txs = sdk.info.user_details(user_address)
+sdk.info.tx_details('0x' + 'ab' * 32)               # a 66-character transaction hash
+```
+
 ## Exchange API (Trading)
 
 ### Basic Orders
@@ -356,7 +418,7 @@ sdk.exchange.market_close(coin: 'BTC', size: 0.01, slippage: 0.03)
 cancel_time = (Time.now.to_f * 1000).to_i + 60_000  # 60 seconds from now
 sdk.exchange.schedule_cancel(time: cancel_time)
 
-# Activate schedule cancel without specifying a time (server default)
+# Remove the scheduled cancel
 sdk.exchange.schedule_cancel
 ```
 
@@ -408,6 +470,34 @@ sdk.exchange.order(
 )
 ```
 
+### TWAP and Trailing Stop Orders
+
+```ruby
+# Buy 1 ETH over 30 minutes
+result = sdk.exchange.twap_order(coin: 'ETH', is_buy: true, size: 1, reduce_only: false,
+                                 minutes: 30, randomize: true)
+twap_id = result.dig('response', 'data', 'status', 'running', 'twapId')
+sdk.exchange.twap_cancel(coin: 'ETH', twap_id: twap_id)
+
+# Reduce-only trailing sell of 0.01 BTC, 1.5% retracement, active once the price reaches 100000
+sdk.exchange.trailing_stop(coin: 'BTC', is_buy: false, size: 0.01, reduce_only: true,
+                           retracement: { pct: '1.5%' }, activation_px: '100000')
+```
+
+### Fast Cancel, Always-Place Modify, Order Expiry
+
+```ruby
+sdk.exchange.cancel(coin: 'BTC', oid: 123, fast: true)
+sdk.exchange.modify_order(oid: 123, coin: 'BTC', is_buy: true, size: 0.01, limit_px: 95_000,
+                          always_place: true)
+
+# Reject L1 actions that reach the exchange after this time (ms); nil clears it.
+# Leave it nil around user-signed actions such as usd_send.
+sdk.exchange.expires_after = (Time.now.to_f * 1000).to_i + 10_000
+sdk.exchange.order(coin: 'BTC', is_buy: true, size: 0.01, limit_px: 90_000)
+sdk.exchange.expires_after = nil
+```
+
 ### Transfers & Account Management
 
 ```ruby
@@ -421,7 +511,7 @@ sdk.exchange.usd_send(
 sdk.exchange.spot_send(
   amount: '50',
   destination: '0x...',
-  token: 'PURR'
+  token: 'PURR:0xc4bf3f870c0e9465323c0b6ed28096c2' # testnet PURR; mainnet is PURR:0xc1fb593aeffbeb02f85e0308e9956a90 (see info.spot_meta)
 )
 
 # Move USDC between perp and spot accounts
@@ -442,6 +532,16 @@ sdk.exchange.send_asset(
   token: 'USDC',
   amount: '100'
 )
+
+# Move USDC between perp and spot for a sub-account
+sdk.exchange.usd_class_transfer(amount: 10, to_perp: true, sub_account: '0x...')
+
+# Send USDC to HyperEVM with calldata for an ICoreReceiveWithData contract
+sdk.exchange.send_to_evm_with_data(
+  token: 'USDC', amount: '5', source_dex: 'spot',
+  destination_recipient: '0x...', address_encoding: 'hex',
+  destination_chain_id: 998, gas_limit: 200_000, data: '0x'
+)
 ```
 
 ### Sub-Account Management
@@ -490,8 +590,54 @@ sdk.exchange.vault_transfer(
   is_deposit: false,
   usd: 50
 )
+
+# Create a vault (at least 100 USD), then manage it as leader
+sdk.exchange.create_vault(name: 'My Vault', description: 'Trend following on BTC', initial_usd: 100)
+sdk.exchange.vault_modify(vault_address: '0x...', allow_deposits: false)
+sdk.exchange.vault_distribute(vault_address: '0x...', usd: 25)
+```
+
+### HIP-2 Borrow/Lend and HIP-4 Outcomes
+
+```ruby
+sdk.exchange.borrow_lend(operation: 'supply', token: 0, amount: '100')
+sdk.exchange.borrow_lend(operation: 'withdraw', token: 0)          # amount nil = full position
+
+sdk.exchange.split_outcome(outcome: 5, amount: '10')               # 10 quote -> 10 Yes + 10 No
+sdk.exchange.merge_outcome(outcome: 5)                             # merge the maximum back
 ```
 
+### Multi-Sig
+
+```ruby
+# 1. Once: turn the multi-sig account into a 2-of-3 multi-sig user
+owner = Hyperliquid.new(testnet: true, private_key: ENV['MULTI_SIG_OWNER_KEY'])
+owner.exchange.convert_to_multi_sig_user(authorized_users: [addr_a, addr_b, addr_c], threshold: 2)
+
+# 2. Each co-signer signs the same inner action and nonce, with the submitter as outer_signer
+multi_sig_user = owner.exchange.address
+submitter = Hyperliquid.new(testnet: true, private_key: ENV['SIGNER_A_KEY'])
+nonce = (Time.now.to_f * 1000).to_i
+inner_action = {
+  type: 'order',
+  orders: [{ a: 4, b: true, p: '1100', s: '0.2', r: false, t: { limit: { tif: 'Gtc' } } }],
+  grouping: 'na'
+}
+signatures = [ENV['SIGNER_A_KEY'], ENV['SIGNER_B_KEY']].map do |key|
+  Hyperliquid::Signing::MultiSig.sign_as_co_signer_l1(
+    signer: Hyperliquid::Signing::Signer.new(private_key: key, testnet: true),
+    inner_action: inner_action, multi_sig_user: multi_sig_user,
+    outer_signer: submitter.exchange.address, nonce: nonce
+  )
+end
+
+# 3. The submitter posts the envelope with the same nonce
+submitter.exchange.multi_sig(multi_sig_user: multi_sig_user, inner_action: inner_action,
+                             signatures: signatures, nonce: nonce)
+```
+
+The inner action is the wire-format action body (here an order for asset 4). For a user-signed inner action, co-signers call `sign_as_co_signer_user_signed` with its EIP-712 primary type and type constant, e.g. `primary_type: 'HyperliquidTransaction:SendAsset', sign_types: Hyperliquid::Signing::EIP712::SEND_ASSET_TYPES`.
+
 ### Referral
 
 ```ruby
@@ -581,6 +727,39 @@ status = sdk.info.user_dex_abstraction(sdk.exchange.address)
 # => { "enabled" => true }
 ```
 
+### HIP-4 Outcome Deployment
+
+For an activated outcome deployer (or a sub-deployer acting for its venue). Responses come back unmodified, so check `status`.
+
+```ruby
+venue = 'abc'
+
+# How many outcomes can this venue still deploy?
+limits = sdk.info.outcome_deployer_limits(venue)
+# => { "nDailyOutcomesRemaining" => 10, "nActiveOutcomesRemaining" => 90 }
+
+# Deploy a standalone Yes/No outcome; keywords are sorted by the SDK
+result = sdk.exchange.register_standalone_outcome_from_template(
+  venue: venue,
+  template_id: 'binaryPrice',
+  keyword_to_value: { perp: 'BTC', priceDescription: 'the Hyperliquid BTC perp trade',
+                      seconds: 90, threshold: 84_793, time: '20261002-1900' },
+  deployer_fee_scale: '1'
+)
+raise result['response'].to_s unless result['status'] == 'ok'
+
+# Settle it later: name, description and side names must match outcome_meta exactly
+outcome = sdk.info.outcome_meta['outcomes'].reverse.find { |o| o['venue'] == venue }
+sdk.exchange.settle_outcome(
+  venue: venue,
+  outcome: outcome['outcome'],
+  settle_fraction: '1', # first side (Yes) pays out in full
+  name: outcome['name'],
+  description: outcome['description'],
+  side_names: outcome['sideSpecs'].map { |s| s['name'] }
+)
+```
+
 ## WebSocket
 
 ### l2Book (Order Book)
@@ -688,6 +867,60 @@ sleep 60
 sdk.ws.close
 ```
 
+### clearinghouseState (per dex)
+
+```ruby
+sdk = Hyperliquid.new(testnet: true)
+user = '0x...'
+
+# Main dex (omit dex:) and a HIP-3 dex are separate subscriptions
+sdk.ws.subscribe({ type: 'clearinghouseState', user: user }) do |data|
+  puts "main dex account value: #{data['clearinghouseState']['marginSummary']['accountValue']}"
+end
+
+sdk.ws.subscribe({ type: 'clearinghouseState', user: user, dex: 'xyz' }) do |data|
+  puts "#{data['dex']} positions: #{data['clearinghouseState']['assetPositions'].length}"
+end
+
+sleep 10
+sdk.ws.close
+```
+
+### activeAssetCtx (Asset Context)
+
+```ruby
+sdk = Hyperliquid.new(testnet: true)
+
+# Perp, HIP-3 ('xyz:XYZ100') or spot ('PURR/USDC', '@107') coins
+sdk.ws.subscribe({ type: 'activeAssetCtx', coin: 'BTC' }) do |data|
+  puts "#{data['coin']} mark=#{data['ctx']['markPx']} funding=#{data['ctx']['funding']}"
+end
+
+sdk.ws.subscribe({ type: 'activeAssetCtx', coin: 'PURR/USDC' }) do |data|
+  puts "#{data['coin']} mark=#{data['ctx']['markPx']}"
+end
+
+sleep 10
+sdk.ws.close
+```
+
+### fastAssetCtxs (mark/mid prices, compressed)
+
+```ruby
+sdk = Hyperliquid.new(testnet: true)
+cache = {}
+
+# First frame: snapshot of every coin. Later frames: only changed coins/fields.
+# Frames arrive base64 + raw DEFLATE; the SDK decodes them before the callback.
+sdk.ws.subscribe({ type: 'fastAssetCtxs' }) do |ctxs|
+  cache.merge!(ctxs) { |_coin, old, new| old.merge(new) }
+  puts "BTC mark=#{cache.dig('BTC', 'markPx')} mid=#{cache.dig('BTC', 'midPx')} (#{cache.size} coins)"
+end
+
+sleep 10
+sdk.ws.close
+```
+
 ### Multiple Subscriptions
 
 ```ruby
@@ -709,6 +942,24 @@ sleep 10
 sdk.ws.close
 ```
 
+### Explorer Blocks and Transactions
+
+```ruby
+sdk = Hyperliquid.new(testnet: true)
+
+# Separate connection to rpc.hyperliquid(-testnet).xyz/ws; each message is an Array
+sdk.ws.subscribe_explorer_block do |blocks|
+  blocks.each { |b| puts "block #{b['height']} with #{b['numTxs']} txs" }
+end
+
+sdk.ws.subscribe_explorer_txs do |txs|
+  txs.each { |tx| puts "#{tx['user']} #{tx.dig('action', 'type')} #{tx['hash']}" }
+end
+
+sleep 10
+sdk.ws.close
+```
+
 ### Handling Reconnection
 
 ```ruby