@gala-chain/launchpad-mcp-server/README.md

MCP server for Gala Launchpad - 102 tools (pool management, event watchers, GSwap DEX trading, price history, token creation, wallet management, DEX pool discovery, liquidity positions, token locks, locked token queries, composite pool data, cross-chain b

# @gala-chain/launchpad-mcp-server

**Version: 4.0.13 (Latest Stable)**

MCP (Model Context Protocol) server for Gala Launchpad SDK - Enables AI agents to interact with Gala Launchpad.

## 🚀 Features

- **102 AI-accessible tools** for complete Gala Launchpad integration (includes 19 pool management & event watcher tools, 13 trading operation tools, 7 balance & portfolio tools, 4 token creation tools, 2 transfer tools, 2 lock/unlock tools, 16 utility tools, 28 DEX/GalaSwap tools, 11 bridge tools)
- **83 slash commands** (prompts) for streamlined workflows - 94% tool coverage (every major operation has a corresponding slash command)
- **Type-safe** - Full TypeScript support with validated inputs
- **Production-ready** - Built on [@gala-chain/launchpad-sdk ](https://www.npmjs.com/package/@gala-chain/launchpad-sdk)
- **Easy setup** - Works with Claude Desktop and other MCP clients
- **Comprehensive** - Pool management, trading, balances, token creation, transfers, DEX trading, liquidity positions
- **Optimized** - Local bonding curve calculations and DEX quote calculations for instant results
- **Real-time monitoring** - WebSocket-based watchers for pool and token creation events

## What's New in v4.0.13

### New Tools (11 Total)

**High-Priority DEX & Pool Tools:**
- **gala_launchpad_fetch_composite_pool_data** - Fetch combined bonding curve + DEX pool data for comprehensive analysis
- **gala_launchpad_calculate_dex_pool_quote** - Calculate DEX pool swap quotes with local/external mode selection
- **gala_launchpad_get_swap_pool_price** - Get current price for token pair in DEX pool
- **gala_launchpad_get_all_swap_user_assets** - Get all user assets with auto-pagination and rich metadata

**Token Discovery (v4.1.0+):**
- **gala_launchpad_fetch_available_dex_tokens** - Paginated token discovery with rich metadata (image, name, description)
- **gala_launchpad_fetch_all_available_dex_tokens** - Auto-paginated fetch of ALL DEX tokens for comprehensive catalogs

**Advanced DEX Quote Calculation:**
- **gala_launchpad_calculate_dex_pool_quote_local** - Local/offline DEX quote calculation (instant, no network)
- **gala_launchpad_calculate_dex_pool_quote_external** - External GalaChain DEX quotes (real-time blockchain data)

**Position Management:**
- **gala_launchpad_fetch_swap_position_by_id** - Direct LP position lookup by ID

**Testing & Utilities:**
- **gala_launchpad_cleanup** - SDK lifecycle cleanup utility

### New Prompts (3 Total)

**Real-Time Monitoring:**
- **galachain-launchpad:watch-dex-pools** - Monitor new DEX pool creation events via WebSocket
- **galachain-launchpad:watch-token-launches** - Monitor new token launch events via WebSocket

**Advanced Pool Analysis:**
- **galachain-launchpad:fetch-pool-details** - Comprehensive bonding curve pool analytics

### Tool Coverage

- **102 total MCP tools** (full coverage of Gala Launchpad features)
- **83 total prompts** (up from 75 in v1.x)
- **81% tool→prompt coverage** (83/102 tools have dedicated prompts)
- **New focus**: DEX ecosystem integration, real-time monitoring, advanced quote calculations, cross-chain bridging

### Category Breakdown

| Category | Tool Count | Key Features |
|----------|------------|--------------|
| **Pool Management** | 19 | Pool data, real-time watchers, price history, analytics |
| **DEX/GalaSwap** | 28 | Swap quotes, liquidity positions, pool discovery, token discovery, leaderboard, composite pool data |
| **Trading Operations** | 13 | Buy, sell, calculate amounts, graduation |
| **Balance & Portfolio** | 7 | Balance queries, locked tokens, profile management |
| **Utilities** | 16 | Config, version, environment, wallet, cache, cleanup |
| **Creation** | 4 | Token launch, image upload |
| **Transfers** | 2 | GALA and token transfers |
| **Locks** | 2 | Token lock/unlock for staking, escrow |
| **Bridge** | 11 | Cross-chain bridging (GalaChain ↔ Ethereum, GalaChain ↔ Solana) |

### Performance Improvements

- **Local DEX quote calculation** - Instant results without network calls
- **Composite pool data** - Single call for bonding curve + DEX metrics
- **Auto-paginated queries** - Fetch all assets without manual pagination
- **WebSocket monitoring** - Real-time updates for pools and token launches

## 📦 Installation

```bash
npm install -g @gala-chain/launchpad-mcp-server
```

### Module Format

The MCP server is built with **CommonJS** (`dist/index.js`) and works seamlessly with the SDK's dual-format support:

- **MCP Server**: CommonJS (Node.js native)
- **Underlying SDK**: Supports ESM, CommonJS, and UMD
- **Compatibility**: Full support for both modern and legacy environments

The MCP server automatically uses the correct SDK format for your Node.js version - no configuration needed!

## 🏁 Quick Start

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gala-launchpad": {
      "command": "npx",
      "args": ["-y", "@gala-chain/launchpad-mcp-server@latest"],
      "env": {
        "PRIVATE_KEY": "0x1234567890abcdef...",
        "ENVIRONMENT": "production"
      }
    }
  }
}
```

**Environment Variables:**
- `PRIVATE_KEY` (optional) - Your Ethereum wallet private key (omit for read-only mode)
- `ENVIRONMENT` (optional) - `development` or `production` (default: production)
- `DEBUG` (optional) - `true` to enable debug logging
- `TIMEOUT` (optional) - Request timeout in milliseconds (default: 30000)

### Using with Claude Desktop

1. **Install**: `npm install -g @gala-chain/launchpad-mcp-server`
2. **Configure**: Add server to `claude_desktop_config.json` (see above)
3. **Restart Claude Desktop**
4. **Use tools**: Ask Claude to interact with Gala Launchpad!

## 🔐 Operational Modes

The MCP server supports two operational modes with dynamic wallet configuration:

### Full-Access Mode (with PRIVATE_KEY)
- Execute token trades (buy/sell)
- Create new tokens
- Transfer GALA and tokens
- Update profile information
- All read operations (fetch pools, prices, balances, etc.)

**Setup:**
```bash
claude mcp add "galachain-launchpad" -- env PRIVATE_KEY=0x... ENVIRONMENT=production npx -y @gala-chain/launchpad-mcp-server@latest
```

### Read-Only Mode (without PRIVATE_KEY)
- Fetch token pools and details
- Get real-time prices and price history
- Check balances and portfolio
- Explore token metadata and distributions
- **Cannot:** Execute trades, create tokens, transfer funds (operations requiring wallet signatures)

**Setup:**
```bash
claude mcp add "galachain-launchpad-readonly" -- env ENVIRONMENT=production npx -y @gala-chain/launchpad-mcp-server@latest
```

### Dynamic Wallet Configuration
Use the wallet management tools to upgrade or switch wallets at runtime:
- `gala_launchpad_has_wallet` - Check current wallet status
- `gala_launchpad_set_wallet` - Upgrade from read-only to full-access mode
- `gala_launchpad_get_wallet` - Retrieve wallet information

## 🛠️ Available Tools (89 Total)

### Pool Management, Pricing & Event Watchers (19 tools)
- `gala_launchpad_fetch_pools` - Fetch token pools with filtering
- `gala_launchpad_fetch_all_pools` - Fetch all available pools with automatic pagination
- `gala_launchpad_fetch_pool_details` - Get detailed pool state
- `gala_launchpad_fetch_pool_details_for_calculation` - Get optimized pool details for local calculations
- `gala_launchpad_fetch_composite_pool_data` - **NEW v2.0** - Fetch combined bonding curve + DEX pool data
- `gala_launchpad_fetch_token_distribution` - Get holder distribution
- `gala_launchpad_fetch_token_badges` - Get achievement badges
- `gala_launchpad_fetch_volume_data` - Get OHLCV charting data
- `gala_launchpad_fetch_token_spot_price` - Fetch USD spot price for DEX tokens
- `gala_launchpad_fetch_gala_spot_price` - Fetch current GALA USD spot price
- `gala_launchpad_fetch_launchpad_token_spot_price` - Fetch USD spot price for launchpad token
- `gala_launchpad_fetch_price_history` - Fetch historical price snapshots from DEX Backend API
- `gala_launchpad_fetch_all_price_history` - Fetch all historical price snapshots with auto-pagination
- `gala_launchpad_fetch_token_details` - Fetch comprehensive token metadata
- `gala_launchpad_check_token_name` - Check name availability
- `gala_launchpad_check_token_symbol` - Check symbol availability
- `gala_launchpad_resolve_vault_address` - Get GalaChain vault address
- `gala_launchpad_resolve_token_class_key` - Get GalaChain TokenClassKey
- `gala_launchpad_on_dex_pool_creation` - Watch for new DEX pool creation events
- `gala_launchpad_on_launchpad_token_creation` - Watch for new launchpad token creation events

#### 🔔 Event Watchers (2 tools) - Real-Time Monitoring

**Real-time pool and token discovery with WebSocket-based watchers:**

**`gala_launchpad_on_dex_pool_creation` - Watch for DEX Pool Creation**

Monitor new liquidity pool creation on GalaSwap DEX with optional filtering:

- **Parameters:**
  - `minTVL` (optional, decimal string) - Only report pools with TVL above this threshold (e.g., "100000" for 100k GALA)
  - `tokens` (optional, array of strings) - Only report pools containing these token symbols (e.g., ["GALA", "GUSDC"])
  - `intervalMs` (optional, number) - Polling interval in milliseconds (default: 2000, minimum: 1000)
  - `durationSeconds` (optional, number) - How long to poll (default: 300 seconds = 5 minutes)

- **Returns:**
  - `poolsDetected` (number) - Count of new pools found matching criteria
  - `durationSeconds` (number) - How long the watcher ran (in seconds)
  - `pools` (array of DexPoolData) - Array of detected pool objects with:
    - `poolPair` - Pool identifier (e.g., "GALA|Unit|none|none/GUSDC|Unit|none|none/10000")
    - `token0` / `token1` - Token symbols (e.g., "GALA", "GUSDC")
    - `tvl` - Total value locked in pool (number)
    - `fee` - Fee percentage as string (e.g., "0.3", "1")
    - `volume1d` / `volume30d` - Trading volume metrics
    - `apr1d` - 1-day APR percentage

- **Use Cases:**
  - Monitor high-value pool creation for opportunities
  - Track specific token pair pools
  - Real-time liquidity discovery
  - Automated opportunity alerts

- **Example:**
```javascript
// Watch for new high-TVL pools with GALA
const result = await gala_launchpad_on_dex_pool_creation({
  minTVL: "500000",     // Only pools with 500k+ GALA TVL
  tokens: ["GALA"],     // Only GALA pairs
  intervalMs: 3000,     // Check every 3 seconds
  durationSeconds: 600  // Poll for 10 minutes
});

