@gala-chain/launchpad-sdk 6.0.0 → 7.0.0-beta.2

package/README.md

@@ -1,3376 +1,94 @@
-# Gala Launchpad SDK
+# @gala-chain/launchpad-sdk
 
-**Version: 5.0.4-beta.46 (Latest)**
+The v6 TypeScript SDK for Gala Launchpad. It provides read APIs for launchpad data, typed launchpad submissions, gateway-backed token transactions, and the official GSwap DEX client through `sdk.dex`.
 
-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+)
-- **Events Tracking**: SDK-side event batching with automatic persistence and overseer monitoring (v8.2.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, platform summary, and cache management (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
-
-## How to Connect Your Wallet
-
-The SDK ships a complete wallet provider system with EIP-6963 browser detection, 4 provider types, and React hooks. Here's how to go from zero to connected.
-
-### Node.js / CLI (PrivateKeyProvider)
-
-```typescript
-import { PrivateKeyProvider } from '@gala-chain/launchpad-sdk/wallet';
-import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
-
-const provider = new PrivateKeyProvider('0xYOUR_PRIVATE_KEY');
-const sdk = createLaunchpadSDK({ walletProvider: provider });
-
-// Ready — sign messages, execute trades, transfer tokens
-const address = await provider.getAddress();       // 0x checksummed
-const galaAddr = await provider.getGalaAddress();  // eth|{40-hex}
-const sig = await provider.signMessage('Hello');
-```
-
-### Browser (React — 3 steps)
-
-**Step 1: Wrap your app**
-
-```tsx
-import { WalletProvider } from '@gala-chain/launchpad-sdk/react';
-
-function App() {
-  return (
-    <WalletProvider autoDetect>
-      <YourApp />
-    </WalletProvider>
-  );
-}
-```
-
-**Step 2: Show detected wallets and connect**
-
-```tsx
-import { useWalletDetection, useWalletConnection } from '@gala-chain/launchpad-sdk/react';
-
-function WalletPicker() {
-  const { wallets, isDetecting } = useWalletDetection();
-  const { connectDetected, isConnecting } = useWalletConnection();
-
-  if (isDetecting) return <p>Scanning for wallets...</p>;
-
-  return (
-    <div>
-      {wallets.map(wallet => (
-        <button key={wallet.id} onClick={() => connectDetected(wallet)} disabled={isConnecting}>
-          <img src={wallet.icon} alt="" width={24} /> {wallet.name}
-        </button>
-      ))}
-    </div>
-  );
-}
-```
-
-**Step 3: Use wallet state**
-
-```tsx
-import { useWallet, useGalaAddress, useWalletProvider } from '@gala-chain/launchpad-sdk/react';
-
-function Dashboard() {
-  const { isConnected, address } = useWallet();
-  const galaAddress = useGalaAddress();
-  const provider = useWalletProvider();
-
-  if (!isConnected) return <WalletPicker />;
-
-  return (
-    <div>
-      <p>ETH: {address}</p>
-      <p>GalaChain: {galaAddress}</p>
-      <button onClick={async () => {
-        const sig = await provider.signMessage('Prove ownership');
-        console.log('Signature:', sig);
-      }}>
-        Sign Message
-      </button>
-    </div>
-  );
-}
-```
-
-### Browser (Vanilla — no React)
-
-```typescript
-import { detectWallets, ExternalWalletProvider, KNOWN_WALLET_RDNS } from '@gala-chain/launchpad-sdk/wallet';
-
-// Detect installed wallets (EIP-6963, 500ms scan)
-const { wallets, primary, hasWallets } = await detectWallets();
-
-if (hasWallets) {
-  // Connect to the first detected wallet
-  const provider = new ExternalWalletProvider(primary.provider);
-  const address = await provider.connect();  // triggers wallet popup
-  console.log('Connected:', address);
-
-  // Sign a message
-  const sig = await provider.signMessage('Hello from Launchpad');
-
-  // Sign EIP-712 typed data (required for GalaChain transactions)
-  const typedSig = await provider.signTypedData(
-    { name: 'GalaChain', version: '1' },
-    { Transfer: [{ name: 'to', type: 'string' }, { name: 'amount', type: 'string' }] },
-    { to: 'eth|0000000000000000000000000000000000000001', amount: '100' }
-  );
-
-  // Disconnect
-  await provider.disconnect();
-}
-
-// Or check for a specific wallet
-import { getWalletByRdns } from '@gala-chain/launchpad-sdk/wallet';
-
-const metamask = await getWalletByRdns(KNOWN_WALLET_RDNS.METAMASK);
-if (metamask) {
-  const provider = new ExternalWalletProvider(metamask.provider);
-  await provider.connect();
-}
-```
-
-### Supported Wallets
-
-EIP-6963 auto-detects any compatible wallet. Known identifiers:
-
-| Wallet | RDNS | Constant |
-|--------|------|----------|
-| MetaMask | `io.metamask` | `KNOWN_WALLET_RDNS.METAMASK` |
-| Coinbase Wallet | `com.coinbase.wallet` | `KNOWN_WALLET_RDNS.COINBASE` |
-| Trust Wallet | `com.trustwallet.app` | `KNOWN_WALLET_RDNS.TRUST_WALLET` |
-| Phantom | `app.phantom` | `KNOWN_WALLET_RDNS.PHANTOM` |
-| Rainbow | `me.rainbow` | `KNOWN_WALLET_RDNS.RAINBOW` |
-| OKX Wallet | `com.okex.wallet` | `KNOWN_WALLET_RDNS.OKX` |
-| Rabby | `io.rabby` | `KNOWN_WALLET_RDNS.RABBY` |
-| Brave Wallet | `com.brave.wallet` | `KNOWN_WALLET_RDNS.BRAVE` |
-| Frame | `sh.frame` | `KNOWN_WALLET_RDNS.FRAME` |
-| Ledger | `com.ledger` | `KNOWN_WALLET_RDNS.LEDGER` |
-| Zerion | `io.zerion.wallet` | `KNOWN_WALLET_RDNS.ZERION` |
-| Gala Wallet | `com.gala.wallet` | `KNOWN_WALLET_RDNS.GALA` |
-
-Falls back to `window.ethereum` if no EIP-6963 announcements received.
-
-### React Hooks Reference
-
-| Hook | Returns |
-|------|---------|
-| `useWallet()` | `{ isConnected, address, galaAddress, provider, error }` |
-| `useWalletAddress()` | `string \| null` (0x format) |
-| `useGalaAddress()` | `string \| null` (eth\| format) |
-| `useWalletProvider()` | `WalletProvider \| null` |
-| `useIsWalletConnected()` | `boolean` |
-| `useWalletConnection()` | `{ connectDetected, disconnect, isConnecting }` |
-| `useWalletDetection()` | `{ wallets, isDetecting, refreshWallets }` |
-
-### Provider Types
-
-| Provider | Use Case | Private Key Access | Browser Required |
-|----------|----------|--------------------|-----------------|
-| `PrivateKeyProvider` | CLI, bots, scripts | Yes | No |
-| `ExternalWalletProvider` | MetaMask, Coinbase, etc. | No | Yes |
-| `GalaWalletProvider` | Gala Wallet extension | No | Yes |
-| `GalaChainConnectProvider` | @gala-chain/connect | No | Yes |
-
-### Error Handling
-
-```typescript
-import { WalletProviderError, WalletProviderErrorCode } from '@gala-chain/launchpad-sdk/wallet';
-
-try {
-  await provider.connect();
-} catch (e) {
-  if (e instanceof WalletProviderError) {
-    switch (e.code) {
-      case WalletProviderErrorCode.USER_REJECTED:
-        console.log('User cancelled');
-        break;
-      case WalletProviderErrorCode.PROVIDER_NOT_AVAILABLE:
-        console.log('Wallet not installed');
-        break;
-      case WalletProviderErrorCode.CONNECTION_FAILED:
-        console.log('Connection failed:', e.message);
-        break;
-    }
-  }
-}
-```
-
-**Full reference**: [docs/WALLET-PROVIDERS.md](./docs/WALLET-PROVIDERS.md) | **Live demo**: `npm run demo:wallet`
-
-### 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:
+## Install
 
 ```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`);
+pnpm add @gala-chain/launchpad-sdk
 ```
 
-#### 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
+The v6 DEX surface delegates to `@gala-chain/gswap-sdk`. Until its rc is published to the public registry, install the unpublished rc from the sibling package or configure the workspace link used by this repository.
 
-#### Migration Checklist
+## Configure
 
-- [ ] 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
+```ts
 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
-  pageSize: 20              // Results per page (default: 20, max: 50)
-});
-
-console.log(`Found ${pools.meta?.total || 'many'} pools`);
-console.log(`Showing ${pools.items.length} pools with cursor-based pagination`);
-
-// Fetch ALL pools with automatic pagination
-const allPools = await sdk.fetchAllDexPools({
-  search: 'GUSDC',
-  sortBy: 'volume30d',
-  sortOrder: 'asc'
+  env: 'stage',
+  baseUrl: 'https://lpad-backend.stage.defi.ovh.gala.com',
 });
 
