@gala-chain/launchpad-mcp-server 1.14.1 → 1.14.2

package/src/tools/utils/explainSdkUsage.ts

@@ -0,0 +1,1277 @@
+/**
+ * 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.fetchTokenSpotPrice(['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\`
+`,
+
+  '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
+// Development (default)
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key',
+  config: {
+    baseUrl: 'https://lpad-backend-dev1.defi.gala.com',
+    debug: true
+  }
+});
+
+// Production
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key',
+  config: {
+    baseUrl: 'https://lpad-backend-prod1.defi.gala.com',
+    debug: false,
+    timeout: 60000
+  }
+});
+\`\`\`
+`,
+
+  '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\`
+`,
+
+  '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\`
+`,
+
+  'mcp-to-sdk-mapping': `
+## MCP Tool to SDK Method Mapping
+
+### Trading Operations
+| MCP Tool | SDK Method | Notes |
+|----------|------------|-------|
+| \`gala_launchpad_calculate_buy_amount\` | \`sdk.calculateBuyAmount(options)\` | Get quote before buying |
+| \`gala_launchpad_calculate_buy_amount_local\` | \`sdk.calculateBuyAmountLocal(options)\` | Local instant quote (buy) |
+| \`gala_launchpad_calculate_buy_amount_external\` | \`sdk.calculateBuyAmountExternal(options)\` | Explicit network quote (buy) |
+| \`gala_launchpad_calculate_sell_amount\` | \`sdk.calculateSellAmount(options)\` | Get quote before selling |
+| \`gala_launchpad_calculate_sell_amount_local\` | \`sdk.calculateSellAmountLocal(options)\` | Local instant quote (sell) |
+| \`gala_launchpad_calculate_sell_amount_external\` | \`sdk.calculateSellAmountExternal(options)\` | Explicit network quote (sell) |
+| \`gala_launchpad_buy_tokens\` | \`sdk.buy(options)\` | Execute token purchase |
+| \`gala_launchpad_sell_tokens\` | \`sdk.sell(options)\` | Execute token sale |
+| \`gala_launchpad_calculate_buy_amount_for_graduation\` | \`sdk.calculateBuyAmountForGraduation(options)\` | Calculate graduation cost |
+| \`gala_launchpad_graduate_token\` | \`sdk.graduateToken(options)\` | One-step pool graduation |
+| \`gala_launchpad_fetch_trades\` | \`sdk.fetchTrades(options)\` | Get trade history |
+| \`gala_launchpad_get_bundler_transaction_result\` | \`sdk.getBundlerTransactionResult(txId)\` | Get transaction result |
+
+### Pool Management
+| MCP Tool | SDK Method | Notes |
+|----------|------------|-------|
+| \`gala_launchpad_fetch_pools\` | \`sdk.fetchPools(options)\` | List pools with filtering |
+| \`gala_launchpad_fetch_all_pools\` | \`sdk.fetchAllPools(options)\` | Auto-paginated all pools |
+| \`gala_launchpad_fetch_pool_details\` | \`sdk.fetchPoolDetails(tokenName)\` | Get specific pool data |
+| \`gala_launchpad_fetch_pool_details_for_calculation\` | \`sdk.fetchPoolDetailsForCalculation(tokenName)\` | Optimized for calculations |
+| \`gala_launchpad_fetch_token_distribution\` | \`sdk.fetchTokenDistribution(tokenName)\` | Holder distribution |
+| \`gala_launchpad_fetch_token_badges\` | \`sdk.fetchTokenBadges(tokenName)\` | Achievement badges |
+| \`gala_launchpad_fetch_volume_data\` | \`sdk.fetchVolumeData(options)\` | OHLCV candlestick data |
+| \`gala_launchpad_fetch_token_spot_price\` | \`sdk.fetchTokenSpotPrice(symbols)\` | DEX token spot prices |
+| \`gala_launchpad_fetch_launchpad_token_spot_price\` | \`sdk.fetchLaunchpadTokenSpotPrice(options)\` | Launchpad token price |
+| \`gala_launchpad_resolve_vault_address\` | \`sdk.resolveVaultAddress(tokenName)\` | Get vault address |
+| \`gala_launchpad_resolve_token_class_key\` | \`sdk.resolveTokenClassKey(tokenName)\` | Get TokenClassKey |
+| \`gala_launchpad_fetch_token_details\` | \`sdk.fetchTokenDetails(tokenId)\` | Comprehensive token metadata |
+
+### Price History & Analysis
+| MCP Tool | SDK Method | Notes |
+|----------|------------|-------|
+| \`gala_launchpad_fetch_price_history\` | \`sdk.fetchPriceHistory(options)\` | Paginated price snapshots |
+| \`gala_launchpad_fetch_all_price_history\` | \`sdk.fetchAllPriceHistory(options)\` | Auto-paginated all prices |
+
+### Balance & Portfolio
+| MCP Tool | SDK Method | Notes |
+|----------|------------|-------|
+| \`gala_launchpad_fetch_gala_balance\` | \`sdk.fetchGalaBalance(address?)\` | GALA balance |
+| \`gala_launchpad_fetch_token_balance\` | \`sdk.fetchTokenBalance(options)\` | Specific token balance |
+| \`gala_launchpad_fetch_tokens_held\` | \`sdk.fetchTokensHeld(options)\` | Portfolio holdings |
+| \`gala_launchpad_fetch_tokens_created\` | \`sdk.fetchTokensCreated(options)\` | Created tokens |
+| \`gala_launchpad_fetch_profile\` | \`sdk.fetchProfile(address?)\` | User profile |
+| \`gala_launchpad_update_profile\` | \`sdk.updateProfile(data)\` | Update profile |
+| \`gala_launchpad_upload_profile_image\` | \`sdk.uploadProfileImage(options)\` | Upload avatar |
+
+### Profile Management
+| MCP Tool | SDK Method | Notes |
+|----------|------------|-------|
+| \`gala_launchpad_fetch_profile\` | \`sdk.fetchProfile(address?)\` | Get user profile |
+| \`gala_launchpad_update_profile\` | \`sdk.updateProfile(data)\` | Update profile info |
+| \`gala_launchpad_upload_profile_image\` | \`sdk.uploadProfileImage(options)\` | Upload profile image |
+
+### Token Creation
+| MCP Tool | SDK Method | Notes |
+|----------|------------|-------|
+| \`gala_launchpad_fetch_launch_token_fee\` | \`sdk.fetchLaunchTokenFee()\` | Get launch cost |
+| \`gala_launchpad_check_token_name\` | \`sdk.isTokenNameAvailable(name)\` | Check name |
+| \`gala_launchpad_check_token_symbol\` | \`sdk.isTokenSymbolAvailable(symbol)\` | Check symbol |
+| \`gala_launchpad_launch_token\` | \`sdk.launchToken(data)\` | Create token |
+| \`gala_launchpad_upload_token_image\` | \`sdk.uploadTokenImage(options)\` | Upload image |
+
+### Transfers & Social
+| MCP Tool | SDK Method | Notes |
+|----------|------------|-------|
+| \`gala_launchpad_transfer_gala\` | \`sdk.transferGala(options)\` | Transfer GALA |
+| \`gala_launchpad_transfer_token\` | \`sdk.transferToken(options)\` | Transfer tokens |
+| \`gala_launchpad_post_comment\` | \`sdk.postComment(options)\` | Post comment |
+| \`gala_launchpad_fetch_comments\` | \`sdk.fetchComments(options)\` | Get comments |
+
+### Utilities
+| MCP Tool | SDK Method | Notes |
+|----------|------------|-------|
+| \`gala_launchpad_create_wallet\` | \`createWallet()\` | Generate wallet |
+| \`gala_launchpad_get_address\` | \`sdk.getAddress()\` | Get backend format |
+| \`gala_launchpad_get_ethereum_address\` | \`sdk.getEthereumAddress()\` | Get 0x format |
+| \`gala_launchpad_get_url_by_token_name\` | \`sdk.getUrlByTokenName(name)\` | Frontend URL |
+| \`gala_launchpad_is_token_graduated\` | \`sdk.isTokenGraduated(tokenName)\` | Check if pool completed |
+
+**Key Difference:** MCP tools return \`{ success: true, data: {...} }\`, SDK methods return direct result objects.
+`,
+};
+
+/**
+ * SDK Usage Explanation Tool
+ */
+export const explainSdkUsageTool: MCPTool = {
+  name: 'gala_launchpad_explain_sdk_usage',
+  description: `Get detailed SDK code examples and explanations for using the Gala Launchpad SDK directly.
+
+This tool provides complete, working code examples showing how to use the SDK instead of MCP tools.
+Perfect for developers who want to integrate the SDK into their applications.
+
+Available topics:
+- 'buy-tokens' - Complete buying workflow with calculation and execution
+- 'sell-tokens' - Complete selling workflow with slippage protection
+- 'pool-graduation' - Graduate a bonding curve pool
+- 'fetch-pools' - Query pool data and details
+- 'balances' - Check GALA and token balances
+- 'price-history' - Historical price analysis and technical analysis
+- 'token-details' - Comprehensive token metadata and validation
+- 'token-distribution' - Analyze token holder distribution and concentration
+- 'token-creation' - Launch new tokens
+- 'profile-management' - User profile management and customization
+- 'multi-wallet' - Use multiple wallets (privateKey override pattern)
+- 'transfers' - Transfer GALA and tokens between wallets
+- 'error-handling' - Handle errors and exceptions
+- 'installation' - Install and configure SDK
+- 'local-calculations' - Local vs external bonding curve calculations
+- 'mcp-to-sdk-mapping' - Complete mapping of MCP tools to SDK methods (56+ tools)
+
+Returns runnable TypeScript code examples with explanations.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      topic: {
+        type: 'string',
+        enum: [
+          'buy-tokens',
+          'sell-tokens',
+          'pool-graduation',
+          'fetch-pools',
+          'balances',
+          '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',
+    });
+  }),
+};