hyperliquid 0.3.0 → 0.4.1

data/README.md

@@ -2,7 +2,7 @@
 
 A Ruby SDK for interacting with the Hyperliquid decentralized exchange API.
 
-The latest version is v0.2.0 - a read-only implementation focusing on the Info API endpoints for market data, user information, and order book data.
+The SDK supports both read operations (Info API) and authenticated write operations (Exchange API) for trading.
 
 ## Installation
 
@@ -27,364 +27,40 @@ Or install it yourself as:
 ```ruby
 require 'hyperliquid'
 
-# Create SDK instance (mainnet by default)
+# Create SDK instance for read-only operations (mainnet by default)
 sdk = Hyperliquid.new
 
 # Or use testnet
 testnet_sdk = Hyperliquid.new(testnet: true)
 
-# Access the Info API
+# Access the Info API (read operations)
 info = sdk.info
-```
-
-### Supported APIs
-
-The SDK provides access to the following Hyperliquid APIs:
-
-#### Info Methods
-- `all_mids()` - Retrieve mids for all coins
-- `open_orders(user)` - Retrieve a user's open orders
-- `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)
-- `user_rate_limit(user)` - Query user rate limits
-- `order_status(user, oid)` - Query order status by order id (oid)
-- `order_status_by_cloid(user, cloid)` - Query order status by client order id (cloid)
-- `l2_book(coin)` - L2 book snapshot (Perpetuals and Spot)
-- `candles_snapshot(coin, interval, start_time, end_time)` - Candle snapshot (Perpetuals and Spot)
-- `max_builder_fee(user, builder)` - Check builder fee approval
-- `historical_orders(user, start_time = nil, end_time = nil)` - Retrieve a user's historical orders
-- `user_twap_slice_fills(user, start_time = nil, end_time = nil)` - Retrieve a user's TWAP slice fills
-- `user_subaccounts(user)` - Retrieve a user's subaccounts
-- `vault_details(vault_address, user = nil)` - Retrieve details for a vault
-- `user_vault_equities(user)` - Retrieve a user's vault deposits
-- `user_role(user)` - Query a user's role
-- `portfolio(user)` - Query a user's portfolio
-- `referral(user)` - Query a user's referral information
-- `user_fees(user)` - Query a user's fees and fee schedule
-- `delegations(user)` - Query a user's staking delegations
-- `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
-
-##### Perpetuals Methods
-- `perp_dexs()` - Retrieve all perpetual DEXs
-- `meta(dex: nil)` - Get asset metadata (optionally for a specific perp DEX)
-- `meta_and_asset_ctxs()` - Get extended asset metadata
-- `user_state(user, dex: nil)` - Retrieve user's perpetuals account summary (optionally for a specific perp DEX)
-- `predicted_fundings()` - Retrieve predicted funding rates across venues
-- `perps_at_open_interest_cap()` - Query perps at open interest caps
-- `perp_deploy_auction_status()` - Retrieve Perp Deploy Auction status
-- `active_asset_data(user, coin)` - Retrieve a user's active asset data for a coin
-- `perp_dex_limits(dex)` - Retrieve builder-deployed perp market limits for a DEX
-- `user_funding(user, start_time, end_time = nil)` - Retrieve a user's funding history (optional end time)
-- `user_non_funding_ledger_updates(user, start_time, end_time = nil)` - Retrieve a user's non-funding ledger updates. Non-funding ledger updates include deposits, transfers, and withdrawals. (optional end time)
-- `funding_history(coin, start_time, end_time = nil)` - Retrieve historical funding rates (optional end time)
-
-##### Spot Methods
-- `spot_meta()` - Retrieve spot metadata (tokens and universe)
-- `spot_meta_and_asset_ctxs()` - Retrieve spot metadata and asset contexts
-- `spot_balances(user)` - Retrieve a user's spot token balances
-- `spot_deploy_state(user)` - Retrieve Spot Deploy Auction information
-- `spot_pair_deploy_auction_status()` - Retrieve Spot Pair Deploy Auction status
-- `token_details(token_id)` - Retrieve information about a token by tokenId
-
-#### Examples: Info
-
-```ruby
-# Retrieve mids for all coins
-mids = sdk.info.all_mids
-# => { "BTC" => "50000", "ETH" => "3000", ... }
-
-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 with additional frontend info
-frontend_orders = sdk.info.frontend_open_orders(user_address)
-# => [{ "coin" => "BTC", "isTrigger" => false, ... }]
-
-# Retrieve a user's fills
-fills = sdk.info.user_fills(user_address)
-# => [{ "coin" => "BTC", "sz" => "0.1", "px" => "50000", "side" => "A", "time" => 1234567890 }]
-
-# Retrieve a user's fills by time
-start_time_ms = 1_700_000_000_000
-end_time_ms = start_time_ms + 86_400_000
-fills_by_time = sdk.info.user_fills_by_time(user_address, start_time_ms, end_time_ms)
-# => [{ "coin" => "ETH", "px" => "3000", "time" => start_time_ms }, ...]
-
-# Query user rate limits
-rate_limit = sdk.info.user_rate_limit(user_address)
-# => { "nRequestsUsed" => 100, "nRequestsCap" => 10000 }
-
-# Query order status by oid
-order_id = 12345
-status_by_oid = sdk.info.order_status(user_address, order_id)
-# => { "status" => "filled", ... }
-
-# Query order status by cloid
-cloid = "client-order-id-123"
-status_by_cloid = sdk.info.order_status_by_cloid(user_address, cloid)
-# => { "status" => "cancelled", ... }
-
-# L2 order book snapshot
-book = sdk.info.l2_book("BTC")
-# => { "coin" => "BTC", "levels" => [[asks], [bids]], "time" => ... }
-
-# Candle snapshot
-candles = sdk.info.candles_snapshot("BTC", "1h", start_time_ms, end_time_ms)
-# => [{ "t" => ..., "o" => "50000", "h" => "51000", "l" => "49000", "c" => "50500", "v" => "100" }]
-
-# Check builder fee approval
-builder_address = "0x..."
-fee_approval = sdk.info.max_builder_fee(user_address, builder_address)
-# => { "approved" => true, ... }
-
-# Retrieve a user's historical orders
-hist_orders = sdk.info.historical_orders(user_address)
-# => [{ "oid" => 123, "coin" => "BTC", ... }]
-hist_orders_ranged = sdk.info.historical_orders(user_address, start_time_ms, end_time_ms)
-# => []
 
-# Retrieve a user's TWAP slice fills
-twap_fills = sdk.info.user_twap_slice_fills(user_address)
-# => [{ "sliceId" => 1, "coin" => "ETH", "sz" => "1.0" }, ...]
-twap_fills_ranged = sdk.info.user_twap_slice_fills(user_address, start_time_ms, end_time_ms)
-# => []
+# For trading operations, provide a private key
+trading_sdk = Hyperliquid.new(
+  testnet: true,
+  private_key: ENV['HYPERLIQUID_PRIVATE_KEY']
+)
 
-# Retrieve a user's subaccounts
-subaccounts = sdk.info.user_subaccounts(user_address)
-# => ["0x1111...", ...]
-
-# Retrieve details for a vault
-vault_addr = "0x..."
-vault = sdk.info.vault_details(vault_addr)
-# => { "vaultAddress" => vault_addr, ... }
-vault_with_user = sdk.info.vault_details(vault_addr, user_address)
-# => { "vaultAddress" => vault_addr, "user" => user_address, ... }
-
-# Retrieve a user's vault deposits
-vault_deposits = sdk.info.user_vault_equities(user_address)
-# => [{ "vaultAddress" => "0x...", "equity" => "123.45" }, ...]
-
-# Query a user's role
-role = sdk.info.user_role(user_address)
-# => { "role" => "tradingUser" }
-
-# Query a user's portfolio
-portfolio = sdk.info.portfolio(user_address)
-# => [["day", { "pnlHistory" => [...], "vlm" => "0.0" }], ...]
-
-# Query a user's referral information
-referral = sdk.info.referral(user_address)
-# => { "referredBy" => { "referrer" => "0x..." }, ... }
-
-# Query a user's fees
-fees = sdk.info.user_fees(user_address)
-# => { "userAddRate" => "0.0001", "feeSchedule" => { ... } }
-
-# Query a user's staking delegations
-delegations = sdk.info.delegations(user_address)
-# => [{ "validator" => "0x...", "amount" => "100.0" }, ...]
-
-# Query a user's staking summary
-summary = sdk.info.delegator_summary(user_address)
-# => { "delegated" => "12060.16529862", ... }
-
-# Query a user's staking history
-history = sdk.info.delegator_history(user_address)
-# => [{ "time" => 1_736_726_400_073, "delta" => { ... } }, ...]
-
-# Query a user's staking rewards
-rewards = sdk.info.delegator_rewards(user_address)
-# => [{ "time" => 1_736_726_400_073, "source" => "delegation", "totalAmount" => "0.123" }, ...]
+# Access the Exchange API (write operations)
+exchange = trading_sdk.exchange
 ```
 