console.log(`Found ${result.poolsDetected} new GALA pools`);
result.pools.forEach(pool => {
  console.log(`${pool.tokenA} / ${pool.tokenB}: $${pool.tvl} TVL`);
});
```

**`gala_launchpad_on_launchpad_token_creation` - Watch for Launchpad Token Creation**

Monitor new token launches on Gala Launchpad with optional creator filtering:

- **Parameters:**
  - `creatorAddress` (optional, string) - Only report tokens created by this address (e.g., "eth|0x...")
  - `intervalMs` (optional, number) - Polling interval in milliseconds (default: 2000, minimum: 1000)
  - `durationSeconds` (optional, number) - How long to poll (default: 300 seconds = 5 minutes)

- **Returns:**
  - `tokensDetected` (number) - Count of new tokens found
  - `durationSeconds` (number) - How long the watcher ran (in seconds)
  - `tokens` (array of PoolData) - Array of detected token objects with:
    - `tokenName` - Token name/symbol (e.g., "anime", "dragon")
    - `tokenSymbol` - Token symbol if different from name
    - `creatorAddress` - Creator's wallet address (eth| format)
    - `totalRaised` - GALA amount raised in bonding curve
    - `remainingSupply` - Tokens still available to purchase
    - `saleStatus` - "Ongoing" or "Completed" (graduated to DEX)

- **Use Cases:**
  - Track specific creators' new token launches
  - Monitor all token creation activity
  - Early opportunity discovery
  - Creator relationship tracking

- **Example:**
```javascript
// Watch for tokens from a specific creator
const result = await gala_launchpad_on_launchpad_token_creation({
  creatorAddress: "eth|0x1234567890abcdef1234567890abcdef12345678",
  intervalMs: 2000,     // Check every 2 seconds
  durationSeconds: 300  // Poll for 5 minutes
});

