@gala-chain/launchpad-mcp-server 1.21.6 → 1.22.0

package/src/tools/utils/explainSdkUsage.ts

@@ -0,0 +1,1446 @@
+/**
+ * SDK Usage Explanation Tool
+ *
+ * Provides detailed explanations and code examples for using the Gala Launchpad SDK directly.
+ * Acts as a development reference showing how MCP tools map to SDK methods.
+ */
+
+import type { MCPTool } from '../../types/mcp.js';
+import { withErrorHandling } from '../../utils/error-handler.js';
+import { formatSuccess } from '../../utils/response-formatter.js';
+
+/**
+ * SDK code examples organized by topic
+ */
+const SDK_EXAMPLES = {
+  // Trading workflows
+  'buy-tokens': `
+## Buying Tokens with SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function buyTokens() {
+  // 1. Create SDK instance
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key-or-mnemonic'
+  });
+
+  // 2. Calculate expected amounts FIRST (REQUIRED)
+  const calculation = await sdk.calculateBuyAmount({
+    tokenName: 'dragnrkti',
+    amount: '100',      // Spending 100 GALA
+    type: 'native'      // 'native' = GALA amount, 'exact' = token amount
+  });
+
+  console.log('Expected tokens:', calculation.amount);
+  console.log('RBC Fee:', calculation.reverseBondingCurveFee);
+  console.log('Transaction fee:', calculation.transactionFee);
+
+  // 3. Execute buy with slippage protection
+  const result = await sdk.buy({
+    tokenName: 'dragnrkti',
+    amount: '100',
+    type: 'native',
+    expectedAmount: calculation.amount,  // REQUIRED: from step 2
+    maxAcceptableReverseBondingCurveFee: calculation.reverseBondingCurveFee, // RECOMMENDED
+    slippageToleranceFactor: 0.01  // 1% slippage tolerance (REQUIRED)
+  });
+
+  console.log('Transaction ID:', result.transactionId);
+  console.log('GALA spent:', result.inputAmount);
+  console.log('Tokens received:', result.outputAmount);
+  console.log('Total fees:', result.totalFees);
+}
+\`\`\`
+
+**MCP Tool Equivalent:** \`gala_launchpad_buy_tokens\`
+`,
+
+  'sell-tokens': `
+## Selling Tokens with SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function sellTokens() {
+  // 1. Create SDK instance
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key'
+  });
+
+  // 2. Calculate expected GALA FIRST (REQUIRED)
+  const calculation = await sdk.calculateSellAmount({
+    tokenName: 'dragnrkti',
+    amount: '1000',     // Selling 1000 tokens
+    type: 'exact'       // 'exact' = exact tokens, 'native' = target GALA amount
+  });
+
+  console.log('Expected GALA:', calculation.amount);
+  console.log('RBC Fee:', calculation.reverseBondingCurveFee);
+
+  // 3. Execute sell with slippage protection
+  const result = await sdk.sell({
+    tokenName: 'dragnrkti',
+    amount: '1000',
+    type: 'exact',
+    expectedAmount: calculation.amount,  // REQUIRED: from step 2
+    maxAcceptableReverseBondingCurveFee: calculation.reverseBondingCurveFee, // RECOMMENDED
+    slippageToleranceFactor: 0.01  // 1% slippage
+  });
+
+  console.log('Tokens sold:', result.inputAmount);
+  console.log('GALA received:', result.outputAmount);
+}
+\`\`\`
+
+**MCP Tool Equivalent:** \`gala_launchpad_sell_tokens\`
+`,
+
+  'pool-graduation': `
+## Pool Graduation with SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function graduatePool() {
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key'
+  });
+
+  // Option 1: Calculate graduation cost first (recommended)
+  const calculation = await sdk.calculateBuyAmountForGraduation('dragnrkti');
+
+  console.log('GALA cost to graduate:', calculation.amount);
+  console.log('RBC Fee:', calculation.reverseBondingCurveFee);
+  console.log('Transaction fee:', calculation.transactionFee);
+
+  // Check if you have enough balance
+  const balance = await sdk.fetchGalaBalance();
+  if (parseFloat(balance.balance) < parseFloat(calculation.amount)) {
+    throw new Error('Insufficient GALA balance');
+  }
+
+  // Option 2: One-step graduation (convenience method)
+  const result = await sdk.graduateToken({
+    tokenName: 'dragnrkti',
+    slippageToleranceFactor: 0.01  // Optional: defaults to SDK config
+  });
+
+  console.log('Pool graduated!');
+  console.log('Transaction ID:', result.transactionId);
+  console.log('Total GALA spent:', result.inputAmount);
+  console.log('Tokens received:', result.outputAmount);
+}
+\`\`\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_calculate_buy_amount_for_graduation\`
+- \`gala_launchpad_graduate_token\`
+`,
+
+  'fetch-pools': `
+## Fetching Pool Data with Advanced Methods
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// 1. BASIC POOL FETCHING - With Pagination
+async function basicPoolFetching() {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Fetch recent pools with pagination
+  const pools = await sdk.fetchPools({
+    type: 'recent',
+    limit: 10,
+    page: 1
+  });
+
+  console.log(\`Found \${pools.total} pools, page \${pools.page} of \${pools.totalPages}\`);
+  pools.pools.forEach(pool => {
+    console.log(\`\${pool.tokenName}: \${pool.tokenSymbol}\`);
+  });
+}
+
+// 2. AUTO-PAGINATED FETCHING - Get ALL Pools
+async function fetchAllPools() {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Auto-paginated - returns all pools without manual pagination
+  const allPools = await sdk.fetchAllPools({
+    type: 'recent'
+  });
+
+  console.log(\`Total pools: \${allPools.pools.length}\`);
+}
+
+// 3. POOL DETAILS - Complete information
+async function getPoolDetails(tokenName) {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  const details = await sdk.fetchPoolDetails(tokenName);
+
+  console.log('Sale status:', details.saleStatus); // 'Ongoing' or 'Completed'
+  console.log('Base price:', details.basePrice);
+  console.log('Max supply:', details.maxSupply);
+  console.log('Remaining tokens:', details.sellingTokenQuantity);
+}
+
+// 4. POOL DETAILS FOR CALCULATIONS - Optimized for math
+async function getOptimizedPoolDetails(tokenName) {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Returns only fields needed for bonding curve calculations
+  const poolData = await sdk.fetchPoolDetailsForCalculation(tokenName);
+
+  console.log('Current supply:', poolData.currentSupply);
+  console.log('Remaining tokens:', poolData.remainingTokens);
+  console.log('Max supply:', poolData.maxSupply);
+  console.log('Reverse bonding curve max fee:', poolData.reverseBondingCurveMaxFeeFactor);
+}
+
+// 5. VOLUME & OHLCV DATA - Historical candlestick data
+async function getVolumeData(tokenName) {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Different resolutions: '1m', '5m', '15m', '1h', '4h', '1d'
+  const volumeData = await sdk.fetchVolumeData({
+    tokenName: tokenName,
+    from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000), // Last 7 days
+    to: new Date(),
+    resolution: '1h' // 1-hour candlesticks
+  });
+
+  volumeData.forEach(candle => {
+    console.log(\`\${candle.time}: O:\${candle.open} H:\${candle.high} L:\${candle.low} C:\${candle.close} V:\${candle.volume}\`);
+  });
+}
+
+// 6. SPOT PRICES - DEX tokens (GALA, SILK, MUSIC)
+async function getDexTokenPrices() {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Fetch prices for multiple DEX tokens
+  const prices = await sdk.fetchTokenPrice(['GALA', 'SILK', 'MUSIC']);
+
+  console.log(\`GALA: $\${prices.GALA}\`);
+  console.log(\`SILK: $\${prices.SILK}\`);
+  console.log(\`MUSIC: $\${prices.MUSIC}\`);
+}
+
+// 7. LAUNCHPAD TOKEN SPOT PRICES
+async function getLaunchpadTokenPrice(tokenName) {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Get USD spot price for a launchpad token (anime, woohoo, etc.)
+  const price = await sdk.fetchLaunchpadTokenSpotPrice(tokenName);
+
+  console.log(\`\${tokenName} price: $\${price}\`);
+}
+
+// 8. RESOLVE UTILITY ADDRESSES
+async function resolveAddresses(tokenName) {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Get GalaChain vault address for token
+  const vaultAddress = await sdk.resolveVaultAddress(tokenName);
+  console.log(\`Vault address: \${vaultAddress}\`);
+
+  // Get TokenClassKey for token
+  const tokenClassKey = await sdk.resolveTokenClassKey(tokenName);
+  console.log(\`TokenClassKey: \${tokenClassKey}\`);
+}
+
+// 9. COMPLETE INVESTMENT ANALYSIS WORKFLOW
+async function analyzeToken(tokenName) {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Get all token data in parallel
+  const [details, volumeData, distribution, badges] = await Promise.all([
+    sdk.fetchPoolDetails(tokenName),
+    sdk.fetchVolumeData({ tokenName, resolution: '1d' }),
+    sdk.fetchTokenDistribution(tokenName),
+    sdk.fetchTokenBadges(tokenName)
+  ]);
+
+  // Analyze status
+  console.log(\`Pool Status: \${details.saleStatus}\`);
+  console.log(\`Supply: \${details.currentSupply} / \${details.maxSupply}\`);
+
+  // Analyze volume trend
+  const volumes = volumeData.map(v => parseFloat(v.volume));
+  const avgVolume = volumes.reduce((a, b) => a + b, 0) / volumes.length;
+  console.log(\`Avg daily volume: $\${avgVolume.toFixed(2)}\`);
+
+  // Analyze distribution
+  const top5Ownership = distribution.holders
+    .sort((a, b) => parseFloat(b.balance) - parseFloat(a.balance))
+    .slice(0, 5)
+    .reduce((sum, h) => sum + h.percentage, 0);
+  console.log(\`Top 5 holders: \${top5Ownership.toFixed(2)}%\`);
+
+  // Check badges
+  console.log(\`Badges: \${badges.join(', ')}\`);
+}
+\`\`\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_fetch_pools\` - Paginated pool list
+- \`gala_launchpad_fetch_all_pools\` - Auto-paginated all pools
+- \`gala_launchpad_fetch_pool_details\` - Complete pool information
+- \`gala_launchpad_fetch_pool_details_for_calculation\` - Optimized for calculations
+- \`gala_launchpad_fetch_volume_data\` - OHLCV candlestick data
+- \`gala_launchpad_fetch_token_spot_price\` - DEX token prices (GALA, SILK, MUSIC)
+- \`gala_launchpad_fetch_launchpad_token_spot_price\` - Launchpad token USD prices
+- \`gala_launchpad_fetch_token_distribution\` - Token holder analysis
+- \`gala_launchpad_fetch_token_badges\` - Achievement badges
+- \`gala_launchpad_resolve_vault_address\` - Get vault address
+- \`gala_launchpad_resolve_token_class_key\` - Get TokenClassKey
+`,
+
+  'balances': `
+## Checking Balances with SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function checkBalances() {
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key'
+  });
+
+  // Check GALA balance
+  const galaBalance = await sdk.fetchGalaBalance();
+  console.log(\`GALA: \${galaBalance.balance}\`);
+  console.log(\`Decimals: \${galaBalance.decimals}\`);
+  console.log(\`Last updated: \${galaBalance.lastUpdated.toISOString()}\`);
+
+  // Check specific token balance
+  const tokenBalance = await sdk.fetchTokenBalance({
+    tokenName: 'dragnrkti',
+    address: sdk.getAddress()
+  });
+
+  console.log(\`Token: \${tokenBalance.quantity}\`);
+  console.log(\`USD value: $\${tokenBalance.holdingPriceUsd}\`);
+  console.log(\`GALA value: \${tokenBalance.holdingPriceGala}\`);
+
+  // Check all tokens held
+  const portfolio = await sdk.fetchTokensHeld({
+    address: sdk.getAddress(),
+    limit: 20
+  });
+
+  console.log(\`Holding \${portfolio.total} different tokens\`);
+  portfolio.tokens.forEach(token => {
+    console.log(\`\${token.name}: \${token.quantity}\`);
+  });
+
+  // Check tokens created by this wallet
+  const createdTokens = await sdk.fetchTokensCreated({
+    address: sdk.getAddress(),
+    limit: 10
+  });
+
+  console.log(\`Created \${createdTokens.total} tokens\`);
+  createdTokens.tokens.forEach(token => {
+    console.log(\`  \${token.symbol}: \${token.name}\`);
+  });
+
+  // Get user profile
+  const profile = await sdk.fetchProfile();
+  console.log(\`Profile: \${profile.fullName}\`);
+
+  // Check profile of another user
+  const otherProfile = await sdk.fetchProfile('eth|0x...');
+  console.log(\`Other user: \${otherProfile.fullName}\`);
+}
+\`\`\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_fetch_gala_balance\`
+- \`gala_launchpad_fetch_token_balance\`
+- \`gala_launchpad_fetch_tokens_held\`
+- \`gala_launchpad_fetch_tokens_created\`
+- \`gala_launchpad_fetch_profile\`
+`,
+
+  'token-creation': `
+## Creating Tokens with SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function launchToken() {
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key'
+  });
+
+  // 1. Check if name/symbol available
+  const nameAvailable = await sdk.isTokenNameAvailable('mytoken');
+  const symbolAvailable = await sdk.isTokenSymbolAvailable('MTK');
+
+  if (!nameAvailable || !symbolAvailable) {
+    throw new Error('Name or symbol already taken');
+  }
+
+  // 2. Check launch fee
+  const launchFee = await sdk.fetchLaunchTokenFee();
+  console.log(\`Launch fee: \${launchFee} GALA\`);
+
+  // 3. Upload token image (Node.js only)
+  const imageUpload = await sdk.uploadTokenImage({
+    tokenName: 'mytoken',
+    imagePath: '/path/to/image.png'
+  });
+
+  // 4. Launch the token
+  const result = await sdk.launchToken({
+    tokenName: 'mytoken',
+    tokenSymbol: 'MTK',
+    tokenDescription: 'My awesome token',
+    tokenImage: imageUpload.imageUrl,
+    websiteUrl: 'https://mytoken.com',
+    twitterUrl: 'https://twitter.com/mytoken',
+    preBuyQuantity: '100'  // Optional: pre-buy with GALA
+  });
+
+  console.log('Token launched!');
+  console.log('Transaction ID:', result.transactionId);
+
+  // Get frontend URL
+  const url = sdk.getUrlByTokenName('mytoken');
+  console.log(\`View at: \${url}\`);
+}
+\`\`\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_check_token_name\`
+- \`gala_launchpad_check_token_symbol\`
+- \`gala_launchpad_fetch_launch_token_fee\`
+- \`gala_launchpad_upload_token_image\`
+- \`gala_launchpad_launch_token\`
+- \`gala_launchpad_get_url_by_token_name\`
+`,
+
+  'multi-wallet': `
+## Multi-Wallet Support with SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK, createWallet } from '@gala-chain/launchpad-sdk';
+
+async function multiWalletExample() {
+  // Main SDK with your wallet
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-main-private-key'
+  });
+
+  // Create a test wallet
+  const testWallet = createWallet();
+  console.log('Test wallet:', testWallet.address);
+
+  // 1. Fund test wallet from main wallet
+  await sdk.transferGala({
+    recipientAddress: testWallet.address,
+    amount: '1000'
+  });
+
+  // 2. Have test wallet buy tokens (using privateKey override)
+  const buyCalc = await sdk.calculateBuyAmount({
+    tokenName: 'dragnrkti',
+    amount: '100',
+    type: 'native'
+  });
+
+  const buyResult = await sdk.buy({
+    tokenName: 'dragnrkti',
+    amount: '100',
+    type: 'native',
+    expectedAmount: buyCalc.amount,
+    slippageToleranceFactor: 0.01,
+    privateKey: testWallet.privateKey  // Override to use test wallet
+  });
+
+  console.log('Test wallet bought tokens');
+
+  // 3. Have test wallet post comment
+  await sdk.postComment({
+    tokenName: 'dragnrkti',
+    content: 'Great project!',
+    privateKey: testWallet.privateKey  // Test wallet posts
+  });
+
+  // 4. Check balances for both wallets
+  const mainBalance = await sdk.fetchGalaBalance();  // Main wallet
+  const testBalance = await sdk.fetchGalaBalance(testWallet.address);  // Test wallet
+
+  console.log(\`Main wallet: \${mainBalance.balance} GALA\`);
+  console.log(\`Test wallet: \${testBalance.balance} GALA\`);
+}
+\`\`\`
+
+**Key Points:**
+- All signing operations support \`privateKey\` parameter
+- Creates temporary SDK instance internally
+- Supports: buy, sell, launchToken, transfers, comments, profile updates
+`,
+
+  'transfers': `
+## Token Transfers with SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function transferTokens() {
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key'
+  });
+
+  // Transfer GALA tokens
+  const galaTransfer = await sdk.transferGala({
+    recipientAddress: '0x1234...', // or 'eth|1234...'
+    amount: '100',
+    uniqueKey: 'galaconnect-operation-my-transfer-123'  // Optional idempotency
+  });
+
+  console.log('GALA transfer ID:', galaTransfer.transactionId);
+  console.log('Status:', galaTransfer.status);
+
+  // Transfer launchpad tokens
+  const tokenTransfer = await sdk.transferToken({
+    to: 'eth|5678...',
+    tokenName: 'dragnrkti',
+    amount: '1000',  // Token amount
+    uniqueKey: 'galaconnect-operation-token-456'
+  });
+
+  console.log('Token transfer ID:', tokenTransfer.transactionId);
+}
+\`\`\`
+
+**Features:**
+- EIP-712 signatures for security
+- Supports both \`0x\` and \`eth|\` address formats
+- Optional idempotency keys prevent duplicates
+- Comprehensive validation
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_transfer_gala\`
+- \`gala_launchpad_transfer_token\`
+`,
+
+  'dex-trading': `
+## DEX Trading with SDK - GalaSwap Integration
+
+Trade graduated tokens on the GalaSwap DEX with real-time WebSocket monitoring:
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function dexTradingExample() {
+  // 1. Initialize SDK with wallet
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key',
+    env: 'production'
+  });
+
+  // ============================================================================
+  // QUOTES: Get pricing information (read-only operations)
+  // ============================================================================
+
+  // Quote 1: Exact input (spend known GALA amount)
+  const quoteIn = await sdk.getSwapQuoteExactInput('GALA', 'GUSDC', '100');
+  console.log('Spend 100 GALA → get ~' + quoteIn.estimatedOutput + ' GUSDC');
+  console.log('Price impact: ' + quoteIn.priceImpact + '%');
+  console.log('Fee tier: ' + quoteIn.feeTier + ' bps');
+
+  // Quote 2: Exact output (get known token amount)
+  const quoteOut = await sdk.getSwapQuoteExactOutput('GALA', 'GUSDC', '100');
+  console.log('Get exactly 100 GUSDC → need ~' + quoteOut.inputAmount + ' GALA');
+
+  // ============================================================================
+  // EXECUTE: Perform the swap with slippage protection
+  // ============================================================================
+
+  const result = await sdk.executeSwap(
+    'GALA',                       // from token
+    'GUSDC',                      // to token
+    '100',                        // input amount (100 GALA)
+    quoteIn.estimatedOutput,      // Use quote's output!
+    quoteIn.feeTier,              // Use quote's fee tier!
+    0.01                          // 1% slippage tolerance
+  );
+
+  console.log('Transaction ID: ' + result.transactionId);
+  console.log('Status: ' + result.status);
+  console.log('Received: ' + result.outputAmount + ' ' + result.toToken);
+
+  // ============================================================================
+  // PORTFOLIO: Check balances and assets
+  // ============================================================================
+
+  const assets = await sdk.getSwapUserAssets(sdk.getEthereumAddress());
+  console.log('Assets in wallet:');
+  assets.forEach(asset => {
+    console.log('  ' + asset.symbol + ': ' + asset.balance);
+  });
+
+  // ============================================================================
+  // POOL INFO: Check liquidity before trading
+  // ============================================================================
+
+  const pool = await sdk.getSwapPoolInfo('GALA', 'GUSDC');
+  console.log('GALA↔GUSDC Pool Info:');
+  console.log('  Liquidity: ' + pool.liquidity);
+  console.log('  Available fee tiers: ' + pool.feeTiers.join(', ') + ' bps');
+  console.log('  24h swaps: ' + pool.swapCount);
+}
+\`\`\`
+
+**Key Architecture:**
+- **Unified WebSocket**: Uses LaunchpadSDK's unified WebSocket for transaction monitoring
+- **Environment Alignment**: STAGE/PROD URLs must match between LaunchpadSDK and GSwapService
+- **Token Formats**: Supports simple names ('GALA') or full IDs ('GALA|Unit|none|none')
+- **Slippage Protection**: Always use quote values for execution
+- **Fee Tiers**: 500 (0.05%), 3000 (0.30%), 10000 (1.00%)
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_get_swap_quote_exact_input\`
+- \`gala_launchpad_get_swap_quote_exact_output\`
+- \`gala_launchpad_execute_swap\`
+- \`gala_launchpad_get_swap_user_assets\`
+- \`gala_launchpad_get_swap_pool_info\`
+`,
+
+  'error-handling': `
+## Error Handling with SDK
+
+\`\`\`typescript
+import {
+  createLaunchpadSDK,
+  ValidationError,
+  NetworkError,
+  TransactionError,
+  TokenNotFoundError
+} from '@gala-chain/launchpad-sdk';
+
+async function errorHandlingExample() {
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key'
+  });
+
+  try {
+    // Attempt trade
+    const result = await sdk.buy({
+      tokenName: 'dragnrkti',
+      amount: '100',
+      type: 'native',
+      expectedAmount: '5000',
+      slippageToleranceFactor: 0.01
+    });
+
+    console.log('Success:', result.transactionId);
+
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      console.error('Invalid input:', error.message);
+      console.error('Field:', error.field);
+      console.error('Code:', error.code);
+
+    } else if (error instanceof TokenNotFoundError) {
+      console.error('Token does not exist:', error.tokenName);
+
+    } else if (error instanceof NetworkError) {
+      console.error('Network issue:', error.message);
+      console.error('Status code:', error.statusCode);
+
+    } else if (error instanceof TransactionError) {
+      console.error('Transaction failed:', error.message);
+      console.error('Transaction ID:', error.transactionId);
+
+    } else {
+      console.error('Unexpected error:', error);
+    }
+  }
+}
+\`\`\`
+
+**Error Types:**
+- \`ValidationError\` - Invalid input parameters
+- \`NetworkError\` - HTTP/network failures
+- \`TransactionError\` - Blockchain transaction failures
+- \`TokenNotFoundError\` - Token doesn't exist
+- \`ConfigurationError\` - SDK misconfiguration
+- \`WebSocketError\` - Real-time connection issues
+`,
+
+  'installation': `
+## Installing and Importing SDK
+
+### NPM Installation
+
+\`\`\`bash
+# Install SDK
+npm install @gala-chain/launchpad-sdk
+
+# Install peer dependencies
+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
+\`\`\`
+
+### Import Patterns
+
+\`\`\`typescript
+// Main SDK class
+import { LaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Helper functions (recommended)
+import {
+  createLaunchpadSDK,
+  createTestLaunchpadSDK,
+  createWallet,
+  validateWalletInput
+} from '@gala-chain/launchpad-sdk';
+
+// Error types
+import {
+  ValidationError,
+  NetworkError,
+  TransactionError,
+  TokenNotFoundError
+} from '@gala-chain/launchpad-sdk';
+
+// Type definitions
+import type {
+  PoolData,
+  TradeResult,
+  TokenBalanceInfo,
+  BuyTokenOptions,
+  SellTokenOptions
+} from '@gala-chain/launchpad-sdk';
+\`\`\`
+
+### Environment Configuration
+
+\`\`\`typescript
+// Production (default)
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key',
+  config: {
+    baseUrl: 'https://lpad-backend-prod1.defi.gala.com',
+    debug: false,
+    timeout: 60000
+  }
+});
+
+// Development
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key',
+  config: {
+    baseUrl: 'https://lpad-backend-dev1.defi.gala.com',
+    debug: true
+  }
+});
+\`\`\`
+`,
+
+  'local-calculations': `
+## Local Bonding Curve Calculations with SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function localCalculationsExample() {
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key'
+  });
+
+  // ============================================================================
+  // LOCAL CALCULATIONS - Instant quotes without network calls
+  // ============================================================================
+
+  // 1. Buy calculation (local, instant)
+  const localBuy = await sdk.calculateBuyAmountLocal({
+    tokenName: 'dragnrkti',
+    amount: '100',      // Spending 100 GALA
+    type: 'native'      // 'native' = GALA amount, 'exact' = token amount
+  });
+
+  console.log('LOCAL Buy Quote (instant):');
+  console.log('  Tokens received:', localBuy.amount);
+  console.log('  Transaction fee:', localBuy.transactionFee);
+  console.log('  RBC Fee:', localBuy.reverseBondingCurveFee); // Always "0" for buys
+  console.log('  Gas fee:', localBuy.gasFee);
+
+  // 2. Sell calculation (local, requires pool details)
+  const poolDetails = await sdk.fetchPoolDetails('dragnrkti');
+
+  const localSell = await sdk.calculateSellAmountLocal({
+    tokenName: 'dragnrkti',
+    amount: '1000',     // Selling 1000 tokens
+    type: 'exact',
+    // Required parameters from pool details:
+    maxSupply: poolDetails.maxSupply.toString(),
+    minFeePortion: poolDetails.reverseBondingCurveMinFeeFactor || 0,
+    maxFeePortion: poolDetails.reverseBondingCurveMaxFeeFactor || 0
+  });
+
+  console.log('LOCAL Sell Quote (instant):');
+  console.log('  GALA received:', localSell.amount);
+  console.log('  RBC Fee:', localSell.reverseBondingCurveFee);
+  console.log('  Transaction fee:', localSell.transactionFee);
+
+  // ============================================================================
+  // EXTERNAL CALCULATIONS - Real-time network queries (explicit)
+  // ============================================================================
+
+  // 3. External buy (explicit network call)
+  const externalBuy = await sdk.calculateBuyAmountExternal({
+    tokenName: 'dragnrkti',
+    amount: '100',
+    type: 'native'
+  });
+
+  console.log('EXTERNAL Buy Quote (network):');
+  console.log('  Tokens received:', externalBuy.amount);
+
+  // 4. External sell (explicit network call)
+  const externalSell = await sdk.calculateSellAmountExternal({
+    tokenName: 'dragnrkti',
+    amount: '1000',
+    type: 'exact'
+  });
+
+  console.log('EXTERNAL Sell Quote (network):');
+  console.log('  GALA received:', externalSell.amount);
+
+  // ============================================================================
+  // A/B COMPARISON - Verify local accuracy
+  // ============================================================================
+
+  const buyDiff = Math.abs(parseFloat(localBuy.amount) - parseFloat(externalBuy.amount));
+  const buyPct = (buyDiff / parseFloat(externalBuy.amount)) * 100;
+
+  console.log('Local vs External Accuracy:');
+  console.log(\`  Buy difference: \${buyPct.toFixed(4)}% (should be <0.01%)\`);
+
+  // ============================================================================
+  // PERFORMANCE BENEFIT - Local is instant
+  // ============================================================================
+
+  console.time('Local calculation');
+  await sdk.calculateBuyAmountLocal({ tokenName: 'dragnrkti', amount: '100', type: 'native' });
+  console.timeEnd('Local calculation');  // ~0ms (instant)
+
+  console.time('External calculation');
+  await sdk.calculateBuyAmountExternal({ tokenName: 'dragnrkti', amount: '100', type: 'native' });
+  console.timeEnd('External calculation');  // ~200-500ms (network roundtrip)
+}
+\`\`\`
+
+**Benefits of Local Calculations:**
+- ✅ Instant quotes (no network delay)
+- ✅ Offline support (no internet required)
+- ✅ No API rate limits
+- ✅ Perfect accuracy (<0.01% difference)
+- ✅ Reduced server load
+
+**When to Use:**
+- Local: Price discovery, UI updates, offline scenarios
+- External: Production trades (always verify before executing)
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_calculate_buy_amount_local\`
+- \`gala_launchpad_calculate_buy_amount_external\`
+- \`gala_launchpad_calculate_sell_amount_local\`
+- \`gala_launchpad_calculate_sell_amount_external\`
+`,
+
+  'price-history': `
+## Historical Price Analysis with SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function analyzePriceHistory() {
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key-or-mnemonic'
+  });
+
+  // Paginated price history
+  const history = await sdk.fetchPriceHistory({
+    tokenId: 'Token|Unit|GUSDC|eth:0x...',
+    from: new Date('2025-01-01'),
+    to: new Date('2025-01-31'),
+    sortOrder: 'DESC',
+    page: 1,
+    limit: 50
+  });
+
+  console.log(\`Found \${history.snapshots.length} snapshots\`);
+  console.log(\`Total available: \${history.total} (page \${history.page} of \${history.totalPages})\`);
+
+  // Auto-paginated complete history
+  const allHistory = await sdk.fetchAllPriceHistory({
+    tokenId: 'GWETH|Unit|none|none',
+    from: new Date('2024-01-01'),
+    sortOrder: 'ASC'
+  });
+
+  // Price analysis
+  const prices = allHistory.snapshots.map(s => parseFloat(s.price));
+  const avg = prices.reduce((a, b) => a + b, 0) / prices.length;
+  const variance = prices.reduce((sum, p) => sum + Math.pow(p - avg, 2), 0) / prices.length;
+  const volatility = Math.sqrt(variance);
+
+  console.log(\`Average: $\${avg.toFixed(4)}, Volatility: $\${volatility.toFixed(4)}\`);
+
+  // Data export (CSV)
+  const csv = ['timestamp,price'].concat(
+    allHistory.snapshots.map(s => \`\${s.timestamp.toISOString()},\${s.price}\`)
+  ).join('\\n');
+
+  console.log('CSV export:', csv.split('\\n').slice(0, 3).join('\\n'));
+}
+\`\`\`
+
+**Key Methods:**
+- \`fetchPriceHistory()\` - Paginated historical prices (max 50 per page)
+- \`fetchAllPriceHistory()\` - Auto-paginated complete history (all snapshots)
+
+**Response Fields:**
+- \`price\` - Token price as decimal string
+- \`timestamp\` - ISO 8601 timestamp
+- \`tokenId\` - Token identifier (pipe-delimited)
+
+**Use Cases:**
+- Technical analysis and charting
+- Volatility assessment
+- Price trend identification
+- Data export for analytics
+- Backtesting strategies
+
+**Token ID Formats:**
+- String: \`Token|Unit|GUSDC|eth:0x...\`
+- Object: \`{ collection, category, type, additionalKey }\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_fetch_price_history\` - Paginated
+- \`gala_launchpad_fetch_all_price_history\` - Auto-paginated
+`,
+
+  'token-details': `
+## Token Details and Metadata with SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function analyzeTokenDetails() {
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key-or-mnemonic'
+  });
+
+  // Fetch token metadata
+  const details = await sdk.fetchTokenDetails('Token|Unit|GUSDC|eth:0x...');
+
+  console.log('Token Information:');
+  console.log(\`  Name: \${details.name}\`);
+  console.log(\`  Symbol: \${details.symbol}\`);
+  console.log(\`  Decimals: \${details.decimals}\`);
+  console.log(\`  Verified: \${details.verified}\`);
+  console.log(\`  Trading: \${details.tradingEnabled}\`);
+  console.log(\`  Network: \${details.network}\`);
+  console.log(\`  Image: \${details.image}\`);
+
+  // Pre-trading validation
+  async function validateBeforeTrade(tokenId: string) {
+    const token = await sdk.fetchTokenDetails(tokenId);
+
+    if (!token.verified) {
+      console.warn(\`⚠️  \${token.symbol} is NOT verified\`);
+    }
+
+    if (!token.tradingEnabled) {
+      throw new Error(\`Trading disabled for \${token.symbol}\`);
+    }
+
+    if (token.network !== 'ethereum') {
+      throw new Error(\`Wrong network: got \${token.network}\`);
+    }
+
+    return token;
+  }
+
+  // Batch token comparison
+  const tokens = ['GALA|Unit|none|none', 'Token|Unit|GUSDC|eth:0x...'];
+  const details_list = await Promise.all(
+    tokens.map(id => sdk.fetchTokenDetails(id).catch(() => null))
+  );
+
+  const verified = details_list.filter(t => t?.verified).length;
+  console.log(\`Verified tokens: \${verified}/\${tokens.length}\`);
+}
+\`\`\`
+
+**Response Fields:**
+- \`symbol\` - Token symbol (e.g., 'GUSDC')
+- \`name\` - Full token name
+- \`decimals\` - Decimal places
+- \`verified\` - Verification status
+- \`tradingEnabled\` - Trading availability
+- \`network\` - Network name (e.g., 'ethereum')
+- \`contractAddress\` - Smart contract address
+- \`image\` - Token image URL
+- \`chainId\` - Blockchain chain ID
+
+**Use Cases:**
+- Pre-trading validation and safety checks
+- Display token metadata in UI
+- Verify token authenticity
+- Network compatibility checking
+
+**Token ID Formats:**
+- String: \`Token|Unit|GUSDC|eth:0x...\`
+- Object: \`{ collection, category, type, additionalKey }\`
+
+**MCP Tool Equivalent:** \`gala_launchpad_fetch_token_details\`
+`,
+
+  'spot-prices-smart-routing': `
+## Smart Spot Price Routing with DEX Fallback
+
+The SDK intelligently routes pricing requests between DEX and Launchpad backends based on token graduation status - no need to know which backend a token uses!
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function tokenPricing() {
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key'
+  });
+
+  // OPTION 1: SMART ROUTING (Recommended) - Automatic backend selection
+  // Use tokenId for ANY token (graduated or ungraduated)
+  // SDK automatically detects and routes to correct backend
+  console.log('=== Smart Routing (Recommended) ===');
+  const smartPrice = await sdk.fetchTokenPrice({
+    tokenId: 'Token|Unit|ANIME|eth:0x...'  // Works for ANY token!
+  });
+  console.log(\`Token price: $\${smartPrice}\`);
+  // ✅ Handles graduated tokens (DEX) automatically
+  // ✅ Handles ungraduated tokens (Launchpad) automatically
+  // ✅ No need to know token status beforehand
+
+  // OPTION 2: EXPLICIT DEX PRICING - Graduated tokens only
+  // Use tokenId directly for DEX tokens
+  console.log('\\n=== Explicit DEX Pricing ===');
+  const dexPrices = await sdk.fetchTokenPrice({
+    tokenId: 'GALA|Unit|none|none'  // Or other DEX token
+  });
+  console.log(\`DEX Token GALA: $\${dexPrices}\`);
+
+  // OPTION 3: EXPLICIT LAUNCHPAD PRICING - Ungraduated tokens
+  // Use tokenName for launchpad bonding curve tokens
+  console.log('\\n=== Explicit Launchpad Pricing ===');
+  const launchpadPrice = await sdk.fetchLaunchpadTokenSpotPrice('anime');
+  console.log(\`Launchpad token anime: $\${launchpadPrice}\`);
+
+  // ADVANCED: Handle both pricing methods with error recovery
+  console.log('\\n=== Fallback Pricing Strategy ===');
+  async function getPriceWithFallback(tokenId: string, tokenName?: string) {
+    try {
+      // Try DEX pricing first
+      return await sdk.fetchTokenPrice({ tokenId });
+    } catch (error) {
+      // If not on DEX, try launchpad pricing
+      if (tokenName) {
+        try {
+          return await sdk.fetchLaunchpadTokenSpotPrice(tokenName);
+        } catch (fallbackError) {
+          throw new Error(\`Could not fetch price for \${tokenName}\`);
+        }
+      }
+      throw error;
+    }
+  }
+
+  const fallbackPrice = await getPriceWithFallback(
+    'Token|Unit|ANIME|eth:0x...',
+    'anime'
+  );
+  console.log(\`Fallback price: $\${fallbackPrice}\`);
+
+  // USECASE: Price comparison and discovery
+  console.log('\\n=== Price Discovery ===');
+  async function comparePrices(tokenName: string) {
+    const launchpadPrice = await sdk.fetchLaunchpadTokenSpotPrice(tokenName);
+
+    // Check if graduated (on DEX)
+    const isGraduated = await sdk.isTokenGraduated(tokenName);
+
+    if (isGraduated) {
+      const dexPrice = await sdk.fetchTokenPrice({
+        tokenId: \`Token|Unit|\${tokenName.toUpperCase()}|eth:0x...\`
+      });
+      console.log(\`Launchpad: $\${launchpadPrice}, DEX: $\${dexPrice}\`);
+      return { launchpadPrice, dexPrice, graduated: true };
+    } else {
+      console.log(\`Launchpad: $\${launchpadPrice} (not on DEX yet)\`);
+      return { launchpadPrice, graduated: false };
+    }
+  }
+
+  const priceComparison = await comparePrices('anime');
+}
+\`\`\`
+
+**Smart Routing Benefits:**
+- ✅ **Seamless Transitions** - Works before and after token graduation
+- ✅ **No Backend Knowledge** - SDK handles routing automatically
+- ✅ **Error Handling** - Automatic fallback if needed
+- ✅ **Single API** - Use same method for all tokens
+
+**When to Use Each Method:**
+
+| Method | Use Case | Token Status |
+|--------|----------|--------------|
+| \`fetchTokenPrice({ tokenId })\` | Smart routing (recommended) | Any (DEX or Launchpad) |
+| \`fetchLaunchpadTokenSpotPrice(name)\` | Launchpad-only pricing | Ungraduated tokens |
+| \`isTokenGraduated(name)\` | Check token status | Any |
+
+**Key Differences:**
+
+**Ungraduated Tokens (Launchpad):**
+- Priced on exponential bonding curve
+- Token name parameter works: \`fetchLaunchpadTokenSpotPrice('anime')\`
+- Price affected by supply/demand
+
+**Graduated Tokens (DEX):**
+- Priced on DEX via order books
+- Token ID format needed: \`Token|Unit|SYMBOL|eth:0x...\`
+- Market-driven pricing
+
+**Graduation Impact:**
+When a token graduates from launchpad to DEX:
+- Bonding curve closes
+- Trading moves to DEX order books
+- Smart routing automatically switches backends
+- Old launchpad queries will fail (use DEX pricing instead)
+
+**Error Handling:**
+\`\`\`typescript
+async function safePriceQuery(tokenId: string) {
+  try {
+    // Always try smart routing first
+    return await sdk.fetchTokenPrice({ tokenId });
+  } catch (error) {
+    if (error.message.includes('not found')) {
+      console.log('Token not available on DEX');
+      // Could try fallback to launchpad pricing here
+    }
+    throw error;
+  }
+}
+\`\`\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_fetch_token_spot_price\` - Smart routing
+- \`gala_launchpad_fetch_launchpad_token_spot_price\` - Launchpad-only
+- \`gala_launchpad_is_token_graduated\` - Check graduation status
+`,
+
+  'profile-management': `
+## User Profile Management with SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function manageUserProfiles() {
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key-or-mnemonic'
+  });
+
+  // Fetch current user profile
+  const myProfile = await sdk.fetchProfile();
+  console.log(\`Name: \${myProfile.fullName}\`);
+  console.log(\`Avatar: \${myProfile.profileImage}\`);
+
+  // Fetch another user's profile
+  const other = await sdk.fetchProfile('eth|0x...');
+  console.log(\`Other user: \${other.fullName}\`);
+
+  // Update profile
+  const updated = await sdk.updateProfile({
+    fullName: 'Satoshi Nakamoto',
+    profileImage: 'https://example.com/avatar.png',
+    address: sdk.getAddress()
+  });
+
+  console.log(\`Updated: \${updated.fullName}\`);
+
+  // Upload profile image (Node.js only)
+  const imgResult = await sdk.uploadProfileImage({
+    imagePath: '/path/to/avatar.png'
+  });
+
+  // Update with uploaded image
+  await sdk.updateProfile({
+    fullName: 'My Name',
+    profileImage: imgResult.imageUrl,
+    address: sdk.getAddress()
+  });
+
+  // Complete workflow: Update profile, then launch token
+  async function createTokenWithProfile() {
+    const avatar = await sdk.uploadProfileImage({
+      imagePath: '/path/to/pic.png'
+    });
+
+    await sdk.updateProfile({
+      fullName: 'Token Creator',
+      profileImage: avatar.imageUrl,
+      address: sdk.getAddress()
+    });
+
+    const logo = await sdk.uploadTokenImage({
+      tokenName: 'mytoken',
+      imagePath: '/path/to/logo.png'
+    });
+
+    const result = await sdk.launchToken({
+      tokenName: 'mytoken',
+      tokenSymbol: 'MTK',
+      tokenDescription: 'Awesome token',
+      tokenImage: logo.imageUrl,
+      websiteUrl: 'https://mytoken.com'
+    });
+
+    return result;
+  }
+
+  // Batch profile fetching
+  const addresses = ['eth|0xaddress1', 'eth|0xaddress2'];
+  const profiles = await Promise.all(
+    addresses.map(addr => sdk.fetchProfile(addr).catch(() => null))
+  );
+
+  console.log('Profiles:', profiles.filter(p => p).map(p => p.fullName));
+}
+\`\`\`
+
+**Profile Methods:**
+- \`fetchProfile(address?)\` - Get user profile
+- \`updateProfile(data)\` - Update profile info
+- \`uploadProfileImage(options)\` - Upload avatar (Node.js)
+
+**Profile Fields:**
+- \`fullName\` - Display name (max 100 chars)
+- \`profileImage\` - Avatar image URL
+- \`address\` - Wallet address
+- \`createdAt\` - Creation date
+- \`updatedAt\` - Update timestamp
+
+**Use Cases:**
+- Display user profiles
+- Allow profile customization
+- Manage profile images
+- Token creator attribution
+- Multi-wallet profiles
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_fetch_profile\`
+- \`gala_launchpad_update_profile\`
+- \`gala_launchpad_upload_profile_image\`
+`,
+
+  'token-distribution': `
+## Token Holder Distribution with SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function analyzeTokenDistribution() {
+  const sdk = createLaunchpadSDK({
+    wallet: 'your-private-key-or-mnemonic'
+  });
+
+  // Fetch complete token distribution (all holders, non-paginated)
+  const distribution = await sdk.fetchTokenDistribution('anime');
+
+  console.log(\`Total holders: \${distribution.totalHolders}\`);
+  console.log(\`Total supply: \${distribution.totalSupply}\`);
+  console.log(\`Last updated: \${distribution.lastUpdated.toISOString()}\`);
+
+  // Analyze top holders
+  distribution.holders
+    .sort((a, b) => parseFloat(b.balance) - parseFloat(a.balance))
+    .slice(0, 5)
+    .forEach((holder, index) => {
+      console.log(\`#\${index + 1}: \${holder.address}\`);
+      console.log(\`  Balance: \${holder.balance}\`);
+      console.log(\`  Ownership: \${holder.percentage.toFixed(2)}%\`);
+    });
+
+  // Check concentration risk (e.g., top 5 holders own >80%)
+  const top5Ownership = distribution.holders
+    .sort((a, b) => parseFloat(b.balance) - parseFloat(a.balance))
+    .slice(0, 5)
+    .reduce((sum, holder) => sum + holder.percentage, 0);
+
+  console.log(\`Top 5 holders control: \${top5Ownership.toFixed(2)}%\`);
+
+  // Find specific holder
+  const myAddress = sdk.getAddress();
+  const myHolding = distribution.holders.find(h => h.address === myAddress);
+
+  if (myHolding) {
+    console.log(\`Your ownership: \${myHolding.percentage.toFixed(4)}%\`);
+    console.log(\`Your balance: \${myHolding.balance}\`);
+  }
+
+  // Calculate concentration metrics
+  const giniCoefficient = calculateGini(distribution.holders);
+  console.log(\`Gini coefficient: \${giniCoefficient.toFixed(4)}\`);
+
+  // Count whales (holders with >5%)
+  const whales = distribution.holders.filter(h => h.percentage > 5);
+  console.log(\`Whales (>5%): \${whales.length}\`);
+}
+
+// Helper: Calculate Gini coefficient for wealth distribution
+function calculateGini(holders: Array<{balance: string}>) {
+  const balances = holders.map(h => parseFloat(h.balance)).sort((a, b) => a - b);
+  const n = balances.length;
+  const sum = balances.reduce((a, b) => a + b, 0);
+
+  let numerator = 0;
+  for (let i = 0; i < n; i++) {
+    numerator += (2 * (i + 1) - n - 1) * balances[i];
+  }
+
+  return numerator / (n * sum);
+}
+\`\`\`
+
+**Key Characteristics:**
+- **Non-Paginated**: Returns ALL token holders in single response (no pagination)
+- **Complete Distribution**: Full holder list with addresses, balances, and ownership percentages
+- **BigNumber Precision**: Uses BigNumber.js for accurate percentage calculations
+- **Total Supply**: Computed from holder balances (sum of all holdings)
+- **Service Account Included**: Vault/service accounts appear in holder list
+
+**Use Cases:**
+- Analyze token concentration risk
+- Identify whale holders
+- Track ownership changes over time
+- Generate holder reports
+- Calculate distribution metrics (Gini coefficient, etc.)
+
+**MCP Tool Equivalent:** \`gala_launchpad_fetch_token_distribution\`
+`,
+
+  'liquidity-positions': `
+## GSwap Liquidity Position Management
+
+Provide liquidity on GalaSwap DEX and earn passive trading fees from swaps.
+
+**Overview:** Concentrated liquidity allows capital deployment within specific price ranges. Liquidity providers earn fees when trades occur within their price range, making it an attractive passive income strategy.
+
+**8 Core SDK Methods:**
+
+1. **getSwapUserLiquidityPositions(ownerAddress, limit?, bookmark?)** - View all open positions for wallet
+   - Returns: Array of positions with token pairs, amounts, accumulated fees
+
+2. **getSwapLiquidityPositionById(ownerAddress, positionId)** - Get specific position by UUID
+
+3. **getSwapLiquidityPosition(ownerAddress, position)** - Get position by token pair and tick range
+
+4. **addSwapLiquidityByPrice(args)** - Create position using user-friendly price ranges
+   - params: token0, token1, fee, minPrice, maxPrice, amount0Desired, amount1Desired
+
+5. **addSwapLiquidityByTicks(args)** - Create position using precise tick boundaries (advanced)
+
+6. **getSwapEstimateRemoveLiquidity(args)** - Preview removal amounts before executing
+   - Returns: estimated token amounts and accumulated fees
+
+7. **removeSwapLiquidity(args)** - Close or reduce position with slippage protection
+   - Removes liquidity and collects accumulated fees
+
+8. **collectSwapPositionFees(args)** - Harvest accumulated fees without closing position
+   - Passive income collection
+
+**Fee Tiers:** 500 bps (0.05%), 3000 bps (0.30%), 10000 bps (1.00%)
+
+**MCP Tools (8 tools):**
+- gala_launchpad_get_user_liquidity_positions
+- gala_launchpad_get_liquidity_position_by_id
+- gala_launchpad_get_liquidity_position
+- gala_launchpad_add_liquidity_by_price
+- gala_launchpad_add_liquidity_by_ticks
+- gala_launchpad_estimate_remove_liquidity
+- gala_launchpad_remove_liquidity
+- gala_launchpad_collect_position_fees
+
+**Slash Commands (4 commands):**
+- /galachain-launchpad:my-positions - View all positions
+- /galachain-launchpad:add-liquidity - Create position
+- /galachain-launchpad:remove-liquidity - Close position
+- /galachain-launchpad:collect-fees - Harvest fees
+
+**Demo Script:** See packages/sdk/examples/demo-liquidity-positions.ts for complete workflows
+`,
+
+};
+
+/**
+ * SDK Usage Explanation Tool
+ */
+export const explainSdkUsageTool: MCPTool = {
+  name: 'gala_launchpad_explain_sdk_usage',
+  description: 'Get detailed SDK code examples for: buy-tokens, sell-tokens, pool-graduation, fetch-pools, balances, dex-trading, liquidity-positions, price-history, token-details, token-distribution, token-creation, profile-management, multi-wallet, transfers, error-handling, installation, local-calculations, mcp-to-sdk-mapping',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      topic: {
+        type: 'string',
+        enum: [
+          'buy-tokens',
+          'sell-tokens',
+          'pool-graduation',
+          'fetch-pools',
+          'balances',
+          'dex-trading',
+          'liquidity-positions',
+          'price-history',
+          'token-details',
+          'token-distribution',
+          'token-creation',
+          'profile-management',
+          'multi-wallet',
+          'transfers',
+          'error-handling',
+          'installation',
+          'local-calculations',
+          'mcp-to-sdk-mapping',
+        ],
+        description: 'The SDK usage topic to explain',
+      },
+    },
+    required: ['topic'],
+  },
+  handler: withErrorHandling(async (_sdk, args) => {
+    const example = SDK_EXAMPLES[args.topic as keyof typeof SDK_EXAMPLES];
+
+    if (!example) {
+      throw new Error('Unknown topic: ' + args.topic);
+    }
+
+    return formatSuccess({
+      topic: args.topic,
+      explanation: example,
+      sdkVersion: '3.19.0',
+      packageName: '@gala-chain/launchpad-sdk',
+      documentation: 'https://www.npmjs.com/package/@gala-chain/launchpad-sdk',
+    });
+  }),
+};