-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"]`.
-
-##### Examples: Perpetuals
-
-```ruby
-# Retrieve all perpetual DEXs
-perp_dexs = sdk.info.perp_dexs
-# => [nil, { "name" => "test", "full_name" => "test dex", ... }]
-
-# Retrieve perpetuals metadata (optionally for a specific perp dex)
-meta = sdk.info.meta
-# => { "universe" => [...] }
-meta = sdk.info.meta(dex: "perp-dex-name")
-# => { "universe" => [...] }
-
-# Retrieve perpetuals asset contexts (includes mark price, current funding, open interest, etc.)
-meta_ctxs = sdk.info.meta_and_asset_ctxs  
-# => { "universe" => [...], "assetCtxs" => [...] }
-
-# Retrieve user's perpetuals account summary (optionally for a specific perp dex)
-state = sdk.info.user_state(user_address)
-# => { "assetPositions" => [...], "marginSummary" => {...} }
-state = sdk.info.user_state(user_address, dex: "perp-dex-name")
-# => { "assetPositions" => [...], "marginSummary" => {...} }
-
-# Retrieve a user's funding history or non-funding ledger updates (optional end_time)
-funding = sdk.info.user_funding(user_address, start_time)
-# => [{ "delta" => { "type" => "funding", ... }, "time" => ... }]
-funding = sdk.info.user_funding(user_address, start_time, end_time)
-# => [{ "delta" => { "type" => "funding", ... }, "time" => ... }]
-
-# Retrieve historical funding rates
-hist = sdk.info.funding_history("ETH", start_time)
-# => [{ "coin" => "ETH", "fundingRate" => "...", "time" => ... }]
-
-# Retrieve predicted funding rates for different venues
-pred = sdk.info.predicted_fundings
-# => [["AVAX", [["HlPerp", { "fundingRate" => "0.0000125", "nextFundingTime" => ... }], ...]], ...]
-
-# Query perps at open interest caps
-oi_capped = sdk.info.perps_at_open_interest_cap
-# => ["BADGER", "CANTO", ...]
+### Documentation
 
-# Retrieve information about the Perp Deploy Auction
-auction = sdk.info.perp_deploy_auction_status
-# => { "startTimeSeconds" => ..., "durationSeconds" => ..., "startGas" => "500.0", ... }
-
-# 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 }, ... }
-
-# Retrieve Builder-Deployed Perp Market Limits
-limits = sdk.info.perp_dex_limits("builder-dex")
-# => { "totalOiCap" => "10000000.0", "oiSzCapPerPerp" => "...", ... }
-```
-
-##### Examples: Spot
-
-```ruby
-# Retrieve spot metadata
-spot_meta = sdk.info.spot_meta
-# => { "tokens" => [...], "universe" => [...] }
-
-# Retrieve spot asset contexts
-spot_meta_ctxs = sdk.info.spot_meta_and_asset_ctxs
-# => [ { "tokens" => [...], "universe" => [...] }, [ { "midPx" => "...", ... } ] ]
-
-# Retrieve a user's token balances
-balances = sdk.info.spot_balances(user_address)
-# => { "balances" => [{ "coin" => "USDC", "token" => 0, "total" => "..." }, ...] }
-
-# Retrieve information about the Spot Deploy Auction
-deploy_state = sdk.info.spot_deploy_state(user_address)
-# => { "states" => [...], "gasAuction" => { ... } }
-
-# Retrieve information about the Spot Pair Deploy Auction
-pair_status = sdk.info.spot_pair_deploy_auction_status
-# => { "startTimeSeconds" => ..., "durationSeconds" => ..., "startGas" => "...", ... }
-
-# Retrieve information about a token by onchain id in 34-character hexadecimal format
-details = sdk.info.token_details("0x00000000000000000000000000000000")
-# => { "name" => "TEST", "maxSupply" => "...", "midPx" => "...", ... }
-```
-
-### Configuration
-
-```ruby
-# Custom timeout (default: 30 seconds)
-sdk = Hyperliquid.new(timeout: 60)
-
-# Enable retry logic for handling transient failures (default: disabled)
-sdk = Hyperliquid.new(retry_enabled: true)
-
-# Combine multiple configuration options
-sdk = Hyperliquid.new(testnet: true, timeout: 60, retry_enabled: true)
-
-# Check which environment you're using
-sdk.testnet?  # => false
-sdk.base_url  # => "https://api.hyperliquid.xyz"
-```
-
-#### Retry Configuration
-
-By default, retry logic is **disabled** for predictable API behavior. When enabled, the SDK will automatically retry requests that fail due to:
-
-- Network connectivity issues (connection failed, timeouts)
-- Server errors (5xx status codes)
-- Rate limiting (429 status codes)
-
-**Retry Settings:**
-- Maximum retries: 2
-- Base interval: 0.5 seconds
-- Backoff factor: 2x (exponential backoff)
-- Randomness: ±50% to prevent thundering herd
-
-**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.
-
-### Error Handling
-
-The SDK provides comprehensive error handling:
-
-```ruby
-begin
-  orders = sdk.info.open_orders(user_address)
-rescue Hyperliquid::AuthenticationError
-  # Handle authentication issues
-rescue Hyperliquid::RateLimitError  
-  # Handle rate limiting
-rescue Hyperliquid::ServerError
-  # Handle server errors
-rescue Hyperliquid::NetworkError
-  # Handle network connectivity issues
-rescue Hyperliquid::Error => e
-  # Handle any other Hyperliquid API errors
-  puts "Error: #{e.message}"
-  puts "Status: #{e.status_code}" if e.status_code
-  puts "Response: #{e.response_body}" if e.response_body
-end
-```
-
-Available error classes:
-- `Hyperliquid::Error` - Base error class
-- `Hyperliquid::ClientError` - 4xx errors
-- `Hyperliquid::ServerError` - 5xx errors
-- `Hyperliquid::AuthenticationError` - 401 errors
-- `Hyperliquid::BadRequestError` - 400 errors
-- `Hyperliquid::NotFoundError` - 404 errors
-- `Hyperliquid::RateLimitError` - 429 errors
-- `Hyperliquid::NetworkError` - Connection issues
-- `Hyperliquid::TimeoutError` - Request timeouts
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-Run the example:
-```bash
-ruby example.rb
-```
-
-Run tests:
-```bash  
-rake spec
-```
-
-Run tests and linting together:
-```bash
-rake
-```
-
-Run linting:
-```bash
-rake rubocop
-```
+- [API Reference](docs/API.md) - Complete list of available methods
+- [Examples](docs/EXAMPLES.md) - Code examples for Info and Exchange APIs
+- [Configuration](docs/CONFIGURATION.md) - SDK configuration options
+- [Error Handling](docs/ERRORS.md) - Error types and handling
+- [Development](docs/DEVELOPMENT.md) - Contributing and running tests
 
 ## Roadmap
 