console.log(`Found ${result.tokensDetected} new tokens from creator`);
result.tokens.forEach(token => {
  console.log(`${token.tokenName}: ${token.totalRaised} GALA raised`);
});
```

#### Key Characteristics

- **Polling-based Architecture** - Uses client-side polling (no WebSocket), configurable intervals
- **Automatic Deduplication** - Never reports the same pool/token twice within a single watch session
- **Client-side Filtering** - Optional minTVL and tokens parameters reduce API load
- **Long-running Support** - Safely polls for extended periods without memory leaks
- **Error Resilience** - Continues polling after transient errors (network timeouts, API errors)
- **Interval Validation** - Enforces minimum 1000ms interval to prevent API spam
- **Return Values** - Both detect count and full objects for flexible usage

### Trading Operations (13 tools)
- `gala_launchpad_calculate_buy_amount` - Calculate buy amounts (network call)
- `gala_launchpad_calculate_sell_amount` - Calculate sell amounts (network call)
- `gala_launchpad_calculate_buy_amount_local` - Calculate buy amounts (local, instant)
- `gala_launchpad_calculate_buy_amount_external` - Calculate buy amounts (explicit network call)
- `gala_launchpad_calculate_sell_amount_local` - Calculate sell amounts (local, instant)
- `gala_launchpad_calculate_sell_amount_external` - Calculate sell amounts (explicit network call)
- `gala_launchpad_buy_tokens` - Execute token purchase
- `gala_launchpad_sell_tokens` - Execute token sale
- `gala_launchpad_fetch_trades` - Get trade history
- `gala_launchpad_calculate_initial_buy` - Calculate initial buy
- `gala_launchpad_get_bundler_transaction_result` - Get transaction status by ID
- `gala_launchpad_calculate_buy_amount_for_graduation` - Calculate cost to graduate pool
- `gala_launchpad_graduate_token` - One-step pool graduation

#### 🎓 Understanding Graduation Calculations

**CRITICAL:** The `amount` field in `gala_launchpad_calculate_buy_amount_for_graduation` represents **GALA cost**, NOT token quantity!

```javascript
// Example response
{
  "amount": "1594263.41948877",
  "transactionFee": "1594.26341949",
  "gasFee": "1"
}

// ❌ WRONG INTERPRETATION:
// "Need to buy 1,594,263 tokens"

// ✅ CORRECT INTERPRETATION:
// "Need to spend 1,594,263.42 GALA to buy all remaining tokens and graduate the pool"
```

**Amount Field Reference:**

| Tool | `amount` Field Represents | Example | Meaning |
|------|---------------------------|---------|---------|
| `calculate_buy_amount` | **Token quantity** received | "16843.758" | 16,843.76 tokens |
| `calculate_sell_amount` | **GALA amount** received | "125.50" | 125.50 GALA |
| `calculate_buy_amount_for_graduation` | **GALA cost** to graduate | "1594263.419" | 1,594,263.42 GALA |
| `calculate_initial_buy` | **Token quantity** from pre-buy | "3663321.363" | 3,663,321.36 tokens |

**Key Points:**
- Read the full number as-is - decimal point is NOT shifted
- Graduation amounts are typically in the hundreds of thousands to millions of GALA
- Always use `graduate_token` for convenience - it handles calculations internally
- Pool status changes from "Ongoing" to "Completed" upon successful graduation

#### ⚡ Performance Optimization for AI Agents

The following tools now support optional performance parameters to reduce network calls by **66%** and speed up operations by **~70%**:

- `gala_launchpad_fetch_launchpad_token_spot_price`
- `gala_launchpad_calculate_buy_amount_for_graduation`
- `gala_launchpad_graduate_token`

**New Optional Parameters:**
- `calculateAmountMode` (enum: `'local'` | `'external'`) - Calculation strategy
- `currentSupply` (string) - Pre-fetched current token supply

**Optimization Pattern:**

```javascript
// ❌ WITHOUT OPTIMIZATION (3 network calls)
const spotPrice1 = await gala_launchpad_fetch_launchpad_token_spot_price({ tokenName: "tinyevil" });
// → Network call #1

const graduation1 = await gala_launchpad_calculate_buy_amount_for_graduation({ tokenName: "tinyevil" });
// → Network call #2

const result1 = await gala_launchpad_graduate_token({ tokenName: "tinyevil" });
// → Network call #3

// ✅ WITH OPTIMIZATION (1 network call + instant local calculations)
// Step 1: Fetch pool details once
const poolDetails = await gala_launchpad_fetch_pool_details_for_calculation({ tokenName: "tinyevil" });
const currentSupply = poolDetails.currentSupply;

// Step 2: Reuse currentSupply for instant local calculations
const spotPrice2 = await gala_launchpad_fetch_launchpad_token_spot_price({
  tokenName: "tinyevil",
  calculateAmountMode: "local",
  currentSupply: currentSupply
});
// → Instant (no network call)

const graduation2 = await gala_launchpad_calculate_buy_amount_for_graduation({
  tokenName: "tinyevil",
  calculateAmountMode: "local",
  currentSupply: currentSupply
});
// → Instant (no network call)

