lighter-ts-sdk 1.0.4 → 1.0.6

package/README.md

@@ -1,487 +1,405 @@
-# Lighter Protocol TypeScript SDK (Unofficial)
-
-> **⚠️ Disclaimer**: This is an **unofficial** TypeScript SDK for Lighter Protocol, built by the community. It is not officially maintained by the Lighter Protocol team.
-
-TypeScript SDK for Lighter Protocol - Trade perpetuals with unmatched efficiency and fairness.
-
-## Requirements
-
-- Node.js 16+
-- TypeScript 4.5+
-
-## Installation & Usage
-
-### npm install
-
-```sh
-npm install lighter-ts-sdk
-```
-
-### yarn install
-
-```sh
-yarn add lighter-ts-sdk
-```
-
-Then import the package:
-
-```typescript
-import { SignerClient, ApiClient } from 'lighter-ts-sdk';
-```
-
-## Quick Start Examples
-
-### 1. Basic API Usage
-
-```typescript
-import { ApiClient, AccountApi } from 'lighter-ts-sdk';
-
-async function getAccountInfo() {
-  const client = new ApiClient({ host: 'https://mainnet.zklighter.elliot.ai' });
-  const accountApi = new AccountApi(client);
-  
-  const account = await accountApi.getAccount({ by: 'index', value: '1' });
-  console.log('Account:', account);
-}
-
-getAccountInfo().catch(console.error);
-```
-
-### 2. Create Market Order (Standalone WASM Signer)
-
-```typescript
-import { SignerClient } from 'lighter-ts-sdk';
-
-async function createMarketOrder() {
-  const client = new SignerClient({
-    url: 'https://mainnet.zklighter.elliot.ai',
-    privateKey: 'your-api-key-private-key',
-    accountIndex: 123,
-    apiKeyIndex: 0
-    // No wasmConfig needed - standalone signer auto-resolves paths
-  });
-
-  await client.initialize();
-  await (client as any).ensureWasmClient();
-
-  const [tx, txHash, err] = await client.createMarketOrder({
-    marketIndex: 0,
-    clientOrderIndex: Date.now(),
-    baseAmount: 10, // Base amount
-    avgExecutionPrice: 4500, // Price in cents
-    isAsk: true // Sell order
-  });
-
-  if (err) {
-    console.error('Order failed:', err);
-  } else {
-    console.log('Market order created:', { tx, txHash });
-  }
-}
-
-createMarketOrder().catch(console.error);
-```
-
-### 3. Create Limit Order
-
-```typescript
-import { SignerClient } from 'lighter-ts-sdk';
-
-async function createLimitOrder() {
-  const client = new SignerClient({
-    url: 'https://mainnet.zklighter.elliot.ai',
-    privateKey: 'your-api-key-private-key',
-    accountIndex: 123,
-    apiKeyIndex: 0
-  });
-
-  await client.initialize();
-  await (client as any).ensureWasmClient();
-
-  const [tx, txHash, err] = await client.createOrder({
-    marketIndex: 0,
-    clientOrderIndex: Date.now(),
-    baseAmount: 5, // Base amount
-    price: 4500, // Price in cents
-    isAsk: false, // Buy order
-    timeInForce: SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME
-  });
-
-  if (err) {
-    console.error('Order failed:', err);
-  } else {
-    console.log('Limit order created:', { tx, txHash });
-  }
-}
-
-createLimitOrder().catch(console.error);
-```
-
-### 4. Cancel Order
-
-```typescript
-import { SignerClient } from 'lighter-ts-sdk';
-
-async function cancelOrder() {
-  const client = new SignerClient({
-    url: 'https://mainnet.zklighter.elliot.ai',
-    privateKey: 'your-api-key-private-key',
-    accountIndex: 123,
-    apiKeyIndex: 0
-  });
-
-  await client.initialize();
-  await (client as any).ensureWasmClient();
-
-  const [tx, txHash, err] = await client.cancelOrder({
-    marketIndex: 0,
-    orderIndex: 12345
-  });
-
-  if (err) {
-    console.error('Cancel failed:', err);
-  } else {
-    console.log('Order cancelled:', { tx, txHash });
-  }
-}
-
-cancelOrder().catch(console.error);
-```
-
-### 5. Transfer USDC
-
-```typescript
-import { SignerClient } from 'lighter-ts-sdk';
-
-async function transferUSDC() {
-  const client = new SignerClient({
-    url: 'https://mainnet.zklighter.elliot.ai',
-    privateKey: 'your-api-key-private-key',
-    accountIndex: 123,
-    apiKeyIndex: 0
-  });
-
-  await client.initialize();
-  await (client as any).ensureWasmClient();
-
-  const [tx, txHash, err] = await client.transfer(
-    456, // toAccountIndex
-    1000000 // usdcAmount in cents ($10,000)
-  );
-
-  if (err) {
-    console.error('Transfer failed:', err);
-  } else {
-    console.log('USDC transferred:', { tx, txHash });
-  }
-}
-
-transferUSDC().catch(console.error);
-```
-
-### 6. Update Leverage
-
-```typescript
-import { SignerClient } from 'lighter-ts-sdk';
-
-async function updateLeverage() {
-  const client = new SignerClient({
-    url: 'https://mainnet.zklighter.elliot.ai',
-    privateKey: 'your-api-key-private-key',
-    accountIndex: 123,
-    apiKeyIndex: 0
-  });
-
-  await client.initialize();
-  await (client as any).ensureWasmClient();
-
-  const [tx, txHash, err] = await client.updateLeverage(
-    0, // marketIndex
-    SignerClient.CROSS_MARGIN_MODE, // marginMode
-    10 // initialMarginFraction (10x leverage)
-  );
-
-  if (err) {
-    console.error('Leverage update failed:', err);
-  } else {
-    console.log('Leverage updated:', { tx, txHash });
-  }
-}
-
-updateLeverage().catch(console.error);
-```
-
-### 7. Cancel All Orders
-
-```typescript
-import { SignerClient } from 'lighter-ts-sdk';
-
-async function cancelAllOrders() {
-  const client = new SignerClient({
-    url: 'https://mainnet.zklighter.elliot.ai',
-    privateKey: 'your-api-key-private-key',
-    accountIndex: 123,
-    apiKeyIndex: 0
-  });
-
-  await client.initialize();
-  await (client as any).ensureWasmClient();
-
-  const [tx, txHash, err] = await client.cancelAllOrders(
-    SignerClient.CANCEL_ALL_TIF_IMMEDIATE, // timeInForce
-    Date.now() // time
-  );
-
-  if (err) {
-    console.error('Cancel all failed:', err);
-  } else {
-    console.log('All orders cancelled:', { tx, txHash });
-  }
-}
-
-cancelAllOrders().catch(console.error);
-```
-
-### 8. Get Referral Points with Auth Token
-
-```typescript
-import { SignerClient, ApiClient } from 'lighter-ts-sdk';
-
-async function getReferralPoints() {
-  const signerClient = new SignerClient({
-    url: 'https://mainnet.zklighter.elliot.ai',
-    privateKey: 'your-api-key-private-key',
-    accountIndex: 123,
-    apiKeyIndex: 0
-  });
-
-  await signerClient.initialize();
-  await (signerClient as any).ensureWasmClient();
-
-  // Create an authentication token
-  const authToken = await signerClient.createAuthTokenWithExpiry(600); // 10 minutes
-  console.log('Auth Token:', authToken);
-
-  // Initialize API client
-  const apiClient = new ApiClient({ host: 'https://mainnet.zklighter.elliot.ai' });
-  
-  // Get referral points using auth token
-  const response = await apiClient.get('/api/v1/referral/points', {
-    account_index: 123,
-    auth: authToken
-  });
-  
-  console.log('Referral points:', response.data);
-}
-
-getReferralPoints().catch(console.error);
-```
-
-### 9. WebSocket Real-time Data
-
-```typescript
-import { WsClient } from 'lighter-ts-sdk';
-
-async function connectWebSocket() {
-  const wsClient = new WsClient({
-    url: 'wss://mainnet.zklighter.elliot.ai/ws',
-    onOpen: () => console.log('WebSocket connected'),
-    onMessage: (message) => console.log('Received:', message),
-    onClose: () => console.log('WebSocket closed'),
-    onError: (error) => console.error('WebSocket error:', error)
-  });
-
-  await wsClient.connect();
-  
-  // Subscribe to order book updates
-  wsClient.subscribe('orderbook', { market_id: 0 });
-  
-  // Subscribe to account updates
-  wsClient.subscribe('account', { account_index: 123 });
-}
-
-connectWebSocket().catch(console.error);
-```
-
-## Standalone WASM Signer
-
-The SDK now includes a **standalone WASM signer** that requires no Go installation:
-
-```typescript
-interface SignerConfig {
-  url: string;                    // API endpoint
-  privateKey: string;            // API key private key
-  accountIndex: number;          // Your account index
-  apiKeyIndex: number;           // API key index (usually 0)
-  // wasmConfig is optional - auto-resolves bundled wasm files
-}
-```
-
-### Key Features:
-- ✅ **No Go Required** - Users don't need Go installed
-- ✅ **Auto Path Resolution** - Automatically finds bundled wasm files
-- ✅ **Cross-Platform** - Works on Windows, Linux, macOS
-
-## Available Constants
-
-```typescript
-// Order Types
-SignerClient.ORDER_TYPE_LIMIT = 0
-SignerClient.ORDER_TYPE_MARKET = 1
-
-// Time in Force
-SignerClient.ORDER_TIME_IN_FORCE_IMMEDIATE_OR_CANCEL = 0  // Immediate or Cancel
-SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME = 1  // Good Till Time
-SignerClient.ORDER_TIME_IN_FORCE_FILL_OR_KILL = 2  // Fill or Kill
-
-// Margin Modes
-SignerClient.CROSS_MARGIN_MODE = 0
-SignerClient.ISOLATED_MARGIN_MODE = 1
-```
-
-## Documentation
-
-- [Getting Started Guide](docs/GettingStarted.md)
-- [API Reference](docs/API.md)
-- [SignerClient Documentation](docs/SignerClient.md)
-- [WebSocket Client](docs/WsClient.md)
-- [Type Definitions](docs/types/)
-
-## Examples
-
-Check the `examples/` directory for comprehensive usage examples:
-
-- `create_market_order.ts` - Basic market order creation
-- `create_cancel_order.ts` - Order management
-- `transfer_update_leverage.ts` - Account operations
-- `system_setup.ts` - API key management
-- `get_points.ts` - Referral points with auth tokens
-- `ws_*.ts` - WebSocket examples
-
-## SDK Status Report
-
-### ✅ **Currently Working & Released**
-
-#### **Core Trading Functionality**
-- ✅ **Market Orders** - Create market buy/sell orders with price limits
-- ✅ **Limit Orders** - Create limit orders with GTC/IOC/FOK time in force
-- ✅ **Order Cancellation** - Cancel individual orders by market and order index
-- ✅ **Cancel All Orders** - Cancel all orders for an account
-- ✅ **USDC Transfers** - Transfer USDC between accounts with memo support
-- ✅ **Leverage Updates** - Update leverage for cross/isolated margin modes
-
-#### **Account Management**
-- ✅ **API Key Generation** - Generate new API keys for trading
-- ✅ **API Key Management** - Change API keys and manage permissions
-- ✅ **Account Information** - Retrieve account details, positions, and balances
-- ✅ **Nonce Management** - Automatic nonce handling for transactions
-
-#### **Real-time Data**
-- ✅ **WebSocket Client** - Real-time order book, trades, and account updates
-- ✅ **Order Book Data** - Live market depth and price levels
-- ✅ **Trade Data** - Recent trades and execution information
-- ✅ **Account Updates** - Real-time position and balance updates
-
-#### **API Coverage**
-- ✅ **AccountApi** - Complete account management endpoints
-- ✅ **OrderApi** - Order book, trades, and exchange statistics
-- ✅ **TransactionApi** - Transaction history and nonce management
-- ✅ **BlockApi** - Block information and current height
-- ✅ **CandlestickApi** - Historical price data and funding rates
-
-#### **Technical Features**
-- ✅ **WASM Signer** - Go-compiled WebAssembly for cryptographic operations
-- ✅ **Cross-Platform** - Windows, Linux, macOS support
-- ✅ **TypeScript Support** - Complete type definitions and IntelliSense
-- ✅ **Error Handling** - Comprehensive error handling and validation
-- ✅ **Chain ID Support** - Correct mainnet chain ID (304) integration
-
-### 🔧 **Technical Implementation**
-
-#### **WASM Signer Capabilities**
-- ✅ **Transaction Signing** - All transaction types properly signed
-- ✅ **Signature Validation** - Server-side signature verification working
-- ✅ **Order Expiry Handling** - Correct OrderExpiry and ExpiredAt management
-- ✅ **Field Validation** - Proper field names and types (MarketIndex, USDCAmount, etc.)
-- ✅ **Memo Support** - 32-byte memo field for transfers
-- ✅ **Margin Mode Support** - Cross and isolated margin mode handling
-
-#### **API Integration**
-- ✅ **sendTxWithIndices** - Correct API endpoint for transaction submission
-- ✅ **Authentication** - API key-based authentication working
-- ✅ **Rate Limiting** - Proper request handling and retry logic
-- ✅ **Error Codes** - Complete error code handling (21120, 21505, etc.)
-
-### 📋 **What's Working in Production**
-
-1. **Complete Trading Flow**
-   - Generate API keys → Create orders → Monitor positions → Cancel orders
-   - All order types (market, limit) with proper time in force
-   - Real-time order book and trade data via WebSocket
-
-2. **Account Operations**
-   - USDC transfers between accounts
-   - Leverage updates for risk management
-   - API key rotation and management
-
-3. **Cross-Platform Compatibility**
-   - Node.js 16+ support across all platforms
-   - Browser compatibility with WebAssembly
-   - TypeScript 4.5+ support
-
-### 🚀 **Performance Optimizations (v1.0.1)**
-
-#### **Implemented Optimizations**
-- ⚡ **~200ms Performance Improvement** - Optimized WASM initialization and path resolution
-- ⚡ **Automatic Path Resolution** - Fixed WASM file path issues in NPM packages
-- ⚡ **Enhanced Nonce Caching** - Improved transaction throughput with smart nonce management
-- ⚡ **Connection Pooling** - Optimized HTTP client with keep-alive connections
-- ⚡ **Memory Pool Management** - Reduced memory allocation overhead
-- ⚡ **Request Batching** - Batch multiple operations for better performance
-- ⚡ **Advanced Caching** - Intelligent caching for frequently accessed data
-
-#### **Additional Order Types**
-- ✅ **Stop Loss Orders** - Market orders triggered by price levels
-- ✅ **Stop Loss Limit Orders** - Limit orders triggered by price levels
-- ✅ **Take Profit Orders** - Market orders for profit taking
-- ✅ **Take Profit Limit Orders** - Limit orders for profit taking
-- ✅ **TWAP Orders** - Time-weighted average price orders
-
-#### **Enhanced Examples**
-- 📚 **Performance Testing** - Comprehensive performance benchmarking
-- 📚 **Advanced Order Management** - Stop-loss and take-profit examples
-- 📚 **Batch Operations** - Multiple order creation examples
-- 📚 **WebSocket Optimization** - Real-time data streaming examples
-- 📚 **Error Handling** - Comprehensive error handling patterns
-
-### 🔄 **Next Release Features**
-
-#### **Planned Enhancements**
-- 🔄 **Additional Order Types** - More advanced order types
-- 🔄 **Enhanced Error Recovery** - Improved error handling and recovery
-- 🔄 **Additional WebSocket Subscriptions** - More real-time data streams
-- 🔄 **Enhanced Documentation** - More comprehensive guides
-- 🔄 **Unit Tests** - Complete test coverage
-- 🔄 **Integration Tests** - End-to-end testing
-- 🔄 **CI/CD Pipeline** - Automated testing and deployment
-
-### 🎯 **Current Version: 1.0.2 (Unofficial Release)**
-
-**⚠️ Community-Built SDK**
-- This is an **unofficial** TypeScript SDK built by the community
-- Not officially maintained by Lighter Protocol team
-- Built with full feature parity to the official Python SDK
-- Ready for production use with comprehensive testing
-
-**Ready for Production Use**
-- All core trading functionality implemented and tested
-- Complete API coverage matching Python SDK
-- Cross-platform compatibility verified
-- Comprehensive documentation and examples
-- TypeScript support with full type definitions
-
-**Installation**: `npm install lighter-ts-sdk`
-
-**Documentation**: Complete API reference and getting started guides included
-
-**Support**: Full feature parity with Python SDK, ready for production trading
+# Lighter Protocol TypeScript SDK (Unofficial)
+
+> **⚠️ Disclaimer**: This is an **unofficial** TypeScript SDK for Lighter Protocol, built by the community. It is not officially maintained by the Lighter Protocol team.
+
+A complete TypeScript SDK for Lighter Protocol - trade perpetual futures with built-in stop-loss and take-profit orders, position management, and comprehensive error handling.
+
+## 📦 Installation
+
+```bash
+npm install lighter-ts-sdk
+# or
+yarn add lighter-ts-sdk
+```
+
+## 🚀 What Does This SDK Do?
+
+The Lighter TypeScript SDK provides everything you need to:
+- **Trade perpetual futures** on Lighter Protocol
+- **Create orders** (Market, Limit, TWAP) with automatic SL/TP
+- **Manage positions** (open, close, update leverage)
+- **Transfer funds** between accounts
+- **Monitor transactions** with built-in status tracking
+- **Handle errors** automatically with retry logic
+
+## 🎯 Getting Started
+
+### Step 1: Set Up Your Environment
+
+Create a `.env` file in your project root:
+
+```bash
+# Required credentials
+API_PRIVATE_KEY=your_private_key_here
+ACCOUNT_INDEX=0
+API_KEY_INDEX=0
+BASE_URL=https://mainnet.zklighter.elliot.ai
+
+# Optional: for specific examples
+MARKET_ID=0
+SUB_ACCOUNT_INDEX=1
+DEPOSIT_AMOUNT=1
+```
+
+### Step 2: Install the SDK
+
+```bash
+npm install lighter-ts-sdk
+```
+
+### Step 3: Your First Trade
+
+```typescript
+import { SignerClient, OrderType } from 'lighter-ts-sdk';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+async function placeOrder() {
+  // Initialize the client
+  const signerClient = new SignerClient({
+    url: process.env.BASE_URL!,
+    privateKey: process.env.API_PRIVATE_KEY!,
+    accountIndex: parseInt(process.env.ACCOUNT_INDEX!),
+    apiKeyIndex: parseInt(process.env.API_KEY_INDEX!)
+  });
+
+  // Initialize WASM signer (required)
+  await signerClient.initialize();
+  await signerClient.ensureWasmClient();
+
+  // Create a market order with SL/TP
+  const result = await signerClient.createUnifiedOrder({
+    marketIndex: 0,              // ETH market
+    clientOrderIndex: Date.now(), // Unique ID
+    baseAmount: 10000,           // 0.01 ETH (scaled: 1 ETH = 1,000,000)
+    isAsk: false,                // BUY (true = SELL)
+    orderType: OrderType.MARKET,
+    
+    // Slip page protection
+    idealPrice: 400000,           // Ideal price ($4000)
+    maxSlippage: 0.001,           // Max 0.1% slippage
+    
+    // Automatic stop-loss and take-profit
+    stopLoss: {
+      triggerPrice: 380000,       // Stop loss at $3800
+      isLimit: false              // Market SL
+    },
+    takeProfit: {
+      triggerPrice: 420000,       // Take profit at $4200
+      isLimit: false              // Market TP
+    }
+  });
+
+  // Check if order succeeded
+  if (!result.success) {
+    console.error('❌ Order failed:', result.mainOrder.error);
+    return;
+  }
+
+  console.log('✅ Order created!');
+  console.log('Main order hash:', result.mainOrder.hash);
+  console.log('SL order hash:', result.stopLoss?.hash);
+  console.log('TP order hash:', result.takeProfit?.hash);
+
+  // Wait for transaction confirmation
+  await signerClient.waitForTransaction(result.mainOrder.hash, 30000);
+  
+  await signerClient.close();
+}
+
+placeOrder().catch(console.error);
+```
+
+## 📚 Core Concepts
+
+### Understanding Price Units
+
+Lighter uses fixed decimal scaling:
+- **ETH amounts**: 1 ETH = 1,000,000 units
+- **Prices**: $1 = 100 units
+
+```typescript
+// To buy 0.01 ETH at $4000:
+baseAmount: 10000        // 0.01 ETH (10,000 / 1,000,000)
+price: 400000           // $4000 (400,000 / 100)
+```
+
+### Order Types
+
+```typescript
+OrderType.MARKET    // Executes immediately at market price
+OrderType.LIMIT     // Executes at your specified price
+OrderType.TWAP      // Executes gradually over time
+```
+
+### Direction (isAsk)
+
+```typescript
+isAsk: false  // BUY - You're buying ETH
+isAsk: true   // SELL - You're selling ETH
+```
+
+### Stop-Loss and Take-Profit
+
+SL/TP orders are **automatically reduce-only** - they only close positions:
+
+```typescript
+stopLoss: {
+  triggerPrice: 380000,  // When price hits this, close position
+  isLimit: false         // false = market SL, true = limit SL
+},
+takeProfit: {
+  triggerPrice: 420000,  // When price hits this, take profit
+  isLimit: false         // false = market TP, true = limit TP
+}
+```
+
+**Important**: SL/TP orders require an existing position. For Market orders, this works immediately. For Limit orders, SL/TP are created in the same batch.
+
+**Note for TWAP orders**: TWAP orders execute over time, creating positions gradually. SL/TP cannot be created in the same batch as TWAP orders. You should create SL/TP orders separately after the TWAP has started creating positions.
+
+## 🔧 Common Operations
+
+### Create a Market Order
+
+```typescript
+const result = await signerClient.createUnifiedOrder({
+  marketIndex: 0,
+  clientOrderIndex: Date.now(),
+  baseAmount: 10000,        // Amount (0.01 ETH)
+  idealPrice: 400000,       // Your target price ($4000)
+  maxSlippage: 0.001,       // 0.1% max slippage
+  isAsk: false,             // BUY
+  orderType: OrderType.MARKET
+});
+
+if (!result.success) {
+  console.error('Failed:', result.mainOrder.error);
+  return;
+}
+```
+
+### Create a Limit Order
+
+```typescript
+const result = await signerClient.createUnifiedOrder({
+  marketIndex: 0,
+  clientOrderIndex: Date.now(),
+  baseAmount: 10000,        // Amount (0.01 ETH)
+  price: 400000,            // Limit price ($4000)
+  isAsk: false,             // BUY
+  orderType: OrderType.LIMIT,
+  orderExpiry: Date.now() + (60 * 60 * 1000) // Expires in 1 hour
+});
+
+// Wait for it to fill
+if (result.success) {
+  await signerClient.waitForTransaction(result.mainOrder.hash);
+}
+```
+
+### Cancel an Order
+
+```typescript
+const [tx, hash, error] = await signerClient.cancelOrder({
+  marketIndex: 0,
+  orderIndex: 12345  // Your order's index
+});
+
+if (error) {
+  console.error('Cancel failed:', error);
+  return;
+}
+
+await signerClient.waitForTransaction(hash);
+console.log('✅ Order cancelled');
+```
+
+### Close a Position
+
+```typescript
+const [tx, hash, error] = await signerClient.createMarketOrder({
+  marketIndex: 0,
+  clientOrderIndex: Date.now(),
+  baseAmount: 10000,        // Position size to close
+  avgExecutionPrice: 400000,
+  isAsk: false,              // Opposite of position
+  reduceOnly: true          // IMPORTANT: Only closes, doesn't open new
+});
+
+if (error) {
+  console.error('Close failed:', error);
+  return;
+}
+
+await signerClient.waitForTransaction(hash);
+console.log('✅ Position closed');
+```
+
+### Check Order Status
+
+```typescript
+const status = await signerClient.getTransaction(txHash);
+console.log('Status:', status.status); // 0=pending, 1=queued, 2=committed, 3=executed
+```
+
+## 🛠️ API Reference
+
+### SignerClient Methods
+
+#### Order Management
+```typescript
+// Create a unified order (main order + SL/TP)
+createUnifiedOrder(params) -> Promise<UnifiedOrderResult>
+
+// Create a single order
+createOrder(params) -> Promise<[txInfo, txHash, error]>
+
+// Cancel a specific order
+cancelOrder(params) -> Promise<[txInfo, txHash, error]>
+
+// Cancel all orders
+cancelAllOrders(timeInForce, time) -> Promise<[txInfo, txHash, error]>
+```
+
+#### Position Management
+```typescript
+// Close specific position
+createMarketOrder({ reduceOnly: true }) -> Promise<[txInfo, txHash, error]>
+
+// Close all positions
+closeAllPositions() -> Promise<[txs[], responses[], errors[]]>
+```
+
+#### Transaction Monitoring
+```typescript
+// Get transaction details
+getTransaction(txHash) -> Promise<Transaction>
+
+// Wait for transaction (with timeout)
+waitForTransaction(txHash, maxWaitTime, pollInterval) -> Promise<Transaction>
+```
+
+### Order Parameters
+
+```typescript
+interface UnifiedOrderParams {
+  marketIndex: number;           // Market ID (0 = ETH)
+  clientOrderIndex: number;       // Unique ID (use Date.now())
+  baseAmount: number;             // Amount in units (1 ETH = 1,000,000)
+  isAsk: boolean;                 // true = SELL, false = BUY
+  orderType: OrderType;           // MARKET, LIMIT, or TWAP
+  
+  // For market orders
+  idealPrice?: number;            // Target price
+  maxSlippage?: number;           // Max slippage (e.g., 0.001 = 0.1%)
+  
+  // For limit orders
+  price?: number;                 // Limit price
+  
+  // Optional SL/TP (automatically reduce-only)
+  stopLoss?: {
+    triggerPrice: number;
+    isLimit?: boolean;
+  };
+  takeProfit?: {
+    triggerPrice: number;
+    isLimit?: boolean;
+  };
+  
+  // Optional
+  orderExpiry?: number;           // Expiry timestamp (milliseconds)
+}
+```
+
+## 💡 Tips for Beginners
+
+### 1. Always Use Environment Variables
+
+```typescript
+// ❌ DON'T hardcode credentials
+const privateKey = '0xabc123...';
+
+// ✅ DO use environment variables
+const privateKey = process.env.API_PRIVATE_KEY;
+```
+
+### 2. Handle Errors Properly
+
+```typescript
+try {
+  const result = await signerClient.createUnifiedOrder(params);
+  
+  if (!result.success) {
+    console.error('Order failed:', result.mainOrder.error);
+    return; // Exit early
+  }
+  
+  // Success path
+  console.log('Order created:', result.mainOrder.hash);
+} catch (error) {
+  console.error('Unexpected error:', error);
+}
+```
+
+### 3. Check Transaction Status
+
+```typescript
+// Wait for transaction to be confirmed
+try {
+  await signerClient.waitForTransaction(txHash, 30000, 2000);
+  console.log('✅ Transaction confirmed');
+} catch (error) {
+  console.error('❌ Transaction failed:', error.message);
+}
+```
+
+### 4. Close Resources
+
+```typescript
+try {
+  // ... use signerClient
+} finally {
+  await signerClient.close(); // Always close when done
+}
+```
+
+## 📖 Examples
+
+The `examples/` directory contains working examples for every feature:
+
+```bash
+# Run examples
+npx ts-node examples/create_market_order.ts   # Market order with SL/TP
+npx ts-node examples/create_limit_order.ts     # Limit order with SL/TP
+npx ts-node examples/cancel_order.ts           # Cancel orders
+npx ts-node examples/close_position.ts         # Close positions
+npx ts-node examples/deposit_to_subaccount.ts  # Fund transfers
+```
+
+## 🎓 Learning Path
+
+1. **Start Here**: `examples/create_market_order.ts` - Simplest order creation
+2. **Next**: `examples/create_limit_order.ts` - Learn about limit orders
+3. **Then**: `examples/cancel_order.ts` - Learn about order management
+4. **Advanced**: `examples/send_tx_batch.ts` - Batch transactions
+
+## 🔒 Security
+
+- ✅ Never commit `.env` files
+- ✅ Use environment variables for all credentials
+- ✅ Test with small amounts first
+- ✅ Monitor all transactions
+- ✅ Use proper error handling
+
+## 📞 Getting Help
+
+- Check the examples in `examples/` directory
+- Read error messages carefully - they're informative
+- Ensure environment variables are set correctly
+- Start with `examples/create_market_order.ts`
+
+## License
+
+MIT License - see LICENSE file for details.