-The latest version implements read-only Info API support. Future versions will include:
+The SDK now supports both Info API (read) and Exchange API (trading). Future versions will include:
 
-- Trading API (place orders, cancel orders, etc.)
 - WebSocket support for real-time data
-- Advanced trading features
+- Additional exchange operations (leverage, margin adjustments, transfers)
+- Advanced trading features (TWAP, etc.)
 
 ## Contributing
 

data/docs/API.md

@@ -0,0 +1,95 @@
+# API Reference
+
+## Info Methods
+
+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
+- `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)
+- `user_rate_limit(user)` - Query user rate limits
+- `order_status(user, oid)` - Query order status by order id (oid)
+- `order_status_by_cloid(user, cloid)` - Query order status by client order id (cloid)
+- `l2_book(coin)` - L2 book snapshot (Perpetuals and Spot)
+- `candles_snapshot(coin, interval, start_time, end_time)` - Candle snapshot (Perpetuals and Spot)
+- `max_builder_fee(user, builder)` - Check builder fee approval
+- `historical_orders(user, start_time = nil, end_time = nil)` - Retrieve a user's historical orders
+- `user_twap_slice_fills(user, start_time = nil, end_time = nil)` - Retrieve a user's TWAP slice fills
+- `user_subaccounts(user)` - Retrieve a user's subaccounts
+- `vault_details(vault_address, user = nil)` - Retrieve details for a vault
+- `user_vault_equities(user)` - Retrieve a user's vault deposits
+- `user_role(user)` - Query a user's role
+- `portfolio(user)` - Query a user's portfolio
+- `referral(user)` - Query a user's referral information
+- `user_fees(user)` - Query a user's fees and fee schedule
+- `delegations(user)` - Query a user's staking delegations
+- `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
+
+### Perpetuals Methods
+
+- `perp_dexs()` - Retrieve all perpetual DEXs
+- `meta(dex: nil)` - Get asset metadata (optionally for a specific perp DEX)
+- `meta_and_asset_ctxs()` - Get extended asset metadata
+- `user_state(user, dex: nil)` - Retrieve user's perpetuals account summary (optionally for a specific perp DEX)
+- `predicted_fundings()` - Retrieve predicted funding rates across venues
+- `perps_at_open_interest_cap()` - Query perps at open interest caps
+- `perp_deploy_auction_status()` - Retrieve Perp Deploy Auction status
+- `active_asset_data(user, coin)` - Retrieve a user's active asset data for a coin
+- `perp_dex_limits(dex)` - Retrieve builder-deployed perp market limits for a DEX
+- `user_funding(user, start_time, end_time = nil)` - Retrieve a user's funding history (optional end time)
+- `user_non_funding_ledger_updates(user, start_time, end_time = nil)` - Retrieve a user's non-funding ledger updates. Non-funding ledger updates include deposits, transfers, and withdrawals. (optional end time)
+- `funding_history(coin, start_time, end_time = nil)` - Retrieve historical funding rates (optional end time)
+
+### Spot Methods
+
+- `spot_meta()` - Retrieve spot metadata (tokens and universe)
+- `spot_meta_and_asset_ctxs()` - Retrieve spot metadata and asset contexts
+- `spot_balances(user)` - Retrieve a user's spot token balances
+- `spot_deploy_state(user)` - Retrieve Spot Deploy Auction information
+- `spot_pair_deploy_auction_status()` - Retrieve Spot Pair Deploy Auction status
+- `token_details(token_id)` - Retrieve information about a token by tokenId
+
+## Exchange Methods (Trading)
+
+**Note:** Exchange methods require initializing the SDK with a `private_key`.
+
+- `order(coin:, is_buy:, size:, limit_px:, ...)` - Place a single limit order
+- `bulk_orders(orders:, grouping:, ...)` - Place multiple orders in a batch
+- `market_order(coin:, is_buy:, size:, slippage:, ...)` - Place a market order with slippage
+- `cancel(coin:, oid:, ...)` - Cancel an order by order ID
+- `cancel_by_cloid(coin:, cloid:, ...)` - Cancel an order by client order ID
+- `bulk_cancel(cancels:, ...)` - Cancel multiple orders by order ID
+- `bulk_cancel_by_cloid(cancels:, ...)` - Cancel multiple orders by client order ID
+- `address` - Get the wallet address associated with the private key
+
+All exchange methods support an optional `vault_address:` parameter for vault trading.
+
+### Order Types
+
+- `{ limit: { tif: 'Gtc' } }` - Good-til-canceled (default)
+- `{ limit: { tif: 'Ioc' } }` - Immediate-or-cancel
+- `{ limit: { tif: 'Alo' } }` - Add-liquidity-only (post-only)
+
+### Trigger Orders (Stop Loss / Take Profit)
+
+Trigger orders execute when a price threshold is reached:
+
+- `tpsl: 'sl'` - Stop loss
+- `tpsl: 'tp'` - Take profit
+- `is_market: true/false` - Execute as market or limit order when triggered
+
+### Client Order IDs (Cloid)
+
+Client order IDs must be 16 bytes in hex format (`0x` + 32 hex characters).
+
+Factory methods:
+- `Hyperliquid::Cloid.from_int(n)` - Create from integer (zero-padded)
+- `Hyperliquid::Cloid.from_str(s)` - Create from hex string
+- `Hyperliquid::Cloid.from_uuid(uuid)` - Create from UUID
+- `Hyperliquid::Cloid.random` - Generate random