-console.log(`Retrieved ${allPools.items.length} total pools`);
+const pools = await sdk.fetchPools({ pageSize: 10 });
+console.log(pools);
 ```
 
-### Pool Data Structure
+`Environment` is `'prod' | 'stage'`. The SDK defaults to `prod`; it does not infer an environment from a custom `baseUrl`. Use `gatewayBaseUrl` for the chain gateway override.
 
-Each DEX pool includes comprehensive trading metrics:
+## Launchpad writes
 
-```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
+Launchpad buys, sells, and sale creation are submitted to the bundler. The result exposes `bundleId`, `uniqueKey`, and `wait()`:
 
-**Find high-volume pools:**
-```typescript
-const highVolumePoolsAsc = await sdk.fetchAllDexPools({
-  sortBy: 'volume1d',
-  sortOrder: 'desc'
+```ts
+const submission = await sdk.launchpad.buyWithNative({
+  vaultAddress: 'client|example-token',
+  quantity: '1',
+  expectedAmount: '1',
 });
 
-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)}%`);
+const result = await submission.wait();
+console.log(submission.bundleId, result);
 ```
 
-**Discover GALA trading pairs:**
-```typescript
-const galaPools = await sdk.fetchDexPools({
-  search: 'GALA',
-  sortBy: 'tvl',
-  pageSize: 20
-});
-
-galaPools.items.forEach(pool => {
-  console.log(`${pool.poolPair}: $${pool.tvl.toLocaleString()} TVL`);
-});
-```
+## Token writes
 