const result2 = await gala_launchpad_graduate_token({
  tokenName: "tinyevil",
  calculateAmountMode: "local",
  currentSupply: currentSupply,
  slippageToleranceFactor: 0.01
});
// → Uses local calculation (no redundant pool fetch)
```

**Performance Impact:**
| Pattern | Network Calls | Speed | Best For |
|---------|--------------|-------|----------|
| Without optimization | 3 calls | ~600-900ms | One-off operations |
| With optimization | 1 call | ~200ms | Batch operations, analytics |
| **Reduction** | **66% fewer** | **~70% faster** | |

**When to Use Optimization:**
- ✅ Multiple calculations on the same token
- ✅ Price discovery and analytics
- ✅ Trading bot logic with frequent calculations
- ✅ Simulations and backtests
- ❌ Single one-off calculations (not worth the complexity)

**Accuracy:** Local calculations match external (network) with <0.01% difference.

### DEX Pool Discovery (2 tools)

**Discover and explore GalaSwap DEX liquidity pools with filtering, sorting, and pagination:**

- `gala_launchpad_fetch_dex_pools` - Discover DEX liquidity pools with pagination, sorting, and search filtering
- `gala_launchpad_fetch_all_dex_pools` - Discover ALL DEX liquidity pools with automatic pagination

**Features:**
- 🔍 **Search filtering** - Find pools by token symbol (GALA, GUSDC, etc.)
- 📊 **Sorting options** - Sort by TVL, 24h volume, or 30d volume
- 📄 **Pagination** - Browse large pool datasets efficiently (max 20 per page)
- 🚀 **Auto-pagination** - Fetch all pools automatically with `fetchAllDexPools`
- 💰 **Complete pool data** - TVL, fees, APR, volume metrics, and token pricing

### GSwap DEX Trading (26 tools)

**Real-time DEX trading for graduated tokens with slippage protection:**

- `gala_launchpad_get_swap_quote_exact_input` - Get swap quote for exact input amount
- `gala_launchpad_get_swap_quote_exact_output` - Get swap quote for exact desired output
- `gala_launchpad_execute_swap` - Execute token swap on GalaSwap DEX with slippage protection
- `gala_launchpad_get_swap_user_assets` - Get user token balances across all DEX pools
- `gala_launchpad_get_all_swap_user_assets` - **NEW v2.0** - Get all user assets with auto-pagination
- `gala_launchpad_get_swap_pool_info` - Get liquidity and fee tier information for token pairs
- `gala_launchpad_get_swap_pool_price` - **NEW v2.0** - Get current price for token pair in DEX pool
- `gala_launchpad_fetch_composite_pool_data` - **NEW v2.0** - Fetch complete pool state for offline quote calculations
- `gala_launchpad_calculate_dex_pool_quote_local` - **NEW v2.0** - Local/offline DEX quote calculation (instant)
- `gala_launchpad_calculate_dex_pool_quote_external` - **NEW v2.0** - External GalaChain DEX quotes (real-time)
- **9 liquidity position tools** - Add, remove, collect fees, query positions
- **4 leaderboard tools** - Top traders, tokens, volume rankings
- **1 volume tool** - DEX trading volume metrics

**Complete DEX Trading Workflow Example:**

```javascript
// Step 1: Get a quote (how much output for 100 GALA input?)
const quote = await gala_launchpad_get_swap_quote_exact_input({
  fromToken: 'GALA',
  toToken: 'GUSDC',
  amount: '100'
});
// Returns: { estimatedOutput: "100.50", feeTier: 3000, priceImpact: "0.23", ... }

// Step 2: Check pool liquidity before large trades
const pool = await gala_launchpad_get_swap_pool_info({
  tokenA: 'GALA',
  tokenB: 'GUSDC'
});
// Returns: { liquidity: "5000000", feeTiers: [500, 3000, 10000], swapCount: 1234 }

// Step 3: Execute the swap with slippage protection
const result = await gala_launchpad_execute_swap({
  fromToken: 'GALA',
  toToken: 'GUSDC',
  inputAmount: '100',
  estimatedOutput: quote.estimatedOutput,  // Use quoted amount!
  feeTier: quote.feeTier,                  // Use quoted fee tier!
  slippageTolerance: 0.01                  // 1% slippage tolerance
});
// Returns: { transactionId: "...", status: "PENDING", outputAmount: "100.45" }