data/docs/CONFIGURATION.md

@@ -0,0 +1,53 @@
+# Configuration
+
+## Basic Options
+
+```ruby
+# Custom timeout (default: 30 seconds)
+sdk = Hyperliquid.new(timeout: 60)
+
+# Enable retry logic for handling transient failures (default: disabled)
+sdk = Hyperliquid.new(retry_enabled: true)
+
+# Enable trading with a private key
+sdk = Hyperliquid.new(private_key: ENV['HYPERLIQUID_PRIVATE_KEY'])
+
+# Set global order expiration (orders expire after this timestamp)
+expires_at_ms = (Time.now.to_f * 1000).to_i + 30_000  # 30 seconds from now
+sdk = Hyperliquid.new(
+  private_key: ENV['HYPERLIQUID_PRIVATE_KEY'],
+  expires_after: expires_at_ms
+)
+
+# Combine multiple configuration options
+sdk = Hyperliquid.new(
+  testnet: true,
+  timeout: 60,
+  retry_enabled: true,
+  private_key: ENV['HYPERLIQUID_PRIVATE_KEY'],
+  expires_after: expires_at_ms
+)
+
+# Check which environment you're using
+sdk.testnet?  # => false
+sdk.base_url  # => "https://api.hyperliquid.xyz"
+
+# Check if exchange is available (private_key was provided)
+sdk.exchange  # => nil if no private_key, Hyperliquid::Exchange instance otherwise
+```
+
+## Retry Configuration
+
+By default, retry logic is **disabled** for predictable API behavior. When enabled, the SDK will automatically retry requests that fail due to:
+
+- Network connectivity issues (connection failed, timeouts)
+- Server errors (5xx status codes)
+- Rate limiting (429 status codes)
+
+**Retry Settings:**
+- Maximum retries: 2
+- Base interval: 0.5 seconds
+- Backoff factor: 2x (exponential backoff)
+- Randomness: ±50% to prevent thundering herd
+
+**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.