-**Analyze liquidity provider opportunities:**
-```typescript
-const liquidityOpportunities = await sdk.fetchAllDexPools({
-  sortBy: 'apr1d',
-  sortOrder: 'desc'
-});
+Token transfers and other direct chain token operations go straight to the GalaChain gateway and return a `ChainResult` carrying `status`, `data`, and — read from the `x-transaction-id` and `x-block-number` response headers — `transactionId` and `blockNumber`:
 
-// Find pools with highest APR
-const bestAprPools = liquidityOpportunities.items.slice(0, 10);
-bestAprPools.forEach(pool => {
-  console.log(`${pool.poolPair}: ${pool.apr1d.toFixed(2)}% APR`);
+```ts
+const submission = await sdk.tokens.transfer({
+  tokenClassKey: 'GALA|Unit|none|none',
+  quantity: '1',
+  from: 'eth|0x0123456789012345678901234567890123456789',
+  to: 'eth|0x9876543210987654321098765432109876543210',
 });
-```
-
-### 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 uses cursor-based pagination with configurable page sizes. Use `fetchAllDexPools()` for complete enumeration:
 
-```typescript
-// Cursor-based discovery (20 max per page)
-let cursor: string | undefined;
-const result = await sdk.fetchDexPools({ pageSize: 20, cursor });
-console.log(`Showing: ${result.items.length} pools`);
-console.log(`Has next: ${result.pageInfo?.hasNextPage}`);
-if (result.pageInfo?.hasNextPage) cursor = result.pageInfo?.nextCursor;
-
-// Automatic pagination - get all at once
-const allAtOnce = await sdk.fetchAllDexPools();
-console.log(`All pools: ${allAtOnce.items.length}`);
-```
-
-**Cursor-Based Pagination Loop:**
-```typescript
-// Manually iterate through paginated results using cursors
-let cursor: string | undefined;
-const allPools = [];
-while (true) {
-  const result = await sdk.fetchDexPools({ pageSize: 20, cursor });
-  allPools.push(...result.items);
-  if (!result.pageInfo?.hasNextPage) break;
-  cursor = result.pageInfo?.nextCursor;
-}
-console.log(`Retrieved ${allPools.length} total pools`);
+console.log(submission.transactionId, submission.blockNumber, submission.data);
 ```
 
-### Development vs Production Environments
+Never place a private key in source control. For a write-capable SDK, provide a signer through the supported wallet configuration.
 
-The SDK automatically uses the correct DEX backend based on your environment configuration:
+## GSwap DEX
 
-```typescript
-// Production (default)
-const prodSdk = createLaunchpadSDK({
-  environment: 'production'  // Uses prod DEX backend
-});
+DEX calls live under `sdk.dex` and use the `@gala-chain/gswap-sdk` contracts:
 