// Step 4: Check user portfolio after swap
const assets = await gala_launchpad_get_swap_user_assets({
  walletAddress: 'eth|0x...'
});
// Returns: [{ symbol: 'GALA', balance: '900', decimals: 8 }, { symbol: 'GUSDC', balance: '100.45', decimals: 6 }]
```

**Key Characteristics:**
- ✅ **Real-time** - Integrated with unified WebSocket for instant transaction monitoring
- ✅ **Slippage Protection** - Automatic minimum output calculation
- ✅ **Multi-format tokens** - Supports simple names ('GALA') or full token IDs ('GALA|Unit|none|none')
- ✅ **Fee Tiers** - Automatic detection of available liquidity pools (0.05%, 0.3%, 1.0%)
- ✅ **Environment-aligned** - Uses same URLs as LaunchpadSDK (STAGE/PROD cannot be mixed)
- ✅ **Local Quote Calculation** - **NEW v2.0** - Instant offline DEX quotes for high-frequency operations

#### 📊 Historical Price Analysis

**`gala_launchpad_fetch_price_history`** - Fetch historical price snapshots for DEX tokens

This tool queries the DEX Backend API for historical token price data, enabling trend analysis and volatility assessment.

**Requirements:**
- DEX Backend API must be configured and accessible (automatic with environment configuration)
- Node.js environment only (not available in browser)
- Only works for DEX tokens with recorded price snapshots

**Parameters:**
- `tokenId` (required) - Token identifier (string format: "collection|category|type|additionalKey" or object with collection, category, type, additionalKey)
- `from` (optional) - Start date (ISO 8601, defaults to 30 days ago)
- `to` (optional) - End date (ISO 8601, defaults to now)
- `sortOrder` (optional) - Sort order: 'ASC' or 'DESC' (default: DESC for newest-first)
- `page` (optional) - Page number for pagination (default: 1)
- `limit` (optional) - Results per page, max 50 (default: 10)

**Use Cases:**
- Historical price analysis and charting
- Price trend identification
- Volatility analysis over time periods
- Data export for external analytics

**Example:**

Ask Claude:

> "Fetch the last 30 days of hourly price data for GUSDC token"

> "Show me GALA token price history from the last 7 days with daily snapshots"

---

#### 📊 All Historical Price Data (Auto-Paginated)

**`gala_launchpad_fetch_all_price_history`** - Fetch all historical price snapshots (auto-paginated)

Automatically fetches all pages of historical price data and returns complete dataset in single result.

**Use Cases:**
- Complete volatility analysis
- Full historical trend analysis
- Statistical calculations on entire dataset
- Data export for backtesting

**Example:**

Ask Claude:

> "Get all price history for GUSDC token from January 2024 and calculate volatility"

---

#### 💰 Latest Token Prices

**`gala_launchpad_fetch_prices`** - Fetch latest prices for all tokens (paginated)

Returns the most recent price snapshot for each unique token in the database.

**Use Cases:**
- Market overview dashboards
- Price comparison across tokens
- Real-time price monitoring
- Market statistics

**Example:**

Ask Claude:

> "Fetch the latest prices for the top 20 most expensive tokens"

> "Show me all token prices sorted alphabetically"

---

**`gala_launchpad_fetch_all_prices`** - Fetch all latest prices (auto-paginated)

Convenience method that automatically paginates through all tokens and returns all latest prices.

**Use Cases:**
- Complete market analysis
- Market-wide statistics and calculations
- Price monitoring across all tokens
- Data export for analysis tools

**Example:**

Ask Claude:

> "Get all latest token prices and tell me the average price across all tokens"

> "Show me the most and least expensive tokens right now"

### Balance & Portfolio (6 tools)
- `gala_launchpad_fetch_gala_balance` - Get GALA balance
- `gala_launchpad_fetch_token_balance` - Get token balance
- `gala_launchpad_fetch_tokens_held` - Get portfolio holdings
- `gala_launchpad_fetch_tokens_created` - Get created tokens
- `gala_launchpad_fetch_profile` - Get user profile
- `gala_launchpad_update_profile` - Update profile
- `gala_launchpad_get_swap_user_assets` - Get user token balances from DEX
- `gala_launchpad_get_all_swap_user_assets` - **NEW v2.0** - Get all user assets with auto-pagination

### Wallet Management (3 tools)
- `gala_launchpad_has_wallet` - Check if wallet is configured
- `gala_launchpad_get_wallet` - Get currently configured wallet instance
- `gala_launchpad_set_wallet` - Configure wallet for signing operations (upgrade from read-only mode)

### Token Creation (4 tools)
- `gala_launchpad_launch_token` - Create new token pool
- `gala_launchpad_upload_token_image` - Upload token image from filesystem
- `gala_launchpad_upload_profile_image` - Upload profile image from filesystem
- `gala_launchpad_fetch_launch_token_fee` - Get current GALA fee to launch a token

### Token Transfers (2 tools)
- `gala_launchpad_transfer_gala` - Transfer GALA tokens
- `gala_launchpad_transfer_token` - Transfer launchpad tokens

### Utility Tools (16 tools)
- `gala_launchpad_create_wallet` - Create new GalaChain wallet
- `gala_launchpad_get_address` - Get user's GalaChain address
- `gala_launchpad_get_ethereum_address` - Get user's Ethereum address
- `gala_launchpad_get_config` - Get current SDK configuration
- `gala_launchpad_get_url_by_token_name` - Generate frontend URL for a token
- `gala_launchpad_explain_sdk_usage` - Get SDK code examples for specific topics
- `gala_launchpad_get_cache_info` - Get token metadata cache statistics
- `gala_launchpad_clear_cache` - Clear token metadata cache
- `gala_launchpad_has_wallet` - Check if wallet is configured
- `gala_launchpad_get_wallet` - Get currently configured wallet instance
- `gala_launchpad_set_wallet` - Configure wallet for signing operations
- `gala_launchpad_get_environment` - Get current MCP server environment
- `gala_launchpad_switch_environment` - Switch MCP server environment
- `gala_launchpad_get_version` - Get SDK and MCP server version information
- `gala_launchpad_is_token_graduated` - Check if token has completed bonding curve
- `gala_launchpad_cleanup` - **NEW v2.0** - SDK lifecycle cleanup utility

## 💡 Example Usage

Ask Claude (or your AI assistant):

> "Fetch the 10 most recent token pools on Gala Launchpad"

> "What's my GALA balance?"

> "Calculate how many tokens I'd get if I buy with 100 GALA on dragnrkti"

> "Buy 50 GALA worth of rocketri tokens with 5% slippage"

> "Show me all tokens I'm holding"

> "Watch for new DEX pool creation for the next 5 minutes"

> "Get the current GALA/GUSDC price from the DEX pool"

## ⚡ Slash Commands (Prompts) - 78 Total

The MCP server exposes **78 slash commands** (prompts) for streamlined workflows with 89% tool coverage - every major operation has a corresponding slash command for quick access. These appear as `/galachain-launchpad:<<method>>` in Claude Desktop.

### Trading Commands (4 commands)

**`/galachain-launchpad:analyze-token`**
- Comprehensive token analysis (pool details, spot price, graduation cost)
- **Arguments**: `tokenName` (required)
- **Example**: `/galachain-launchpad:analyze-token tokenName=anime`
- Uses optimized LOCAL calculations for speed

**`/galachain-launchpad:buy-tokens`**
- Guided token purchase with slippage protection
- **Arguments**: `tokenName` (required), `galaAmount` (required), `slippage` (optional, default 1%)
- **Example**: `/galachain-launchpad:buy-tokens tokenName=anime galaAmount=100 slippage=2`
- Shows breakdown and asks for confirmation before executing

**`/galachain-launchpad:sell-tokens`**
- Guided token sale with slippage protection
- **Arguments**: `tokenName` (required), `tokenAmount` (required), `slippage` (optional, default 1%)
- **Example**: `/galachain-launchpad:sell-tokens tokenName=anime tokenAmount=1000`
- Checks balance and shows breakdown before executing

**`/galachain-launchpad:graduate-token`**
- One-step pool graduation workflow
- **Arguments**: `tokenName` (required), `slippage` (optional, default 1%)
- **Example**: `/galachain-launchpad:graduate-token tokenName=anime`
- Checks if already graduated, calculates cost, and executes with confirmation

### Portfolio Commands (5 commands)

**`/galachain-launchpad:portfolio`**
- Complete portfolio analysis with USD values
- **Arguments**: None
- Shows GALA balance, all token holdings, total portfolio value, and top holdings

**`/galachain-launchpad:tokens-held`**
- List all tokens currently held
- **Arguments**: `search` (optional fuzzy filter), `limit` (optional, default 20)
- **Example**: `/galachain-launchpad:tokens-held search=dragon limit=10`

**`/galachain-launchpad:tokens-created`**
- Show tokens created by the user with status
- **Arguments**: `search` (optional), `limit` (optional, default 20)
- Shows graduation status and progress for each token

**`/galachain-launchpad:balance`**
- Check GALA and optional token balance
- **Arguments**: `tokenName` (optional)
- **Example**: `/galachain-launchpad:balance tokenName=anime`
- Displays both token amounts and USD values

**`/galachain-launchpad:profile`**
- Show user profile and activity summary
- **Arguments**: None
- Displays profile info, wallet addresses, activity metrics, and current balance

### Analysis Commands (6 commands)

**`/galachain-launchpad:compare-tokens`**
- Side-by-side comparison of two tokens
- **Arguments**: `token1` (required), `token2` (required)
- **Example**: `/galachain-launchpad:compare-tokens token1=anime token2=test216253`
- Shows comparison table with metrics, holders, and investment analysis

**`/galachain-launchpad:graduation-status`**
- Check graduation readiness for multiple tokens
- **Arguments**: `tokens` (required, comma-separated)
- **Example**: `/galachain-launchpad:graduation-status tokens=anime,test216253,dragnrkti`
- Shows progress table and identifies graduation opportunities

**`/galachain-launchpad:spot-prices`**
- Batch spot price lookup for multiple tokens
- **Arguments**: `tokens` (required, comma-separated)
- **Example**: `/galachain-launchpad:spot-prices tokens=anime,test216253`
- Uses optimized LOCAL calculations for instant results

**`/galachain-launchpad:pool-details`**
- Comprehensive pool information with badges and distribution
- **Arguments**: `tokenName` (required)
- **Example**: `/galachain-launchpad:pool-details tokenName=anime`
- Shows complete pool metrics, achievements, and recent activity

**`/galachain-launchpad:trade-history`**
- View recent trades with filtering
- **Arguments**: `tokenName` (optional), `userAddress` (optional), `tradeType` (optional: BUY/SELL), `limit` (optional, default 20)
- **Example**: `/galachain-launchpad:trade-history tokenName=anime tradeType=BUY limit=10`

**`/galachain-launchpad:fetch-all-pools`**
- Fetch all available pools with auto-pagination
- **Arguments**: None
- Retrieves complete list of all token pools on Launchpad

### Creation & Discovery Commands (2 commands)

**`/galachain-launchpad:create-token`**
- Guided token creation workflow
- **Arguments**: `tokenName` (required), `tokenSymbol` (required), `description` (required), `websiteUrl` (optional), `twitterUrl` (optional), `telegramUrl` (optional), `imagePath` (optional), `preBuyGala` (optional)
- **Example**: `/galachain-launchpad:create-token tokenName=mytoken tokenSymbol=MTK description="My awesome token" websiteUrl=https://example.com`
- Validates availability, checks fees, uploads image, and guides through launch process
- **Note**: At least one social URL (website, Twitter, or Telegram) is required

