@gala-chain/launchpad-sdk 5.0.4-beta.6 → 5.0.4-beta.60

package/README.md.bak

@@ -0,0 +1,3174 @@
+# Gala Launchpad SDK
+
+**Version: 5.0.3 (Latest)**
+
+A comprehensive TypeScript SDK for the Gala Launchpad Backend API, providing type-safe authentication, trading, and real-time features for DeFi applications.
+
+> **⚠️ BREAKING CHANGE (v3.33.0+)**: Token format parsing now **ONLY accepts delimited formats** (`GALA|Unit|none|none` or `GALA$Unit$none$none`). Plain token strings (`'GALA'`, `'GUSDC'`) are **permanently rejected** for security. See [Migration Guide](#token-format-migration-v330) below.
+
+[![npm version](https://badge.fury.io/js/@gala-chain%2Flaunchpad-sdk.svg)](https://badge.fury.io/js/@gala-chain%2Flaunchpad-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
+[![Documentation Coverage](https://img.shields.io/badge/Documentation%20Coverage-100%25-success)](./docs/API-REFERENCE.md)
+
+## Features
+
+**Clean Result Types with No Wrapper Overhead:**
+
+- **Direct Result Access**: Get clean, typed results without wrapper objects
+- **Semantic Type Conversion**: Dates as Date objects, numbers as numbers, strings for precision
+- **Comprehensive Type Safety**: Full TypeScript support with precise result interfaces
+- **Zero Wrapper Overhead**: No more `result.data.success` - direct property access
+- **Options Object Pattern**: All methods with 2+ parameters use clean options objects
+- **Auto-Pagination**: Automatic multi-page fetching with configurable concurrency
+
+### Developer Experience
+
+```typescript
+import { createLaunchpadSDK, createWallet } from '@gala-chain/launchpad-sdk';
+
+// Auto-detect wallet format and create SDK
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic' // Auto-detects format!
+});
+
+// Direct result access - no wrapper objects!
+const pools = await sdk.fetchPools({ type: 'recent' });
+console.log(`Found ${pools.total} pools`); // Direct property access
+console.log(`Page ${pools.page} of ${pools.totalPages}`); // Clean pagination
+console.log(`Has next: ${pools.hasNext}`); // Boolean convenience properties
+
+// Clean typed results everywhere
+const balance = await sdk.fetchGalaBalance();
+console.log(`Balance: ${balance.balance} GALA`); // Direct balance access
+console.log(`Last updated: ${balance.lastUpdated.toISOString()}`); // Date object
+```
+
+## Clean API Architecture
+
+**Direct result access with no wrapper overhead:**
+
+```typescript
+// Get pools with direct property access
+const pools = await sdk.fetchPools({ type: 'recent' });
+console.log(pools.items); // Direct access to pool array
+console.log(pools.meta.total); // Immediate pagination info
+console.log(pools.meta.page < pools.meta.totalPages); // Has more pages
+```
+
+## Key Features
+
+- **Type-Safe API Client**: Full TypeScript support with comprehensive type definitions
+- **Clean Result Types**: Direct property access without wrapper objects
+- **Options Object Pattern**: All multi-parameter methods use clean options objects
+- **Auto-Pagination**: Automatic multi-page fetching for large result sets
+- **Signature Authentication**: Ethereum wallet-based authentication with automatic signature generation
+- **Helper Functions**: Auto-detecting wallet creation and SDK factory functions
+- **Pool Management**: Create, fetch, and check token pools on the launchpad
+- **Token Trading**: Buy and sell tokens with slippage protection via GalaChain
+- **DEX Pool Discovery**: Discover and explore GalaSwap liquidity pools with filtering, sorting, and pagination
+- **DEX Trading**: Real-time token swaps on GalaSwap DEX with quote generation and slippage protection
+- **Liquidity Management**: Manage liquidity positions on GalaSwap (add, remove, collect fees) with filtering and organization utilities
+- **Token Transfers**: Transfer GALA and launchpad tokens between wallets with EIP-712 signatures
+- **User Operations**: Portfolio management, token balances, and account management
+- **Comment System**: Post and retrieve comments on token pools
+- **Price History**: Fetch historical price data for DEX tokens with pagination (Node.js only)
+- **Cross-Chain Bridging**: Transfer tokens between GalaChain, Ethereum, and Solana with fee estimation
+- **External Wallet Balances**: Query Ethereum and Solana wallet balances (single-token or full portfolio)
+- **Live Streaming**: Start/stop streams, manage recordings and simulcast targets for token pools (v5.1.0+)
+- **Stream Chat**: Real-time chat messaging via REST and WebSocket with admin controls (v5.1.0+)
+- **Global Feed**: Unified real-time event stream for token updates and site configuration changes (v7.0.0+)
+- **Overseer System**: Global platform oversight with CCTV dashboard, invite management, and platform summary (v5.9.0+)
+- **Moderator System**: Token-scoped moderation with magic link invites (v5.7.0+)
+- **Content Flags**: Report and manage flagged content with two-tier review system (v5.8.0+)
+- **User Bans**: Per-token and global user banning with active user tracking (v5.5.0+)
+- **Comprehensive Validation**: Input validation and error handling for all operations
+- **Multi-Environment Support**: Production, staging, and custom backend URLs
+
+## Installation
+
+### NPM
+
+```bash
+npm install @gala-chain/launchpad-sdk
+```
+
+### Yarn
+
+```bash
+yarn add @gala-chain/launchpad-sdk
+```
+
+### Peer Dependencies
+
+This SDK requires the following peer dependencies to be installed:
+
+```bash
+npm install ethers@^6.15.0 @gala-chain/api@^2.4.3 @gala-chain/connect@^2.4.3 socket.io-client@^4.8.1 axios@^1.12.2 bignumber.js@^9.1.2 zod@^3.25.76
+```
+
+**Or with yarn:**
+
+```bash
+yarn add ethers@^6.15.0 @gala-chain/api@^2.4.3 @gala-chain/connect@^2.4.3 socket.io-client@^4.8.1 axios@^1.12.2 bignumber.js@^9.1.2 zod@^3.25.76
+```
+
+**All peer dependencies are required** - this includes `socket.io-client` which is needed for transaction verification via WebSocket.
+
+## Module Formats
+
+The SDK is distributed in **three module formats** to support both modern and legacy projects:
+
+### ESM (ES Modules) - Primary Format
+
+**For modern bundlers and Node.js 16+:**
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+```
+
+**When to use:**
+- ✅ React, Vue, Svelte, Angular applications
+- ✅ Next.js, Nuxt, SvelteKit
+- ✅ Vite, Webpack, esbuild bundlers
+- ✅ Modern Node.js projects with `"type": "module"`
+
+### CommonJS - Legacy Support
+
+**For CommonJS projects and older Node.js environments:**
+
+```javascript
+const { createLaunchpadSDK } = require('@gala-chain/launchpad-sdk');
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+```
+
+**When to use:**
+- ✅ Legacy Node.js projects with CommonJS modules
+- ✅ Older tooling that doesn't support ESM
+- ✅ Express.js, Nest.js (CommonJS mode)
+- ✅ Projects without build tools
+
+### UMD (Universal Module Definition) - Browser Legacy
+
+**For browser globals and legacy environments:**
+
+```html
+<script src="node_modules/@gala-chain/launchpad-sdk/dist/index.js"></script>
+<script>
+  const sdk = window.GalaLaunchpadSDK.createLaunchpadSDK({
+    wallet: 'your-private-key-or-mnemonic'
+  });
+</script>
+```
+
+**When to use:**
+- ✅ Direct browser `<script>` tags
+- ✅ Older browser environments
+- ✅ CDN delivery
+
+### Module Resolution
+
+Node.js automatically selects the correct module format based on your project:
+
+| Project Type | Method | Format Used | File |
+|---|---|---|---|
+| ESM Module | `import` | ESM | `dist/index.esm.js` |
+| CommonJS | `require()` | CommonJS | `dist/index.cjs.js` |
+| Legacy Tools | Direct Include | UMD | `dist/index.js` |
+
+**No configuration needed** - Node.js and bundlers automatically select the optimal format via the package exports field!
+
+## Wallet Configuration Modes
+
+The SDK supports **two operational modes** with optional wallet configuration:
+
+### Full-Access Mode (with Wallet)
+
+**For executing trades, creating tokens, and managing funds:**
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Initialize with wallet - enables signing operations
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+
+// Now you can execute trades
+const result = await sdk.buy({
+  tokenName: 'anime',
+  amount: '100',
+  type: 'native',
+  slippageToleranceFactor: 0.01
+});
+```
+
+**Capabilities:**
+- ✅ Execute token trades (buy/sell)
+- ✅ Create new tokens
+- ✅ Transfer GALA and tokens
+- ✅ Update user profile
+- ✅ Post comments
+- ✅ All read operations (fetch pools, prices, etc.)
+
+### Read-Only Mode (without Wallet)
+
+**For querying data without wallet authentication:**
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Initialize without wallet - read-only operations only
+const sdk = createLaunchpadSDK({});
+
+// Query operations work fine
+const pools = await sdk.fetchPools({ type: 'recent' });
+const prices = await sdk.fetchTokenSpotPrice('anime');
+const balance = await sdk.fetchGalaBalance();
+```
+
+**Capabilities:**
+- ✅ Fetch token pools and details
+- ✅ Get real-time prices and price history
+- ✅ Check balances and portfolio
+- ✅ Browse comments and token information
+- ✅ Explore token metadata and distributions
+- ❌ Cannot: Execute trades, create tokens, transfer funds (require signatures)
+
+### Dynamic Wallet Configuration
+
+**Upgrade from read-only to full-access mode at runtime:**
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Start in read-only mode
+const sdk = createLaunchpadSDK({});
+console.log(sdk.hasWallet()); // false
+
+// Later, upgrade to full-access
+sdk.setWallet('your-private-key-or-mnemonic');
+console.log(sdk.hasWallet()); // true
+
+// Now signing operations work
+const result = await sdk.buy({
+  tokenName: 'anime',
+  amount: '100',
+  type: 'native',
+  slippageToleranceFactor: 0.01
+});
+```
+
+**Wallet Management Methods:**
+- `hasWallet()` - Check if wallet is configured
+- `getWallet()` - Retrieve current wallet instance
+- `setWallet(wallet)` - Configure wallet for signing operations
+- `validateWallet()` - Type guard that throws if wallet not present
+
+### Method Categorization: Wallet Requirements
+
+**Methods that DON'T require a wallet (Read-Only Operations):**
+
+| Category | Methods | Notes |
+|----------|---------|-------|
+| **Pool Queries** | `fetchPools`, `fetchAllPools`, `fetchPoolDetails`, `fetchPoolDetailsForCalculation`, `isTokenGraduated`, `isTokenNameAvailable`, `isTokenSymbolAvailable` | Query pool data and token availability |
+| **Token Data** | `fetchTokenDetails`, `fetchTokenDistribution`, `fetchTokenBadges` | Get token metadata and holder information |
+| **Pricing** | `fetchTokenSpotPrice`, `fetchGalaSpotPrice`, `fetchLaunchpadTokenSpotPrice`, `fetchVolumeData` | Get current prices and OHLCV data |
+| **Price History** | `fetchPriceHistory`, `fetchAllPriceHistory` | Get historical price snapshots (Node.js only) |
+| **Balance Info** | `fetchGalaBalance`, `fetchTokenBalance` | Check GALA and token balances (your own only) |
+| **Portfolio** | `fetchTokensHeld`, `fetchTokensCreated` | View your token portfolio and created tokens |
+| **Profile** | `fetchProfile` | Retrieve user profile information |
+| **Comments** | `fetchComments` | View comments on token pools |
+| **Trade History** | `fetchTrades` | View your past trades |
+| **Utilities** | `getAddress`, `getEthereumAddress`, `getConfig`, `getVersion`, `getUrlByTokenName`, `getCacheInfo`, `clearCache`, `cleanup`, `cleanupAll` | Utility and configuration methods |
+| **Reference** | `resolveTokenClassKey`, `resolveVaultAddress`, `calculateInitialBuyAmount` | Resolve IDs and get reference data |
+
+**Methods that REQUIRE a wallet (Signing Operations):**
+
+| Category | Methods | Error When Missing |
+|----------|---------|-------------------|
+| **Trading** | `buy`, `sell`, `calculateBuyAmount`, `calculateSellAmount`, `calculateBuyAmountLocal`, `calculateBuyAmountExternal`, `calculateSellAmountLocal`, `calculateSellAmountExternal` | `ValidationError: Wallet is required` |
+| **Token Creation** | `launchToken`, `uploadTokenImage`, `uploadProfileImage`, `calculateBuyAmountForGraduation`, `graduateToken` | `ValidationError: Wallet is required` |
+| **Account Management** | `updateProfile`, `postComment` | `ValidationError: Wallet is required` |
+| **Transfers** | `transferGala`, `transferToken` | `ValidationError: Wallet is required` |
+| **Admin** | `getBundlerTransactionResult` | May require wallet for certain operations |
+
+**Key Points:**
+- ✅ All read operations work in **read-only mode** without a wallet
+- ✅ Wallet can be added later via `setWallet()` to enable signing operations
+- ✅ Missing wallet throws `ValidationError` with code `WALLET_REQUIRED`
+- ⚠️ Only methods that sign transactions require a wallet
+
+## Environment Configuration
+
+The SDK supports multiple environments (STAGE and PROD). All demo scripts and examples use a **centralized environment configuration pattern** via `.env` file.
+
+### Quick Setup
+
+Create/edit `.env` in the repository root:
+
+```bash
+# .env
+ENVIRONMENT=STAGE          # Switch between STAGE and PROD
+WALLET_PRIVATE_KEY=0x...   # Your wallet private key (optional)
+```
+
+All demo scripts automatically read from this `.env` file:
+
+```bash
+npm run demo:read-only    # Uses ENVIRONMENT from .env
+npm run demo:dex          # Uses ENVIRONMENT from .env
+npm run demo:liquidity    # Uses ENVIRONMENT from .env
+```
+
+### Environment Values
+
+| Value | Accepts | Use Case |
+|-------|---------|----------|
+| `STAGE` | `STAGE`, `STAGING` | Development/staging |
+| `PROD` | `PROD`, `PRODUCTION` | Production |
+| Default | (if not set) | Defaults to `STAGE` with warning |
+
+### SDK Initialization
+
+When using demo scripts or examples, the environment is automatically loaded:
+
+```typescript
+import { getEnvironment } from './examples/utils/get-environment';
+
+const environment = getEnvironment();  // Reads from .env
+const sdk = new LaunchpadSDK({
+  env: environment,
+  wallet: undefined  // Optional
+});
+```
+
+### Validation
+
+Prevent hardcoded environment values:
+
+```bash
+npm run validate:env  # Validates no hardcoded 'STAGE' or 'PROD'
+```
+
+### Full Documentation
+
+See [docs/ENVIRONMENT_CONFIGURATION.md](./docs/ENVIRONMENT_CONFIGURATION.md) for:
+- Architecture and implementation details
+- Pattern for adding new scripts
+- Troubleshooting guide
+- Migration guide for existing scripts
+
+## Token Format Migration (v3.33.0)
+
+### Breaking Change: Strict Token Format Enforcement
+
+**v3.33.0 removes support for plain token strings** and requires all tokens to use **delimited format**.
+
+#### Old Behavior (v3.32.x and below) - DEPRECATED
+
+Plain token strings were accepted:
+```typescript
+// ❌ NO LONGER WORKS (v3.33.0+)
+await sdk.addSwapLiquidityByPrice({
+  token0: 'GALA',      // Plain string
+  token1: 'GUSDC',     // Plain string
+  fee: 3000,
+  minPrice: '0.95',
+  maxPrice: '1.05',
+  amount0Desired: '100',
+  amount1Desired: '100'
+});
+```
+
+#### New Behavior (v3.33.0+) - REQUIRED
+
+All tokens must use **pipe-delimited** (`|`) or **dollar-delimited** (`$`) format:
+
+```typescript
+// ✅ REQUIRED FORMAT (v3.33.0+)
+await sdk.addSwapLiquidityByPrice({
+  token0: 'GALA|Unit|none|none',      // Delimited format
+  token1: 'GUSDC|Unit|none|none',     // Delimited format
+  fee: 3000,
+  minPrice: '0.95',
+  maxPrice: '1.05',
+  amount0Desired: '100',
+  amount1Desired: '100'
+});
+```
+
+#### Format Options
+
+**Pipe-Delimited (Recommended):**
+```typescript
+'GALA|Unit|none|none'
+'GUSDC|Unit|none|none'
+'MYTOKEN|Unit|none|none'
+```
+
+**Dollar-Delimited (Alternative):**
+```typescript
+'GALA$Unit$none$none'
+'GUSDC$Unit$none$none'
+'MYTOKEN$Unit$none$none'
+```
+
+#### Migration Checklist
+
+- [ ] Search codebase for plain token strings: `'GALA'`, `'GUSDC'`, etc.
+- [ ] Replace with delimited format: `'GALA|Unit|none|none'`, `'GUSDC|Unit|none|none'`
+- [ ] Update all SDK method calls that pass token parameters
+- [ ] Test thoroughly - TypeScript strict mode will catch most issues
+- [ ] Update internal token handling code
+
+#### Affected Methods
+
+The following methods now require delimited token format:
+- `getSwapQuoteExactInput(token0, token1, amount)`
+- `getSwapQuoteExactOutput(token0, token1, amount)`
+- `executeSwap(token0, token1, ...)`
+- `addSwapLiquidityByPrice({token0, token1, ...})`
+- `addSwapLiquidityByTicks({token0, token1, ...})`
+- `removeSwapLiquidity({token0, token1, ...})`
+- `getSwapPoolInfo(token0, token1)`
+
+#### Security Rationale
+
+This breaking change enforces **strict token format validation** to:
+- ✅ **Prevent injection attacks** via token string manipulation
+- ✅ **Ensure deterministic parsing** with no ambiguous fallbacks
+- ✅ **Eliminate security gaps** from loose string handling
+- ✅ **Force explicit token specification** with full TokenClassKey structure
+
+Plain string support created a dangerous "escape hatch" where ambiguous token identifiers could be accepted. v3.33.0 eliminates this by requiring all tokens be properly delimited.
+
+## Upgrading to v4.0.0
+
+### Breaking Changes: Removed Deprecated Methods
+
+**v4.0.0 removes one deprecated method** that was superseded in v3.22.7. This is a clean removal with **minimal migration effort** - most users will not be affected.
+
+#### Removed Method: `fetchLaunchpadTokenSpotPrice()`
+
+This method was deprecated in v3.22.7 in favor of the more flexible `fetchTokenPrice()` method.
+
+**Old Code (v3.35.x and below) - NO LONGER WORKS:**
+```typescript
+// ❌ REMOVED in v4.0.0
+const price = await sdk.fetchLaunchpadTokenSpotPrice('anime');
+console.log(`Price: ${price} USD`);
+```
+
+**New Code (v4.0.0+) - REQUIRED:**
+```typescript
+// ✅ REQUIRED - Works for both launchpad and DEX tokens
+const price = await sdk.fetchTokenPrice('anime');
+console.log(`Price: ${price} USD`);
+```
+
+#### Why This Change?
+
+The new `fetchTokenPrice()` method:
+- ✅ **Unified pricing** - Works for both launchpad tokens and DEX-graduated tokens
+- ✅ **Automatic routing** - Detects token type and fetches from correct backend
+- ✅ **Better performance** - Single method instead of specialized variants
+- ✅ **Cleaner API** - Less method duplication in SDK
+
+#### Migration Checklist
+
+- [ ] Search codebase for `fetchLaunchpadTokenSpotPrice(`
+- [ ] Replace all occurrences with `fetchTokenPrice(`
+- [ ] Test with both launchpad tokens (e.g., `'anime'`) and DEX tokens
+- [ ] Verify price results haven't changed (same calculation logic)
+
+#### Impact Assessment
+
+**Affected Users:**
+- ⚠️ **Only if you explicitly called** `fetchLaunchpadTokenSpotPrice()`
+- ✅ **Not affected if you** used `fetchTokenPrice()` or `fetchTokenSpotPrice()` methods
+- ✅ **Not affected if you** never queried token prices
+
+**Migration Effort:**
+- ⏱️ **5 minutes** - Simple find/replace across codebase
+- ⚙️ **Zero logic changes** - Functionality remains identical
+- 🎯 **Low risk** - Price calculation algorithm unchanged
+
+### New Features: Service Clients Documentation
+
+v4.0.0 adds internal service client documentation for advanced users who need direct access to underlying blockchain services.
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key'
+});
+
+// Advanced: Direct access to DEX Backend API
+// Use case: Custom swap parameters or debugging
+const quote = await sdk.dexBackendClient.querySwapQuote({
+  orderedTokens: [...],
+  zeroForOne: false,
+  inputAmount: '10',
+  // ... additional parameters
+});
+
+// Advanced: Direct access to GalaChain Gateway
+// Use case: Custom transaction building
+const result = await sdk.galaChainGatewayClient.callContract({
+  address: 'contract-address',
+  method: 'transfer',
+  // ... parameters
+});
+```
+
+**⚠️ Important:** Service clients are internal implementation details. For standard operations, always use public SDK methods:
+- ✅ Use `sdk.buy()` instead of `sdk.galaChainGatewayClient`
+- ✅ Use `sdk.executeSwap()` instead of `sdk.dexBackendClient`
+- ✅ These public methods provide better error handling and validation
+
+For detailed service client documentation, see [docs/API-REFERENCE.md#service-clients](./docs/API-REFERENCE.md#service-clients).
+
+### Migration Summary
+
+**For Most Users:** Nothing to do! v4.0.0 is backward compatible except for the removal of `fetchLaunchpadTokenSpotPrice()`.
+
+**If You Used `fetchLaunchpadTokenSpotPrice()`:** Replace with `fetchTokenPrice()` - identical functionality, better flexibility.
+
+**If You Need Service Client Access:** They're now documented and available for advanced use cases, but use public SDK methods when possible.
+
+## DEX Pool Discovery & Analysis
+
+### Overview
+
+The SDK provides complete DEX liquidity pool discovery for GalaSwap with filtering, sorting, and pagination. Perfect for finding trading pairs, analyzing pool metrics, and discovering investment opportunities.
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({});
+
+// Discover DEX pools with filtering
+const pools = await sdk.fetchDexPools({
+  search: 'GALA',           // Filter by token symbol
+  sortBy: 'tvl',            // Sort options: tvl, volume30d, volume1d
+  sortOrder: 'desc',        // asc or desc
+  page: 1,                  // Pagination (default: 1)
+  limit: 10                 // Results per page (default: 10, max: 20)
+});
+
+console.log(`Found ${pools.meta.total} total pools`);
+console.log(`Showing ${pools.items.length} pools on page ${pools.meta.page}`);
+
+// Fetch ALL pools with automatic pagination
+const allPools = await sdk.fetchAllDexPools({
+  search: 'GUSDC',
+  sortBy: 'volume30d',
+  sortOrder: 'asc'
+});
+
+console.log(`Retrieved ${allPools.items.length} total pools`);
+```
+
+### Pool Data Structure
+
+Each DEX pool includes comprehensive trading metrics:
+
+```typescript
+interface DexPoolData {
+  poolPair: string;              // e.g., "GALA/GUSDC"
+  poolHash: string;              // Unique pool identifier
+  token0: string;                // Token A symbol
+  token1: string;                // Token B symbol
+  token0Price: string;           // Token A USD price
+  token1Price: string;           // Token B USD price
+  fee: string;                   // Fee tier (0.05%, 0.30%, 1.00%)
+  fee24h: number;                // 24h accumulated fees
+  tvl: number;                   // Total Value Locked (USD)
+  token0Tvl: number;             // TVL in Token A
+  token1Tvl: number;             // TVL in Token B
+  token0TvlUsd: number;          // Token A TVL in USD
+  token1TvlUsd: number;          // Token B TVL in USD
+  volume1d: number;              // 24h trading volume
+  volume30d: number;             // 30d trading volume
+  apr1d: number;                 // 24h APR for liquidity providers
+  dayPerTvl: number;             // Fee ratio (volume/TVL)
+}
+```
+
+### Common Use Cases
+
+**Find high-volume pools:**
+```typescript
+const highVolumePoolsAsc = await sdk.fetchAllDexPools({
+  sortBy: 'volume1d',
+  sortOrder: 'desc'
+});
+
+const topPool = highVolumePoolsAsc.items[0];
+console.log(`Highest volume pair: ${topPool.poolPair}`);
+console.log(`24h Volume: $${topPool.volume1d}`);
+console.log(`APR: ${topPool.apr1d.toFixed(2)}%`);
+```
+
+**Discover GALA trading pairs:**
+```typescript
+const galaPools = await sdk.fetchDexPools({
+  search: 'GALA',
+  sortBy: 'tvl',
+  limit: 20
+});
+
+galaPools.items.forEach(pool => {
+  console.log(`${pool.poolPair}: $${pool.tvl.toLocaleString()} TVL`);
+});
+```
+
+**Analyze liquidity provider opportunities:**
+```typescript
+const liquidityOpportunities = await sdk.fetchAllDexPools({
+  sortBy: 'apr1d',
+  sortOrder: 'desc'
+});
+
+// Find pools with highest APR
+const bestAprPools = liquidityOpportunities.items.slice(0, 10);
+bestAprPools.forEach(pool => {
+  console.log(`${pool.poolPair}: ${pool.apr1d.toFixed(2)}% APR`);
+});
+```
+
+### Sorting Options
+
+| Sort Value | Description | Best For |
+|-----------|-------------|----------|
+| `tvl` (default) | Total Value Locked | Finding main liquidity pools |
+| `volume1d` | 24-hour trading volume | High-activity pairs |
+| `volume30d` | 30-day trading volume | Trend analysis |
+
+### Pagination
+
+The SDK enforces a **maximum of 20 items per page** (backend limit). Use `fetchAllDexPools()` for complete enumeration:
+
+```typescript
+// Page-by-page discovery (20 max per page)
+const page1 = await sdk.fetchDexPools({ page: 1, limit: 20 });
+console.log(`Page 1: ${page1.items.length} pools`);
+console.log(`Total pages: ${page1.meta.totalPages}`);
+console.log(`Has next: ${page1.meta.page < page1.meta.totalPages}`);
+
+// Automatic pagination - get all at once
+const allAtOnce = await sdk.fetchAllDexPools();
+console.log(`All pools: ${allAtOnce.items.length}`);
+```
+
+### Development vs Production Environments
+
+The SDK automatically uses the correct DEX backend based on your environment configuration:
+
+```typescript
+// Production (default)
+const prodSdk = createLaunchpadSDK({
+  environment: 'production'  // Uses prod DEX backend
+});
+
+// Development
+const devSdk = createLaunchpadSDK({
+  environment: 'development'  // Uses dev DEX backend
+});
+
+// Custom URL
+const customSdk = createLaunchpadSDK({
+  dexBackendBaseUrl: 'https://custom-dex.example.com'
+});
+```
+
+## WebSocket Event Watchers (v3.29.0+)
+
+Real-time event monitoring for DEX pools and launchpad tokens using polling-based watchers with automatic deduplication.
+
+### Public WebSocket Methods
+
+Connect and manage WebSocket connections for real-time event subscriptions:
+
+```typescript
+// Connect to WebSocket
+sdk.connectWebSocket();
+
+// Check connection status
+if (sdk.isWebSocketConnected()) {
+  console.log('✅ WebSocket connected');
+}
+
+// Subscribe to custom WebSocket events
+const unsubscribe = sdk.subscribeToEvent<MyEventType>('custom-channel', (data) => {
+  console.log('Event received:', data);
+});
+
+// Cleanup when done
+unsubscribe();
+
+// Disconnect from WebSocket
+sdk.disconnectWebSocket();
+```
+
+### Event Watchers: Real-Time Pool & Token Discovery
+
+Watch for new DEX pools and launchpad tokens with optional filtering and automatic deduplication.
+
+#### Watch DEX Pool Creation
+
+Monitor new liquidity pool creation with TVL and token pair filtering:
+
+```typescript
+const unsubscribe = sdk.onDexPoolCreation(
+  (pool) => {
+    console.log(`✨ New pool: ${pool.poolName}`);
+    console.log(`  Pair: ${pool.token0} / ${pool.token1}`);
+    console.log(`  TVL: $${pool.tvl.toFixed(2)}`);
+    console.log(`  24h Volume: $${pool.volume1d.toFixed(2)}`);
+  },
+  {
+    minTVL: 10000,              // Only notify for pools with TVL >= $10,000
+    tokens: ['GALA', 'GUSDC'],  // Only GALA or GUSDC pairs
+    intervalMs: 30000            // Poll every 30 seconds (default)
+  }
+);
+
+// Stop watching after some time
+setTimeout(() => {
+  unsubscribe();
+  console.log('Stopped watching for new pools');
+}, 300000); // 5 minutes
+```
+
+#### Watch Launchpad Token Creation
+
+Monitor new token launches with optional creator filtering:
+
+```typescript
+const unsubscribe = sdk.onLaunchpadTokenCreation(
+  (token) => {
+    console.log(`🚀 New token: ${token.tokenName}`);
+    console.log(`  Symbol: ${token.symbol}`);
+    console.log(`  Creator: ${token.creatorAddress}`);
+    console.log(`  Created: ${new Date(token.createdAt).toISOString()}`);
+  },
+  {
+    creatorAddress: 'eth|0x1234...',  // Only watch specific creator (optional)
+    intervalMs: 30000                  // Poll every 30 seconds (default)
+  }
+);
+
+// Example: Watch all tokens for 2 minutes
+setTimeout(() => {
+  unsubscribe();
+  console.log('Stopped watching for new tokens');
+}, 120000);
+```
+
+### Key Characteristics
+
+- **Polling-Based**: Intelligent polling with configurable intervals (recommended minimum: 5 seconds)
+- **Automatic Deduplication**: Prevents duplicate callbacks for the same pool/token
+- **Client-Side Filtering**: Minimizes API calls with local filtering (minTVL, token pairs, creator address)
+- **Cleanup Functions**: All watchers return cleanup functions for proper resource management
+- **Error Resilience**: Watchers continue polling after errors without blocking
+- **Long-Running Support**: Suitable for background monitoring in production applications
+
+### Demo Scripts
+
+Try the event watcher examples:
+
+```bash
+# Watch for new DEX pools
+npm run demo:watch-pools
+
+# Watch for new launchpad tokens
+npm run demo:watch-tokens
+```
+
+## AI Agent Integration
+
+### For Claude Desktop Users
+
+Install the MCP server to enable Claude to interact with Gala Launchpad directly:
+
+**Full-Access Mode** (with wallet for executing trades):
+```bash
+claude mcp add "galachain-launchpad" -- env PRIVATE_KEY=<YOUR_PRIVATE_KEY> ENVIRONMENT=development npx -y @gala-chain/launchpad-mcp-server@latest
+```
+
+**Read-Only Mode** (query data without wallet):
+```bash
+claude mcp add "galachain-launchpad-readonly" -- env ENVIRONMENT=development npx -y @gala-chain/launchpad-mcp-server@latest
+```
+
+**Environment Variables:**
+- `PRIVATE_KEY` (optional) - Your wallet private key (omit for read-only mode)
+- `ENVIRONMENT` - Backend environment: `development` | `production` (default: production)
+- `DEBUG` - Enable debug logging: `true` | `false` (default: false)
+- `TIMEOUT` - Request timeout in milliseconds (default: 30000)
+
+**Features**: 224 tools for complete Gala Launchpad operations including:
+- Pool management, pricing, and token discovery
+- Token trading with slippage protection
+- Token creation and management
+- Balance and portfolio queries
+- Wallet status checking and configuration
+- Price history and analysis (Node.js only)
+- Comments and social features
+- Transfers and transactions
+
+See: [MCP Server Documentation](../../mcp-server/README.md)
+
+**Try slash commands** (MCP v1.4.0+):
+```
+/galachain-launchpad:analyze-token tokenName=anime
+/galachain-launchpad:portfolio
+/galachain-launchpad:buy-tokens tokenName=anime galaAmount=100
+```
+
+### For AI Developers
+
+Need help with SDK integration, trading bots, or MCP server development?
+
+Ask **[@agent-galachain-launchpad-developer](../../@agent-galachain-launchpad-developer.md)** - a specialized AI agent with expertise in:
+- Complete SDK API (230+ methods)
+- Optional wallet configuration and dual operational modes
+- Trading patterns and DeFi best practices
+- MCP server architecture
+- Error handling strategies
+- Performance optimization
+
+**Full Integration Guide**: [AI Agent Guide](./docs/AI-AGENT-GUIDE.md)
+
+## Quick Start
+
+### Using Helper Functions (Recommended)
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Auto-detecting SDK creation (easiest method)
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic' // Auto-detects format!
+});
+
+// Clean, direct result access - All methods use options objects
+
+// Pool Management - Direct result properties
+const pools = await sdk.fetchPools({ type: 'recent', limit: 10 });
+console.log(`Found ${pools.total} pools across ${pools.totalPages} pages`);
+console.log(`Current page: ${pools.page}, Has next: ${pools.hasNext}`);
+
+const badges = await sdk.fetchTokenBadges('dragnrkti');
+console.log(`Volume badges: ${badges.volumeBadges.length}`);
+console.log(`Engagement badges: ${badges.engagementBadges.length}`);
+
+const details = await sdk.fetchPoolDetails('dragnrkti');
+console.log(`Sale status: ${details.saleStatus}`);
+console.log(`Native token quantity: ${details.nativeTokenQuantity}`);
+
+// Price Calculations - Direct amount access
+const buyAmount = await sdk.calculateBuyAmount({
+  tokenName: 'dragnrkti',
+  amount: '1', // 1 GALA
+  type: 'native'
+});
+console.log(`Buy amount: ${buyAmount.amount}`);
+console.log(`Transaction fee: ${buyAmount.transactionFee}`);
+
+// Trading Operations - Required expectedAmount and slippageToleranceFactor
+const buyResult = await sdk.buy({
+  tokenName: 'dragnrkti',
+  amount: '1',
+  type: 'native',
+  expectedAmount: buyAmount.amount,  // Required: from calculation
+  slippageToleranceFactor: 0.05  // Required: decimal format (5% slippage)
+});
+console.log(`Transaction ID: ${buyResult.transactionId}`);
+
+// Data & Analytics - Clean pagination
+const trades = await sdk.fetchTrades({ tokenName: 'dragnrkti' });
+console.log(`Found ${trades.meta.total} trades`);
+console.log(`Page ${trades.meta.page} of ${trades.meta.totalPages}`);
+trades.items.forEach(trade => {
+  console.log(`Trade: ${trade.tradeType} ${trade.tokenAmount} at ${trade.createdAt.toISOString()}`);
+});
+
+const comments = await sdk.fetchComments({ tokenName: 'dragnrkti' });
+console.log(`${comments.meta.total} comments found`);
+
+// User Operations - Direct balance access
+const galaBalance = await sdk.fetchGalaBalance();
+console.log(`GALA Balance: ${galaBalance.balance}`);
+console.log(`Last updated: ${galaBalance.lastUpdated.toISOString()}`);
+
+const tokenBalance = await sdk.fetchTokenBalance({
+  tokenName: 'dragnrkti',
+  address: sdk.getAddress()
+});
+console.log(`Token balance: ${tokenBalance.quantity}`);
+console.log(`USD value: $${tokenBalance.holdingPriceUsd}`);
+
+// Profile - Direct user data
+const profile = await sdk.fetchProfile();
+console.log(`Profile name: ${profile.fullName || 'Not set'}`);
+
+// URL Utilities - Generate frontend URLs
+const tokenUrl = sdk.getUrlByTokenName('dragnrkti');
+console.log(`View token: ${tokenUrl}`);
+// Output: https://lpad-frontend-test1.defi.gala.com/buy-sell/dragnrkti
+```
+
+## Auto-Pagination Feature
+
+The SDK now supports automatic pagination for pool fetching with three powerful modes:
+
+### Three Pagination Modes
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+
+// MODE 1: Single Page (backward compatible)
+// Limit <= 20: Single API call
+const recent = await sdk.fetchPools({ type: 'recent', limit: 20 });
+console.log(`Fetched ${recent.items.length} pools in one request`);
+
+// MODE 2: Multi-Page Auto-Fetch
+// Limit > 20: Automatic concurrent multi-page fetching
+const large = await sdk.fetchPools({ type: 'popular', limit: 100 });
+console.log(`Fetched ${large.items.length} pools across multiple pages`);
+// Internally fetches 5 pages concurrently: 20+20+20+20+20 = 100 pools
+
+// MODE 3: Infinite Fetch
+// Limit = 0: Fetches ALL available pools
+const all = await sdk.fetchPools({ limit: 0 });
+console.log(`Fetched all ${all.items.length} pools from the platform`);
+
+// Convenience method for "fetch all" pattern
+const allRecent = await sdk.fetchAllPools({ type: 'recent' });
+console.log(`Total pools: ${allRecent.meta.total}`);
+```
+
+### Concurrency Configuration
+
+The SDK uses `MAX_CONCURRENT_POOL_FETCHES` to control parallel API requests:
+
+```typescript
+import { MAX_CONCURRENT_POOL_FETCHES } from '@gala-chain/launchpad-sdk';
+
+console.log(`SDK fetches up to ${MAX_CONCURRENT_POOL_FETCHES} pages concurrently`);
+// Output: "SDK fetches up to 5 pages concurrently"
+```
+
+**Default**: 5 concurrent requests
+**Benefit**: Balances speed with API rate limits
+
+### Performance Benefits
+
+| Scenario | Pages Fetched | Network Calls | Time (Sequential) | Time (Concurrent) | Improvement |
+|----------|---------------|---------------|-------------------|-------------------|-------------|
+| 20 pools | 1 page | 1 call | ~200ms | ~200ms | No change |
+| 100 pools | 5 pages | 5 calls | ~1000ms | ~200ms | 5x faster |
+| 500 pools | 25 pages | 25 calls | ~5000ms | ~1000ms | 5x faster |
+| All pools (1000+) | 50+ pages | 50+ calls | ~10,000ms | ~2000ms | 5x faster |
+
+### When to Use Each Mode
+
+**Single Page (limit <= 20)**
+- Quick queries
+- UI pagination with next/previous buttons
+- When you only need recent results
+
+**Multi-Page (limit > 20)**
+- Analytics dashboards
+- Bulk operations on specific token counts
+- When you know how many results you need
+
+**Infinite (limit = 0 or fetchAllPools())**
+- Complete market scans
+- Full portfolio analysis
+- Trading bot initialization
+- Data exports and backups
+
+### Example: Market Scanner
+
+```typescript
+async function scanEntireMarket() {
+  // Fetch all pools at once (auto-pagination handles everything)
+  const allPools = await sdk.fetchAllPools({ type: 'popular' });
+
+  console.log(`Scanning ${allPools.meta.total} pools...`);
+
+  // Filter for interesting opportunities
+  const highVolume = allPools.items.filter(pool =>
+    parseFloat(pool.volumeGala) > 10000
+  );
+
+  console.log(`Found ${highVolume.length} high-volume pools`);
+
+  return highVolume;
+}
+```
+
+### New Methods
+
+**fetchAllPools(options?)**
+
+Convenience method that automatically fetches all available pools:
+
+```typescript
+// Fetch all recent pools
+const allRecent = await sdk.fetchAllPools({ type: 'recent' });
+
+// Fetch all pools matching search
+const dragons = await sdk.fetchAllPools({ search: 'dragon' });
+
+// Fetch specific token across all results
+const specific = await sdk.fetchAllPools({ tokenName: 'anime' });
+
+// Equivalent to fetchPools({ limit: 0 })
+const all = await sdk.fetchAllPools();
+```
+
+### Stream Filtering (v5.7.0+)
+
+Filter pools by streaming activity and language:
+
+```typescript
+// Find pools with upcoming scheduled shows
+const upcomingShows = await sdk.fetchPools({ hasUpcomingShows: true });
+
+// Find pools that recently went live (last 24 hours)
+const recentlyLive = await sdk.fetchPools({ recentlyStreamed: 24 });
+
+// Find active streaming communities (last week)
+const activeCommunities = await sdk.fetchAllPools({ recentlyStreamed: 168 });
+
+// Filter by stream language (ISO 639-1 codes)
+const englishPools = await sdk.fetchPools({ language: 'en' });
+const spanishPools = await sdk.fetchPools({ language: 'es' });
+
+// Pool data includes stream stats
+const pools = await sdk.fetchPools({ type: 'popular' });
+pools.items.forEach(pool => {
+  console.log(`${pool.tokenName}:`);
+  console.log(`  Viewers: ${pool.currentViewerCount || 0}`);
+  console.log(`  Peak viewers: ${pool.peakViewerCount || 0}`);
+  console.log(`  Last streamed: ${pool.lastStreamedAt || 'Never'}`);
+});
+```
+
+### Manual SDK Creation (Alternative)
+
+```typescript
+import { Wallet } from 'ethers';
+import { LaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Create wallet manually
+const wallet = new Wallet(process.env.PRIVATE_KEY);
+
+// Initialize SDK
+const sdk = new LaunchpadSDK({
+  wallet: wallet,
+  baseUrl: 'https://lpad-backend-dev1.defi.gala.com',
+  timeout: 30000,
+  debug: false
+});
+
+// Same clean API available
+const pools = await sdk.fetchPools({ type: 'recent' });
+console.log(`${pools.total} pools found`);
+```
+
+## Complete Example: Trading Flow with Clean Results
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// 1. Create SDK with auto-detection
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+
+// 2. Check available pools - direct access to results
+const pools = await sdk.fetchPools({
+  type: 'recent',
+  limit: 10
+});
+
+console.log(`Found ${pools.meta.total} pools across ${pools.meta.totalPages} pages`);
+pools.items.forEach(pool => {
+  console.log(`Pool: ${pool.tokenName} created at ${pool.createdAt}`);
+});
+
+// 3. Get price quote - direct amount access
+const quote = await sdk.calculateBuyAmount({
+  tokenName: 'tinyevil',
+  amount: '100',
+  type: 'native'
+});
+
+console.log(`Buying 100 GALA worth will get you: ${quote.amount} TINYEVIL`);
+console.log(`Transaction fee: ${quote.transactionFee} GALA`);
+console.log(`Reverse bonding curve fee: ${quote.reverseBondingCurveFee} GALA`);
+
+// 4. Execute trade with slippage protection - requires expectedAmount
+const buyResult = await sdk.buy({
+  tokenName: 'tinyevil',
+  amount: '100',
+  type: 'native',
+  expectedAmount: quote.amount,  // Required: from calculation above
+  slippageToleranceFactor: 0.05 // Required: decimal format for 5% slippage
+});
+
+console.log(`Transaction submitted: ${buyResult.transactionId}`);
+
+// 5. Check trade history - clean pagination
+const trades = await sdk.fetchTrades({ tokenName: 'tinyevil' });
+console.log(`Found ${trades.meta.total} trades on page ${trades.meta.page}`);
+console.log(`Has more pages: ${trades.meta.page < trades.meta.totalPages}`);
+
+trades.items.forEach(trade => {
+  console.log(`${trade.tradeType}: ${trade.tokenAmount} at ${trade.createdAt.toISOString()}`);
+});
+
+// 6. Post a comment about your trade
+const comment = await sdk.postComment({
+  tokenName: 'tinyevil',
+  content: 'Just bought some tokens! Great project!'
+});
+
+console.log(`Comment posted with ID: ${comment.id}`);
+
+// 7. Check your balance - direct balance access
+const galaBalance = await sdk.fetchGalaBalance();
+console.log(`GALA Balance: ${galaBalance.balance}`);
+console.log(`Decimals: ${galaBalance.decimals}`);
+console.log(`Last updated: ${galaBalance.lastUpdated.toISOString()}`);
+
+const tokenBalance = await sdk.fetchTokenBalance({
+  tokenName: 'tinyevil',
+  address: sdk.getAddress()
+});
+
+console.log(`TINYEVIL Balance: ${tokenBalance.quantity}`);
+console.log(`USD Value: $${tokenBalance.holdingPriceUsd}`);
+console.log(`GALA Value: ${tokenBalance.holdingPriceGala} GALA`);
+console.log(`Finalized: ${tokenBalance.isFinalized}`);
+```
+
+## Transfer Operations
+
+Transfer GALA and launchpad tokens between wallets with EIP-712 signatures:
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+
+// Transfer GALA tokens - direct result access
+const galaTransfer = await sdk.transferGala({
+  recipientAddress: 'eth|1234567890abcdef1234567890abcdef12345678', // or 0x format
+  amount: '1', // 1 GALA
+  uniqueKey: 'galaconnect-operation-my-transfer-123' // Optional for idempotency
+});
+
+console.log(`GALA Transfer ID: ${galaTransfer.transactionId}`);
+console.log(`Status: ${galaTransfer.status}`);
+
+// Transfer launchpad tokens - direct result access
+const tokenTransfer = await sdk.transferToken({
+  to: '0x9876543210fedcba9876543210fedcba98765432', // or eth| format
+  tokenName: 'tinyevil',
+  amount: '1000000', // Token amount in smallest unit
+  uniqueKey: 'galaconnect-operation-token-transfer-456' // Optional for idempotency
+});
+
+console.log(`Token Transfer ID: ${tokenTransfer.transactionId}`);
+console.log(`Status: ${tokenTransfer.status}`);
+```
+
+### Transfer Features
+- **EIP-712 Signatures**: Secure blockchain transactions
+- **Address Format Handling**: Supports both `0x` and `eth|` formats
+- **Idempotency**: Optional unique keys prevent duplicate transfers (must use `galaswap-operation-` or `galaconnect-operation-` prefix)
+- **Comprehensive Validation**: Amount limits, address formats, token names, unique key formats
+- **GalaChain Integration**: Direct transfers via GalaChain gateway
+- **Error Handling**: Detailed error types for different failure scenarios
+
+## Lock/Unlock Operations
+
+Lock and unlock tokens on GalaChain for staking, escrow, and vesting mechanisms:
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+
+// Lock tokens - caller becomes lock authority by default
+const lockResult = await sdk.lockToken({
+  tokenName: 'tinyevil',
+  amount: '1000' // Token amount in smallest unit
+});
+
+console.log(`Locked tokens, tx: ${lockResult.transactionId}`);
+
+// Lock with custom authority and expiration
+const escrowLock = await sdk.lockToken({
+  tokenName: 'tinyevil',
+  amount: '5000',
+  lockAuthority: 'eth|0xEscrowContract...', // Third party can unlock
+  expires: Date.now() + 7 * 24 * 60 * 60 * 1000, // Auto-release in 1 week
+  name: 'escrow-deal-123' // Named lock for matching
+});
+
+// Unlock tokens - must be called by lock authority
+const unlockResult = await sdk.unlockToken({
+  tokenName: 'tinyevil',
+  amount: '1000'
+});
+
+console.log(`Unlocked tokens, tx: ${unlockResult.transactionId}`);
+
+// Unlock specific named lock
+await sdk.unlockToken({
+  tokenName: 'tinyevil',
+  amount: '5000',
+  name: 'escrow-deal-123' // Must match lock name
+});
+```
+
+### Lock Features
+- **Lock Authority**: Specify who can unlock (defaults to caller)
+- **Expiration**: Optional auto-release timestamp
+- **Named Locks**: Identify locks by name for targeted unlocks
+- **EIP-712 Signatures**: Secure blockchain transactions
+- **Idempotency**: Optional unique keys prevent duplicate operations
+
+### Use Cases
+- **Staking**: Lock tokens for reward programs
+- **Escrow**: Third-party holds tokens until conditions met
+- **Vesting**: Time-locked token releases with expiration
+
+## Cross-Chain Bridge Operations
+
+The SDK provides comprehensive cross-chain bridging for GalaChain ↔ Ethereum and GalaChain ↔ Solana transfers.
+
+### Configuration
+
+```typescript
+import { LaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = new LaunchpadSDK({
+  wallet: process.env.PRIVATE_KEY,
+  // Bridge configuration (optional - enables bridge operations)
+  ethereumPrivateKey: process.env.ETHEREUM_PRIVATE_KEY, // Required for Ethereum bridging
+  solanaPrivateKey: process.env.SOLANA_PRIVATE_KEY,     // Required for Solana bridging
+});
+```
+
+### Wallet Balance Queries
+
+Query Ethereum and Solana wallet balances with two approaches:
+
+**Single Token Queries (Fast - 1 RPC call)**
+```typescript
+// Single ERC-20 token balance
+const gala = await sdk.fetchEthereumWalletTokenBalance('GALA');
+// Returns: { symbol: 'GALA', quantity: '1234.56', decimals: 8, contractAddress: '0x...', isNative: false }
+
+// Native ETH balance
+const eth = await sdk.fetchEthereumWalletNativeBalance();
+// Returns: { symbol: 'ETH', quantity: '0.5', decimals: 18, contractAddress: null, isNative: true }
+
+// Single SPL token balance (Solana)
+const solGala = await sdk.fetchSolanaWalletTokenBalance('GALA');
+// Returns: { symbol: 'GALA', quantity: '789.01', decimals: 8, contractAddress: '...', isNative: false }
+
+// Native SOL balance
+const sol = await sdk.fetchSolanaWalletNativeBalance();
+// Returns: { symbol: 'SOL', quantity: '2.5', decimals: 9, contractAddress: null, isNative: true }
+```
+
+**All Tokens Queries (Complete portfolio view)**
+```typescript
+// Ethereum: ETH + all supported ERC-20s (GALA, GWETH, GUSDC, GUSDT, GWTRX, GWBTC)
+const allEth = await sdk.fetchEthereumWalletAllBalances();
+console.log(allEth.native.quantity);  // ETH balance
+console.log(allEth.tokens);           // 6 ERC-20 balances
+console.log(allEth.address);          // Wallet address
+console.log(allEth.timestamp);        // Query timestamp
+
+// Solana: SOL + all supported SPL tokens (GALA, GSOL)
+const allSol = await sdk.fetchSolanaWalletAllBalances();
+console.log(allSol.native.quantity);  // SOL balance
+console.log(allSol.tokens);           // 2 SPL balances
+```
+
+**When to use which:**
+- **Single-token queries**: Quick checks, performance-critical scenarios, frequent polling
+- **All-tokens queries**: Portfolio dashboards, wallet UIs, multi-token operations
+
+### Bridge Operations
+
+```typescript
+// Estimate fees before bridging
+const fee = await sdk.estimateBridgeFee({
+  tokenSymbol: 'GALA',
+  destinationChain: 'Ethereum',
+  amount: '1000',
+});
+
+// Bridge OUT: GalaChain → Ethereum/Solana
+const result = await sdk.bridgeOut({
+  tokenSymbol: 'GALA',
+  amount: '1000',
+  destinationChain: 'Ethereum',
+  recipientAddress: '0x...',
+});
+
+// Bridge IN: Ethereum/Solana → GalaChain
+const result = await sdk.bridgeIn({
+  tokenSymbol: 'GALA',
+  amount: '1000',
+  sourceChain: 'Ethereum',
+});
+
+// Check bridge status
+const status = await sdk.getBridgeStatus(result.transactionHash);
+```
+
+### Supported Tokens
+
+| Token | Symbol | Ethereum | Solana | Decimals |
+|-------|--------|----------|--------|----------|
+| GALA | GALA | ✅ | ✅ | 8 |
+| Wrapped ETH | GWETH | ✅ | - | 18 |
+| USD Coin | GUSDC | ✅ | - | 6 |
+| Tether USD | GUSDT | ✅ | - | 6 |
+| Wrapped TRON | GWTRX | ✅ | - | 6 |
+| Wrapped BTC | GWBTC | ✅ | - | 8 |
+| Wrapped SOL | GSOL | - | ✅ | 9 |
+
+## Multi-Wallet Support
+
+The SDK supports **per-operation wallet overrides** for testing multi-wallet workflows without creating new SDK instances. This is ideal for:
+- Testing trading scenarios with multiple wallets
+- Building multi-user applications
+- Simulating different user behaviors
+- Creating automated trading bots
+
+### Private Key Override Pattern
+
+All signing operations accept an optional `privateKey` parameter to use a different wallet for that specific operation:
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Create SDK with your main wallet
+const sdk = createLaunchpadSDK({
+  wallet: 'your-main-private-key'
+});
+
+// Different wallet's private key (must be in '0x' + 64 hex format)
+const busterPrivateKey = '0x1234567890abcdef...'; // Buster's wallet
+
+// 1. Send GALA from main wallet to Buster
+await sdk.transferGala({
+  recipientAddress: '0xBusterAddress...',
+  amount: '1000'
+  // Uses main SDK wallet (no privateKey override)
+});
+
+// 2. Have Buster buy tokens using his own wallet
+const buyResult = await sdk.buy({
+  tokenName: 'tinyevil',
+  amount: '100',
+  type: 'native',
+  expectedAmount: '500000',
+  slippageToleranceFactor: 0.05,
+  privateKey: busterPrivateKey // Override to use Buster's wallet
+});
+
+// 3. Have Buster post a comment
+await sdk.postComment({
+  tokenName: 'tinyevil',
+  content: 'Great buy!',
+  privateKey: busterPrivateKey // Buster posts the comment
+});
+
+// 4. Main wallet continues operations normally
+const mainWalletBalance = await sdk.fetchGalaBalance();
+// Uses main SDK wallet address
+```
+
+### Supported Operations with Private Key Override
+
+All signing operations support the `privateKey` parameter:
+
+**Trading Operations:**
+- `buy(options)` - Buy tokens with different wallet
+- `sell(options)` - Sell tokens with different wallet
+
+**Token Creation:**
+- `launchToken(data)` - Create token from different wallet
+- `uploadTokenImage(options)` - Upload image for token
+
+**Transfer Operations:**
+- `transferGala(options)` - Transfer GALA from different wallet
+- `transferToken(options)` - Transfer tokens from different wallet
+
+**Social & Profile:**
+- `postComment(options)` - Post comment from different wallet
+- `updateProfile(data)` - Update profile for different wallet
+- `uploadProfileImage(options)` - Upload profile image for different wallet
+
+### Complete Multi-Wallet Example
+
+```typescript
+import { createLaunchpadSDK, createWallet } from '@gala-chain/launchpad-sdk';
+
+// Main SDK instance
+const sdk = createLaunchpadSDK({
+  wallet: 'your-main-private-key'
+});
+
+// Create a test wallet for "Buster"
+const busterWallet = createWallet(); // Random wallet
+const busterPrivateKey = busterWallet.privateKey;
+const busterAddress = busterWallet.address;
+
+console.log(`Buster's address: ${busterAddress}`);
+
+// 1. Fund Buster with GALA from main wallet
+await sdk.transferGala({
+  recipientAddress: busterAddress,
+  amount: '1000'
+});
+
+// 2. Send Buster some tokens from main wallet
+await sdk.transferToken({
+  to: busterAddress,
+  tokenName: 'tinyevil',
+  amount: '10000'
+});
+
+// 3. Have Buster send some tokens back to main wallet
+await sdk.transferToken({
+  to: sdk.getEthereumAddress(), // Main wallet address
+  tokenName: 'tinyevil',
+  amount: '5000',
+  privateKey: busterPrivateKey // Buster's wallet signs
+});
+
+// 4. Have Buster buy more tokens
+const buyQuote = await sdk.calculateBuyAmount({
+  tokenName: 'tinyevil',
+  amount: '100',
+  type: 'native'
+});
+
+await sdk.buy({
+  tokenName: 'tinyevil',
+  amount: '100',
+  type: 'native',
+  expectedAmount: buyQuote.amount,
+  slippageToleranceFactor: 0.05,
+  privateKey: busterPrivateKey // Buster buys
+});
+
+// 5. Have Buster sell some tokens
+const sellQuote = await sdk.calculateSellAmount({
+  tokenName: 'tinyevil',
+  amount: '50',
+  type: 'native'
+});
+
+await sdk.sell({
+  tokenName: 'tinyevil',
+  amount: '50',
+  type: 'native',
+  expectedAmount: sellQuote.amount,
+  slippageToleranceFactor: 0.05,
+  privateKey: busterPrivateKey // Buster sells
+});
+
+// 6. Check final balances for both wallets
+const mainBalance = await sdk.fetchGalaBalance(); // Main wallet
+const busterBalance = await sdk.fetchGalaBalance(busterAddress); // Buster's wallet
+
+console.log(`Main wallet: ${mainBalance.balance} GALA`);
+console.log(`Buster wallet: ${busterBalance.balance} GALA`);
+```
+
+### Private Key Format Requirements
+
+The `privateKey` parameter must be a string in the format:
+- **Format**: `'0x' + 64 hexadecimal characters`
+- **Example**: `'0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'`
+- **Invalid**: Raw hex without '0x' prefix, mnemonic phrases, addresses
+
+```typescript
+// ✅ Valid private key formats
+const validKey1 = '0x' + 'a'.repeat(64); // Correct format
+const validKey2 = wallet.privateKey; // From ethers.js Wallet
+
+// ❌ Invalid formats (will throw validation error)
+const invalidKey1 = 'a'.repeat(64); // Missing '0x' prefix
+const invalidKey2 = 'word1 word2 ... word24'; // Mnemonic not accepted
+const invalidKey3 = '0x123'; // Too short
+```
+
+## Available Methods & Result Types
+
+### **Fetch Operations**
+
+```typescript
+// Pool Management
+fetchPools(options?): Promise<PoolsResult>
+// Returns: { pools, page, limit, total, totalPages, hasNext, hasPrevious }
+// Supports auto-pagination: limit <= 20 (single page), limit > 20 (multi-page), limit = 0 (all pools)
+
+fetchAllPools(options?): Promise<PoolsResult>
+// Returns: { pools, page, limit, total, totalPages, hasNext, hasPrevious }
+// Convenience method that fetches ALL pools (equivalent to fetchPools({ limit: 0 }))
+
+fetchTokenDistribution(tokenName): Promise<TokenDistributionResult>
+// Returns: { holders, totalSupply, totalHolders, lastUpdated }
+
+fetchTokenBadges(tokenName): Promise<TokenBadgesResult>
+// Returns: { volumeBadges, engagementBadges }
+
+fetchPoolDetails(tokenName): Promise<PoolDetailsData>
+// Returns: { basePrice, maxSupply, saleStatus, nativeTokenQuantity, ... }
+
+fetchTokenDetails(tokenId): Promise<TokenDetails>
+// Returns: { symbol, decimals, name, image, verified, network, chainId, contractAddress, tradingEnabled, ... }
+// Supports flexible tokenId: string ('GUSDC|Unit|none|eth:0x...') or object format
+
+fetchVolumeData(options): Promise<GraphDataResult>
+// Returns: { dataPoints }
+
+// Trade & User Data
+fetchTrades(options): Promise<TradesResult>
+// Returns: { trades, page, limit, total, totalPages, hasNext, hasPrevious }
+
+fetchGalaBalance(address?): Promise<GalaBalanceInfo>
+// Returns: { userAddress, balance, decimals, lastUpdated }
+
+fetchTokenBalance(options): Promise<TokenBalanceInfo>
+// Returns: { quantity, holdingPriceUsd, holdingPriceGala, isFinalized, ... }
+
+fetchComments(options): Promise<CommentsResult>
+// Returns: { comments, page, limit, total, totalPages, hasNext, hasPrevious }
+
+fetchProfile(address?): Promise<UserProfile>
+// Returns: { fullName, profileImage, address, ... }
+
+fetchLaunchTokenFee(): Promise<number>
+// Returns: Current GALA fee required to launch a new token (e.g., 0.001)
+```
+
+### **Calculate Operations**
+
+```typescript
+// Price Calculations
+calculateBuyAmount(options): Promise<AmountCalculationResult>
+// Returns: { amount, reverseBondingCurveFee, transactionFee }
+
+calculateSellAmount(options): Promise<AmountCalculationResult>
+// Returns: { amount, reverseBondingCurveFee, transactionFee }
+
+calculateInitialBuyAmount(options): Promise<AmountCalculationResult>
+// Returns: { amount, reverseBondingCurveFee, transactionFee }
+
+calculateBuyAmountForGraduation(tokenName): Promise<AmountCalculationResult>
+// Returns: { amount, reverseBondingCurveFee, transactionFee }
+// Calculates exact GALA cost to buy all remaining tokens and graduate pool
+
+// Local Calculations (Client-Side, No Network)
+calculateBuyAmountLocal(options): Promise<AmountCalculationResult>
+// Options: { tokenName, amount, type: 'native' | 'exact' }
+// Returns: { amount, reverseBondingCurveFee: '0', transactionFee, gasFee }
+// Instant buy calculation using local bonding curve formulas
+
+calculateSellAmountLocal(options): Promise<AmountCalculationResult>
+// Options: { tokenName, amount, type: 'native' | 'exact', maxSupply, minFeePortion, maxFeePortion }
+// Returns: { amount, reverseBondingCurveFee, transactionFee, gasFee }
+// Instant sell calculation with reverse bonding curve fees
+
+// External Calculations (GalaChain Network)
+calculateBuyAmountExternal(options): Promise<AmountCalculationResult>
+// Explicit external calculation wrapper (same as calculateBuyAmount)
+
+calculateSellAmountExternal(options): Promise<AmountCalculationResult>
+// Explicit external calculation wrapper (same as calculateSellAmount)
+
+// Note: Pass `calculateAmountMode: 'local' | 'external'` to override SDK default mode
+
+// Price History Operations (DEX Backend API, Node.js only)
+fetchPriceHistory(options): Promise<PriceHistoryResult>
+// Options: { tokenName?, tokenId?, from?, to?, sortOrder?, page?, limit? }
+// Token identification (provide EXACTLY ONE):
+//   - tokenName: Simple token name (e.g., "demonkpop") - auto-resolves to tokenId
+//   - tokenId: Full token class key (e.g., "Token|Unit|DKP|eth:...")
+// Returns: { snapshots, page, limit, total, totalPages, hasNext, hasPrevious }
+// Fetches paginated historical price snapshots from DEX Backend API
+
+fetchAllPriceHistory(options): Promise<PriceHistoryResult>
+// Options: { tokenName?, tokenId?, from?, to?, sortOrder? } (no pagination params)
+// Token identification (provide EXACTLY ONE):
+//   - tokenName: Simple token name (e.g., "demonkpop") - auto-resolves to tokenId
+//   - tokenId: Full token class key (e.g., "Token|Unit|DKP|eth:...")
+// Returns: All matching snapshots with total count
+// Convenience method with automatic pagination (returns ALL snapshots)
+```
+
+## Performance Optimization
+
+### Reusing Pool Data to Avoid Redundant Network Calls
+
+Methods that internally use `calculateBuyAmount`/`calculateSellAmount` now support optional `calculateAmountMode` and `currentSupply` parameters for performance optimization. This allows you to:
+
+1. **Fetch pool details once** using `fetchPoolDetailsForCalculation`
+2. **Reuse `currentSupply`** across multiple calculations
+3. **Eliminate redundant network calls** with local mode calculations
+4. **Get instant results** when real-time precision isn't required
+
+### Supported Methods
+
+The following methods accept optional performance parameters:
+
+- `fetchLaunchpadTokenSpotPrice(options)` - Pass `calculateAmountMode` and/or `currentSupply`
+- `calculateBuyAmountForGraduation(options)` - Pass `calculateAmountMode` and/or `currentSupply`
+- `graduateToken(options)` - Pass `calculateAmountMode` and/or `currentSupply`
+
+### Using CALCULATION_MODES Constant
+
+```typescript
+import { createLaunchpadSDK, CALCULATION_MODES } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+
+// Use type-safe calculation mode constants
+console.log(CALCULATION_MODES.LOCAL);    // 'local'
+console.log(CALCULATION_MODES.EXTERNAL); // 'external'
+```
+
+### Basic Optimization Pattern
+
+```typescript
+import { createLaunchpadSDK, CALCULATION_MODES } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+
+const tokenName = 'tinyevil';
+
+// ❌ WITHOUT OPTIMIZATION (3 network calls)
+const spotPrice1 = await sdk.fetchLaunchpadTokenSpotPrice(tokenName);
+// → Fetches pool details internally (call #1)
+
+const graduation1 = await sdk.calculateBuyAmountForGraduation(tokenName);
+// → Fetches pool details internally (call #2)
+
+const graduationResult1 = await sdk.graduateToken({ tokenName });
+// → Fetches pool details internally (call #3)
+
+// ✅ WITH OPTIMIZATION (1 network call + instant local calculations)
+// Step 1: Fetch pool details once
+const poolDetails = await sdk.fetchPoolDetailsForCalculation(tokenName);
+const currentSupply = poolDetails.currentSupply; // Pre-computed with full precision
+
+// Step 2: Reuse currentSupply for instant local calculations
+const spotPrice2 = await sdk.fetchLaunchpadTokenSpotPrice({
+  tokenName,
+  calculateAmountMode: CALCULATION_MODES.LOCAL,
+  currentSupply
+});
+// → Uses local bonding curve formulas (instant, no network call)
+
+const graduation2 = await sdk.calculateBuyAmountForGraduation({
+  tokenName,
+  calculateAmountMode: CALCULATION_MODES.LOCAL,
+  currentSupply
+});
+// → Uses local calculation (instant, no network call)
+
+// Step 3: Graduate with optimized calculation
+const graduationResult2 = await sdk.graduateToken({
+  tokenName,
+  calculateAmountMode: CALCULATION_MODES.LOCAL,
+  currentSupply,
+  slippageToleranceFactor: 0.01
+});
+// → Skips redundant pool fetch, uses local calculation
+```
+
+### Performance Comparison
+
+| Pattern | Network Calls | Speed | Use Case |
+|---------|--------------|-------|----------|
+| **Without Optimization** | 3 calls | ~600-900ms | One-off operations |
+| **With Optimization** | 1 call | ~200ms | Batch operations, price discovery |
+| **Reduction** | **66% fewer calls** | **~70% faster** | |
+
+### Complete Optimization Example
+
+```typescript
+import { createLaunchpadSDK, CALCULATION_MODES } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+
+async function optimizedPoolAnalysis(tokenName: string) {
+  console.time('Optimized Analysis');
+
+  // 1. Fetch pool details once (only network call needed)
+  const poolDetails = await sdk.fetchPoolDetailsForCalculation(tokenName);
+  const {
+    currentSupply,
+    maxSupply,
+    reverseBondingCurveMinFeeFactor,
+    reverseBondingCurveMaxFeeFactor
+  } = poolDetails;
+
+  // 2. Get spot price with local calculation (instant)
+  const spotPrice = await sdk.fetchLaunchpadTokenSpotPrice({
+    tokenName,
+    calculateAmountMode: CALCULATION_MODES.LOCAL,
+    currentSupply
+  });
+  console.log(`Spot price: $${spotPrice.usdPrice.toFixed(6)}`);
+
+  // 3. Calculate graduation cost with local calculation (instant)
+  const graduationCost = await sdk.calculateBuyAmountForGraduation({
+    tokenName,
+    calculateAmountMode: CALCULATION_MODES.LOCAL,
+    currentSupply
+  });
+  console.log(`Graduation cost: ${graduationCost.amount} GALA`);
+
+  // 4. Simulate multiple buy scenarios (all instant)
+  const buyAmounts = ['10', '100', '1000'];
+  for (const amount of buyAmounts) {
+    const buyCalc = await sdk.calculateBuyAmount({
+      tokenName,
+      amount,
+      type: 'native',
+      mode: CALCULATION_MODES.LOCAL, // Can also use 'mode' alias
+      currentSupply
+    });
+    console.log(`Buying ${amount} GALA gets you: ${buyCalc.amount} tokens`);
+  }
+
+  // 5. Simulate multiple sell scenarios (all instant)
+  const sellAmounts = ['10', '100', '1000'];
+  for (const amount of sellAmounts) {
+    const sellCalc = await sdk.calculateSellAmountLocal({
+      tokenName,
+      amount,
+      type: 'native',
+      maxSupply,
+      reverseBondingCurveMinFeeFactor,
+      reverseBondingCurveMaxFeeFactor
+    });
+    console.log(`Selling ${amount} GALA worth gets you: ${sellCalc.amount} GALA`);
+  }
+
+  console.timeEnd('Optimized Analysis');
+  // Output: Optimized Analysis: ~200-300ms (vs ~2-3 seconds without optimization)
+}
+
+optimizedPoolAnalysis('tinyevil');
+```
+
+### When to Use Optimization
+
+**✅ Use optimization when:**
+- Performing multiple calculations on the same token
+- Building price discovery tools or analytics dashboards
+- Running simulations or backtests
+- Creating trading bots with frequent calculations
+- Displaying real-time price feeds (use local mode for smooth updates)
+
+**❌ Skip optimization when:**
+- Performing a single calculation
+- Requiring absolute precision from GalaChain network
+- Token supply changes frequently between calls
+
+### Local vs External Calculations
+
+```typescript
+// Local mode (client-side, instant, <0.01% difference from external)
+const localCalc = await sdk.calculateBuyAmount({
+  tokenName: 'tinyevil',
+  amount: '100',
+  type: 'native',
+  mode: CALCULATION_MODES.LOCAL,
+  currentSupply: poolDetails.currentSupply
+});
+
+// External mode (GalaChain network, real-time, slower)
+const externalCalc = await sdk.calculateBuyAmount({
+  tokenName: 'tinyevil',
+  amount: '100',
+  type: 'native',
+  mode: CALCULATION_MODES.EXTERNAL // or omit to use SDK default
+});
+
+// Accuracy comparison
+const difference = Math.abs(
+  parseFloat(localCalc.amount) - parseFloat(externalCalc.amount)
+);
+const percentDiff = (difference / parseFloat(externalCalc.amount)) * 100;
+console.log(`Difference: ${percentDiff.toFixed(4)}%`); // Typically < 0.01%
+```
+
+### SDK Configuration for Default Calculation Mode
+
+```typescript
+import { createLaunchpadSDK, CALCULATION_MODES } from '@gala-chain/launchpad-sdk';
+
+// Configure SDK to use local calculations by default
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic',
+  config: {
+    calculateAmountMode: CALCULATION_MODES.LOCAL // Default to local mode
+  }
+});
+
+// All calculations will use local mode by default
+const calc1 = await sdk.calculateBuyAmount({
+  tokenName: 'tinyevil',
+  amount: '100',
+  type: 'native'
+  // Uses LOCAL mode from SDK config
+});
+
+// Override per-call if needed
+const calc2 = await sdk.calculateBuyAmount({
+  tokenName: 'tinyevil',
+  amount: '100',
+  type: 'native',
+  mode: CALCULATION_MODES.EXTERNAL // Override to external for this call
+});
+```
+
+## Token Metadata Cache
+
+The SDK includes an **intelligent metadata cache** that eliminates redundant API calls and enables instant local calculations. The cache stores immutable token metadata (reverse bonding curve fees, vault addresses, max supply) that never changes.
+
+### How Cache Warming Works
+
+**Opportunistic & Zero-Cost**: Cache warming happens automatically during normal SDK operations without any additional network requests. When you call `fetchPools()`, the SDK extracts and caches metadata from the pool data that was already fetched.
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+
+// Before fetching - cache is empty
+let cacheInfo = sdk.getCacheInfo();
+console.log('Cached tokens:', cacheInfo.totalTokens); // 0
+
+// Fetch pools - automatically warms cache with RBC fees and vault addresses
+await sdk.fetchPools({ type: 'recent', limit: 20 });
+
+// After fetching - cache is warmed with 20 tokens
+cacheInfo = sdk.getCacheInfo();
+console.log('Cached tokens:', cacheInfo.totalTokens); // 20
+console.log('Cache size:', (cacheInfo.cacheSize / 1024).toFixed(2), 'KB');
+
+// Now local calculations are instant (no network calls required)
+const calc = await sdk.calculateBuyAmountLocal({
+  tokenName: 'anime',
+  amount: '100',
+  type: 'native',
+  currentSupply: '500000'
+});
+console.log('Instant result:', calc.amount); // <1ms, used cached RBC fees
+```
+
+### Performance Benefits
+
+**Dramatic Performance Improvements:**
+
+| Operation | Without Cache | With Cache | Improvement |
+|-----------|---------------|------------|-------------|
+| Single calculation | ~200ms | <1ms | **200x faster** |
+| 10 calculations | ~2000ms | <5ms | **400x faster** |
+| Price discovery (50 tokens) | ~10,000ms | ~50ms | **200x faster** |
+
+**Zero Network Overhead**: Cache warming extracts metadata from pool responses you're already receiving - no extra API calls required.
+
+**Memory Efficient**:
+- ~220 bytes per cached token (includes RBC fees + vault address)
+- Max 10,000 tokens = ~2.5 MB total memory
+- LRU eviction keeps memory bounded
+
+### Cache Lifecycle
+
+**Session Lifetime**:
+- Cache persists for entire MCP server session (survives across conversations)
+- For direct SDK usage, cache lifetime matches SDK instance lifetime
+- Call `sdk.cleanup()` to clear cache and release resources
+
+**LRU Eviction**:
+- Maximum 10,000 tokens cached
+- Least Recently Updated (LRU) tokens evicted when limit reached
+- O(1) get/set/eviction using JavaScript Map insertion order
+
+```typescript
+// Cache automatically manages size
+await sdk.fetchPools({ limit: 100 }); // Warms cache with 100 tokens
+await sdk.fetchPools({ limit: 100 }); // Warms with 100 more tokens
+await sdk.fetchPools({ limit: 100 }); // ... continues
+
+// When 10,000 limit reached, oldest tokens are evicted automatically
+const stats = sdk.getCacheInfo();
+console.log('Total tokens:', stats.totalTokens); // Never exceeds 10,000
+console.log('Oldest entry:', new Date(stats.oldestEntry).toISOString());
+```
+
+### Cache Management API
+
+**Get Cache Statistics:**
+
+```typescript
+const stats = sdk.getCacheInfo();
+console.log('Total tokens cached:', stats.totalTokens);
+console.log('Memory usage:', stats.cacheSize, 'bytes');
+console.log('Average per entry:', (stats.cacheSize / stats.totalTokens).toFixed(0), 'bytes');
+console.log('Oldest entry:', new Date(stats.oldestEntry).toISOString());
+```
+
+**Clear Cache (Selective or Complete):**
+
+```typescript
+// Clear specific token
+sdk.clearCache('anime');
+console.log('Cleared anime from cache');
+
+// Clear all tokens
+sdk.clearCache();
+console.log('Cleared entire cache');
+
+// Verify cache is empty
+const stats = sdk.getCacheInfo();
+console.log('Tokens remaining:', stats.totalTokens); // 0
+```
+
+**Manual Cache Warming (Advanced):**
+
+```typescript
+// Manually warm cache from pool data (useful for custom caching scenarios)
+sdk.warmCacheFromPoolData('mytoken', {
+  vaultAddress: 'service|Token$Unit$MYTOKEN$...',
+  reverseBondingCurveMinFeeFactor: 0.0,
+  reverseBondingCurveMaxFeeFactor: 0.5
+});
+
+// Cache is now warmed for local calculations
+const calc = await sdk.calculateBuyAmountLocal({
+  tokenName: 'mytoken',
+  amount: '100',
+  type: 'native',
+  currentSupply: '1000000'
+});
+```
+
+### Complete Cache Example
+
+```typescript
+import { createLaunchpadSDK, CALCULATION_MODES } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+
+// 1. Warm cache by fetching pools
+console.log('Warming cache...');
+await sdk.fetchPools({ type: 'popular', limit: 50 });
+
+// 2. Check cache statistics
+const stats = sdk.getCacheInfo();
+console.log(`Cache warmed with ${stats.totalTokens} tokens`);
+console.log(`Memory: ${(stats.cacheSize / 1024).toFixed(2)} KB`);
+
+// 3. Perform instant calculations using cached metadata
+const tokens = ['anime', 'dragnrkti', 'rocketri'];
+
+console.log('\nCalculating spot prices (instant, no network calls):');
+console.time('Batch Calculations');
+
+for (const token of tokens) {
+  // Get pool details once for this token
+  const poolDetails = await sdk.fetchPoolDetailsForCalculation(token);
+
+  // Multiple instant calculations using cached data
+  const [buy10, buy100, buy1000] = await Promise.all([
+    sdk.calculateBuyAmountLocal({
+      tokenName: token,
+      amount: '10',
+      type: 'native',
+      currentSupply: poolDetails.currentSupply
+    }),
+    sdk.calculateBuyAmountLocal({
+      tokenName: token,
+      amount: '100',
+      type: 'native',
+      currentSupply: poolDetails.currentSupply
+    }),
+    sdk.calculateBuyAmountLocal({
+      tokenName: token,
+      amount: '1000',
+      type: 'native',
+      currentSupply: poolDetails.currentSupply
+    })
+  ]);
+
+  console.log(`${token}:`);
+  console.log(`  10 GALA → ${buy10.amount} tokens`);
+  console.log(`  100 GALA → ${buy100.amount} tokens`);
+  console.log(`  1000 GALA → ${buy1000.amount} tokens`);
+}
+
+console.timeEnd('Batch Calculations');
+// Output: Batch Calculations: ~50-100ms (vs ~3-5 seconds without cache)
+
+// 4. Clear cache when done (optional)
+sdk.clearCache();
+console.log('\nCache cleared');
+```
+
+## Price History with Token Names (v3.20.0+)
+
+The SDK now supports convenient token name resolution for price history queries. Instead of providing full token class keys, you can now use simple token names like `"demonkpop"` and the SDK automatically resolves them to the full token identifier.
+
+### Basic Usage
+
+```typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic'
+});
+
+// ✅ NEW: Use simple token name (auto-resolves to full token ID)
+const recentHistory = await sdk.fetchPriceHistory({
+  tokenName: 'demonkpop', // Simple, intuitive token name
+  page: 1,
+  limit: 20
+});
+
+console.log(`Latest price: $${recentHistory.snapshots[0].price}`);
+console.log(`Total snapshots: ${recentHistory.total}`);
+
+// ✅ STILL WORKS: Direct token ID (for advanced use cases)
+const historyWithId = await sdk.fetchPriceHistory({
+  tokenId: 'Token|Unit|DKP|eth:4A65D29213de2939373ff9eB63AC38730F192C84',
+  page: 1,
+  limit: 20
+});
+```
+
+### Advanced Examples
+
+```typescript
+// 1. VOLATILITY ANALYSIS - Using token name for convenience
+const monthlyHistory = await sdk.fetchPriceHistory({
+  tokenName: 'demonkpop',
+  from: new Date('2025-01-01'),
+  to: new Date('2025-02-01'),
+  sortOrder: 'ASC', // Chronological order for analysis
+  limit: 50
+});
+
+const prices = monthlyHistory.snapshots.map(s => parseFloat(s.price));
+const avgPrice = prices.reduce((a, b) => a + b, 0) / prices.length;
+console.log(`Average price: $${avgPrice.toFixed(6)}`);
+
+// 2. AUTO-PAGINATION - Fetch complete dataset with token name
+const completeHistory = await sdk.fetchAllPriceHistory({
+  tokenName: 'demonkpop',
+  from: new Date('2024-01-01'),
+  to: new Date('2024-12-31'),
+  sortOrder: 'DESC' // Newest first
+});
+
+console.log(`Total snapshots: ${completeHistory.snapshots.length}`);
+console.log(`Date range: ${completeHistory.snapshots[0].timestamp} to ${completeHistory.snapshots[completeHistory.snapshots.length - 1].timestamp}`);
+
+// 3. PRICE TRENDS - Detect moving averages with pagination
+const recentData = await sdk.fetchPriceHistory({
+  tokenName: 'demonkpop',
+  from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000), // Last 7 days
+  sortOrder: 'DESC',
+  limit: 20
+});
+
+const ma7 = recentData.snapshots
+  .map(s => parseFloat(s.price))
+  .slice(0, 7)
+  .reduce((a, b) => a + b, 0) / 7;
+
+console.log(`7-day moving average: $${ma7.toFixed(6)}`);
+```
+
+### Token Name Resolution Details
+
+**Supported Token Name Formats:**
+- Any token created on the launchpad (e.g., `demonkpop`, `anime`, `shoewars`)
+- Case-sensitive, 3-20 characters
+- Alphanumeric characters only
+- The SDK automatically resolves to full token class key: `Token|Unit|SYMBOL|eth:...`
+
+**Error Handling:**
+```typescript
+try {
+  const history = await sdk.fetchPriceHistory({
+    tokenName: 'unknowntoken'
+  });
+} catch (error) {
+  if (error.message.includes('Token not found')) {
+    console.log('Token does not exist on the launchpad');
+  } else if (error.message.includes('must be a string between 3 and 20 characters')) {
+    console.log('Invalid token name format');
+  } else {
+    console.log('Network or other error');
+  }
+}
+```
+
+### Comparison: Before and After
+
+```typescript
+// ❌ BEFORE (v3.19 and earlier) - Had to provide full token class key
+const history = await sdk.fetchPriceHistory({
+  tokenId: 'Token|Unit|DKP|eth:4A65D29213de2939373ff9eB63AC38730F192C84',
+  page: 1,
+  limit: 10
+});
+
+// ✅ AFTER (v3.20+) - Simple token name, auto-resolves internally
+const history = await sdk.fetchPriceHistory({
+  tokenName: 'demonkpop',
+  page: 1,
+  limit: 10
+});
+```
+
+### Performance Notes
+
+- **First Call**: Token name resolution involves a vault lookup (~100-200ms)
+- **Subsequent Calls**: Vault addresses are cached, making repeated calls instant
+- **Network**: Requires DEX Backend API access (Node.js only)
+- **Backwards Compatible**: Existing code using `tokenId` continues to work unchanged
+
+### Cache Design Philosophy
+
+**Immutable Data Only**: Only caches data that never changes:
+- ✅ Reverse bonding curve fee factors (set at token creation)
+- ✅ Vault addresses (permanent token identifiers)
+- ✅ Max supply (bonding curve constant, typically 10M)
+- ❌ Current supply (changes with every trade - fetched dynamically)
+- ❌ Token balances (user-specific and dynamic)
+
+**Zero-Cost Architecture**: No extra API calls required for cache warming. Metadata is extracted from responses you're already receiving during normal operations.
+
+**Bounded Memory**: LRU eviction ensures cache never exceeds 10,000 tokens (~2.5 MB), making it safe for long-running applications.
+
+**Smart Defaults**: Uses 10,000,000 as default max supply for tokens without explicit data (matches 99%+ of launchpad tokens).
+
+### When to Use the Cache
+
+**✅ Perfect for:**
+- Price discovery and analytics dashboards
+- Trading bots with frequent calculations
+- Batch operations on multiple tokens
+- Real-time price feeds and charts
+- Simulation and backtesting tools
+
+**❌ Not needed for:**
+- Single one-off calculations
+- Operations requiring absolute real-time precision
+- Scenarios where current supply changes between calls
+
+### Cache Warming Demo
+
+Run the complete cache demo to see all features in action:
+
+```bash
+npm run demo-cache
+```
+
+The demo showcases:
+- Opportunistic warming from `fetchPools()`
+- Detailed warming from `fetchPoolDetailsForCalculation()`
+- Token name normalization (case-insensitive)
+- Cache hit performance (200x+ faster than network calls)
+- Memory estimation accuracy
+- LRU eviction behavior
+- Clear cache operations
+
+### **Trading Operations**
+
+```typescript
+// Buy/Sell Tokens
+buy(options): Promise<TransactionResult>
+// Options: { tokenName, amount, type, expectedAmount, slippageToleranceFactor }
+// Returns: { transactionId, status, ... }
+
+sell(options): Promise<TransactionResult>
+// Options: { tokenName, amount, type, expectedAmount, slippageToleranceFactor }
+// Returns: { transactionId, status, ... }
+
+graduateToken(options): Promise<TransactionResult>
+// Options: { tokenName, slippageToleranceFactor?, maxAcceptableReverseBondingCurveFeeSlippageFactor?, privateKey? }
+// Returns: { transactionId, status, ... }
+// One-step pool graduation: calculates cost and buys all remaining tokens
+```
+
+### **GSwap DEX Trading Methods**
+
+```typescript
+// GSwap Quote Operations (read-only, fast)
+getSwapQuoteExactInput(fromToken, toToken, amount): Promise<SwapQuoteResult>
+// Returns: { fromToken, toToken, inputAmount, estimatedOutput, feeTier, priceImpact, executionPrice }
+// Get quote for known input amount (spend known GALA, get estimated token output)
+
+getSwapQuoteExactOutput(fromToken, toToken, amount): Promise<SwapQuoteResult>
+// Returns: { fromToken, toToken, inputAmount, estimatedOutput, feeTier, priceImpact, executionPrice }
+// Get quote for known output amount (get known token output, estimate GALA cost)
+
+// GSwap Swap Execution (requires wallet signer)
+executeSwap(fromToken, toToken, amount, estimatedOutput, feeTier, slippageTolerance): Promise<ExecuteSwapResult>
+// Options: { fromToken, toToken, inputAmount, estimatedOutput, feeTier, slippageTolerance }
+// Returns: { transactionId, status, fromToken, toToken, inputAmount, outputAmount, timestamp }
+// Execute token swap with automatic slippage protection and unified WebSocket monitoring
+
+// GSwap User Operations
+getSwapUserAssets(walletAddress): Promise<UserAsset[]>
+// Returns: [{ tokenId, symbol, name, description, image, balance, decimals, verified, compositeKey }, ...]
+// Get user token balances with rich metadata (v4.1.0+)
+
+getAllSwapUserAssets(walletAddress): Promise<UserAsset[]>
+// Returns: All user tokens with rich metadata (auto-paginated)
+// Optimized: Stops fetching when zero-balance tokens encountered
+
+// Token Discovery (no wallet required)
+fetchAvailableDexTokens({ search?, limit?, page? }): Promise<AvailableDexTokensResult>
+// Returns: { tokens: DexToken[], count, page, limit, hasMore }
+// Paginated token discovery with rich metadata
+
+fetchAllAvailableDexTokens({ search? }): Promise<DexToken[]>
+// Returns: All available DEX tokens (auto-paginated)
+// Use for comprehensive token catalogs and listings
+
+getSwapPoolInfo(tokenA, tokenB): Promise<PoolInfo>
+// Returns: { tokenA, tokenB, liquidity, feeTiers, swapCount }
+// Get liquidity and fee tier information for token pair
+```
+
+**Key Features:**
+- ✅ **Strict token format enforcement** (v3.33.0+): All tokens require delimited format (`'GALA|Unit|none|none'` or `'GALA$Unit$none$none'`)
+- ✅ **Quote pattern**: Always get quote before executing swap for accurate slippage calculations
+- ✅ **Unified WebSocket**: Real-time transaction monitoring via shared LaunchpadSDK WebSocket connection
+- ✅ **Environment alignment**: Automatic STAGE/PROD configuration matching
+- ✅ **Fee tiers**: Standard DEX fees (500 bps = 0.05%, 3000 bps = 0.30%, 10000 bps = 1.00%)
+- ✅ **Error handling**: Dedicated error types (GSwapQuoteError, GSwapSwapError, GSwapAssetError, GSwapPoolError)
+
+### **GSwap DEX Trading** (Graduated Tokens)
+
+For tokens that have graduated from the bonding curve phase, use GSwap SDK integration for full DEX trading:
+
+```typescript
+// Access GSwap trading functionality
+const gswapService = sdk.gswap;
+
+// Get swap quotes for graduated tokens
+const quoteParams = {
+  fromToken: 'GALA',
+  toToken: 'GUSDC',
+  amount: '100'
+};
+
+// Quote for exact input (spend known amount)
+const quoteExactInput = await gswapService.getSwapQuoteExactInput(quoteParams);
+console.log(`Spend 100 GALA, get ~${quoteExactInput.estimatedOutput} GUSDC`);
+console.log(`Price impact: ${quoteExactInput.priceImpact}%`);
+console.log(`Execution price: ${quoteExactInput.executionPrice}`);
+
+// Quote for exact output (receive known amount)
+const quoteExactOutput = await gswapService.getSwapQuoteExactOutput({
+  fromToken: 'GALA',
+  toToken: 'GUSDC',
+  amount: '100' // Desired output amount
+});
+console.log(`To get 100 GUSDC, spend ~${quoteExactOutput.inputAmount} GALA`);
+
+// Execute swap with slippage protection
+const swapResult = await gswapService.executeSwap({
+  fromToken: 'GALA',
+  toToken: 'GUSDC',
+  inputAmount: '100',
+  estimatedOutput: quoteExactInput.estimatedOutput,
+  feeTier: quoteExactInput.feeTier,
+  slippageTolerance: 0.01 // 1% slippage tolerance
+});
+
+console.log(`Swap completed! TX: ${swapResult.transactionId}`);
+console.log(`Received: ${swapResult.outputAmount} GUSDC`);
+
+// Query user assets on DEX (returns rich metadata)
+const assets = await gswapService.getUserAssets('eth|0x...');
+assets.forEach(asset => {
+  console.log(`${asset.symbol} (${asset.name}): ${asset.balance}`);
+  console.log(`  Image: ${asset.image}`);
+  console.log(`  Verified: ${asset.verified}`);
+});
+
+// Discover all available DEX tokens (no wallet required)
+const availableTokens = await sdk.fetchAvailableDexTokens({ limit: 20, page: 1 });
+console.log(`Found ${availableTokens.count} tokens on DEX`);
+availableTokens.tokens.forEach(token => {
+  console.log(`${token.symbol}: ${token.name} - ${token.description}`);
+});
+
+// Get ALL available tokens (auto-paginated)
+const allTokens = await sdk.fetchAllAvailableDexTokens();
+console.log(`Total: ${allTokens.length} tokens available on DEX`);
+
+// Get pool information for token pair
+const poolInfo = await gswapService.getPoolInfo('GALA', 'GUSDC');
+console.log(`Liquidity: ${poolInfo.liquidity}`);
+console.log(`Available fee tiers: ${poolInfo.feeTiers}`);
+```
+
+**GSwap Error Handling:**
+
+The GSwap service provides specific error types for different failure scenarios:
+
+```typescript
+import {
+  GSwapQuoteError,
+  GSwapSwapError,
+  GSwapPoolError,
+  GSwapAssetError
+} from '@gala-chain/launchpad-sdk';
+
+try {
+  const quote = await gswapService.getSwapQuoteExactInput({
+    fromToken: 'INVALID',
+    toToken: 'GUSDC',
+    amount: '100'
+  });
+} catch (error) {
+  if (error instanceof GSwapQuoteError) {
+    console.error(`Quote failed: ${error.message}`);
+    console.error(`Error code: ${error.code}`);
+    console.error(`Original error:`, error.originalError);
+  }
+}
+
+try {
+  await gswapService.executeSwap({...});
+} catch (error) {
+  if (error instanceof GSwapSwapError) {
+    console.error(`Swap failed: ${error.message}`);
+    console.error(`Transaction hash: ${error.transactionHash}`);
+    console.error(`Error code: ${error.code}`);
+  }
+}
+
+try {
+  await gswapService.getUserAssets(walletAddress);
+} catch (error) {
+  if (error instanceof GSwapAssetError) {
+    console.error(`Asset query failed for ${error.walletAddress}: ${error.message}`);
+  }
+}
+```
+
+**GSwap vs Bonding Curve Trading:**
+
+| Feature | Bonding Curve (buy/sell) | GSwap DEX (swaps) |
+|---------|-------------------------|-------------------|
+| **Token Status** | Pre-graduation | Post-graduation |
+| **Liquidity** | Algorithmic curve | Concentrated liquidity pools |
+| **Fee Tiers** | Single: reverseBondingCurveFee | Multiple: 500 (0.05%), 3000 (0.30%), 10000 (1.00%) |
+| **Price Impact** | Linear/exponential | Depends on pool depth |
+| **Method** | Direct buy/sell | Quote + execute pattern |
+| **Quote Types** | Exact input/output | Exact input/output |
+
+**Performance Considerations:**
+
+- Quotes are fast (typically <100ms)
+- Socket connection is auto-established on first swap
+- Socket failures don't block swaps (graceful degradation)
+- Use BigNumber for precision in calculations
+- Slippage tolerance typically 0.5% - 2%
+
+### **Content Operations**
+
+```typescript
+// Comments & Content
+postComment(options): Promise<CommentResult>
+// Returns: { id, content, createdAt, ... }
+
+// Token Creation & Management
+launchToken(data): Promise<LaunchTokenResult>
+// Returns: { transactionId, status, ... }
+
+uploadTokenImage(options): Promise<ImageUploadResult>
+// Returns: { imageUrl, success, ... }
+
+// Profile Management
+updateProfile(data): Promise<ProfileUpdateResult>
+// Returns: { success, data, ... }
+
+uploadProfileImage(options): Promise<ImageUploadResult>
+// Returns: { imageUrl, success, ... }
+```
+
+### **Token Data & Validation (v6.0.0+)**
+
+```typescript
+// Fetch complete token data with streaming information consolidated
+fetchToken(tokenName: string): Promise<PoolData>
+// Returns: Complete pool data including streaming fields (playbackId, muxStreamStatus, currentViewerCount, etc.)
+// Example: const pool = await sdk.fetchToken('mytoken');
+
+// Validate token name/symbol for creation or form validation
+validateToken(options: { tokenName?: string, symbol?: string }): Promise<ValidateTokenResponse>
+// Returns: { nameAvailable, symbolAvailable, nameBlocklisted, symbolBlocklisted, errors }
+// Example: const result = await sdk.validateToken({ tokenName: 'mytoken', symbol: 'MYT' });
+```
+
+**Migration Note (v6.0.0)**: `getStreamInfo()` was removed. Use `fetchToken()` instead - streaming fields now consolidated in PoolData response.
+
+### **Validation & Utilities**
+- `isTokenNameAvailable(tokenName: string): Promise<boolean>`
+- `isTokenSymbolAvailable(symbol: string): Promise<boolean>`
+- `isTokenGraduated(tokenName: string): Promise<boolean>` - Check if token completed bonding curve phase
+- `getAddress(): string` - Get backend format address (eth|...)
+- `getEthereumAddress(): string` - Get Ethereum format address (0x...)
+- `getUrlByTokenName(tokenName: string): string` - Get frontend URL for token
+- `resolveVaultAddress(tokenName: string): Promise<string>`
+- `cleanup(): void` - Cleanup resources
+
+### **Cross-Chain Bridge Operations**
+
+```typescript
+// Bridge Configuration (requires ethereumPrivateKey and/or solanaPrivateKey)
+
+// Wallet Balance Queries - Single Token (Fast - 1 RPC call)
+fetchEthereumWalletTokenBalance(symbol, address?): Promise<ExternalChainBalance>
+// Fetch single ERC-20 balance (GALA, GWETH, GUSDC, GUSDT, GWTRX, GWBTC)
+
+fetchEthereumWalletNativeBalance(address?): Promise<ExternalChainBalance>
+// Fetch native ETH balance only
+
+fetchSolanaWalletTokenBalance(symbol, address?): Promise<ExternalChainBalance>
+// Fetch single SPL token balance (GALA, GSOL)
+
+fetchSolanaWalletNativeBalance(address?): Promise<ExternalChainBalance>
+// Fetch native SOL balance only
+
+// Wallet Balance Queries - All Tokens (Complete Portfolio)
+fetchEthereumWalletAllBalances(address?): Promise<EthereumWalletBalanceResult>
+// Returns: { address, native, tokens[], timestamp } - ETH + 6 ERC-20s
+
+fetchSolanaWalletAllBalances(address?): Promise<SolanaWalletBalanceResult>
+// Returns: { address, native, tokens[], timestamp } - SOL + 2 SPL tokens
+
+// Bridge Operations
+estimateBridgeFee(options): Promise<BridgeFeeEstimate>
+// Estimate fees for bridging tokens
+
+bridgeOut(options): Promise<BridgeResult>
+// Bridge tokens FROM GalaChain TO Ethereum/Solana
+
+bridgeIn(options): Promise<BridgeResult>
+// Bridge tokens FROM Ethereum/Solana TO GalaChain
+
+getBridgeStatus(transactionHash, chainHint?): Promise<BridgeStatus>
+// Check status of bridge transaction
+
+getSupportedBridgeTokens(chain?): BridgeTokenInfo[]
+// List supported bridge tokens
+```
+
+## Configuration
+
+### Constants
+
+```typescript
+import { MAX_CONCURRENT_POOL_FETCHES } from '@gala-chain/launchpad-sdk';
+
+console.log(`SDK fetches up to ${MAX_CONCURRENT_POOL_FETCHES} pages concurrently`);
+// Output: "SDK fetches up to 5 pages concurrently"
+```
+
+**MAX_CONCURRENT_POOL_FETCHES**
+- **Type**: `number`
+- **Value**: `5`
+- **Purpose**: Controls concurrency for parallel page fetching in auto-pagination
+- **Balances**: Speed vs API rate limits
+- **Usage**: Exported constant for reference (not configurable at runtime)
+
+### SDK Configuration
+
+```typescript
+interface LaunchpadSDKConfig {
+  wallet: Wallet;                      // ethers.js Wallet instance
+  baseUrl?: string;                    // Backend URL (default: dev environment)
+  galaChainBaseUrl?: string;           // GalaChain gateway URL
+  bundleBaseUrl?: string;              // Bundle service URL
+  webSocketUrl?: string;               // WebSocket URL for monitoring
+  timeout?: number;                    // Request timeout (default: 30000ms)
+  debug?: boolean;                     // Enable debug logging
+  maxRetries?: number;                 // Retry attempts (default: 3)
+  retryDelay?: number;                 // Retry delay (default: 1000ms)
+}
+```
+
+## Helper Functions
+
+### **Wallet Creation**
+```typescript
+import { createWallet, validateWalletInput } from '@gala-chain/launchpad-sdk';
+
+// Auto-detect format and create wallet
+const wallet = createWallet('private-key-or-24-word-mnemonic');
+const randomWallet = createWallet(); // Generate random wallet
+
+// Validate input format without creating wallet
+const isValid = validateWalletInput('0x1234...'); // boolean
+```
+
+### **Key Derivation**
+
+Derive public keys and addresses from private keys without creating a wallet:
+
+```typescript
+import {
+  getPublicKeyFromPrivateKey,
+  getEthereumAddressFromPrivateKey
+} from '@gala-chain/launchpad-sdk';
+
+// Get public key (both compressed and uncompressed formats)
+const { publicKey, compressedPublicKey } = getPublicKeyFromPrivateKey('0x...');
+// publicKey: "0x04..." (132 chars, uncompressed)
+// compressedPublicKey: "0x02..." or "0x03..." (68 chars)
+
+// Get Ethereum address from private key
+const address = getEthereumAddressFromPrivateKey('0x...');
+// "0x8Ba1f109551bD432803012645Ac136ddd64DBA72" (checksum format)
+
+// Convert to GalaChain format manually
+const galaChainAddress = `eth|${address.slice(2).toLowerCase()}`;
+// "eth|8ba1f109551bd432803012645ac136ddd64dba72"
+```
+
+### **GalaChain Address Override**
+
+For non-standard GalaChain addresses (like `client|ops-admin`), use the `galaChainAddress` config option:
+
+```typescript
+import { LaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Standard: address derived from wallet
+const sdk = new LaunchpadSDK({ wallet });
+sdk.getAddress(); // "eth|a1b2c3d4..."
+
+// Override: use custom GalaChain address
+const adminSdk = new LaunchpadSDK({
+  wallet,
+  galaChainAddress: 'client|ops-admin'
+});
+adminSdk.getAddress(); // "client|ops-admin"
+```
+
+Or via environment variable for MCP/Agent setups:
+```bash
+export WALLET_PRIVATE_KEY=0x...
+export WALLET_ADDRESS=client|ops-admin  # Override
+```
+
+### **SDK Factory Functions**
+```typescript
+import { createLaunchpadSDK, createTestLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Main factory with auto-detection
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key-or-mnemonic',
+  config: {
+    baseUrl: 'https://lpad-backend-dev1.defi.gala.com',
+    debug: true
+  }
+});
+
+// Test-optimized SDK
+const testSDK = createTestLaunchpadSDK({
+  wallet: 'test-private-key'
+});
+```
+
+### **Position Filter Utilities**
+
+Helpers for organizing and filtering liquidity positions by various criteria:
+
+```typescript
+import {
+  filterByLiquidity,           // Remove positions with zero liquidity
+  filterByMinLiquidity,        // Keep positions >= threshold
+  filterByTokenPair,           // Match specific token pair
+  filterByToken,               // Find positions containing a token
+  filterByFeeTier,             // Filter by fee tier (500, 3000, 10000)
+  filterByPoolKey,             // Match specific pool (token pair + fee)
+  sortByLiquidity,             // Sort positions by liquidity amount
+  groupByTokenPair,            // Group by "TOKEN0/TOKEN1"
+  groupByFeeTier,              // Group by fee tier
+  groupByPoolKey,              // Group by "TOKEN0|TOKEN1|FEETIER"
+} from '@gala-chain/launchpad-sdk';
+
+// Example: Find active GALA/GUSDC positions and sort by size
+const allPositions = await sdk.getAllSwapUserLiquidityPositions(address);
+const active = filterByLiquidity(allPositions);                    // Remove zero-liquidity
+const galaPositions = filterByTokenPair(active, 'GALA', 'GUSDC');  // GALA/GUSDC only
+const sorted = sortByLiquidity(galaPositions, 'desc');             // Largest first
+
+// Group positions by token pair for portfolio analysis
+const grouped = groupByTokenPair(active);
+grouped.forEach((positions, pair) => {
+  console.log(`${pair}: ${positions.length} positions`);
+});
+
+// Find positions with significant liquidity
+const large = filterByMinLiquidity(active, '1000');
+
+// Organize by pool (pair + fee tier) for advanced analysis
+const byPool = groupByPoolKey(active);
+byPool.forEach((positions, poolKey) => {
+  console.log(`Pool ${poolKey}: ${positions.length} LPs`);
+});
+```
+
+**Use Cases:**
+- Organize positions by token pair or pool
+- Filter for active positions (non-zero liquidity)
+- Find positions above minimum liquidity threshold
+- Analyze portfolio distribution by token or fee tier
+- Identify opportunities for fee collection
+- Locate positions in specific pools
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run integration tests (requires environment setup)
+npm run test:integration
+
+# Run type checking
+npm run typecheck
+
+# Run linting
+npm run lint
+```
+
+## Documentation
+
+- [API Reference](./docs/API-REFERENCE.md) - Complete reference for all SDK methods with examples
+- [Examples](./examples/) - Code examples and demos
+- [AI Agent Guide](./docs/AI-AGENT-GUIDE.md) - Building AI agents with the Launchpad SDK
+
+### GSwap Liquidity Operations
+
+- [Liquidity Operations Guide](./docs/LIQUIDITY_OPERATIONS.md) - Complete guide for managing liquidity positions (viewing, adding, collecting fees, removing)
+- [Liquidity Response Structures](./docs/LIQUIDITY_RESPONSES.md) - Detailed reference for all liquidity operation response formats and error handling
+- [GSwap SDK Integration](./docs/GSWAP_INTEGRATION.md) - Deep dive into GSwap patterns, token formats, and advanced trading workflows
+
+### NFT Collection Management
+
+- [NFT Quick Reference](./docs/NFT_QUICK_REFERENCE.md) - Quick lookup for NFT collection, token class, and minting operations with fee schedules
+- [NFT Operations Guide](./docs/NFT_OPERATIONS.md) - Complete guide for claiming collections, creating token classes, minting NFTs, and querying NFT data
+
+### WebSocket & Real-Time Events
+
+- [WebSocket Documentation Hub](./docs/websocket/) - Complete guide to WebSocket connections and real-time events
+- [Global Feed Quick Start](./docs/websocket/QUICKSTART.md) - Get real-time updates in 5 minutes
+- [Global Feed Guide](./docs/websocket/GLOBAL-FEED.md) - Comprehensive guide to unified event streaming
+- [WebSocket Authentication](./docs/websocket/AUTHENTICATION.md) - JWT authentication and security best practices
+
+### Demo Scripts
+
+The SDK includes 36 comprehensive demo scripts organized into logical categories for easy discovery and learning.
+
+#### Organized Directory Structure
+
+```
+examples/
+├── core/                    # SDK fundamentals and authentication patterns
+├── liquidity/               # GalaSwap liquidity position management (9 demos)
+├── bonding-curve/           # Token bonding curve trading operations
+├── dex/                     # DEX trading and pool discovery (6 demos)
+├── fees/                    # Fee generation and collection workflows (5 demos)
+├── monitoring/              # Real-time event watching (2 demos)
+├── utilities/               # Balance checks, cache, token supply (5 demos)
+└── debug/                   # Development and troubleshooting tools
+```
+
+#### Quick Start Examples
+
+**Core SDK Operations:**
+```bash
+# Complete SDK feature demonstration
+npm run demo
+
+# Read-only operations (no wallet required)
+npm run demo:read-only
+
+# Authenticated operations (wallet required)
+npm run demo:authenticated
+
+# Multi-wallet private key override pattern
+npm run demo:privatekey-override
+```
+
+#### Liquidity Position Management (9 Demos)
+
+Comprehensive liquidity provision workflows for GalaSwap DEX:
+
+```bash
+# Interactive CLI for position management
+npm run demo:liquidity
+
+# Run all 9 liquidity demos sequentially
+npm run demo:liquidity:all
+
+# Individual demos
+npm run demo:liquidity:detailed        # Detailed position lifecycle
+npm run demo:liquidity:ticks           # Advanced tick-based positions
+npm run demo:liquidity:portfolio       # Multi-position portfolio management
+npm run demo:liquidity:apr             # APR calculation for LP positions
+npm run demo:liquidity:errors          # Error handling patterns
+npm run demo:liquidity:fetch-all       # Fetch all positions with pagination
+npm run demo:liquidity:positions-with-prices  # Position pricing enrichment
+
+# Complete roundtrip workflow (legacy, use orchestrator instead)
+npm run demo:dex:roundtrip
+```
+
+**Orchestrator Pattern:**
+The liquidity orchestrator (`npm run demo:liquidity:all`) runs all demos with intelligent error handling:
+- Skip individual demos: `--skip=detailed,ticks`
+- Run specific demos only: `--only=portfolio,apr`
+- See all available demos: `npm run demo:liquidity:all --help`
+
+#### Bonding Curve Trading (Launchpad Tokens)
+
+Pre-graduation token trading on bonding curve pools:
+
+```bash
+# Basic buy/sell operations with slippage protection
+npm run demo:trades
+```
+
+**Bonding Curve Focus:**
+8 additional bonding curve demos are available through the orchestrator (in development):
+- Pool discovery and filtering
+- Price calculation methods
+- Graduation simulation
+- Multi-token analysis
+- Fee structure exploration
+- Slippage testing scenarios
+
+#### DEX Trading Operations (6 Demos)
+
+Graduated token trading on GalaSwap DEX with full liquidity pool support:
+
+```bash
+# DEX swap workflow (quote → execute → confirm)
+npm run demo:dex
+
+# Pool discovery and metrics
+npm run demo:dex:pools
+
+# Pool pricing and TVL analysis
+npm run demo:dex:pricing
+
+# Quote comparison (exact input vs exact output)
+npm run demo:dex:quotes
+
+# Complete swap roundtrip (buy → sell → verify)
+npm run demo:roundtrip:swap
+```
+
+#### Fee Generation and Collection (5 Demos)
+
+Liquidity provider fee workflows with multi-wallet testing:
+
+```bash
+# Basic fee generation and collection
+npm run demo:fees
+
+# High-volume trading fee accumulation
+npm run demo:fees:high-volume
+
+# Complete fee lifecycle test suite
+npm run demo:fees:test
+
+# Trade and collect fees in single workflow
+npm run demo:fees:trade-collect
+```
+
+**Note:** `demo-multi-wallet-fee-generation.ts` is available but not exposed in npm scripts (advanced usage).
+
+#### Real-Time Monitoring (2 Demos)
+
+WebSocket-based event watchers for pool and token creation:
+
+```bash
+# Watch for new DEX pool creation
+npm run demo:watch
+
+# Watch for new launchpad token launches
+npm run demo:watch:tokens
+```
+
+#### Utility Operations (5 Demos)
+
+Balance queries, caching, and token supply information:
+
+```bash
+# Metadata cache warming and performance testing
+npm run demo:cache
+
+# Token supply metrics from GalaChain
+npm run demo:token-supply
+```
+
+**Additional utilities:**
+- `balances.ts` - Multi-token balance queries
+- `balance.ts` - Single token balance check
+- `price-history.ts` - Historical price data (Node.js only)
+
+#### Debug and Development Tools
+
+Advanced troubleshooting and environment testing:
+
+```bash
+# Environment alignment verification
+tsx examples/debug/test-env-alignment.ts
+
+# Slot0 data debugging
+tsx examples/debug/debug-getslot0-test.ts
+
+# DEX simulation with monkey patching
+tsx examples/debug/demo-dex-monkey-patch-simulation.ts
+```
+
+#### Demo Statistics
+
+- **Total Demos:** 36 working examples
+- **npm Scripts:** 25 convenient shortcuts
+- **Categories:** 8 organized directories
+- **Coverage:** All major SDK features demonstrated
+
+#### Recommended Learning Path
+
+1. **Start Here:** `npm run demo` - Complete SDK overview
+2. **Liquidity Basics:** `npm run demo:liquidity` - Interactive CLI
+3. **DEX Trading:** `npm run demo:dex` - Swap workflow
+4. **Fee Management:** `npm run demo:fees` - LP fee collection
+5. **Advanced:** Explore individual demos by category
+
+#### Migration Notes
+
+**Removed Scripts (v3.32.0+):**
+- `demo:liquidity:simple` - Merged into `demo:liquidity`
+- `demo:liquidity:workflow` - Replaced by orchestrator pattern
+- `demo:dex:swap` - Renamed to `demo:dex` for consistency
+
+**New in v3.32.0+:**
+- Organized directory structure with 8 categories
+- Bonding curve orchestrator (in development)
+- Fee demo npm scripts now exposed
+- Symmetry: Both bonding-curve and dex have pool discovery demos
+
+For detailed migration guide, see [docs/DEMO_MIGRATION_GUIDE.md](./docs/DEMO_MIGRATION_GUIDE.md).
+
+## Architecture
+
+The SDK uses a **service-based architecture** with backend-aligned services:
+
+### Backend-Aligned Services
+
+```typescript
+// Each service maps 1:1 to a specific backend
+import {
+  LaunchpadService,  // → launchpad-backend (pools, trades, comments, profiles)
+  GalaChainService,  // → galachain-gateway (balances, transfers, pool details)
+  DexService,        // → dex-api (spot prices)
+  BundleService,     // → bundle-backend (transaction bundling, trading)
+  WebSocketService   // → WebSocket endpoint (real-time monitoring)
+} from '@gala-chain/launchpad-sdk';
+```
+
+### Service Responsibilities
+
+**LaunchpadService** - Launchpad Backend Operations (Facade)
+
+LaunchpadService uses a **facade pattern** internally, delegating to specialized sub-services:
+
+```typescript
+// Internal architecture (v3.6.0+)
+LaunchpadService (facade)
+├── PoolService - Pool queries, distribution, badges, volume data
+│   ├── fetchPools() - Supports auto-pagination (v3.11.0+)
+│   ├── fetchAllPools() - Convenience method for limit: 0
+│   └── ...other pool operations
+├── TradeService - Trade history and queries
+├── CommentService - Comments with vault resolution
+├── UserService - Profile management and token lists
+├── ImageService - Image upload operations
+└── FaucetService - Faucet transfer operations
+```
+
+**Facade Benefits:**
+- ✅ Single responsibility: Each sub-service has one clear purpose
+- ✅ Maintainability: 76.8% reduction in main service file (1,657 → 384 lines)
+- ✅ Code reuse: Shared utilities for query building and response normalization
+- ✅ Backward compatibility: All public methods unchanged
+- ✅ Testability: Sub-services can be tested independently
+
+**Public API (unchanged):**
+- Pool management (fetch, create, check) with auto-pagination
+- Trade history
+- Comments (post, fetch)
+- User profiles
+- Token images
+- Faucet operations
+
+**GalaChainService** - Blockchain Operations
+- GALA balance queries
+- Token balance queries
+- Token transfers (GALA & launchpad tokens)
+- Pool details from bonding curve contracts
+- Token resolution
+
+**DexService** - Price Queries
+- Spot price fetching
+- Multi-token price queries
+
+**BundleService** - Transaction Bundling
+- Buy token operations
+- Sell token operations
+- Slippage protection
+- Transaction bundling
+
+**WebSocketService** - Real-time Features
+- Transaction monitoring
+- Status updates
+- Connection management
+
+### Benefits of Service Architecture
+
+✅ **Clear Separation**: Each service has a single backend responsibility
+✅ **Type Safety**: Full TypeScript support across all services
+✅ **Testability**: Services can be tested independently
+✅ **Maintainability**: Easy to locate and update backend-specific logic
+
+### AI Agent Integration
+
+The SDK includes comprehensive utilities for AI agent development:
+
+```typescript
+import { AgentConfig } from '@gala-chain/launchpad-sdk';
+
+// Quick setup with intelligent defaults
+const { sdk, validation } = await AgentConfig.quickSetup({
+  environment: 'development',
+  autoValidate: true
+});
+
+console.log(`Ready: ${validation.ready}`);
+console.log(`Can trade: ${validation.capabilities.canTrade}`);
+```
+
+For comprehensive AI agent integration, see:
+- [AI Agent Integration Guide](./docs/AI-AGENT-GUIDE.md) - Complete guide for agent development
+- [MCP Tool Specification](./docs/MCP-TOOL-SPECIFICATION.md) - Blueprint for MCP server creation
+- [Agent Examples](./docs/agent-examples/) - Working code examples
+
+## Clean Result Types Architecture
+
+### Key Benefits
+
+✅ **Direct Property Access**: No more `result.data.success` chains
+✅ **Type Safety**: Full TypeScript IntelliSense for all result properties
+✅ **Semantic Types**: Dates as Date objects, numbers as numbers
+✅ **Computed Properties**: `hasNext`, `hasPrevious` for convenience
+✅ **Zero Wrapper Overhead**: Clean, direct access to all result data
+✅ **Options Object Pattern**: All multi-parameter methods use options objects
+
+### Result Type Examples
+
+```typescript
+// Pool results with pagination
+interface PoolsResult {
+  pools: PoolData[];           // Direct pool array
+  page: number;                // Current page
+  total: number;               // Total items
+  hasNext: boolean;            // Computed convenience
+  // ... more properties
+}
+
+// Token balance with typed values
+interface TokenBalanceInfo {
+  quantity: string;            // Token amount (string for precision)
+  holdingPriceUsd: number;     // USD value (number for math)
+  lastUpdated: Date;           // Date object (not string)
+  isFinalized: boolean;        // Boolean flag
+  // ... more properties
+}
+
+// Trading results
+interface AmountCalculationResult {
+  amount: string;              // Calculated amount
+  transactionFee: string;      // Fee breakdown
+  reverseBondingCurveFee: string; // RBC fee
+  // Direct access to all calculation data
+}
+```
+
+
+## What's New in v7.0.0+
+
+### Unified Messages API
+
+All message types (CHAT and COMMENT) are now accessible through a single unified endpoint:
+
+```typescript
+// List all message types for a token
+const result = await sdk.listMessages({ tokenName: 'anime' });
+
+// Filter by type
+const chatOnly = await sdk.listMessages({
+  tokenName: 'anime',
+  contentType: 'CHAT'
+});
+
+// Create, update, delete messages
+await sdk.createMessage({
+  tokenName: 'anime',
+  contentType: 'CHAT',
+  content: 'Great project!'
+});
+
+// Pin important messages
+await sdk.pinMessage(messageId);
+```
+
+### User Data Access
+
+New methods for accessing user information:
+
+```typescript
+// Fetch user token balances
+const balances = await sdk.fetchUserBalances({
+  address: '0x...',
+  limit: 50
+});
+
+// Get comprehensive user report (Overseer only)
+const report = await sdk.fetchUserReport({
+  address: '0x...'
+});
+```
+
+### Token Statistics
+
+Get engagement metrics for tokens:
+
+```typescript
+const stats = await sdk.fetchTokenStats('anime');
+console.log(`Messages: ${stats.messageCount}`);
+console.log(`Peak viewers: ${stats.peakViewerCount}`);
+```
+
+### Simplified Restricted Names Management
+
+Manage platform restricted words with a simplified API:
+
+```typescript
+// Get current list
+const result = await sdk.getRestrictedNames();
+const names = result.data.content.split('\n');
+
+// Update list
+await sdk.updateRestrictedNames('badword1\nbadword2\nbadword3');
+```
+
+## Documentation
+
+Comprehensive documentation for all SDK features:
+
+- **[SDK API Updates](../docs/SDK_API_UPDATES.md)** - Complete guide to new v7.0.0+ methods
+- **[Usage Guide](../docs/USAGE_GUIDE.md)** - Step-by-step examples for all features
+- **[API Reference](../docs/API-REFERENCE.md)** - Complete method reference with signatures
+- **[DTO Reference](../docs/DTO_REFERENCE.md)** - All data type definitions
+- **[Migration Guide](../docs/MIGRATION_GUIDE_SDK.md)** - Upgrading from v6.x to v7.0+
+- **[Examples](./EXAMPLES.md)** - Practical code examples by category
+
+## Environment URLs
+
+- **Development**: `https://lpad-backend-dev1.defi.gala.com`
+- **Production**: `https://lpad-backend-prod1.defi.gala.com`
+
+## License
+
+MIT License - see [LICENSE](../../LICENSE) file for details.
+
+## Contributing
+
+Please read [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines on contributing to this project.
+
+## Support
+
+- GitHub Issues: [Report bugs and request features](https://github.com/gala-chain/launchpad-sdk/issues)
+- Documentation: [Full documentation and examples](./docs/)
+- API Status: All methods working and tested
+
+---
+
+**Built with love for the Gala ecosystem**