@gala-chain/launchpad-mcp-server 5.0.5-beta.9 → 5.1.1

package/dist/tools/utils/explainSdkUsage.js

@@ -6,7 +6,8 @@
  * Acts as a development reference showing how MCP tools map to SDK methods.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.explainSdkUsageTool = exports.SDK_EXAMPLES = exports.COMPOSITE_TOPICS = exports.TOPIC_METHOD_MAPPING = void 0;
+exports.explainSdkUsageTool = exports.SDK_EXAMPLE_TOPICS = exports.SDK_EXAMPLES = exports.COMPOSITE_TOPICS = exports.TOPIC_METHOD_MAPPING = void 0;
+exports.isValidSdkTopic = isValidSdkTopic;
 const error_handler_js_1 = require("../../utils/error-handler.js");
 const response_formatter_js_1 = require("../../utils/response-formatter.js");
 // BigNumber utilities for precise currency handling (imported from SDK)
@@ -33,12 +34,18 @@ exports.TOPIC_METHOD_MAPPING = {
     'token-details': ['fetchTokenDetails'],
     'token-distribution': ['fetchTokenDistribution', 'fetchUserHolderContext'],
     'token-status': ['isTokenGraduated', 'onDexPoolCreation', 'onLaunchpadTokenCreation'],
-    // Portfolio Management
-    'multi-wallet': ['getAddress'], // Composite workflow topic
+    // Wallet Connection
+    'wallet-connect': ['getAddress', 'createWallet', 'getEthereumAddress'],
+    'multi-wallet': ['getAddress', 'createWallet', 'createSolanaWallet', 'getEthereumAddress', 'getPublicKeyFromPrivateKey', 'getEthereumAddressFromPrivateKey'],
     'transfers': ['transferGala', 'transferToken'],
     'locks': ['lockTokens', 'unlockTokens', 'burnTokens', 'fetchLockedBalance'],
     // DEX Trading
     'dex-trading': ['getSwapQuoteExactInput', 'getSwapQuoteExactOutput', 'executeSwap', 'getSwapUserAssets', 'getAllSwapUserAssets', 'getSwapPoolInfo'],
+    'gdex-stream': [
+        'connect', 'disconnect', 'isConnected', 'request', 'serverInfo', 'ping',
+        'getPool', 'getBalance', 'getPositions', 'getBlockHeight', 'quote', 'getToken',
+        'subscribeSwaps', 'subscribePool', 'subscribeBalances', 'subscribePoolCreated', 'subscribeBlocks'
+    ],
     'error-handling': ['getBundlerTransactionResult'], // Cross-cutting concern
     // Developer Tools
     'installation': ['getVersion'], // Setup topic
@@ -63,7 +70,7 @@ exports.TOPIC_METHOD_MAPPING = {
     'fetch-dex-aggregated-volume-summary': ['fetchDexAggregatedVolumeSummary'],
     'fetch-dex-pools': ['fetchDexPools', 'fetchAllDexPools'],
     // Event Subscriptions
-    'event-subscriptions': ['subscribeToStream', 'unsubscribeFromStream', 'onStreamStatusChanged', 'onUserBanned', 'onUserUnbanned', 'onBanEnforcement', 'onContentFlagged', 'onFlagResolved', 'onStreamChatMessage', 'onStreamChatUpdated', 'onStreamChatDeleted', 'onStreamChatPinned', 'onStreamChatUnpinned', 'onChatStatusChanged', 'onViewerCountChanged', 'onRecordingStatusChanged', 'onSimulcastStatusChanged', 'onDownloadReady', 'onUserTyping', 'onStreamReaction', 'onContentReactionAdded', 'onContentReactionRemoved', 'onStreamCountdownUpdated', 'onStreamLanguageUpdated', 'onStreamControlStatusChanged', 'onConnection', 'onAuthenticated', 'onTokenSubscribed', 'onTokenUnsubscribed', 'onRoomSubscribed', 'onRoomLeft', 'onDexPoolCreation', 'onLaunchpadTokenCreation'],
+    'event-subscriptions': ['subscribeToStream', 'unsubscribeFromStream', 'onStreamStatusChanged', 'onUserBanned', 'onUserUnbanned', 'onBanEnforcement', 'onContentFlagged', 'onFlagResolved', 'onStreamChatMessage', 'onStreamChatUpdated', 'onStreamChatDeleted', 'onStreamChatPinned', 'onStreamChatUnpinned', 'onChatStatusChanged', 'onViewerCountChanged', 'onRecordingStatusChanged', 'onSimulcastStatusChanged', 'onDownloadReady', 'onUserTyping', 'onStreamReaction', 'onContentReactionAdded', 'onContentReactionRemoved', 'onStreamCountdownUpdated', 'onStreamLanguageUpdated', 'onStreamControlStatusChanged', 'onConnection', 'onAuthenticated', 'onTokenSubscribed', 'onTokenUnsubscribed', 'onRoomSubscribed', 'onRoomLeft', 'onDexPoolCreation', 'onLaunchpadTokenCreation', 'onEngagementStatsUpdated'],
     // MCP Integration
     'mcp-to-sdk-mapping': ['explainSdkUsage'], // Composite workflow topic
     // Bridge Operations
@@ -94,10 +101,6 @@ exports.TOPIC_METHOD_MAPPING = {
     'referral-system': [
         'fetchReferralUrl', 'fetchReferrals', 'fetchAllReferrals', 'fetchReferralsSummary'
     ],
-    // Account Management
-    'account-management': [
-        'registerAccount'
-    ],
     // Session Authentication (JWT)
     'session-auth': [
         'login', 'logout', 'refreshToken', 'getSession', 'isAuthenticated',
@@ -137,7 +140,8 @@ exports.TOPIC_METHOD_MAPPING = {
     'overseer-invites': [
         'createOverseerInvite', 'claimOverseerInvite', 'listOverseerInvites',
         'getOverseerInviteByCode', 'revokeOverseerInvite', 'listOverseers',
-        'revokeOverseer', 'getMyOverseerStatus', 'getOverseerSummary'
+        'revokeOverseer', 'getMyOverseerStatus', 'getOverseerSummary',
+        'getBanStats', 'getTokenBanStats', 'getInviteStats', 'getFlagStats', 'getUserStats'
     ],
     // Content Moderation (Flags & Comments)
     'content-flag-management': [
@@ -152,7 +156,7 @@ exports.TOPIC_METHOD_MAPPING = {
     ],
     // Trade History Queries
     'trade-history': [
-        'getTrades'
+        'getTrades', 'getRecentTrades'
     ],
     // Token Ban Management (Platform-wide, Overseer Only)
     'token-ban-management': [
@@ -166,6 +170,71 @@ exports.TOPIC_METHOD_MAPPING = {
         'createNftTokenClass', 'fetchNftTokenClasses',
         'mintNft', 'fetchNftBalances'
     ],
+    // Token Identification & Format Concepts (v5.14.0+)
+    // These are conceptual topics that help AI understand token formats
+    'token-identification': [
+        'fetchPools', 'isTokenGraduated', 'resolveTokenClassKey', 'fetchTokenPrice'
+    ],
+    'graduation-detection': [
+        'isTokenGraduated', 'fetchPools', 'onDexPoolCreation', 'onLaunchpadTokenCreation'
+    ],
+    // AI Moderation (Overseer Only)
+    'ai-moderation': [
+        'getAIModerationSettings', 'updateAIModerationSettings', 'getAIModeration',
+        'triggerAIModeration', 'getAIModerationStatus'
+    ],
+    // Weekly Challenge Leaderboard
+    'weekly-challenge': [
+        'getWeeklyChallengeLeaderboard', 'getTokenWeeklyHistory'
+    ],
+    // Platform Statistics
+    'platform-stats': [
+        'getPlatformStats'
+    ],
+    // Restricted Names (Overseer Only)
+    'restricted-names': [
+        'getRestrictedNames', 'updateRestrictedNames'
+    ],
+    // WebSocket Admin (Overseer/Admin Only)
+    'websocket-admin': [
+        'emitTradeExecuted', 'emitBalanceUpdated', 'emitStreamStatus', 'emitViewerCount',
+        'emitStreamCountdown', 'emitChatMessage', 'emitChatStatus', 'emitTypingIndicator',
+        'emitTokenBanned', 'emitTokenUnbanned', 'emitModeratorAdded', 'emitModeratorRemoved',
+        'emitUserProfileUpdated', 'emitSiteConfigChanged', 'emitFeatureStatus',
+        'getConnectedClients', 'isUserOnline', 'getOnlineUsers', 'getTokenViewers', 'getOnlineOverseers'
+    ],
+    // OEmbed Metadata (Social Media Previews)
+    'oembed': [
+        'getHomeOEmbed', 'getPoolOEmbed', 'getProfileOEmbed'
+    ],
+    // Unified Messages API (CHAT + COMMENT types)
+    'messages': [
+        'fetchMessages', 'createMessage', 'updateMessage', 'deleteMessage',
+        'getPinnedMessage', 'pinMessage', 'unpinMessage', 'getMessageStats'
+    ],
+    // Holder Data Queries (Derived from Distribution + Trade Data)
+    'holders': [
+        'fetchTokenDistribution', 'getTrades',
+        'getTopHolders', 'getHolderCount', 'getHolderRank', 'getHoldersByBalance', 'getHolderHistory'
+    ],
+    // Trading Quotes (Backend Proxy, v9.1.0+)
+    'trading-quotes': [
+        'fetchLaunchpadFee', 'fetchSaleDetails', 'getTradeQuote', 'getPremintQuote'
+    ],
+    // Global Feed Reference (MCP documentation tools)
+    'global-feed-subscription': [
+        'subscribeToStream'
+    ],
+    // Events Tracking (Client-side batching + backend persistence)
+    'events-tracking': [],
+    // Global Ban Management (Platform-wide, Overseer Only)
+    'global-bans': [
+        'createGlobalBan', 'removeGlobalBan', 'listGlobalBans', 'getGlobalBan'
+    ],
+    // Recent Trades (Convenience wrapper)
+    'recent-trades': [
+        'getRecentTrades', 'getTrades'
+    ],
 };
 /**
  * Composite topics that don't map 1:1 to SDK methods
@@ -173,7 +242,7 @@ exports.TOPIC_METHOD_MAPPING = {
  */
 exports.COMPOSITE_TOPICS = new Set([
     'buy-tokens', 'sell-tokens', 'pool-graduation', 'fetch-pools', 'balances',
-    'token-creation', 'token-status', 'multi-wallet', 'transfers', 'locks', 'dex-trading', 'error-handling',
+    'token-creation', 'token-status', 'wallet-connect', 'multi-wallet', 'transfers', 'locks', 'dex-trading', 'gdex-stream', 'error-handling',
     'installation', 'local-calculations', 'price-history', 'token-details',
     'spot-prices-smart-routing', 'profile-management', 'token-distribution',
     'liquidity-positions', 'advanced-dex-analysis',
@@ -184,6 +253,13 @@ exports.COMPOSITE_TOPICS = new Set([
     'session-auth', 'streaming', 'stream-chat', 'ban-management', 'api-key-management',
     'moderator-invites', 'overseer-invites', 'content-flag-management', 'content-reactions', 'trade-history', 'token-ban-management',
     'nft-collection-management',
+    // Token Concepts (v5.14.0+)
+    'token-identification', 'graduation-detection',
+    // New Categories (v7.0.0+)
+    'ai-moderation', 'weekly-challenge', 'platform-stats', 'restricted-names',
+    'websocket-admin', 'oembed', 'messages', 'holders',
+    // Trading & Events (v9.1.0+)
+    'trading-quotes', 'global-feed-subscription', 'events-tracking', 'global-bans', 'recent-trades',
 ]);
 /**
  * SDK code examples organized by topic
@@ -620,63 +696,491 @@ async function launchToken() {
 - \`gala_launchpad_get_url_by_token_name\`
 `,
     // ============================================================================
-    // PORTFOLIO MANAGEMENT: Multi-Wallet & Transfers
+    // WALLET CONNECTION & MANAGEMENT
     // ============================================================================
-    // - multi-wallet: Manage multiple wallets and sessions
+    // - wallet-connect: Quick start guide for connecting wallets (beginner)
+    // - multi-wallet: Full wallet provider system reference (advanced)
     // - transfers: Send GALA and tokens to other addresses
     // ============================================================================
+    'wallet-connect': `
+## How to Connect Your Wallet
+
+The fastest way to add wallet connection to your dapp. Supports 13 browser wallets, React hooks, and Node.js.
+
+---
+
+### React (3 Steps)
+
+**Step 1: Wrap your app**
+
+\`\`\`tsx
+import { WalletProvider } from '@gala-chain/launchpad-sdk/react';
+
+function App() {
+  return (
+    <WalletProvider autoDetect>
+      <YourApp />
+    </WalletProvider>
+  );
+}
+\`\`\`
+
+**Step 2: Detect and connect**
+
+\`\`\`tsx
+import { useWalletDetection, useWalletConnection } from '@gala-chain/launchpad-sdk/react';
+
+function WalletPicker() {
+  const { wallets, isDetecting } = useWalletDetection();
+  const { connectDetected, isConnecting } = useWalletConnection();
+
+  if (isDetecting) return <p>Scanning for wallets...</p>;
+
+  return (
+    <div>
+      {wallets.map(wallet => (
+        <button key={wallet.id} onClick={() => connectDetected(wallet)} disabled={isConnecting}>
+          <img src={wallet.icon} alt="" width={24} /> {wallet.name}
+        </button>
+      ))}
+    </div>
+  );
+}
+\`\`\`
+
+**Step 3: Use wallet state**
+
+\`\`\`tsx
+import { useWallet, useGalaAddress, useWalletProvider } from '@gala-chain/launchpad-sdk/react';
+
+function Dashboard() {
+  const { isConnected, address } = useWallet();
+  const galaAddress = useGalaAddress();       // eth|0x... format
+  const provider = useWalletProvider();
+
+  if (!isConnected) return <WalletPicker />;
+
+  // Sign a message
+  const sig = await provider.signMessage('Hello from my dapp');
+
+  // Sign EIP-712 typed data (required for GalaChain transactions)
+  const typedSig = await provider.signTypedData(domain, types, value);
+}
+\`\`\`
+
+---
+
+### Node.js / CLI
+
+\`\`\`typescript
+import { PrivateKeyProvider } from '@gala-chain/launchpad-sdk/wallet';
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const provider = new PrivateKeyProvider('0xYOUR_PRIVATE_KEY');
+const sdk = createLaunchpadSDK({ walletProvider: provider, environment: 'production' });
+
+const address = await provider.getAddress();       // 0x checksummed
+const galaAddr = await provider.getGalaAddress();  // eth|{40-hex}
+\`\`\`
+
+---
+
+### Vanilla Browser (no React)
+
+\`\`\`typescript
+import { detectWallets, ExternalWalletProvider } from '@gala-chain/launchpad-sdk/wallet';
+
+const { wallets, primary, hasWallets } = await detectWallets();
+if (hasWallets) {
+  const provider = new ExternalWalletProvider(primary.provider);
+  const address = await provider.connect();  // triggers wallet popup
+  const sig = await provider.signMessage('Hello');
+  await provider.disconnect();
+}
+\`\`\`
+
+---
+
+### Supported Wallets (EIP-6963)
+
+MetaMask, Coinbase Wallet, Trust Wallet, Phantom, Rainbow, OKX, Rabby, Brave, Frame, Ledger, Zerion, Gala Wallet, MetaMask Flask.
+
+Falls back to \`window.ethereum\` if no EIP-6963 announcements received.
+
+### React Hooks
+
+| Hook | Returns |
+|------|---------|
+| \`useWallet()\` | isConnected, address, galaAddress, provider, error |
+| \`useWalletAddress()\` | string (0x...) or null |
+| \`useGalaAddress()\` | string (eth|...) or null |
+| \`useWalletProvider()\` | WalletProvider instance or null |
+| \`useWalletConnection()\` | connectDetected(), disconnect(), isConnecting |
+| \`useWalletDetection()\` | wallets[], isDetecting, refreshWallets() |
+
+### Import Paths
+
+\`\`\`typescript
+// React hooks
+import { WalletProvider, useWallet, useWalletDetection } from '@gala-chain/launchpad-sdk/react';
+
+// Low-level providers (non-React)
+import { PrivateKeyProvider, ExternalWalletProvider, detectWallets } from '@gala-chain/launchpad-sdk/wallet';
+\`\`\`
+
+### Next Steps
+
+- **Advanced wallet management**: See the \`multi-wallet\` topic for provider types, EIP-712 signing, error handling, and multi-wallet patterns
+- **Authentication**: See the \`session-auth\` topic for JWT login flows after wallet connection
+- **Trading**: See \`buy-tokens\` to make your first trade after connecting
+`,
     'multi-wallet': `
-## Multi-Wallet Support with SDK
+## Wallet Provider System (v9.0.0+)
 
-**Covers Methods:**
-- \`createWallet()\` (utility function)
-- \`buy()\`, \`sell()\`, \`launchToken()\` with privateKey override
+The SDK provides a unified \`WalletProvider\` interface that abstracts wallet operations across 4 provider types, with EIP-6963 browser wallet detection and full signing support.
+
+**Covers:**
+- 4 wallet provider types (PrivateKey, External, Gala, GalaChainConnect)
+- EIP-6963 wallet detection (13 known wallets)
+- Connection lifecycle (connect, sign, disconnect)
+- Multi-wallet patterns and per-operation overrides
+- MCP wallet tools: \`createWallet\`, \`createSolanaWallet\`, \`getAddress\`, \`getEthereumAddress\`, \`getPublicKeyFromPrivateKey\`, \`getEthereumAddressFromPrivateKey\`
+
+---
+
+### Wallet Provider Types
+
+| Provider | Use Case | Key Access | Browser Required |
+|----------|----------|------------|-----------------|
+| \`PrivateKeyProvider\` | CLI, Node.js, scripts | Yes (full) | No |
+| \`ExternalWalletProvider\` | MetaMask, Coinbase, etc. | No | Yes |
+| \`GalaWalletProvider\` | Gala Wallet extension | No | Yes |
+| \`GalaChainConnectProvider\` | @gala-chain/connect clients | No | Yes |
+
+---
+
+### 1. PrivateKeyProvider (CLI / Node.js)
+
+Best for scripts, bots, and server-side code where you have the private key.
+
+\`\`\`typescript
+import { PrivateKeyProvider, createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Create provider from private key
+const provider = new PrivateKeyProvider('0xYOUR_PRIVATE_KEY');
+
+// Use with SDK
+const sdk = createLaunchpadSDK({
+  walletProvider: provider,
+  environment: 'production',
+});
+
+// Provider is always "connected" - no user interaction needed
+const address = await provider.getAddress();       // 0x checksummed
+const galaAddr = await provider.getGalaAddress();  // eth|{40-hex}
+const key = await provider.getPrivateKey();        // 0x prefixed
+const signature = await provider.signMessage('Hello');
+\`\`\`
+
+---
+
+### 2. ExternalWalletProvider (Browser Extensions)
+
+Wraps any EIP-1193 compatible browser wallet (MetaMask, Coinbase, Phantom, etc.).
+
+\`\`\`typescript
+import { ExternalWalletProvider } from '@gala-chain/launchpad-sdk/wallet';
+
+// Wrap browser extension provider
+const provider = new ExternalWalletProvider(window.ethereum);
+
+// Connect (triggers wallet popup for user approval)
+const address = await provider.connect();
+console.log('Connected:', address);
+
+// Sign messages
+const sig = await provider.signMessage('Sign in to Launchpad');
+
+// Sign EIP-712 typed data (required for GalaChain transfers)
+const typedSig = await provider.signTypedData(
+  { name: 'GalaChain', version: '1' },
+  { Transfer: [{ name: 'to', type: 'address' }, { name: 'amount', type: 'uint256' }] },
+  { to: '0x...', amount: '1000' }
+);
+
+// Disconnect when done
+await provider.disconnect();
+\`\`\`
+
+---
+
+### 3. Browser Wallet Detection (EIP-6963)
+
+The SDK uses the modern EIP-6963 standard to detect installed wallets without conflicts.
+
+\`\`\`typescript
+import {
+  detectWallets,
+  getWalletByRdns,
+  isWalletAvailable,
+  hasAnyWallet,
+  subscribeToWalletChanges,
+  KNOWN_WALLET_RDNS,
+  ExternalWalletProvider,
+} from '@gala-chain/launchpad-sdk/wallet';
+
+// Quick synchronous check (no waiting)
+if (hasAnyWallet()) {
+  console.log('At least one wallet detected');
+}
+
+// Full async detection (waits for EIP-6963 announcements, 500ms default)
+const { wallets, primary, hasWallets, byId } = await detectWallets();
+
+if (hasWallets) {
+  console.log('Available wallets:', wallets.map(w => \`\${w.name} (\${w.rdns})\`));
+
+  // Connect to the primary wallet
+  const provider = new ExternalWalletProvider(primary.provider);
+  await provider.connect();
+}
+
+// Check for a specific wallet
+if (await isWalletAvailable(KNOWN_WALLET_RDNS.METAMASK)) {
+  const metamask = await getWalletByRdns(KNOWN_WALLET_RDNS.METAMASK);
+  const provider = new ExternalWalletProvider(metamask.provider);
+  await provider.connect();
+}
+
+// Subscribe to wallet changes (reactive)
+const unsubscribe = subscribeToWalletChanges((result) => {
+  console.log('Wallets changed:', result.wallets.length);
+});
+// Later: unsubscribe();
+\`\`\`
+
+**13 Known Wallet RDNS Identifiers:**
+\`\`\`typescript
+KNOWN_WALLET_RDNS = {
+  METAMASK: 'io.metamask',
+  METAMASK_FLASK: 'io.metamask.flask',
+  COINBASE: 'com.coinbase.wallet',
+  TRUST_WALLET: 'com.trustwallet.app',
+  PHANTOM: 'app.phantom',
+  RAINBOW: 'me.rainbow',
+  OKX: 'com.okex.wallet',
+  RABBY: 'io.rabby',
+  BRAVE: 'com.brave.wallet',
+  FRAME: 'sh.frame',
+  LEDGER: 'com.ledger',
+  ZERION: 'io.zerion.wallet',
+  GALA: 'com.gala.wallet',
+};
+\`\`\`
+
+---
+
+### 4. GalaWalletProvider
+
+Specialized provider for the Gala Wallet browser extension.
+
+\`\`\`typescript
+import { GalaWalletProvider } from '@gala-chain/launchpad-sdk/wallet';
+
+// window.gala is the Gala Wallet provider
+const provider = new GalaWalletProvider(window.gala);
+const address = await provider.connect();
+\`\`\`
+
+---
+
+### 5. Factory Function
+
+Use \`createWalletProvider()\` when the wallet source is determined at runtime.
+
+\`\`\`typescript
+import { createWalletProvider } from '@gala-chain/launchpad-sdk/wallet';
+
+// From private key
+const cliProvider = createWalletProvider({ privateKey: '0x...' });
+
+// From browser extension
+const browserProvider = createWalletProvider({
+  eip1193Provider: window.ethereum,
+  autoConnect: true,
+});
+\`\`\`
+
+---
+
+### 6. Provider Utilities
+
+\`\`\`typescript
+import {
+  isPrivateKeyProvider,
+  isExternalProvider,
+  getPrivateKeyIfAvailable,
+  ensureConnected,
+  walletToProvider,
+  providerToWallet,
+} from '@gala-chain/launchpad-sdk/wallet';
+
+// Type guards
+if (isPrivateKeyProvider(provider)) {
+  const key = await provider.getPrivateKey();
+}
+
+if (isExternalProvider(provider)) {
+  // Cannot access private key - signing goes through browser wallet
+}
+
+// Safe private key access (returns null for external providers)
+const key = await getPrivateKeyIfAvailable(provider);
+
+// Ensure connected before operations
+await ensureConnected(provider);
+
+// Convert between ethers Wallet and WalletProvider
+import { Wallet } from 'ethers';
+const ethersWallet = new Wallet('0x...');
+const provider = walletToProvider(ethersWallet);
+const wallet = await providerToWallet(provider); // only works for PrivateKeyProvider
+\`\`\`
+
+---
+
+### 7. Multi-Wallet Patterns
+
+**Per-operation privateKey override** (use a different wallet for one operation):
 
 \`\`\`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'
-  });
+const sdk = createLaunchpadSDK({ wallet: 'main-private-key' });
+const testWallet = createWallet();
 
-  // Create a test wallet
-  const testWallet = createWallet();
+// Fund test wallet from main
+await sdk.transferGala({
+  recipientAddress: testWallet.address,
+  amount: '1000',
+});
 
-  // 1. Fund test wallet from main wallet
-  await sdk.transferGala({
-    recipientAddress: testWallet.address,
-    amount: '1000'
-  });
+// Buy with test wallet (privateKey override)
+await sdk.buy({
+  tokenName: 'anime',
+  amount: '100',
+  type: 'native',
+  expectedAmount: '500',
+  slippageToleranceFactor: 0.01,
+  privateKey: testWallet.privateKey,  // Uses test wallet for this operation only
+});
 
-  // 2. Have test wallet buy tokens (using privateKey override)
-  const buyCalc = await sdk.calculateBuyAmount({
-    tokenName: 'dragnrkti',
-    amount: '100',
-    type: 'native'
-  });
+// Main wallet is still the default for other operations
+const mainBalance = await sdk.fetchGalaBalance();
+\`\`\`
 
-  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
-  });
+**Switching wallets at runtime:**
+
+\`\`\`typescript
+// Create SDK with WalletProvider (can be swapped)
+let provider = new PrivateKeyProvider('0xKEY_A');
+const sdk = createLaunchpadSDK({ walletProvider: provider });
+
+// Later: switch to a different wallet
+provider = new PrivateKeyProvider('0xKEY_B');
+const sdk2 = createLaunchpadSDK({ walletProvider: provider });
+\`\`\`
+
+---
+
+### 8. Wallet Creation Utilities
+
+\`\`\`typescript
+import { createWallet, WalletUtils } from '@gala-chain/launchpad-sdk';
+
+// Quick wallet creation (auto-detects input)
+const random = createWallet();                    // Random wallet
+const fromKey = createWallet('0x...');            // From private key
+const fromMnemonic = createWallet('word1 word2...'); // From mnemonic
+
+// WalletUtils class methods
+const wallet = WalletUtils.generateWallet();
+const fromPK = WalletUtils.fromPrivateKey('0x...');
+const fromMN = WalletUtils.fromMnemonic('word1 word2...', 0); // BIP44 index
+
+// Address conversion
+const galaAddr = WalletUtils.toGalaAddress('0x1234...');   // eth|1234...
+const ethAddr = WalletUtils.toEthereumAddress('eth|1234'); // 0x1234...
+
+// Validation
+WalletUtils.isValidEthereumAddress('0x...');  // true/false
+WalletUtils.isValidGalaAddress('eth|...');    // true/false
+\`\`\`
+
+---
+
+### 9. Error Handling
 
-  // 3. Check balances for both wallets
-  const mainBalance = await sdk.fetchGalaBalance();  // Main wallet
-  const testBalance = await sdk.fetchGalaBalance(testWallet.address);  // Test wallet
+\`\`\`typescript
+import { WalletProviderError, WalletProviderErrorCode } from '@gala-chain/launchpad-sdk/wallet';
 
+try {
+  await provider.connect();
+} catch (error) {
+  if (error instanceof WalletProviderError) {
+    switch (error.code) {
+      case WalletProviderErrorCode.USER_REJECTED:
+        console.log('User rejected the connection');
+        break;
+      case WalletProviderErrorCode.PROVIDER_NOT_AVAILABLE:
+        console.log('Wallet not installed');
+        break;
+      case WalletProviderErrorCode.CONNECTION_FAILED:
+        console.log('Connection failed:', error.message);
+        break;
+    }
+  }
 }
 \`\`\`
 
-**Key Points:**
-- All signing operations support \`privateKey\` parameter
-- Creates temporary SDK instance internally
-- Supports: buy, sell, launchToken, transfers, profile updates
+**Error codes:** USER_REJECTED, NOT_CONNECTED, CONNECTION_FAILED, SIGNING_FAILED, PROVIDER_NOT_AVAILABLE, PRIVATE_KEY_NOT_ACCESSIBLE, INVALID_CONFIG, CHAIN_MISMATCH, UNKNOWN.
+
+---
+
+### MCP Tool Equivalents
+
+| Operation | MCP Tool |
+|-----------|----------|
+| Create wallet | \`gala_launchpad_create_wallet\` |
+| Create Solana wallet | \`gala_launchpad_create_solana_wallet\` |
+| Get address | \`gala_launchpad_get_address\` |
+| Get Ethereum address | \`gala_launchpad_get_ethereum_address\` |
+| Derive public key | \`gala_launchpad_get_public_key_from_private_key\` |
+| Derive ETH address from key | \`gala_launchpad_get_ethereum_address_from_private_key\` |
+
+Note: Browser wallet detection and connection are SDK-side operations and don't have MCP tool equivalents (they require a browser environment).
+
+---
+
+### Import Paths
+
+\`\`\`typescript
+// Main SDK entry (includes wallet creation utilities)
+import { createWallet, WalletUtils, createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Wallet submodule (providers, detection, types)
+import {
+  PrivateKeyProvider,
+  ExternalWalletProvider,
+  GalaWalletProvider,
+  GalaChainConnectProvider,
+  detectWallets,
+  KNOWN_WALLET_RDNS,
+  createWalletProvider,
+  WalletProviderError,
+  WalletProviderErrorCode,
+} from '@gala-chain/launchpad-sdk/wallet';
+\`\`\`
 `,
     'transfers': `
 ## Token Transfers with SDK
@@ -964,7 +1468,7 @@ async function tokenLockingAndBurning() {
 - \`getAllSwapUserAssets()\`
 - \`getSwapPoolInfo()\`
 
-Trade graduated tokens on the GalaSwap DEX with real-time WebSocket monitoring:
+Use REST-backed DEX reads for quotes and pool information, then execute signed swaps with real-time WebSocket transaction monitoring:
 
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
@@ -980,6 +1484,10 @@ async function dexTradingExample() {
   // QUOTES: Get pricing information (read-only operations)
   // ============================================================================
 
+  // Quotes come from the DEX backend (~1s freshness) and need no signer.
+  // Restricted tokens: TokenRestrictedError (403); missing pool: not-found;
+  // heavy usage: 429 rate limit.
+
   // Quote 1: Exact input (spend known GALA amount)
   const quoteIn = await sdk.getSwapQuoteExactInput('GALA', 'GUSDC', '100');
 
@@ -1029,6 +1537,7 @@ async function dexTradingExample() {
 \`\`\`
 
 **Key Architecture:**
+- **Public REST Reads**: Quotes and pool information use the DEX backend (~1s freshness) without a signer
 - **Unified WebSocket**: Uses LaunchpadSDK's unified WebSocket for transaction monitoring
 - **Environment Alignment**: STAGE/PROD URLs must match between LaunchpadSDK and GSwapService
 - **Token Formats**:
@@ -1045,6 +1554,117 @@ async function dexTradingExample() {
 - \`gala_launchpad_get_swap_user_assets\`
 - \`gala_launchpad_get_all_swap_user_assets\`
 - \`gala_launchpad_get_swap_pool_info\`
+`,
+    'gdex-stream': `
+## Real-Time gSwap Market Data with GDEX Stream
+
+\`GdexStreamService\` is a public, read-only JSON-RPC 2.0 client for gSwap queries and real-time
+events over one raw WebSocket connection. It does not use Socket.IO and needs no wallet or signer.
+
+**Covers Methods:**
+- \`connect()\`, \`disconnect()\`, \`isConnected()\`, \`request()\`
+- \`serverInfo()\`, \`ping()\`, \`getPool()\`, \`getBalance()\`, \`getPositions()\`
+- \`getBlockHeight()\`, \`quote()\`, \`getToken()\`
+- \`subscribeSwaps()\`, \`subscribePool()\`, \`subscribeBalances()\`
+- \`subscribePoolCreated()\`, \`subscribeBlocks()\`
+
+## Get the Service
+
+Use the SDK facade when the stream should follow the SDK environment, or construct the service
+directly for a standalone market-data client:
+
+\`\`\`typescript
+import { GdexStreamService, LaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+// Lazily created by the SDK; no wallet is required.
+const sdk = new LaunchpadSDK({ env: 'STAGE' });
+const gdex = sdk.getGdexStreamService();
+
+// Or use the service without a LaunchpadSDK instance.
+const standalone = new GdexStreamService({
+  url: 'wss://swap-backend.stage.defi.ovh.gala.com/ws',
+});
+
+await gdex.connect();
+console.log(await gdex.serverInfo());
+\`\`\`
+
+## Stream Swaps and Dedupe Replays
+
+Delivery is effectively at least once after a reconnect or server restart, so dedupe swap events by
+\`transactionId\` before updating application state:
+
+\`\`\`typescript
+const seenTransactions = new Set<string>();
+
+const swaps = await gdex.subscribeSwaps(swap => {
+  const transactionId = swap.transactionId as string;
+  if (seenTransactions.has(transactionId)) return;
+  seenTransactions.add(transactionId);
+
+  console.log(transactionId, swap.amount0, swap.amount1, swap.timestamp);
+}, {
+  poolHash: '760ae55afa52316deb0eeb5d38178d80d90f3a85fcfb93b1c18e2c86c28e886c',
+});
+
+// Later: await swaps.unsubscribe();
+\`\`\`
+
+## Watch a Pool from Snapshot to Live Updates
+
+Set \`snapshot: true\` to receive current pool state followed by live deltas on the same callback:
+
+\`\`\`typescript
+const pool = await gdex.subscribePool(
+  { poolHash: '760ae55afa52316deb0eeb5d38178d80d90f3a85fcfb93b1c18e2c86c28e886c' },
+  update => {
+    if (update.snapshot === true) console.log('Current pool state:', update);
+    else console.log('Pool update:', update);
+  },
+  { snapshot: true }
+);
+
+// The same handle remains valid after automatic reconnect.
+// Later: await pool.unsubscribe();
+\`\`\`
+
+## Get a Quote over the WebSocket
+
+\`quote()\` accepts exactly one of \`amountIn\` or \`amountOut\`. Omit \`fee\` to compare all
+existing fee tiers.
+
+\`\`\`typescript
+const quote = await gdex.quote({
+  tokenIn: 'GALA|Unit|none|none',
+  tokenOut: 'GUSDC|Unit|none|none',
+  fee: 10000,
+  amountIn: '100',
+});
+
+console.log(quote);
+\`\`\`
+
+## Key Facts
+
+- **Exact values:** On-chain numerics and epoch-millisecond timestamps are decimal strings. Do not
+  round-trip them through JavaScript floating-point numbers.
+- **Reconnect behavior:** Unexpected closes use automatic exponential-backoff reconnect. Every
+  active subscription is resubscribed sequentially with forced \`snapshot: true\`; treat that
+  snapshot as truth and compare \`blockNumber\` for state channels.
+- **Errors:** REST DEX reads may use \`TokenRestrictedError\`-family exceptions. GDEX JSON-RPC
+  protocol and application errors, including \`-32xxx\` codes, reject as \`GdexStreamError\` with
+  \`code\` and optional \`data\`.
+- **Endpoint availability:** STAGE is live. PROD may reject connections until its server feature flag
+  is enabled; QA1 currently uses STAGE.
+- **Node.js compatibility:** Browsers and Node.js 22+ use \`globalThis.WebSocket\`. Node.js versions
+  before 22 must pass a standards-compatible constructor through \`webSocketImpl\` (for example,
+  from the \`ws\` package).
+- **Shutdown:** Call \`disconnect()\` when the application exits; intentional disconnect disables
+  automatic reconnect.
+
+There is no MCP tool equivalent. See the WebSocket documentation page at
+\`packages/sdk/docs/websocket/README.md\` and the complete
+\`packages/sdk/docs/websocket/GDEX-STREAM.md\` guide.
 `,
     'error-handling': `
 ## Error Handling with SDK
@@ -1442,13 +2062,13 @@ async function analyzeTokenDetails() {
 
 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!
 
+DEX \`tokenId\` price reads use the public \`/v1/trade/price\` REST endpoint (~1s freshness) without a signer. Restricted or ungraduated tokens can return \`TokenRestrictedError\` (403), a missing pool returns a not-found error, and heavy usage can return 429 rate limit.
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
 async function tokenPricing() {
-  const sdk = createLaunchpadSDK({
-    wallet: 'your-private-key'
-  });
+  const sdk = createLaunchpadSDK({ environment: 'production' });
 
   // OPTION 1: SMART ROUTING (Recommended) - Automatic backend selection
   // Use tokenId for ANY token (graduated or ungraduated)
@@ -1823,6 +2443,8 @@ async function getUserCard() {
 
 Provide liquidity on GalaSwap DEX and earn passive trading fees from swaps.
 
+Position reads and removal estimates use the DEX backend's public REST endpoints (~1s freshness) and do not require a signer. Restricted tokens can return \`TokenRestrictedError\` (403), missing pools or positions return a not-found error, and heavy usage can return 429 rate limit.
+
 **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.
 
 **9 Core SDK Methods:**
@@ -1899,6 +2521,8 @@ allPositions.forEach(position => {
 
 This workflow demonstrates analyzing graduated tokens using composite data and price calculations.
 
+\`fetchCompositePoolData()\` and external quotes are REST-backed DEX reads with ~1s freshness and require no signer. Local quote math performs no network request once composite pool data is supplied. REST reads can return \`TokenRestrictedError\` (403) for restricted tokens, a not-found error for missing pools, or 429 under heavy usage.
+
 **Use Cases:**
 - Arbitrage opportunity detection
 - Price impact analysis before large trades
@@ -2263,11 +2887,13 @@ async function analyzeVolumeTrends() {
 
 Discover and query liquidity pools on GalaSwap with advanced filtering and pagination.
 
+These public reads use the DEX backend's REST API (~1s freshness), require no signer, and may return 429 under heavy usage.
+
 \`\`\`typescript
 import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
 
 async function queryDexPools() {
-  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+  const sdk = createLaunchpadSDK({ environment: 'production' });
 
   // Option 1: Fetch pools with pagination
   const pools = await sdk.fetchDexPools({
@@ -2852,6 +3478,26 @@ await sdk.sendTypingStop({
 });
 \`\`\`
 
+### Engagement Stats Updates (v8.5.0+)
+
+\`\`\`typescript
+// Subscribe to engagement stats updates for a token stream
+// Fires every ~15 seconds when chat activity occurs
+await sdk.connectStreamWebSocket();
+await sdk.authenticateStreamWebSocket('jwt-token');
+await sdk.subscribeToStream('anime');
+
+// Register global engagement stats callback
+const unsubscribe = sdk.onEngagementStatsUpdated((event) => {
+  console.log(\`\${event.tokenName}: \${event.chat.messageCount} chat messages\`);
+  console.log(\`Unique chatters: \${event.chat.uniqueChatters}\`);
+  console.log(\`Comments: \${event.comments.count} from \${event.comments.uniqueCommenters} users\`);
+});
+
+// Clean up when done
+unsubscribe();
+\`\`\`
+
 **MCP Tool Equivalents:**
 - \`gala_launchpad_subscribe_to_dex_liquidity_added\`
 - \`gala_launchpad_subscribe_to_dex_liquidity_changed\`
@@ -2859,6 +3505,7 @@ await sdk.sendTypingStop({
 - \`gala_launchpad_subscribe_to_dex_pool_added\`
 - \`gala_launchpad_subscribe_to_dex_swap_executed\`
 - \`gala_launchpad_subscribe_to_token_creations\`
+- \`gala_launchpad_on_engagement_stats_updated\`
 `,
     // ============================================================================
     // MCP TO SDK MAPPING: Cross-Reference Guide
@@ -3177,6 +3824,69 @@ async function participateInSeason() {
 - \`fetchCurrentDexLeaderboard()\` - Get current season leaderboard (convenience)
 
 **MCP Tool Equivalent:** \`gala_launchpad_fetch_current_dex_season\`
+`,
+    'fetch-current-dex-leaderboard': `
+## Fetch Current DEX Leaderboard
+
+**Covers Methods:**
+- \`fetchCurrentDexLeaderboard()\`
+
+Convenience method to fetch the leaderboard for the current active DEX season.
+This is a shortcut that combines \`fetchCurrentDexSeason()\` and \`fetchDexLeaderboardBySeasonId()\`.
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function viewCurrentLeaderboard() {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Fetch current season leaderboard directly
+  const leaderboard = await sdk.fetchCurrentDexLeaderboard();
+
+  if (leaderboard) {
+    console.log('Current Season:', leaderboard.season.name);
+    console.log('Total Participants:', leaderboard.entries.length);
+
+    // Display top 10 traders
+    console.log('\\nTop 10 Traders:');
+    leaderboard.entries.slice(0, 10).forEach((entry, rank) => {
+      console.log(\`#\${rank + 1}: \${entry.wallet}\`);
+      console.log(\`   XP: \${entry.xp}, Volume: $\${entry.totalVolume}\`);
+
+      // Display mastery titles
+      if (entry.masteryTitles.length > 0) {
+        console.log(\`   Titles: \${entry.masteryTitles.join(', ')}\`);
+      }
+    });
+
+    // Find your own position
+    const myAddress = sdk.getAddress();
+    const myPosition = leaderboard.entries.findIndex(e => e.wallet === myAddress);
+
+    if (myPosition !== -1) {
+      const myEntry = leaderboard.entries[myPosition];
+      console.log(\`\\nYour position: #\${myPosition + 1}\`);
+      console.log(\`XP: \${myEntry.xp}, Volume: $\${myEntry.totalVolume}\`);
+    } else {
+      console.log('\\nYou have not participated in this season yet.');
+    }
+  } else {
+    console.log('No active season currently running.');
+  }
+}
+\`\`\`
+
+**Use Cases:**
+- Quick access to current season standings
+- Display leaderboard in UI without multiple API calls
+- Check your competitive position
+- Show top traders on dashboard
+
+**Related Methods:**
+- \`fetchCurrentDexSeason()\` - Get season metadata only
+- \`fetchDexLeaderboardBySeasonId()\` - Get leaderboard for any season
+
+**MCP Tool Equivalent:** \`gala_launchpad_fetch_current_dex_leaderboard\`
 `,
     // ============================================================================
     // BRIDGE OPERATIONS: Cross-Chain Token Bridging
@@ -3493,44 +4203,6 @@ async function getReferralSummary() {
 - \`gala_launchpad_fetch_referrals\`
 - \`gala_launchpad_fetch_all_referrals\`
 - \`gala_launchpad_fetch_referrals_summary\`
-`,
-    'account-management': `
-# Account Management
-
-The SDK provides methods for account registration and management.
-
-## Register Account
-
-Register an account for trading on Gala. This should be called before the first purchase
-to ensure the wallet is ready for trading operations.
-
-\`\`\`typescript
-import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
-
-async function registerAccount() {
-  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
-
-  // Register the SDK wallet
-  const result = await sdk.registerAccount();
-
-  // Register a specific address
-  const otherResult = await sdk.registerAccount({
-    address: '0x1234...'  // Supports eth|, 0x, or client| formats
-  });
-
-}
-\`\`\`
-
-**Response Structure:**
-\`\`\`typescript
-interface RegisterAccountResult {
-  exists: boolean;       // Whether account is registered
-  walletAlias: string;   // Normalized wallet alias (client|...)
-}
-\`\`\`
-
-**MCP Tool Equivalents:**
-- \`gala_launchpad_register_account\`
 `,
     // ============================================================================
     // LIVE STREAMING: Stream Management & Recordings
@@ -3556,7 +4228,10 @@ async function manageStream() {
   // Start a stream for your token
   const stream = await sdk.startStream('mytoken');
 
-  // Use stream.streamKey in OBS or other RTMP software
+  // stream.rtmpsUrl — full RTMPS ingest URL for OBS or compatible software
+  // stream.srtUrl — full SRT ingest URL for low-latency encoders
+  // stream.streamKey — raw key for manual RTMPS configuration
+  // stream.srtPassphrase — raw passphrase for manual SRT configuration
 
   // Get stream info (public endpoint)
   const info = await sdk.getStreamInfo('mytoken');
@@ -3658,10 +4333,10 @@ async function adminOperations() {
 **Available SDK Methods:**
 | Method | Description | Auth |
 |--------|-------------|------|
-| \`startStream(tokenName)\` | Start a stream | Wallet |
+| \`startStream(tokenName)\` | Start a stream (returns rtmpsUrl, srtUrl, streamKey, srtPassphrase) | Wallet |
 | \`stopStream(tokenName)\` | Stop a stream | Wallet |
 | \`getStreamInfo(tokenName)\` | Get stream status | Public |
-| \`resetStreamKey(tokenName)\` | Generate new stream key | Wallet |
+| \`resetStreamKey(tokenName)\` | Generate new stream key (returns rtmpsUrl, srtUrl, streamKey, srtPassphrase) | Wallet |
 | \`disableStream(tokenName)\` | Disable token streaming | Admin |
 | \`enableStream(tokenName)\` | Enable token streaming | Admin |
 | \`getStreamRecordings(options)\` | List recordings | Public |
@@ -3923,7 +4598,7 @@ These operations require JWT authentication (call \\\`login()\\\` first):
 
 **Streaming:**
 - \\\`startStream()\\\` - Start live stream
-- \\\`resetStreamKey()\\\` - Reset RTMP key
+- \\\`resetStreamKey()\\\` - Reset stream key
 - \\\`getRecordingDownload()\\\` - Download recordings
 - \\\`deleteRecording()\\\` - Delete recordings
 - \\\`addSimulcastTarget()\\\` - Add simulcast
@@ -4190,7 +4865,7 @@ sdk.connectStreamWebSocket({
 - \`gala_launchpad_get_active_users\`
 `,
     'api-key-management': `
-# API Key Management - SDK v5.6.0+
+# API Key Management - SDK v5.0.4-beta.56+
 
 User-managed API keys with role-based permissions for delegating token management
 authority to third-party services or automated systems.
@@ -4789,6 +5464,106 @@ await sdk.deleteComment({ commentId: comment.id });
 - \`gala_launchpad_delete_comment\`
 - \`gala_launchpad_add_reaction\`
 - \`gala_launchpad_remove_reaction\`
+`,
+    'content-reactions': `
+## Content Reactions - SDK v5.13.0+
+
+Add and remove reactions on chat messages and pool comments. Reactions provide
+social engagement features for community interaction.
+
+**Covers Methods:**
+- \`addContentReaction()\` - Add reaction to any content
+- \`removeContentReaction()\` - Remove reaction from any content
+- \`addReactionToChatMessage()\` - Add reaction specifically to chat message
+- \`removeReactionFromChatMessage()\` - Remove reaction from chat message
+- \`addReactionToComment()\` - Add reaction specifically to pool comment
+- \`removeReactionFromComment()\` - Remove reaction from pool comment
+
+## Adding Reactions
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  privateKey: process.env.PRIVATE_KEY,
+});
+
+await sdk.login();
+
+// Generic method - works for any content type
+await sdk.addContentReaction({
+  messageId: 'msg-123',
+  reactionType: '👍',
+  tokenName: 'mytoken', // optional - backend can resolve from messageId
+});
+
+// Specific method for chat messages
+await sdk.addReactionToChatMessage({
+  tokenName: 'mytoken',
+  messageId: 'chat-msg-456',
+  reactionType: '🔥',
+});
+
+// Specific method for pool comments
+await sdk.addReactionToComment({
+  tokenName: 'mytoken',
+  messageId: 'comment-789',
+  reactionType: '❤️',
+});
+\`\`\`
+
+## Removing Reactions
+
+\`\`\`typescript
+// Generic method
+await sdk.removeContentReaction({
+  messageId: 'msg-123',
+  reactionType: '👍',
+});
+
+// Specific method for chat messages
+await sdk.removeReactionFromChatMessage({
+  tokenName: 'mytoken',
+  messageId: 'chat-msg-456',
+  reactionType: '🔥',
+});
+
+// Specific method for pool comments
+await sdk.removeReactionFromComment({
+  tokenName: 'mytoken',
+  messageId: 'comment-789',
+  reactionType: '❤️',
+});
+\`\`\`
+
+## Common Reaction Types
+
+| Emoji | Meaning |
+|-------|---------|
+| 👍 | Thumbs up / Like |
+| ❤️ | Love |
+| 🔥 | Fire / Hot |
+| 🚀 | Rocket / Moon |
+| 😂 | Laughing |
+
+## SDK Methods Reference
+
+| Method | Description | Auth |
+|--------|-------------|------|
+| \`addContentReaction(options)\` | Add reaction to any content | JWT |
+| \`removeContentReaction(options)\` | Remove reaction from content | JWT |
+| \`addReactionToChatMessage(options)\` | Add reaction to chat message | JWT |
+| \`removeReactionFromChatMessage(options)\` | Remove reaction from chat message | JWT |
+| \`addReactionToComment(options)\` | Add reaction to pool comment | JWT |
+| \`removeReactionFromComment(options)\` | Remove reaction from pool comment | JWT |
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_add_content_reaction\`
+- \`gala_launchpad_remove_content_reaction\`
+- \`gala_launchpad_add_reaction_to_chat_message\`
+- \`gala_launchpad_remove_reaction_from_chat_message\`
+- \`gala_launchpad_add_reaction_to_comment\`
+- \`gala_launchpad_remove_reaction_from_comment\`
 `,
     'trade-history': `
 ## Trade History
@@ -4964,7 +5739,6 @@ for (const ban of page1.items) {
 // Search for specific tokens (partial match, case-insensitive)
 const searchResults = await sdk.listTokenBans({
   search: 'scam',
-  page: 1,
   limit: 10,
 });
 
@@ -5177,83 +5951,1115 @@ const balances = await sdk.fetchNftBalances(userWallet, 'MyEpicNFTs');
 - \`gala_launchpad_mint_nft\`
 - \`gala_launchpad_fetch_nft_balances\`
 `,
-};
-/**
- * SDK Usage Explanation Tool
+    // ============================================================================
+    // TOKEN IDENTIFICATION: Understanding Token Formats (v5.14.0+)
+    // ============================================================================
+    // These conceptual topics help AI assistants understand when to use which
+    // token identifier format (tokenName vs tokenClassKey).
+    // ============================================================================
+    'token-identification': `
+# Token Identification in Launchpad SDK
+
+The SDK uses **TWO distinct token identifier formats**. Using the wrong format causes errors.
+
+## Format 1: Token Name (Launchpad/Bonding Curve Tokens)
+
+- **Format**: Simple lowercase string, 3-20 alphanumeric characters
+- **Examples**: \`"anime"\`, \`"demonkpop"\`, \`"shoewars"\`
+- **Parameter**: Usually \`tokenName\`
+- **Used for**: Bonding curve operations (before graduation)
+
+\`\`\`typescript
+// ✅ CORRECT - Bonding curve buy
+await sdk.buy({ tokenName: 'anime', amount: '100', type: 'native' });
+
+// ✅ CORRECT - Bonding curve sell
+await sdk.sell({ tokenName: 'anime', amount: '50', type: 'tokens' });
+
+// ✅ CORRECT - Check pool status
+const pool = await sdk.fetchPools({ tokenName: 'anime' });
+\`\`\`
+
+## Format 2: TokenClassKey (GalaChain/DEX Tokens)
+
+- **Format**: Pipe-delimited string: \`collection|category|type|additionalKey\`
+- **Examples**: \`"GALA|Unit|none|none"\`, \`"GUSDC|Unit|none|eth:0xa0b..."\`
+- **Parameter**: Usually \`tokenId\`, \`fromToken\`, \`toToken\`
+- **Used for**: DEX swaps, LP operations, standard GalaChain tokens
+
+\`\`\`typescript
+// ✅ CORRECT - DEX swap (requires full tokenClassKey)
+const quote = await sdk.getSwapQuoteExactInput('GALA|Unit|none|none', 'GUSDC|Unit|none|eth:0xa0b...', '100');
+await sdk.executeSwap('GALA|Unit|none|none', 'GUSDC|Unit|none|eth:0xa0b...', '100', quote.estimatedOutput, quote.feeTier);
+
+// ✅ CORRECT - Add DEX liquidity
+await sdk.addSwapLiquidityByPrice({
+  token0: 'GALA|Unit|none|none',
+  token1: 'GUSDC|Unit|none|eth:0xa0b...',
+  fee: 3000,
+  minPrice: '0.01',
+  maxPrice: '0.05',
+  amount0Desired: '1000',
+  amount1Desired: '50'
+});
+\`\`\`
+
+## Common Mistakes
+
+\`\`\`typescript
+// ❌ WRONG - Bare symbol for DEX (throws ValidationError)
+await sdk.executeSwap('GALA', 'GUSDC', '100', output, fee);
+
+// ❌ WRONG - TokenClassKey for bonding curve
+await sdk.buy({ tokenName: 'Token|Unit|ANIME|client:gala-launchpad', amount: '100' });
+
+// ❌ WRONG - Simple name for DEX quote
+await sdk.getSwapQuoteExactInput('anime', 'GALA|Unit|none|none', '100');
+\`\`\`
+
+## Method-to-Format Quick Reference
+
+| Method | tokenName | tokenClassKey | Notes |
+|--------|:---------:|:-------------:|-------|
+| \`buy()\` | ✅ | ❌ | Bonding curve only |
+| \`sell()\` | ✅ | ❌ | Bonding curve only |
+| \`graduateToken()\` | ✅ | ❌ | Triggers DEX migration |
+| \`executeSwap()\` | ❌ | ✅ | DEX only |
+| \`getSwapQuote*()\` | ❌ | ✅ | DEX quotes |
+| \`addSwapLiquidity*()\` | ❌ | ✅ | LP operations |
+| \`transferToken()\` | ✅ | ✅ | Both work |
+| \`fetchTokenPrice()\` | ✅ | ✅ | Smart router |
+
+## Getting TokenClassKey for a Graduated Token
+
+**⚠️ IMPORTANT: Never construct a tokenClassKey manually!**
+
+The tokenClassKey contains the token's **symbol** (set at creation), which may differ
+from the tokenName. Always query for it:
+
+\`\`\`typescript
+// From pool data after graduation (RECOMMENDED)
+const pool = await sdk.fetchPools({ tokenName: 'anime' });
+const tokenClassKey = pool.items[0]?.tokenClassKey;
+// → Returns the actual tokenClassKey (symbol may differ from tokenName!)
+
+// Or use the resolver
+const resolved = await sdk.resolveTokenClassKey('anime');
+// → Queries backend for the correct tokenClassKey
+\`\`\`
+
+## Well-Known Token Constants
+
+\`\`\`typescript
+const GALA = 'GALA|Unit|none|none';
+const GUSDC = 'GUSDC|Unit|none|eth:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
+const WETH = 'GETH|Unit|none|eth:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2';
+\`\`\`
+
+**See Also:** \`src/types/token.types.ts\` for full type definitions and utilities.
+`,
+    'graduation-detection': `
+# Detecting Token Graduation Status
+
+Launchpad tokens transition from bonding curve to DEX when they "graduate."
+This affects which SDK methods work and which token format to use.
+
+## Checking Graduation Status
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+async function checkGraduationStatus(tokenName: string) {
+  const sdk = createLaunchpadSDK();
+
+  // Method 1: Check via pool data (recommended)
+  const pool = await sdk.fetchPools({ tokenName });
+  const isGraduated = pool.items[0]?.isGraduated ?? false;
+
+  // Method 2: Use the helper method
+  const graduated = await sdk.isTokenGraduated(tokenName);
+
+  return graduated;
+}
+\`\`\`
+
+## Handling Graduated vs Non-Graduated Tokens
+
+\`\`\`typescript
+async function tradeToken(tokenName: string, galaAmount: string) {
+  const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+  // Check graduation status first
+  const pool = await sdk.fetchPools({ tokenName });
+  const isGraduated = pool.items[0]?.isGraduated ?? false;
+
+  if (isGraduated) {
+    // Token is on DEX - use tokenClassKey format
+    const tokenClassKey = pool.items[0]?.tokenClassKey;
+    if (!tokenClassKey) throw new Error('Token graduated but no tokenClassKey found');
+
+    const quote = await sdk.getSwapQuoteExactInput(
+      'GALA|Unit|none|none',
+      tokenClassKey,
+      galaAmount
+    );
+
+    const result = await sdk.executeSwap(
+      'GALA|Unit|none|none',
+      tokenClassKey,
+      galaAmount,
+      quote.estimatedOutput,
+      quote.feeTier
+    );
+
+    return { method: 'DEX', result };
+  } else {
+    // Token is on bonding curve - use simple tokenName
+    const calc = await sdk.calculateBuyAmount({
+      tokenName,
+      amount: galaAmount,
+      type: 'native'
+    });
+
+    const result = await sdk.buy({
+      tokenName,
+      amount: galaAmount,
+      type: 'native',
+      expectedAmount: calc.amount,
+      slippageToleranceFactor: 0.01
+    });
+
+    return { method: 'BondingCurve', result };
+  }
+}
+\`\`\`
+
+## Subscribing to Graduation Events
+
+\`\`\`typescript
+// Listen for new DEX pool creation (graduation event)
+sdk.onDexPoolCreation((event) => {
+  console.log(\`Token graduated: \${event.tokenName}\`);
+  console.log(\`New tokenClassKey: \${event.tokenClassKey}\`);
+  // Update your local state to use DEX trading
+});
+
+// Listen for new launchpad token creation
+sdk.onLaunchpadTokenCreation((event) => {
+  console.log(\`New token launched: \${event.tokenName}\`);
+  // This token is on bonding curve, use tokenName
+});
+\`\`\`
+
+## Key Differences: Pre vs Post Graduation
+
+| Aspect | Pre-Graduation | Post-Graduation |
+|--------|----------------|-----------------|
+| Trading venue | Bonding curve | GalaSwap DEX |
+| Token format | \`tokenName\` ("anime") | \`tokenClassKey\` ("Token\\|Unit\\|ANIME\\|...") |
+| Buy method | \`sdk.buy()\` | \`sdk.executeSwap()\` |
+| Sell method | \`sdk.sell()\` | \`sdk.executeSwap()\` |
+| Liquidity | None | LP positions available |
+| Price source | Bonding curve formula | DEX pool |
+
+## Why This Matters
+
+- **Wrong format = Error**: Using tokenName for DEX throws \`ValidationError\`
+- **Wrong method = Error**: Using \`buy()\` for graduated token may fail
+- **Performance**: Checking graduation once avoids repeated API calls
+- **User experience**: Show appropriate UI based on trading venue
+
+**Related Topics:** \`token-identification\`, \`dex-trading\`, \`buy-tokens\`, \`pool-graduation\`
+`,
+    // ============================================================================
+    // AI MODERATION: AI-Powered Content Moderation
+    // ============================================================================
+    'ai-moderation': `
+## AI Moderation with SDK
+
+**Covers Methods:**
+- \`getAIModerationSettings()\` - Get current AI moderation configuration
+- \`updateAIModerationSettings()\` - Update AI moderation settings
+- \`getAIModeration()\` - Get AI analysis result for a message/content
+- \`triggerAIModeration()\` - Manually trigger AI analysis on content
+- \`getAIModerationStatus()\` - Check AI moderation service status
+
+**Auth Required:** Admin API key or Overseer JWT token
+
+### Get AI Moderation Settings
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({ apiKey: 'your-admin-api-key' });
+
+// Get current AI moderation configuration
+const settings = await sdk.getAIModerationSettings();
+console.log('AI Moderation Settings:', settings);
+// Returns: { enabled, sensitivityLevel, autoAction, actionThreshold, ... }
+\`\`\`
+
+### Update AI Moderation Settings
+
+\`\`\`typescript
+const result = await sdk.updateAIModerationSettings({
+  enabled: true,
+  sensitivityLevel: 'medium',   // 'low' | 'medium' | 'high'
+  autoAction: 'flag',           // 'none' | 'flag' | 'hide' | 'delete'
+  actionThreshold: 0.8,         // 0.0 - 1.0 confidence threshold
+});
+console.log('Settings updated:', result);
+\`\`\`
+
+### Get AI Moderation Result for Content
+
+\`\`\`typescript
+// Get AI analysis for a specific message
+const result = await sdk.getAIModeration({
+  contentId: 'message-uuid-here',
+  contentType: 'CHAT',   // 'CHAT' | 'COMMENT'
+});
+console.log('AI Score:', result.score);
+console.log('AI Action:', result.suggestedAction);
+console.log('Categories:', result.categories); // spam, toxicity, explicit, etc.
+\`\`\`
+
+### Trigger Manual AI Analysis
+
+\`\`\`typescript
+// Manually trigger AI analysis on content that hasn't been analyzed yet
+const result = await sdk.triggerAIModeration({
+  contentId: 'message-uuid-here',
+  contentType: 'COMMENT',
+});
+console.log('Moderation triggered:', result.jobId);
+\`\`\`
+
+### Check AI Service Status
+
+\`\`\`typescript
+// Check if the AI moderation service is operational
+const status = await sdk.getAIModerationStatus();
+console.log('AI Service:', status.status); // 'operational' | 'degraded' | 'offline'
+console.log('Queue Size:', status.queueSize);
+console.log('Processing Rate:', status.processingRate);
+\`\`\`
+
+**Related Topics:** \`content-flag-management\`, \`ban-management\`, \`overseer-invites\`
+`,
+    // ============================================================================
+    // WEEKLY CHALLENGE: Weekly Token Competition Leaderboard
+    // ============================================================================
+    'weekly-challenge': `
+## Weekly Challenge with SDK
+
+**Covers Methods:**
+- \`getWeeklyChallengeLeaderboard()\` - Get tokens ranked by market cap increase
+- \`getTokenWeeklyHistory()\` - Get historical weekly challenge results for a token
+
+**Challenge Rules:**
+- Week runs Saturday to Friday (UTC)
+- Baseline market cap taken Saturday at 00:00 UTC
+- Tokens ranked by percentage market cap increase from baseline
+- Results available after each week closes
+
+### Get Weekly Challenge Leaderboard
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK();
+
+// Get current week's leaderboard
+const leaderboard = await sdk.getWeeklyChallengeLeaderboard();
+console.log('Top tokens this week:', leaderboard.tokens.slice(0, 10));
+
+// Get leaderboard with pagination
+const page2 = await sdk.getWeeklyChallengeLeaderboard({
+  limit: 20,
+  page: 2,
+});
+console.log('Week Period:', page2.weekStart, '-', page2.weekEnd);
+
+// Get a specific past week by timestamp
+const pastWeek = await sdk.getWeeklyChallengeLeaderboard({
+  weekTimestamp: '2026-01-01T00:00:00Z',
+});
+\`\`\`
+
+### Get Token's Weekly History
+
+\`\`\`typescript
+// Get how a specific token has performed in past weekly challenges
+const history = await sdk.getTokenWeeklyHistory({
+  tokenName: 'anime',
+  limit: 10,   // Last 10 weeks
+});
+
+history.weeks.forEach((week) => {
+  console.log(\`Week \${week.weekStart}: Rank #\${week.rank}, +\${week.percentageIncrease}%\`);
+});
+\`\`\`
+
+**Related Topics:** \`trading-analytics\`, \`token-details\`, \`fetch-pools\`
+`,
+    // ============================================================================
+    // PLATFORM STATS: Platform-Wide Trading Statistics
+    // ============================================================================
+    'platform-stats': `
+## Platform Statistics with SDK
+
+**Covers Methods:**
+- \`getPlatformStats()\` - Get platform-wide trading statistics
+
+**Auth Required:** None (public endpoint)
+
+### Get Platform Statistics
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK();
+
+// Get platform-wide statistics
+const stats = await sdk.getPlatformStats();
+
+console.log('GALA Volume (1h):', stats.galaVolume1h);
+console.log('GALA Volume (24h):', stats.galaVolume24h);
+console.log('GALA Volume (7d):', stats.galaVolume7d);
+console.log('Total Tokens:', stats.totalTokens);
+\`\`\`
+
+### Display Trading Dashboard
+
+\`\`\`typescript
+async function displayPlatformDashboard() {
+  const stats = await sdk.getPlatformStats();
+
+  return {
+    tradingVolume: {
+      lastHour: \`\${stats.galaVolume1h} GALA\`,
+      last24Hours: \`\${stats.galaVolume24h} GALA\`,
+      last7Days: \`\${stats.galaVolume7d} GALA\`,
+    },
+    tokens: {
+      total: stats.totalTokens,
+    },
+  };
+}
+\`\`\`
+
+**Related Topics:** \`weekly-challenge\`, \`trading-analytics\`, \`fetch-pools\`
+`,
+    // ============================================================================
+    // RESTRICTED NAMES: Restricted Token Names Management (Overseer Only)
+    // ============================================================================
+    'restricted-names': `
+## Restricted Names with SDK
+
+**Covers Methods:**
+- \`getRestrictedNames()\` - Get the list of restricted token names
+- \`updateRestrictedNames()\` - Update the restricted names list
+
+**Auth Required:** Overseer JWT token only
+
+### Get Restricted Names
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({ jwtToken: 'your-overseer-jwt' });
+
+// Get current restricted names list
+const result = await sdk.getRestrictedNames();
+
+// Names are stored as a newline-separated text blob
+const namesList = result.names.split('\\n').filter(Boolean);
+console.log('Restricted names:', namesList);
+console.log('Total count:', namesList.length);
+\`\`\`
+
+### Update Restricted Names
+
+\`\`\`typescript
+// Add new restricted names to the list
+const currentResult = await sdk.getRestrictedNames();
+const currentNames = currentResult.names.split('\\n').filter(Boolean);
+
+// Add new names
+const updatedNames = [...currentNames, 'badword1', 'badword2'];
+const newNamesBlob = updatedNames.join('\\n');
+
+const result = await sdk.updateRestrictedNames({
+  names: newNamesBlob,
+});
+console.log('Updated successfully:', result);
+\`\`\`
+
+### Check If a Name Would Be Restricted
+
+\`\`\`typescript
+// Check if a token name would be blocked before creating
+async function isNameRestricted(tokenName: string): Promise<boolean> {
+  const result = await sdk.getRestrictedNames();
+  const restrictedList = result.names.split('\\n').filter(Boolean);
+  return restrictedList.some(
+    (name) => name.toLowerCase() === tokenName.toLowerCase()
+  );
+}
+
+const blocked = await isNameRestricted('badword1');
+console.log('Name is restricted:', blocked);
+\`\`\`
+
+**Related Topics:** \`token-creation\`, \`overseer-invites\`, \`token-ban-management\`
+`,
+    // ============================================================================
+    // WEBSOCKET ADMIN: Real-Time Event Broadcasting (Admin/Overseer Only)
+    // ============================================================================
+    'websocket-admin': `
+## WebSocket Admin with SDK
+
+**Covers Methods:**
+- **Connection Monitoring:** \`getConnectedClients()\`, \`isUserOnline()\`, \`getOnlineUsers()\`, \`getTokenViewers()\`, \`getOnlineOverseers()\`
+- **Event Emission:** \`emitTradeExecuted()\`, \`emitBalanceUpdated()\`, \`emitStreamStatus()\`, \`emitViewerCount()\`, \`emitStreamCountdown()\`, \`emitChatMessage()\`, \`emitChatStatus()\`, \`emitTypingIndicator()\`, \`emitTokenBanned()\`, \`emitTokenUnbanned()\`, \`emitModeratorAdded()\`, \`emitModeratorRemoved()\`, \`emitUserProfileUpdated()\`, \`emitSiteConfigChanged()\`, \`emitFeatureStatus()\`
+
+**Auth Required:** Admin API key or Overseer JWT token
+
+### Monitor Connected Clients
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({ apiKey: 'your-admin-api-key' });
+
+// Get all connected WebSocket clients
+const clients = await sdk.getConnectedClients();
+console.log('Total connected:', clients.total);
+console.log('By token:', clients.byToken);
+
+// Check if a specific user is online
+const onlineStatus = await sdk.isUserOnline('eth|0x1234...');
+console.log('User online:', onlineStatus.isOnline);
+console.log('Connected since:', onlineStatus.connectedSince);
+
+// Check multiple users at once
+const statuses = await sdk.getOnlineUsers(['eth|0x1111...', 'eth|0x2222...']);
+statuses.forEach((s) => console.log(\`\${s.address}: \${s.isOnline}\`));
+
+// Get viewers of a specific token stream
+const viewers = await sdk.getTokenViewers({
+  tokenName: 'anime',
+  limit: 50,
+});
+console.log('Current viewers:', viewers.count);
+
+// Get all online overseers
+const overseers = await sdk.getOnlineOverseers();
+console.log('Online overseers:', overseers.addresses);
+\`\`\`
+
+### Emit WebSocket Events
+
+\`\`\`typescript
+// Emit a trade executed event (triggers real-time UI updates)
+await sdk.emitTradeExecuted('anime', {
+  tradeType: 'BUY',
+  amount: '100',
+  price: '0.05',
+  userAddress: 'eth|0x1234...',
+});
+
+// Emit stream status change
+await sdk.emitStreamStatus('anime', {
+  isLive: true,
+  viewerCount: 150,
+});
+
+// Emit a chat message to all viewers
+await sdk.emitChatMessage('anime', {
+  messageId: 'uuid-here',
+  content: 'Hello from admin!',
+  authorAddress: 'eth|0x1234...',
+  timestamp: Date.now(),
+});
+
+// Broadcast site-wide config change
+await sdk.emitSiteConfigChanged({
+  key: 'maintenance_mode',
+  value: false,
+});
+
+// Emit feature flag change
+await sdk.emitFeatureStatus({
+  feature: 'trading',
+  enabled: true,
+});
+\`\`\`
+
+**Related Topics:** \`streaming\`, \`stream-chat\`, \`ban-management\`, \`overseer-invites\`
+`,
+    // ============================================================================
+    // OEMBED: Social Media Link Preview Metadata
+    // ============================================================================
+    'oembed': `
+## OEmbed Metadata with SDK
+
+**Covers Methods:**
+- \`getHomeOEmbed()\` - Get oEmbed metadata for the Launchpad home page
+- \`getPoolOEmbed()\` - Get oEmbed metadata for a token pool page
+- \`getProfileOEmbed()\` - Get oEmbed metadata for a user profile page
+
+**Auth Required:** None (public endpoint)
+
+OEmbed is a format that allows embedding rich content when sharing links on social media platforms (Twitter/X, Discord, Slack, etc.). These methods return JSON metadata used to generate link previews.
+
+### Get Home Page OEmbed
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK();
+
+// Get metadata for the Launchpad home page
+const homeEmbed = await sdk.getHomeOEmbed();
+console.log('Title:', homeEmbed.title);
+console.log('Description:', homeEmbed.description);
+console.log('Thumbnail:', homeEmbed.thumbnail_url);
+console.log('Provider:', homeEmbed.provider_name);
+\`\`\`
+
+### Get Token Pool OEmbed
+
+\`\`\`typescript
+// Get metadata for a specific token's pool page
+const poolEmbed = await sdk.getPoolOEmbed({
+  tokenName: 'anime',
+});
+console.log('Token Title:', poolEmbed.title);  // e.g., "Anime Token - Gala Launchpad"
+console.log('Token Image:', poolEmbed.thumbnail_url);
+console.log('Description:', poolEmbed.description);  // Price, volume, etc.
+
+// For social sharing: generate the shareable URL
+const shareUrl = \`https://launchpad.gala.com/pools/\${tokenName}\`;
+\`\`\`
+
+### Get User Profile OEmbed
+
+\`\`\`typescript
+// Get metadata for a user's profile page
+const profileEmbed = await sdk.getProfileOEmbed({
+  userAddress: 'eth|0x1234...',
+});
+console.log('User Name:', profileEmbed.title);
+console.log('Avatar:', profileEmbed.thumbnail_url);
+\`\`\`
+
+### Integration with Social Sharing
+
+\`\`\`typescript
+// Generate open graph meta tags from oEmbed data
+async function generateMetaTags(tokenName: string) {
+  const embed = await sdk.getPoolOEmbed({ tokenName });
+  return {
+    'og:title': embed.title,
+    'og:description': embed.description,
+    'og:image': embed.thumbnail_url,
+    'og:type': 'website',
+  };
+}
+\`\`\`
+
+**Related Topics:** \`token-details\`, \`profile-management\`, \`fetch-pools\`
+`,
+    // ============================================================================
+    // MESSAGES: Unified Messages API (CHAT + COMMENT types)
+    // ============================================================================
+    'messages': `
+## Unified Messages API with SDK
+
+**Covers Methods:**
+- \`fetchMessages()\` - Query messages with type/token/user filters
+- \`createMessage()\` - Create a CHAT or COMMENT message
+- \`updateMessage()\` - Update message content (author only)
+- \`deleteMessage()\` - Delete a message (author/owner/moderator)
+- \`getPinnedMessage()\` - Get the pinned message for a token
+- \`pinMessage()\` - Pin a message (owner/moderator)
+- \`unpinMessage()\` - Unpin the current pinned message
+- \`getMessageStats()\` - Get platform-wide message statistics
+
+The unified messages API handles both \`CHAT\` (live stream chat) and \`COMMENT\` (token page comments) message types through a single /v1/messages endpoint.
+
+### Fetch Messages
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({ jwtToken: 'your-jwt-token' });
+
+// Fetch chat messages for a token
+const chatMessages = await sdk.fetchMessages({
+  tokenName: 'anime',
+  type: 'CHAT',
+  limit: 50,
+  page: 1,
+});
+
+// Fetch comment-type messages for a token
+const comments = await sdk.fetchMessages({
+  tokenName: 'anime',
+  type: 'COMMENT',
+  limit: 20,
+});
+
+// Fetch messages by a specific user
+const userMessages = await sdk.fetchMessages({
+  userAddress: 'eth|0x1234...',
+  type: 'CHAT',
+});
+\`\`\`
+
+### Create Messages
+
+\`\`\`typescript
+// Create a chat message (live stream chat)
+const chatMsg = await sdk.createMessage({
+  tokenName: 'anime',
+  content: 'This token is amazing!',
+  type: 'CHAT',
+});
+console.log('Created chat message:', chatMsg.id);
+
+// Create a comment (token page)
+const comment = await sdk.createMessage({
+  tokenName: 'anime',
+  content: 'Great project, bullish on this!',
+  type: 'COMMENT',
+});
+console.log('Created comment:', comment.id);
+\`\`\`
+
+### Update and Delete Messages
+
+\`\`\`typescript
+// Update your own message
+const updated = await sdk.updateMessage('message-uuid', {
+  content: 'Updated message content',
+});
+
+// Delete a message (must be author, or have moderator/owner role)
+await sdk.deleteMessage('message-uuid');
+\`\`\`
+
+### Pin/Unpin Messages
+
+\`\`\`typescript
+// Get the currently pinned message for a token
+const pinned = await sdk.getPinnedMessage('anime');
+if (pinned) {
+  console.log('Pinned message:', pinned.content);
+  console.log('Pinned by:', pinned.pinnedBy);
+}
+
+// Pin a message (requires owner or moderator role)
+await sdk.pinMessage('message-uuid');
+
+// Unpin the current pinned message
+await sdk.unpinMessage('message-uuid');
+\`\`\`
+
+### Get Message Statistics
+
+\`\`\`typescript
+// Get platform-wide message statistics (admin/overseer only)
+const stats = await sdk.getMessageStats();
+console.log('Total CHAT messages:', stats.chatCount);
+console.log('Total COMMENT messages:', stats.commentCount);
+console.log('Messages today:', stats.todayCount);
+\`\`\`
+
+**Related Topics:** \`stream-chat\`, \`content-reactions\`, \`content-flag-management\`, \`moderator-invites\`
+`,
+    // ============================================================================
+    // HOLDERS: Token Holder Data and Distribution Analysis
+    // ============================================================================
+    'holders': `
+## Token Holder Data with SDK
+
+**Covers Methods:**
+- \`getTopHolders(tokenName, limit?)\` - Get top N token holders by balance (v9.2.0+)
+- \`getHolderCount(tokenName)\` - Get total holder count and combined balance (v9.2.0+)
+- \`getHolderRank(tokenName, userAddress)\` - Get a user's rank and balance (v9.2.0+)
+- \`getHoldersByBalance(tokenName, options?)\` - Filter holders by balance range (v9.2.0+)
+- \`getHolderHistory(tokenName, userAddress, limit?)\` - Get a holder's trade history (v9.2.0+)
+- \`fetchTokenDistribution(tokenName)\` - Raw distribution data (used internally by the above)
+
+### Check Holder Rank
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK();
+
+// Direct SDK convenience method (v9.2.0+)
+const rank = await sdk.getHolderRank('anime', 'eth|0x1234...');
+if (rank) {
+  console.log(\`Rank #\${rank.rank} of \${rank.holderCount} holders\`);
+  console.log(\`Balance: \${rank.balance}\`);
+} else {
+  console.log('User holds no tokens');
+}
+\`\`\`
+
+### Get Top Holders
+
+\`\`\`typescript
+// Get top 10 holders with rank enrichment
+const top10 = await sdk.getTopHolders('anime', 10);
+top10.forEach((holder) => {
+  console.log(\`#\${holder.rank}: \${holder.address} - \${holder.balance} tokens (\${holder.percentage}%)\`);
+});
+\`\`\`
+
+### Holder Statistics
+
+\`\`\`typescript
+const { count, totalBalance } = await sdk.getHolderCount('anime');
+console.log(\`\${count} holders, total supply: \${totalBalance}\`);
+\`\`\`
+
+### Filter Holders by Balance (Whale Detection)
+
+\`\`\`typescript
+// Find all holders with ≥10,000 tokens
+const whales = await sdk.getHoldersByBalance('anime', { minBalance: 10000 });
+console.log(\`\${whales.length} whales hold ≥10,000 tokens\`);
+console.log('Top whale:', whales[0]?.address);
+\`\`\`
+
+### Get a Holder's Trade History
+
+\`\`\`typescript
+// Get last 20 trades for a specific holder
+const history = await sdk.getHolderHistory('anime', 'eth|0x1234...', 20);
+history.trades.forEach((t) => {
+  console.log(\`\${t.txnType}: \${t.inputAmount} → \${t.outputAmount} at \${t.createdAt}\`);
+});
+\`\`\`
+
+**Related Topics:** \`token-distribution\`, \`token-details\`, \`trading-analytics\`, \`recent-trades\`
+`,
+    'trading-quotes': `
+## Trading Quotes via Backend Proxy (v9.1.0+)
+
+**Covers Methods:**
+- \`fetchLaunchpadFee()\` — Backend-cached launchpad fee (1h TTL, @Public)
+- \`fetchSaleDetails(tokenName)\` — Backend-cached token sale details (10s TTL, @Public)
+- \`getTradeQuote(params)\` — Instant quote via local bonding curve math (no chain call, @Public)
+- \`getPremintQuote(amount)\` — Pre-mint quote assuming zero supply (token creation flow, @Public)
+
+All endpoints are @Public() — no authentication required. These replace the deprecated
+\`calculateBuyAmountExternal()\` / \`calculateSellAmountExternal()\` chain-direct methods.
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK();
+
+// 1. Fetch current launchpad fee (cached 1h on backend)
+const fee = await sdk.fetchLaunchpadFee();
+console.log(\`Launchpad fee: \${fee} GALA\`);
+
+// 2. Fetch token sale details (cached 10s on backend)
+const details = await sdk.fetchSaleDetails('anime');
+console.log(\`Supply: \${details.sellingTokenQuantity} / \${details.maxSupply}\`);
+console.log(\`Status: \${details.saleStatus}\`);
+
+// 3. Get a buy quote: how many tokens for 100 GALA?
+const buyQuote = await sdk.getTradeQuote({
+  tokenName: 'anime',
+  amount: '100',
+  type: 'NATIVE',  // GALA input
+  method: 'IN',   // spending this amount
+});
+console.log(\`You will receive: \${buyQuote.amount} tokens\`);
+console.log(\`Fee: \${buyQuote.reverseBondingCurveFee} GALA\`);
+
+// 4. Get a sell quote: how much GALA for 500 tokens?
+const sellQuote = await sdk.getTradeQuote({
+  tokenName: 'anime',
+  amount: '500',
+  type: 'MEME',   // token input
+  method: 'IN',  // selling this amount
+});
+console.log(\`You will receive: \${sellQuote.amount} GALA\`);
+
+// 5. Pre-mint quote for token creation flow (supply = 0)
+const premintQuote = await sdk.getPremintQuote('500');
+console.log(\`Initial purchase will yield: \${premintQuote.amount} tokens\`);
+\`\`\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_fetch_launch_token_fee\`
+- \`gala_launchpad_calculate_buy_amount_local\`
+
+**Related Topics:** \`buy-tokens\`, \`sell-tokens\`, \`local-calculations\`
+`,
+    'global-feed-subscription': `
+## Global Feed Reference Tools (MCP Documentation)
+
+The global feed reference tools are **documentation/reference tools** in the MCP server, not
+direct SDK API methods. They explain how to monitor platform-wide events (trades, token launches,
+pool creations) via WebSocket subscriptions.
+
+**MCP Reference Tools:**
+- \`gala_launchpad_global_feed_reference\` — Overview of all global feed event types
+- \`gala_launchpad_global_feed_status_reference\` — Connection and authentication status patterns
+- \`gala_launchpad_monitor_global_feed_events_reference\` — Code examples for monitoring events
+- \`gala_launchpad_site_config_state_reference\` — Site configuration state management
+- \`gala_launchpad_unsubscribe_from_global_feed_reference\` — Cleanup patterns
+
+**SDK Equivalent (Direct Usage):**
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({ wallet: 'your-private-key' });
+
+// Subscribe to token creation events globally
+const unsubscribeLaunch = sdk.onLaunchpadTokenCreation((token) => {
+  console.log('New token launched:', token.tokenName);
+});
+
+// Subscribe to DEX pool creation events
+const unsubscribePool = sdk.onDexPoolCreation((pool) => {
+  console.log('New DEX pool:', pool.token0, '/', pool.token1);
+});
+
+// Subscribe to stream WebSocket for token-level events
+await sdk.connectStreamWebSocket();
+await sdk.authenticateStreamWebSocket('jwt-token');
+await sdk.subscribeToStream('anime', {
+  onTradeExecuted: (trade) => console.log('Trade:', trade),
+  onStreamStatusChanged: (status) => console.log('Status:', status),
+});
+
+// Clean up
+unsubscribeLaunch();
+unsubscribePool();
+\`\`\`
+
+**Related Topics:** \`event-subscriptions\`, \`streaming\`, \`stream-chat\`
+`,
+    'events-tracking': `
+## Client-Side Events Tracking (v8.2.0+)
+
+**Covers Methods:**
+- \`sdk.events.track(eventType, payload, options?)\` — Track an event (client-side batching)
+- \`sdk.events.flush()\` — Manually flush buffered events to backend
+- \`sdk.events.getStats()\` — Get buffering statistics
+- \`sdk.events.shutdown(timeoutMs?)\` — Graceful shutdown with final flush
+
+Events are batched client-side and flushed automatically on time (3s) or size (20 events) thresholds.
+The backend accepts batches via POST /v1/events, persists via RabbitMQ → MySQL, and broadcasts
+to the WebSocket firehose for real-time overseer monitoring.
+
+\`\`\`typescript
+import { createLaunchpadSDK, EVENT_TYPES } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({
+  wallet: 'your-private-key',
+  events: {
+    batchSize: 20,           // Flush after 20 events (default)
+    flushIntervalMs: 3000,   // Or after 3 seconds (default)
+    maxQueueSize: 1000       // Drop oldest if queue exceeds (default)
+  }
+});
+
+// Track trading events
+sdk.events.track(EVENT_TYPES.TOKEN_BUY, {
+  tokenName: 'anime',
+  amount: '100',
+  price: '0.05'
+});
+
+sdk.events.track(EVENT_TYPES.TOKEN_SELL, {
+  tokenName: 'anime',
+  amount: '50'
+});
+
+// Track page navigation
+sdk.events.track(EVENT_TYPES.PAGE_VIEW, {
+  path: '/tokens/anime',
+  referrer: 'homepage'
+});
+
+// Force immediate send for critical events
+await sdk.events.track(EVENT_TYPES.LOGIN, { userAddress: 'eth|0x...' }, { immediate: true });
+
+// Get buffering statistics
+const stats = sdk.events.getStats();
+console.log(\`Buffered: \${stats.buffered}, Sent: \${stats.flushed}\`);
+
+// Manually flush before page unload
+await sdk.events.flush();
+
+// Graceful shutdown (waits up to 5 seconds)
+await sdk.events.shutdown(5000);
+
+// Get statistics about buffered/sent events
+const stats = sdk.events.getStats();
+console.log(\`Buffered: \${stats.buffered}, Sent: \${stats.flushed}, Failed: \${stats.failed}\`);
+\`\`\`
+
+**Available EVENT_TYPES Constants:**
+- \`LOGIN\`, \`LOGOUT\`
+- \`TOKEN_BUY\`, \`TOKEN_SELL\`, \`TOKEN_SWAP\`
+- \`STREAM_START\`, \`STREAM_END\`
+- \`CHAT_MESSAGE_SENT\`, \`COMMENT_CREATED\`
+- \`PAGE_VIEW\`, \`PAGE_LEAVE\`
+
+**Related Topics:** \`stream-chat\`, \`streaming\`, \`overseer-invites\`
+`,
+    'global-bans': `
+## Global Ban Management (Platform-wide, Overseer Only)
+
+**Covers Methods:**
+- \`createGlobalBan(options)\` — Create a platform-wide ban for a user address
+- \`removeGlobalBan(options)\` — Remove a global ban
+- \`listGlobalBans(options?)\` — List all platform-wide bans with pagination
+- \`getGlobalBan(options)\` — Check if a specific user is globally banned
+
+**Authentication:** All methods require overseer JWT session or admin API key.
+
+**Distinction from Per-Token Bans:**
+- **Global bans** (\`createGlobalBan\`) — Platform-wide, applied to ALL tokens
+- **Per-token bans** (\`createBan\`) — Scoped to a specific token's chat/moderation
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK({ wallet: 'overseer-private-key' });
+
+// Create a global ban (platform-wide)
+const ban = await sdk.createGlobalBan({
+  userAddress: 'eth|0x1234...',
+  reason: 'Repeated platform policy violations',
+  expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000) // 30 days
+});
+console.log('Global ban created:', ban.id);
+
+// Check if a user is globally banned
+const banStatus = await sdk.getGlobalBan({ userAddress: 'eth|0x1234...' });
+if (banStatus) {
+  console.log(\`Banned until: \${banStatus.expiresAt ?? 'permanent'}\`);
+  console.log(\`Reason: \${banStatus.reason}\`);
+}
+
+// List all global bans (paginated)
+const bans = await sdk.listGlobalBans({ page: 1, limit: 20 });
+console.log(\`\${bans.meta.totalItems} total global bans\`);
+bans.items.forEach((b) => {
+  console.log(\`\${b.userAddress}: \${b.reason}\`);
+});
+
+// Remove a global ban
+await sdk.removeGlobalBan({ userAddress: 'eth|0x1234...' });
+console.log('Global ban removed');
+\`\`\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_create_ban\` (global scope)
+- \`gala_launchpad_remove_ban\` (global scope)
+- \`gala_launchpad_list_global_flags\`
+
+**Related Topics:** \`ban-management\`, \`overseer-invites\`, \`content-flag-management\`
+`,
+    'recent-trades': `
+## Recent Trades Query (v9.2.0+)
+
+**Covers Methods:**
+- \`getRecentTrades(tokenName?, limit?)\` — Get most recent trades (convenience wrapper)
+- \`getTrades(options)\` — Full paginated trades query with all filter options
+
+\`getRecentTrades\` is a convenience wrapper around \`getTrades\` for quick access to recent
+market activity. Use \`getTrades\` directly for advanced filtering (date ranges, addresses, etc.).
+
+\`\`\`typescript
+import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
+
+const sdk = createLaunchpadSDK();
+
+// Get 50 most recent trades across all tokens
+const { trades } = await sdk.getRecentTrades();
+trades.forEach((t) => {
+  console.log(\`\${t.tokenName} \${t.txnType}: \${t.inputAmount} → \${t.outputAmount}\`);
+});
+
+// Get last 10 trades for a specific token
+const { trades: animeTrades } = await sdk.getRecentTrades('anime', 10);
+console.log(\`Last 10 anime trades:\`, animeTrades.length);
+
+// Advanced filtering with getTrades()
+const { trades: filteredTrades, pageInfo } = await sdk.getTrades({
+  tokenName: 'anime',
+  txnType: 'BUY',
+  startDate: '2025-01-01',
+  endDate: '2025-01-31',
+  pageSize: 20,
+});
+console.log(\`Page \${pageInfo.currentPage} of \${pageInfo.totalPages}\`);
+\`\`\`
+
+**MCP Tool Equivalents:**
+- \`gala_launchpad_get_recent_trades\` — Recent trades with optional filtering
+- \`gala_launchpad_get_trades\` — Full trades query
+
+**Related Topics:** \`trading-analytics\`, \`trade-history\`, \`holders\`
+`,
+};
+/**
+ * All valid SDK example topics as a readonly array
+ */
+exports.SDK_EXAMPLE_TOPICS = Object.keys(exports.SDK_EXAMPLES);
+/**
+ * Type guard to check if a string is a valid SDK example topic
+ */
+function isValidSdkTopic(topic) {
+    return typeof topic === 'string' && topic in exports.SDK_EXAMPLES;
+}
+/**
+ * SDK Usage Explanation Tool
+ *
+ * Provides detailed SDK code examples organized by topic.
+ * The topic enum is derived from SDK_EXAMPLES keys to ensure type safety.
  */
 exports.explainSdkUsageTool = {
     name: 'gala_launchpad_explain_sdk_usage',
-    description: 'Get detailed SDK code examples for all 224 MCP tools (mapping to ~208 SDK methods) organized into 49 composite workflow topics covering: buy-tokens, sell-tokens, pool-graduation, fetch-pools, balances, token-creation, token-status, dex-trading, liquidity-positions, advanced-dex-analysis, price-history, token-details, token-distribution, profile-management, multi-wallet, transfers, locks, trading-analytics, utilities-and-helpers, utilities-system, error-handling, installation, local-calculations, spot-prices-smart-routing, event-subscriptions, mcp-to-sdk-mapping, DEX leaderboards, bridge-operations, dex-token-discovery, wrap-unwrap-operations, referral-system, account-management, session-auth, streaming, stream-chat, ban-management, api-key-management, moderator-invites, overseer-invites, content-flag-management, content-reactions, trade-history, token-ban-management, and nft-collection-management.',
+    description: 'Get detailed SDK code examples for all 310 MCP tools (mapping to 273 SDK methods) organized into 65 composite workflow topics covering: buy-tokens, sell-tokens, pool-graduation, fetch-pools, balances, token-creation, token-status, dex-trading, gdex-stream, liquidity-positions, advanced-dex-analysis, price-history, token-details, token-distribution, profile-management, multi-wallet, transfers, locks, trading-analytics, utilities-and-helpers, utilities-system, error-handling, installation, local-calculations, spot-prices-smart-routing, event-subscriptions, mcp-to-sdk-mapping, DEX leaderboards, bridge-operations, dex-token-discovery, wrap-unwrap-operations, referral-system, account-management, session-auth, streaming, stream-chat, ban-management, api-key-management, moderator-invites, overseer-invites, content-flag-management, content-reactions, trade-history, token-ban-management, nft-collection-management, token-identification, graduation-detection, ai-moderation (AI content analysis - overseer only), weekly-challenge (weekly token competition leaderboard), platform-stats (platform-wide trading metrics), restricted-names (blocked token names list - overseer only), websocket-admin (real-time event broadcasting - admin/overseer), oembed (social media link preview metadata), messages (unified CHAT+COMMENT messages API), and holders (token holder distribution and whale analysis).',
     inputSchema: {
         type: 'object',
         properties: {
             topic: {
                 type: 'string',
-                enum: [
-                    'buy-tokens',
-                    'sell-tokens',
-                    'pool-graduation',
-                    'fetch-pools',
-                    'balances',
-                    'dex-trading',
-                    'liquidity-positions',
-                    'advanced-dex-analysis',
-                    'price-history',
-                    'token-details',
-                    'token-distribution',
-                    'token-status',
-                    'token-creation',
-                    'profile-management',
-                    'multi-wallet',
-                    'transfers',
-                    'locks',
-                    'trading-analytics',
-                    'utilities-and-helpers',
-                    'utilities-system',
-                    'error-handling',
-                    'installation',
-                    'local-calculations',
-                    'spot-prices-smart-routing',
-                    'event-subscriptions',
-                    'mcp-to-sdk-mapping',
-                    'fetch-all-dex-seasons',
-                    'fetch-current-dex-season',
-                    'fetch-dex-leaderboard-by-season-id',
-                    'fetch-current-dex-leaderboard',
-                    'fetch-dex-aggregated-volume-summary',
-                    'fetch-dex-pools',
-                    'bridge-operations',
-                    'dex-token-discovery',
-                    'wrap-unwrap-operations',
-                    'referral-system',
-                    'account-management',
-                    'streaming',
-                    'stream-chat',
-                    'session-auth',
-                    'ban-management',
-                    'api-key-management',
-                    'moderator-invites',
-                    'overseer-invites',
-                    'content-flag-management',
-                    'content-reactions',
-                    'trade-history',
-                    'token-ban-management',
-                    'nft-collection-management',
-                ],
+                // Derive enum from SDK_EXAMPLES keys to ensure they're always in sync
+                enum: exports.SDK_EXAMPLE_TOPICS,
                 description: 'The SDK usage topic to explain.',
             },
         },
         required: ['topic'],
     },
     handler: (0, error_handler_js_1.withErrorHandling)(async (_sdk, args) => {
-        const example = exports.SDK_EXAMPLES[args.topic];
+        const { topic } = args;
+        // Type-safe lookup - topic is already typed as SdkExampleTopic
+        const example = exports.SDK_EXAMPLES[topic];
         if (example === undefined || example === '') {
-            throw new Error('Unknown topic: ' + args.topic);
+            throw new Error(`Unknown topic: ${topic}`);
         }
         return (0, response_formatter_js_1.formatSuccess)({
-            topic: args.topic,
+            topic,
             explanation: example,
-            sdkVersion: '5.6.0',
+            sdkVersion: '5.0.4-beta.56',
             packageName: '@gala-chain/launchpad-sdk',
             documentation: 'https://www.npmjs.com/package/@gala-chain/launchpad-sdk',
         });