**`/galachain-launchpad:discover-tokens`**
- Discover new tokens on Gala Launchpad
- **Arguments**: `type` (optional: recent/popular/near-graduation, default: recent), `limit` (optional, default: 10), `minProgress` (optional: graduation %), `maxPrice` (optional: max USD price)
- **Example**: `/galachain-launchpad:discover-tokens type=near-graduation minProgress=90 limit=10`
- Helps find investment opportunities with filtering and analysis

### Real-Time Monitoring Commands (2 commands) - NEW v2.0

**`/galachain-launchpad:watch-dex-pools`** - **NEW v2.0**
- Monitor new DEX pool creation events in real-time via WebSocket
- **Arguments**: `duration` (optional: seconds, default 60), `minTVL` (optional: minimum TVL filter), `tokens` (optional: comma-separated token symbols)
- **Example**: `/galachain-launchpad:watch-dex-pools duration=300 minTVL=100000 tokens=GALA,GUSDC`
- Real-time alerts as new liquidity pools are created

**`/galachain-launchpad:watch-token-launches`** - **NEW v2.0**
- Monitor new token launch events in real-time via WebSocket
- **Arguments**: `duration` (optional: seconds, default 60), `creatorAddress` (optional: filter by creator)
- **Example**: `/galachain-launchpad:watch-token-launches duration=300 creatorAddress=eth|0x...`
- Discover new tokens immediately as they launch

### DEX Pool Discovery Commands (2 commands)

**`/galachain-launchpad:fetch-dex-pools`**
- Discover DEX liquidity pools with pagination and filtering
- **Arguments**: `search` (optional: token symbol filter), `sortBy` (optional: tvl/volume30d/volume1d, default: tvl), `sortOrder` (optional: asc/desc, default: desc), `page` (optional, default: 1), `limit` (optional, default: 10, max: 20)
- **Example**: `/galachain-launchpad:fetch-dex-pools search=GALA sortBy=volume30d limit=10`
- Browse DEX pools with complete metrics: TVL, trading volume, APR, and fee data