-// Development
-const devSdk = createLaunchpadSDK({
-  environment: 'development'  // Uses dev DEX backend
-});
+```ts
+const quote = await sdk.dex.quoting.quoteExactInput(
+  'GALA|Unit|none|none',
+  'GUSDC|Unit|none|none',
+  '100',
+);
 
-// Custom URL
-const customSdk = createLaunchpadSDK({
-  dexBackendBaseUrl: 'https://custom-dex.example.com'
-});
+const swap = await sdk.dex.swaps.swap(
+  'GALA|Unit|none|none',
+  'GUSDC|Unit|none|none',
+  quote.fee,
+  { exactIn: '100', amountOutMinimum: quote.amountOut },
+);
+// The swap is queued (swap.mode === 'queued'); confirm() resolves the applied trade
+// or throws the chain's rejection.
+const applied = await swap.confirm();
+console.log(applied.transactionId, applied.result);
 ```
 
-## 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', pageSize: 20 });
-console.log(`Found ${pools.meta?.total} pools`);
-console.log(`Has next page: ${pools.pageInfo?.hasNextPage}`);
-
-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', pageSize: 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', pageSize: 100 });
-console.log(`Fetched ${large.items.length} pools across multiple pages`);
-// Internally uses cursor-based pagination to efficiently fetch all items
-
-// MODE 3: Infinite Fetch
-// Limit = 0: Fetches ALL available pools
-const all = await sdk.fetchAllPools();
-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' });
-
-// Automatic pagination handles all pages internally
-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',
-  pageSize: 20
-});
-
-console.log(`Found ${pools.meta.total} pools`);
-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: { items, meta: { total }, pageInfo: { hasNextPage, nextCursor } }
-// Supports cursor-based pagination with configurable pageSize
-
-fetchAllPools(options?): Promise<PoolsResult>
-// Returns: { items, meta: { total }, pageInfo: { hasNextPage } }
-// Convenience method that fetches ALL pools using cursor-based pagination
-
-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: { items, meta: { total }, pageInfo: { hasNextPage, nextCursor } }
-
-fetchGalaBalance(address?): Promise<GalaBalanceInfo>
-// Returns: { userAddress, balance, decimals, lastUpdated }
-
-fetchTokenBalance(options): Promise<TokenBalanceInfo>
-// Returns: { quantity, holdingPriceUsd, holdingPriceGala, isFinalized, ... }
-
-fetchComments(options): Promise<CommentsResult>
-// Returns: { items, meta: { total }, pageInfo: { hasNextPage, nextCursor } }
-
-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: { items, meta: { total }, pageInfo: { hasNextPage, nextCursor } }
-// 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', pageSize: 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({ pageSize: 100 }); // Fetches 100 tokens
-await sdk.fetchPools({ pageSize: 100 }); // Fetches 100 more tokens
-await sdk.fetchPools({ pageSize: 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', pageSize: 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
-  pageSize: 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',
-  pageSize: 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
-  pageSize: 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',
-  pageSize: 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',
-  pageSize: 10
-});
-
-// ✅ AFTER (v3.20+) - Simple token name, auto-resolves internally
-const history = await sdk.fetchPriceHistory({
-  tokenName: 'demonkpop',
-  pageSize: 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 fetching all pools
-│   └── ...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
-✅ **Cursor Pagination**: `pageInfo.hasNextPage`, `pageInfo.nextCursor` for cursor-based navigation
-✅ **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
-  cursor?: string;              // Cursor for pagination
-  total: number;               // Total items
-  pageSize: number;             // Items returned per page
-  // ... 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...',
-  pageSize: 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.
+Use `sdk.dex.pools`, `sdk.dex.positions`, `sdk.dex.symbols`, and `sdk.dex.assets` for pool discovery, liquidity, token identifiers, and user assets. DEX reads are unsigned; state-changing DEX calls require the configured signer.
 
-## Support
+## Hosts
 
-- 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
+The stage defaults are `lpad-backend.stage.defi.ovh.gala.com` for launchpad reads, `swap-backend.stage.defi.ovh.gala.com` for DEX reads, and `gateway-testnet.galachain.com` for gateway operations. Production host values are selected by `env: 'prod'`.
 
----
+## Further reading
 
-**Built with love for the Gala ecosystem**
+- [Migration 5.x → 6.0](../../MIGRATION.md)
+- [GSwap integration](../../docs/gswap-integration.md)
+- [Examples](../../examples/)