data/docs/DEVELOPMENT.md

@@ -0,0 +1,54 @@
+# Development
+
+## Setup
+
+After checking out the repo, run `bin/setup` to install dependencies.
+
+```bash
+bin/setup
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+rake spec
+
+# Run tests and linting together (default)
+rake
+```
+
+## Linting
+
+```bash
+rake rubocop
+```
+
+## Interactive Console
+
+```bash
+bin/console
+```
+
+This opens an interactive prompt with the SDK loaded for experimentation.
+
+## Example Script
+
+```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/ERRORS.md

@@ -0,0 +1,38 @@
+# Error Handling
+
+The SDK provides comprehensive error handling with typed exceptions.
+
+## Usage
+
+```ruby
+begin
+  orders = sdk.info.open_orders(user_address)
+rescue Hyperliquid::AuthenticationError
+  # Handle authentication issues
+rescue Hyperliquid::RateLimitError
+  # Handle rate limiting
+rescue Hyperliquid::ServerError
+  # Handle server errors
+rescue Hyperliquid::NetworkError
+  # Handle network connectivity issues
+rescue Hyperliquid::Error => e
+  # Handle any other Hyperliquid API errors
+  puts "Error: #{e.message}"
+  puts "Status: #{e.status_code}" if e.status_code
+  puts "Response: #{e.response_body}" if e.response_body
+end
+```
+
+## Error Classes
+
+| Error Class | Description |
+|-------------|-------------|
+| `Hyperliquid::Error` | Base error class |
+| `Hyperliquid::ClientError` | 4xx errors |
+| `Hyperliquid::ServerError` | 5xx errors |
+| `Hyperliquid::AuthenticationError` | 401 errors |
+| `Hyperliquid::BadRequestError` | 400 errors |
+| `Hyperliquid::NotFoundError` | 404 errors |
+| `Hyperliquid::RateLimitError` | 429 errors |
+| `Hyperliquid::NetworkError` | Connection issues |
+| `Hyperliquid::TimeoutError` | Request timeouts |