**`/galachain-launchpad:fetch-all-dex-pools`**
- Discover ALL available DEX liquidity pools with automatic pagination
- **Arguments**: `search` (optional: token symbol filter), `sortBy` (optional: tvl/volume30d/volume1d, default: tvl), `sortOrder` (optional: asc/desc, default: desc)
- **Example**: `/galachain-launchpad:fetch-all-dex-pools search=GUSDC sortBy=volume1d sortOrder=asc`
- Retrieves the complete list of all DEX pools - perfect for comprehensive analysis and discovery

### Pool Management Commands (14 commands)

**`/galachain-launchpad:fetch-pools`** - Fetch token pools with filtering
**`/galachain-launchpad:fetch-pool-details`** - **NEW v2.0** - Get comprehensive bonding curve pool analytics
**`/galachain-launchpad:fetch-pool-details-for-calculation`** - Get optimized pool details for local calculations
**`/galachain-launchpad:fetch-token-details`** - Fetch comprehensive token metadata
**`/galachain-launchpad:fetch-token-distribution`** - Get holder distribution and supply metrics
**`/galachain-launchpad:fetch-token-badges`** - Get achievement badges for volume and engagement
**`/galachain-launchpad:fetch-volume-data`** - Get OHLCV (candlestick) data for charting
**`/galachain-launchpad:fetch-gala-spot-price`** - Fetch current GALA USD spot price
**`/galachain-launchpad:fetch-price-history`** - Fetch historical price snapshots with pagination
**`/galachain-launchpad:fetch-all-price-history`** - Fetch all historical price data (auto-paginated)
**`/galachain-launchpad:check-token-name`** - Check if token name is available
**`/galachain-launchpad:check-token-symbol`** - Check if token symbol is available
**`/galachain-launchpad:resolve-vault-address`** - Get GalaChain vault address for a token
**`/galachain-launchpad:resolve-token-class-key`** - Get GalaChain TokenClassKey for a token

### Trading Calculation Commands (11 commands)

**`/galachain-launchpad:calculate-buy-amount`** - Calculate token amounts for buying
**`/galachain-launchpad:calculate-sell-amount`** - Calculate GALA amounts for selling
**`/galachain-launchpad:fetch-trades`** - Query trading history with optional filters
**`/galachain-launchpad:calculate-initial-buy`** - Calculate pre-buy amounts during token creation
**`/galachain-launchpad:get-bundler-transaction-result`** - Check bundler transaction status by ID
**`/galachain-launchpad:calculate-graduation-cost`** - Calculate cost to graduate a token pool
**`/galachain-launchpad:calculate-buy-amount-local`** - Calculate buy amount using LOCAL bonding curve (instant)
**`/galachain-launchpad:calculate-buy-amount-external`** - Calculate buy amount using EXTERNAL GalaChain call
**`/galachain-launchpad:calculate-sell-amount-local`** - Calculate sell amount using LOCAL bonding curve
**`/galachain-launchpad:calculate-sell-amount-external`** - Calculate sell amount using EXTERNAL GalaChain call
**`/galachain-launchpad:is-token-graduated`** - Check if token has completed bonding curve and graduated to DEX

### Balance & Portfolio Commands (4 commands)

**`/galachain-launchpad:fetch-gala-balance`** - Get your GALA balance
**`/galachain-launchpad:fetch-token-balance`** - Get balance for a specific token
**`/galachain-launchpad:fetch-tokens-created`** - List tokens you've created with status
**`/galachain-launchpad:update-profile`** - Update your user profile information

### Creation Utility Commands (2 commands)

**`/galachain-launchpad:upload-profile-image`** - Upload profile image from filesystem
**`/galachain-launchpad:fetch-launch-token-fee`** - Get current GALA fee required to launch a token

### Transfer Commands (2 commands)

**`/galachain-launchpad:transfer-gala`** - Transfer GALA tokens to another wallet
**`/galachain-launchpad:transfer-token`** - Transfer launchpad tokens to another wallet

### Utility & System Commands (12 commands)

**`/galachain-launchpad:create-wallet`** - Generate a new wallet with random private key
**`/galachain-launchpad:get-address`** - Get the GalaChain format address of authenticated wallet
**`/galachain-launchpad:get-ethereum-address`** - Get the standard Ethereum address format of authenticated wallet
**`/galachain-launchpad:get-config`** - View current SDK and MCP server configuration
**`/galachain-launchpad:get-url-by-token-name`** - Get the launchpad frontend URL for a token
**`/galachain-launchpad:explain-sdk-usage`** - Get detailed SDK usage examples for a topic
**`/galachain-launchpad:get-cache-info`** - Get token metadata cache statistics
**`/galachain-launchpad:clear-cache`** - Clear token metadata cache
**`/galachain-launchpad:has-wallet`** - Check if a wallet is configured in the MCP server
**`/galachain-launchpad:get-wallet`** - Get the currently configured wallet instance
**`/galachain-launchpad:set-wallet`** - Configure a wallet for signing operations
**`/galachain-launchpad:get-environment`** - Get the current MCP server environment

### Version Command (1 command)

**`/galachain-launchpad:version`**
- Display SDK and MCP server version information
- **Arguments**: None
- Shows current version numbers and release information

### Slash Command Benefits

✅ **Quick access** - Type `/galachain-launchpad:` to see all available commands
✅ **Guided workflows** - Each command provides step-by-step execution
✅ **Optimized** - Uses LOCAL calculations for maximum performance
✅ **Safe** - Asks for confirmation before executing transactions
✅ **Educational** - Shows what MCP tools are being used behind the scenes
✅ **Real-time monitoring** - **NEW v2.0** - WebSocket watchers for pools and token launches

### Example Slash Command Usage

```
User: /galachain-launchpad:analyze-token tokenName=anime

Claude: I'll analyze the token "anime" using the Gala Launchpad MCP server:

1. Fetching optimized pool details...
   ✅ Current supply: 510,379.79
   ✅ Remaining tokens: 9,489,620.21
   ✅ Max supply: 10,000,000

2. Calculating USD spot price (LOCAL mode - instant!)...
   ✅ Spot price: $0.000153

3. Calculating graduation cost (LOCAL mode - instant!)...
   ✅ GALA required: 1,640,974.33 GALA
   ✅ Transaction fee: 1,640.97 GALA
   ✅ Total cost: 1,642,615.30 GALA

4. Pool progress: 5.10% complete

Analysis:
- Current price is relatively low (early stage token)
- Requires significant GALA (~1.6M) to graduate
- Only 5% through bonding curve - high risk, high potential reward
- Good opportunity for early entry if you believe in the project
```

