@gala-chain/launchpad-mcp-server 1.7.2 → 1.7.4

package/src/tools/utils/explainSdkUsage.ts

@@ -0,0 +1,765 @@
+/**
+ * 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 SDK
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function fetchPools() {
+  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\`);
+  console.log(\`Page \${pools.page} of \${pools.totalPages}\`);
+  console.log(\`Has next page: \${pools.hasNext}\`);
+
+  pools.pools.forEach(pool => {
+    console.log(\`\${pool.tokenName}: \${pool.tokenSymbol}\`);
+    console.log(\`Creator: \${pool.creatorAddress}\`);
+    console.log(\`Created: \${pool.createdAt}\`);
+  });
+
+  // Fetch specific pool details
+  const details = await sdk.fetchPoolDetails('dragnrkti');
+
+  console.log('Sale status:', details.saleStatus);
+  console.log('Base price:', details.basePrice);
+  console.log('Max supply:', details.maxSupply);
+  console.log('Native token quantity:', details.nativeTokenQuantity);
+}
+\`\`\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_fetch_pools\`
+- \`gala_launchpad_fetch_pool_details\`
+`,
+
+  '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}\`);
+  });
+}
+\`\`\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_fetch_gala_balance\`
+- \`gala_launchpad_fetch_token_balance\`
+- \`gala_launchpad_fetch_tokens_held\`
+`,
+
+  '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);
+
+    } catch 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\`
+`,
+
+  '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_graduate_token\` | \`sdk.graduateToken(options)\` | One-step pool graduation |
+
+### Pool Management
+| MCP Tool | SDK Method | Notes |
+|----------|------------|-------|
+| \`gala_launchpad_fetch_pools\` | \`sdk.fetchPools(options)\` | List pools with filtering |
+| \`gala_launchpad_fetch_pool_details\` | \`sdk.fetchPoolDetails(tokenName)\` | Get specific pool data |
+| \`gala_launchpad_fetch_token_distribution\` | \`sdk.fetchTokenDistribution(tokenName)\` | Holder distribution |
+| \`gala_launchpad_fetch_token_badges\` | \`sdk.fetchTokenBadges(tokenName)\` | Achievement badges |
+
+### 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 |
+
+### 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
+- 'token-creation' - Launch new tokens
+- '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
+
+Returns runnable TypeScript code examples with explanations.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      topic: {
+        type: 'string',
+        enum: [
+          'buy-tokens',
+          'sell-tokens',
+          'pool-graduation',
+          'fetch-pools',
+          'balances',
+          'token-creation',
+          '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.8.0',
+      packageName: '@gala-chain/launchpad-sdk',
+      documentation: 'https://www.npmjs.com/package/@gala-chain/launchpad-sdk',
+    });
+  }),
+};