## 📚 SDK Usage Reference

The MCP server includes a built-in SDK documentation tool that provides complete, runnable code examples for using the SDK directly instead of through MCP tools. This is perfect for developers who want to integrate the SDK into their applications.

**Ask Claude for SDK code examples:**

> "Explain how to buy tokens using the SDK"

> "Show me the SDK code for selling tokens"

> "How do I use multiple wallets with the SDK?"

> "Show me all MCP tools and their SDK method equivalents"

**Available topics:**
- `buy-tokens` - Complete buying workflow
- `sell-tokens` - Complete selling workflow
- `pool-graduation` - Graduate bonding curve pools
- `fetch-pools` - Query pool data
- `balances` - Check GALA and token balances
- `token-creation` - Launch new tokens
- `multi-wallet` - Multi-wallet patterns
- `transfers` - Transfer tokens between wallets
- `error-handling` - Handle exceptions
- `installation` - Install and configure SDK
- `local-calculations` - Local vs external bonding curve calculations
- `mcp-to-sdk-mapping` - Complete tool-to-method mapping

Each topic returns complete TypeScript code with explanations, making it easy to transition from MCP tools to direct SDK integration.

## 🔐 Multi-Wallet Support

All signing operations support an optional `privateKey` parameter for per-operation wallet overrides. This enables:
- Testing multi-wallet workflows
- Simulating different user behaviors
- Building multi-agent trading systems
- Operating multiple wallets from a single MCP server

### Tools Supporting privateKey Override

**Trading Operations:**
- `gala_launchpad_buy_tokens` - Buy tokens from different wallet
- `gala_launchpad_sell_tokens` - Sell tokens from different wallet

**Token Creation:**
- `gala_launchpad_launch_token` - Create token from different wallet
- `gala_launchpad_upload_token_image` - Upload image for token
- `gala_launchpad_upload_profile_image` - Upload profile image

**Transfer Operations:**
- `gala_launchpad_transfer_gala` - Transfer GALA from different wallet
- `gala_launchpad_transfer_token` - Transfer tokens from different wallet

**Profile:**
- `gala_launchpad_update_profile` - Update profile for different wallet

### Example: Multi-Wallet Trading Scenario

Ask Claude:

> "Create a scenario where Buster's wallet buys and sells tokens:
> 1. Send Buster 1000 GALA from the main wallet
> 2. Have Buster buy 100 GALA worth of tinyevil tokens using his private key: 0x1234...
> 3. Have Buster sell 50 GALA worth back
> 4. Check both wallets' final balances"

Claude will use:
```javascript
// 1. Main wallet sends GALA to Buster
gala_launchpad_transfer_gala({
  recipientAddress: "0xBusterAddress...",
  amount: "1000"
  // No privateKey - uses main wallet
});

// 2. Buster buys tokens with his wallet
gala_launchpad_buy_tokens({
  tokenName: "tinyevil",
  amount: "100",
  type: "native",
  expectedAmount: "50000",
  slippageToleranceFactor: 0.05,
  privateKey: "0x1234..." // Buster's wallet
});

// 3. Buster sells tokens
gala_launchpad_sell_tokens({
  tokenName: "tinyevil",
  amount: "50",
  type: "native",
  expectedAmount: "48",
  slippageToleranceFactor: 0.05,
  privateKey: "0x1234..." // Buster's wallet
});
```

### Private Key Format Requirements

The `privateKey` parameter must be:
- **Format**: `'0x' + 64 hexadecimal characters`
- **Example**: `'0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'`
- **Invalid**: Raw hex without '0x', mnemonics, or addresses

### Security Considerations

When using privateKey overrides:
1. **Never expose private keys** in prompts or logs
2. **Use test wallets** for development and testing
3. **Limit fund amounts** in test wallets
4. **Monitor operations** when testing multi-wallet scenarios
5. **Validate addresses** before transfers

## 🔧 Development

### Local Development

```bash
# Clone repository
git clone https://gitlab.com/gala-games/defi/launchpad/sdk.git
cd launchpad-sdk/packages/mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev
```

### Testing

```bash
npm test
```

## 📚 Documentation

- [MCP Tool Specification](../../packages/sdk/docs/MCP-TOOL-SPECIFICATION.md) - Complete tool reference
- [AI Agent Guide](../../packages/sdk/docs/AI-AGENT-GUIDE.md) - Integration patterns
- [SDK Documentation](../sdk/README.md) - Underlying SDK reference

## 🔐 Security

**Important Security Notes:**

1. **Private Keys** - Never commit private keys to version control
2. **Environment Variables** - Store credentials in `claude_desktop_config.json` securely
3. **Wallet Safety** - Use separate wallets for development and production
4. **Amount Limits** - Consider setting up trading limits for automated agents

## 🐛 Troubleshooting

### "SDK not initialized"
- Ensure `PRIVATE_KEY` is set in environment variables
- Check that private key format is valid (0x + 64 hex characters)

### "Tool not found"
- Restart Claude Desktop after configuration changes
- Verify server is listed in Claude Desktop settings

### "Connection failed"
- Check DEBUG=true logs for detailed error messages
- Verify network connectivity to Gala Launchpad backends

## 📄 License

MIT License - see [LICENSE](../../LICENSE) file for details.

## 🤝 Contributing

Contributions welcome! Please read [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

## 📞 Support

- **Issues**: [GitLab Issues](https://gitlab.com/gala-games/defi/launchpad/sdk/-/issues)
- **Documentation**: [Full Documentation](../../packages/sdk/docs/)
- **SDK Package**: [@gala-chain/launchpad-sdk](https://www.npmjs.com/package/@gala-chain/launchpad-sdk)

---

**Built with ❤️ for the Gala ecosystem**