@gala-chain/launchpad-sdk 4.0.3 → 4.0.4-beta.1

package/API.md

@@ -1,1475 +0,0 @@
-# Gala Launchpad SDK - API Reference
-
-Complete API documentation for the Gala Launchpad SDK (v3.23.0+).
-
-> **⚠️ BREAKING CHANGE (v3.33.0+)**: Token format parsing now **ONLY accepts delimited formats**. Plain token strings (`'GALA'`, `'GUSDC'`) are **permanently rejected** for security. Use delimited format: `'GALA|Unit|none|none'` or `'GALA$Unit$none$none'`. See README.md for [migration guide](./README.md#token-format-migration-v330).
-
-## Table of Contents
-
-- [SDK Initialization](#sdk-initialization)
-- [Bonding Curve Trading (Launchpad Tokens)](#bonding-curve-trading)
-- [DEX Trading (Graduated Tokens)](#dex-trading-galaswap)
-- [GalaSwap Liquidity Position Management](#galaswap-liquidity-position-management)
-- [Pool Information](#pool-information)
-- [Token Management](#token-management)
-- [Portfolio & Balances](#portfolio--balances)
-- [Price History & Analytics](#price-history--analytics)
-- [Real-Time Features](#real-time-features)
-- [Type Definitions](#type-definitions)
-- [Error Handling](#error-handling)
-
----
-
-## SDK Initialization
-
-### `createLaunchpadSDK(config?)`
-
-Creates and returns a configured LaunchpadSDK instance for interacting with the Gala Launchpad Backend.
-
-**Parameters:**
-```typescript
-interface LaunchpadSDKConfig {
-  environment?: 'development' | 'staging' | 'production';  // Default: 'production'
-  privateKey?: string;                                      // Private key for signing (optional)
-  wallet?: string;                                          // Wallet address (optional)
-  timeout?: number;                                         // Request timeout in ms (default: 30000)
-  debug?: boolean;                                          // Enable debug logging (default: false)
-}
-```
-
-**Example:**
-```typescript
-import { createLaunchpadSDK } from '@gala-chain/launchpad-sdk';
-
-// Read-only mode
-const sdk = createLaunchpadSDK({ environment: 'production' });
-
-// With wallet for signing operations
-const sdk = createLaunchpadSDK({
-  environment: 'production',
-  privateKey: process.env.PRIVATE_KEY,
-  wallet: 'eth|0x...'
-});
-```
-
----
-
-## Bonding Curve Trading
-
-Trading tokens that are still in bonding curve pools (pre-graduation).
-
-### `calculateBuyAmount(tokenName, amount, type?)`
-
-Calculate token amounts and fees for a purchase on a bonding curve.
-
-**Parameters:**
-```typescript
-tokenName: string;  // Token symbol (e.g., "anime")
-amount: string;     // Input amount (GALA or exact token count)
-type?: 'native' | 'exact';  // 'native' = GALA amount, 'exact' = token amount (default: 'native')
-```
-
-**Returns:**
-```typescript
-{
-  amount: string;              // Token quantity you'll receive
-  totalCost: string;           // Total GALA cost (input + fees)
-  transactionFee: string;      // Transaction fee in GALA
-  gasFee: string;              // Gas fee in GALA
-  reverseBondingCurveFee: string;  // RBC fee in GALA
-}
-```
-
-**Example:**
-```typescript
-// How many tokens for 100 GALA?
-const quote = await sdk.calculateBuyAmount('anime', '100', 'native');
-console.log(`Receive: ${quote.amount} tokens`);
-console.log(`Cost: ${quote.totalCost} GALA`);
-
-// How much GALA for 10,000 tokens?
-const exactQuote = await sdk.calculateBuyAmount('anime', '10000', 'exact');
-console.log(`Need: ${exactQuote.totalCost} GALA`);
-```
-
-### `calculateSellAmount(tokenName, amount, type?)`
-
-Calculate GALA amount received when selling tokens.
-
-**Parameters:**
-```typescript
-tokenName: string;  // Token symbol
-amount: string;     // Token amount or GALA desired
-type?: 'native' | 'exact';  // 'native' = GALA desired, 'exact' = token amount (default: 'native')
-```
-
-**Returns:**
-```typescript
-{
-  amount: string;              // GALA you'll receive
-  transactionFee: string;      // Transaction fee
-  gasFee: string;              // Gas fee
-  reverseBondingCurveFee: string;  // RBC fee
-}
-```
-
-**Example:**
-```typescript
-// How much GALA for selling 5000 tokens?
-const sellQuote = await sdk.calculateSellAmount('anime', '5000', 'exact');
-console.log(`Receive: ${sellQuote.amount} GALA`);
-```
-
-### `buyTokens(tokenName, amount, expectedAmount, slippageToleranceFactor?, maxAcceptableReverseBondingCurveFee?)`
-
-Execute a token purchase with slippage protection.
-
-**Parameters:**
-```typescript
-tokenName: string;  // Token symbol
-amount: string;     // GALA amount to spend
-expectedAmount: string;  // Expected token output (from calculateBuyAmount)
-slippageToleranceFactor?: number;  // Slippage tolerance (0-1, default: 0.01 = 1%)
-maxAcceptableReverseBondingCurveFee?: string;  // Max RBC fee
-```
-
-**Returns:**
-```typescript
-{
-  transactionId: string;
-  status: 'PENDING' | 'COMPLETED' | 'FAILED';
-  inputAmount: string;
-  outputAmount: string;
-  actualFees: { transaction: string; gas: string; rbc: string };
-  wait(): Promise<TransactionResult>;  // Wait for completion
-}
-```
-
-**Example:**
-```typescript
-// Get quote first
-const quote = await sdk.calculateBuyAmount('anime', '100', 'native');
-
-// Execute buy with 1% slippage tolerance
-const result = await sdk.buyTokens('anime', '100', quote.amount, 0.01);
-
-console.log(`Transaction ID: ${result.transactionId}`);
-
-// Wait for completion (optional)
-const completed = await result.wait();
-console.log(`Received: ${completed.outputAmount} tokens`);
-```
-
-### `sellTokens(tokenName, amount, expectedAmount, slippageToleranceFactor?)`
-
-Execute a token sale with slippage protection.
-
-**Parameters:**
-```typescript
-tokenName: string;  // Token symbol
-amount: string;     // Token amount to sell
-expectedAmount: string;  // Expected GALA output (from calculateSellAmount)
-slippageToleranceFactor?: number;  // Slippage tolerance (default: 0.01 = 1%)
-```
-
-**Returns:** Same structure as `buyTokens()`
-
-**Example:**
-```typescript
-// Get quote
-const quote = await sdk.calculateSellAmount('anime', '5000', 'exact');
-
-// Execute sell
-const result = await sdk.sellTokens('anime', '5000', quote.amount, 0.01);
-console.log(`Received: ${result.outputAmount} GALA`);
-```
-
-### `calculateBuyAmountForGraduation(tokenName)`
-
-Calculate total GALA cost to graduate a token (buy all remaining tokens).
-
-**⚠️ CRITICAL:** Returns **GALA cost**, NOT token quantity!
-
-**Parameters:**
-```typescript
-tokenName: string;  // Token symbol
-```
-
-**Returns:**
-```typescript
-{
-  amount: string;     // GALA cost to graduate (e.g., "1639972.84")
-  totalCost: string;  // Total cost including fees
-  transactionFee: string;
-  gasFee: string;
-}
-```
-
-**Example:**
-```typescript
-const graduation = await sdk.calculateBuyAmountForGraduation('QATOKEN');
-console.log(`Cost to graduate: ${graduation.amount} GALA`);
-// Example output: "1639972.84 GALA" (1.6 million GALA, not tokens!)
-```
-
-### `graduateToken(tokenName, options?)`
-
-Graduate a token by buying all remaining bonding curve tokens (convenience method).
-
-**Parameters:**
-```typescript
-tokenName: string;
-options?: {
-  slippageToleranceFactor?: number;  // Default: 0.01 (1%)
-}
-```
-
-**Returns:** Transaction result (same as buyTokens)
-
-**Example:**
-```typescript
-const result = await sdk.graduateToken('QATOKEN', { slippageToleranceFactor: 0.01 });
-console.log(`Graduation initiated: ${result.transactionId}`);
-
-// Verify graduation
-const pool = await sdk.fetchPoolDetails('QATOKEN');
-console.log(`Pool status: ${pool.saleStatus}`);  // Should be "Completed"
-```
-
----
-
-## DEX Trading (GalaSwap)
-
-Trading tokens that have graduated from bonding curves to full DEX trading.
-
-### `getSwapQuoteExactInput(fromToken, toToken, amount)`
-
-Get a quote for swapping a known input amount on GalaSwap DEX.
-
-**Parameters:**
-```typescript
-fromToken: string;  // Source token in delimited format (e.g., "GALA|Unit|none|none" or "GALA$Unit$none$none") - v3.33.0+ REQUIRED
-toToken: string;    // Destination token in delimited format (e.g., "GUSDC|Unit|none|none" or "GUSDC$Unit$none$none") - v3.33.0+ REQUIRED
-amount: string;     // Input amount (how much fromToken to spend)
-```
-
-**Returns:**
-```typescript
-{
-  estimatedOutput: string;     // Expected toToken amount
-  priceImpact: number;         // Price impact percentage (0-1)
-  feeTier: number;             // Fee tier in basis points (500, 3000, 10000)
-  exchangeRate: string;        // Rate: toToken per fromToken
-  minimumOutput: string;       // Minimum output with 1% slippage
-}
-```
-
-**Example:**
-```typescript
-// How many GUSDC for 100 GALA? (v3.33.0+ requires delimited token format)
-const quote = await sdk.getSwapQuoteExactInput('GALA|Unit|none|none', 'GUSDC|Unit|none|none', '100');
-console.log(`Spend: 100 GALA`);
-console.log(`Receive: ~${quote.estimatedOutput} GUSDC`);
-console.log(`Price impact: ${(quote.priceImpact * 100).toFixed(2)}%`);
-console.log(`Fee tier: ${quote.feeTier} (${quote.feeTier / 100}%)`);
-```
-
-### `getSwapQuoteExactOutput(fromToken, toToken, amount)`
-
-Get a quote for swapping to a known output amount on GalaSwap DEX.
-
-**Parameters:**
-```typescript
-fromToken: string;  // Source token
-toToken: string;    // Destination token
-amount: string;     // Desired output amount (how much toToken you want)
-```
-
-**Returns:**
-```typescript
-{
-  inputAmount: string;         // fromToken amount needed to spend
-  priceImpact: number;         // Price impact percentage
-  feeTier: number;             // Fee tier
-  exchangeRate: string;        // Exchange rate
-  maximumInput: string;        // Maximum input with 1% slippage
-}
-```
-
-**Example:**
-```typescript
-// How much GALA to get 100 GUSDC?
-const quote = await sdk.getSwapQuoteExactOutput('GALA', 'GUSDC', '100');
-console.log(`Need: ${quote.inputAmount} GALA`);
-console.log(`To get: 100 GUSDC`);
-```
-
-### `executeSwap(fromToken, toToken, inputAmount, estimatedOutput, feeTier, slippageTolerance?)`
-
-Execute a token swap on GalaSwap DEX with slippage protection.
-
-**Parameters:**
-```typescript
-fromToken: string;      // Source token
-toToken: string;        // Destination token
-inputAmount: string;    // How much fromToken to spend
-estimatedOutput: string; // Expected output (from quote)
-feeTier: number;        // Fee tier (from quote)
-slippageTolerance?: number;  // Slippage tolerance (0-1, default: 0.01)
-```
-
-**Returns:**
-```typescript
-{
-  transactionId: string;
-  status: 'PENDING' | 'COMPLETED' | 'FAILED';
-  inputAmount: string;
-  outputAmount: string;
-  actualFees: { transaction: string; gas: string };
-  wait(): Promise<TransactionResult>;
-}
-```
-
-**Example:**
-```typescript
-// Get quote
-const quote = await sdk.getSwapQuoteExactInput('GALA', 'GUSDC', '100');
-
-// Execute swap with 1% slippage protection
-const result = await sdk.executeSwap(
-  'GALA',
-  'GUSDC',
-  '100',
-  quote.estimatedOutput,
-  quote.feeTier,
-  0.01  // 1% slippage tolerance
-);
-
-console.log(`Swap ID: ${result.transactionId}`);
-console.log(`Received: ${result.outputAmount} GUSDC`);
-
-// Wait for confirmation (optional)
-await result.wait();
-```
-
-### `getSwapUserAssets(walletAddress)`
-
-Get all token balances for a wallet on GalaSwap.
-
-**Parameters:**
-```typescript
-walletAddress: string;  // Wallet address (eth|0x... format)
-```
-
-**Returns:**
-```typescript
-Array<{
-  symbol: string;      // Token symbol (e.g., "GALA")
-  balance: string;     // Token balance
-  decimals: number;    // Token decimals
-  tokenId: string;     // Pipe-delimited token ID
-}>
-```
-
-**Example:**
-```typescript
-const assets = await sdk.getSwapUserAssets('eth|0x...');
-
-assets.forEach(asset => {
-  console.log(`${asset.symbol}: ${asset.balance}`);
-});
-```
-
-### `getSwapPoolInfo(tokenA, tokenB)`
-
-Get liquidity and fee information for a DEX pool.
-
-**Parameters:**
-```typescript
-tokenA: string;  // First token
-tokenB: string;  // Second token
-```
-
-**Returns:**
-```typescript
-{
-  liquidity: string;          // Total pool liquidity
-  feeTiers: number[];         // Available fee tiers
-  volume24h: string;          // 24-hour volume
-  swapCount: number;          // Total swap count
-  lastUpdated: Date;          // Snapshot timestamp
-}
-```
-
-**Example:**
-```typescript
-const pool = await sdk.getSwapPoolInfo('GALA', 'GUSDC');
-console.log(`Liquidity: ${pool.liquidity}`);
-console.log(`Fee tiers: ${pool.feeTiers.map(t => t / 100 + '%').join(', ')}`);
-```
-
----
-
-## GalaSwap Liquidity Position Management
-
-Provide liquidity to DEX pools and earn trading fees. Liquidity positions enable passive income through fee accumulation while helping maintain DEX liquidity.
-
-### `getAllSwapUserLiquidityPositions(ownerAddress)`
-
-Get **all** open liquidity positions for a wallet with automatic pagination (recommended).
-
-**Parameters:**
-```typescript
-ownerAddress: string;  // Wallet address (e.g., "0x1234..." or "eth|1234...")
-```
-
-**Returns:**
-```typescript
-Array<{
-  positionId: string;      // Unique position identifier
-  token0: string;          // First token symbol
-  token1: string;          // Second token symbol
-  feeTier: number;         // Fee tier in basis points
-  liquidity: string;       // Liquidity amount
-  amount0: string;         // Token0 amount in position
-  amount1: string;         // Token1 amount in position
-  feeAmount0: string;      // Accumulated fees (Token0)
-  feeAmount1: string;      // Accumulated fees (Token1)
-  tickLower: number;       // Lower tick boundary
-  tickUpper: number;       // Upper tick boundary
-}>
-```
-
-**Example:**
-```typescript
-// Fetch all positions with automatic pagination
-const allPositions = await sdk.getAllSwapUserLiquidityPositions('eth|0x...');
-
-console.log(`Total positions: ${allPositions.length}`);
-
-// Analyze positions
-allPositions.forEach(pos => {
-  console.log(`${pos.token0}/${pos.token1}: ${pos.liquidity} liquidity`);
-  console.log(`Fees earned: ${pos.feeAmount0} ${pos.token0}, ${pos.feeAmount1} ${pos.token1}`);
-});
-
-// Find best-performing position (highest accumulated fees)
-const bestPosition = allPositions.reduce((best, current) => {
-  const currentFees = parseFloat(current.feeAmount0) + parseFloat(current.feeAmount1);
-  const bestFees = parseFloat(best.feeAmount0) + parseFloat(best.feeAmount1);
-  return currentFees > bestFees ? current : best;
-});
-console.log(`Best position: ${bestPosition.token0}/${bestPosition.token1}`);
-```
-
-### `getSwapUserLiquidityPositions(ownerAddress, limit?, bookmark?)`
-
-Get open liquidity positions with manual pagination control (paginated version).
-
-**Parameters:**
-```typescript
-ownerAddress: string;     // Wallet address
-limit?: number;           // Results per page (default: 10, max: 20)
-bookmark?: string;        // Pagination bookmark from previous response
-```
-
-**Returns:** Same array structure as getAllSwapUserLiquidityPositions, plus pagination metadata:
-```typescript
-{
-  positions: Array<...>;  // Array of position objects
-  bookmark?: string;      // Bookmark for next page (if more results exist)
-  hasMore: boolean;       // True if more pages available
-  total: number;          // Total positions
-}
-```
-
-**Example:**
-```typescript
-// Paginated retrieval for streaming/processing
-let allPositions = [];
-let bookmark;
-let hasMore = true;
-
-while (hasMore) {
-  const page = await sdk.getSwapUserLiquidityPositions('eth|0x...', 10, bookmark);
-  allPositions = allPositions.concat(page.positions);
-  hasMore = !!page.bookmark;
-  bookmark = page.bookmark;
-  console.log(`Fetched page: ${page.positions.length} positions`);
-}
-
-console.log(`Total fetched: ${allPositions.length}`);
-```
-
-### `getSwapLiquidityPositionById(ownerAddress, positionId)`
-
-Get a specific liquidity position by its ID.
-
-**Parameters:**
-```typescript
-ownerAddress: string;     // Wallet address
-positionId: string;       // Position UUID
-```
-
-**Returns:** Single position object (same structure as above)
-
-**Example:**
-```typescript
-const position = await sdk.getSwapLiquidityPositionById('eth|0x...', 'position-uuid');
-
-console.log(`Position: ${position.token0}/${position.token1}`);
-console.log(`Liquidity: ${position.liquidity}`);
-console.log(`Accumulated fees: ${position.feeAmount0} + ${position.feeAmount1}`);
-```
-
-### `getSwapLiquidityPosition(ownerAddress, token0, token1, fee, tickLower, tickUpper)`
-
-Get a liquidity position by token pair and price range.
-
-**Parameters:**
-```typescript
-ownerAddress: string;  // Wallet address
-token0: string;        // First token
-token1: string;        // Second token
-fee: number;           // Fee tier (500, 3000, or 10000)
-tickLower: number;     // Lower tick boundary
-tickUpper: number;     // Upper tick boundary
-```
-
-**Returns:** Single position object
-
-**Example:**
-```typescript
-const position = await sdk.getSwapLiquidityPosition(
-  'eth|0x...',
-  'GALA',
-  'GUSDC',
-  3000,
-  -1000,
-  1000
-);
-
-console.log(`Active: ${position.liquidity > 0}`);
-```
-
-### `getSwapEstimateRemoveLiquidity(token0, token1, fee, liquidity, tickLower, tickUpper)`
-
-Estimate tokens and fees you'll receive when removing liquidity.
-
-**Parameters:**
-```typescript
-token0: string;        // First token
-token1: string;        // Second token
-fee: number;           // Fee tier
-liquidity: string;     // Liquidity amount to remove
-tickLower: number;     // Lower tick
-tickUpper: number;     // Upper tick
-```
-
-**Returns:**
-```typescript
-{
-  amount0: string;       // Token0 amount to receive
-  amount1: string;       // Token1 amount to receive
-  fee0: string;          // Collected fees (Token0)
-  fee1: string;          // Collected fees (Token1)
-  feeAmount0: string;    // Same as fee0
-  feeAmount1: string;    // Same as fee1
-  token0Symbol: string;  // Token0 symbol
-  token1Symbol: string;  // Token1 symbol
-}
-```
-
-**Example:**
-```typescript
-// Preview removal before executing
-const estimate = await sdk.getSwapEstimateRemoveLiquidity(
-  'GALA',
-  'GUSDC',
-  3000,
-  position.liquidity,
-  position.tickLower,
-  position.tickUpper
-);
-
-console.log(`Will receive: ${estimate.amount0} GALA, ${estimate.amount1} GUSDC`);
-console.log(`Collected fees: ${estimate.feeAmount0} GALA, ${estimate.feeAmount1} GUSDC`);
-```
-
-### `addSwapLiquidityByPrice(token0, token1, fee, minPrice, maxPrice, amount0Desired, amount1Desired, amount0Min?, amount1Min?)`
-
-Add liquidity by specifying a price range (user-friendly approach).
-
-**Parameters:**
-```typescript
-token0: string;          // First token
-token1: string;          // Second token
-fee: number;             // Fee tier (500, 3000, or 10000)
-minPrice: string;        // Minimum price (e.g., "0.95")
-maxPrice: string;        // Maximum price (e.g., "1.05")
-amount0Desired: string;  // Desired Token0 amount to provide
-amount1Desired: string;  // Desired Token1 amount to provide
-amount0Min?: string;     // Minimum Token0 (slippage protection, default: "0")
-amount1Min?: string;     // Minimum Token1 (slippage protection, default: "0")
-```
-
-**Returns:**
-```typescript
-{
-  transactionId: string;
-  status: 'PENDING' | 'COMPLETED' | 'FAILED';
-  positionId: string;    // New position ID
-  liquidity: string;     // Liquidity amount provided
-  amount0Used: string;   // Actual Token0 used
-  amount1Used: string;   // Actual Token1 used
-  wait(): Promise<TransactionResult>;
-}
-```
-
-**Example:**
-```typescript
-// Create position with 0.95-1.05 price range
-const result = await sdk.addSwapLiquidityByPrice({
-  token0: 'GALA',
-  token1: 'GUSDC',
-  fee: 3000,          // 0.30% fee tier
-  minPrice: '0.95',   // Active when price between 0.95-1.05
-  maxPrice: '1.05',
-  amount0Desired: '100',   // Provide 100 GALA
-  amount1Desired: '100',   // Provide 100 GUSDC
-  amount0Min: '95',        // Accept at least 95 GALA
-  amount1Min: '95'         // Accept at least 95 GUSDC
-});
-
-console.log(`Position created: ${result.positionId}`);
-console.log(`Liquidity provided: ${result.liquidity}`);
-
-// Wait for confirmation
-await result.wait();
-```
-
-### `addSwapLiquidityByTicks(token0, token1, feeTier, tickLower, tickUpper, amount0Desired, amount1Desired, amount0Min?, amount1Min?)`
-
-Add liquidity by specifying exact tick boundaries (advanced users).
-
-**Parameters:**
-```typescript
-token0: string;          // First token
-token1: string;          // Second token
-feeTier: number;         // Fee tier (500, 3000, or 10000)
-tickLower: number;       // Lower tick (must align with tickSpacing)
-tickUpper: number;       // Upper tick (must align with tickSpacing)
-amount0Desired: string;  // Desired Token0 amount
-amount1Desired: string;  // Desired Token1 amount
-amount0Min?: string;     // Minimum Token0 (default: "0")
-amount1Min?: string;     // Minimum Token1 (default: "0")
-```
-
-**Returns:** Same as addSwapLiquidityByPrice
-
-**Example:**
-```typescript
-// Create position with exact tick boundaries (advanced)
-// Note: ticks must be multiples of tickSpacing (varies by fee tier)
-const result = await sdk.addSwapLiquidityByTicks({
-  token0: 'GALA',
-  token1: 'GUSDC',
-  feeTier: 3000,
-  tickLower: -1000,   // Exact tick
-  tickUpper: 1000,    // Exact tick
-  amount0Desired: '100',
-  amount1Desired: '100'
-});
-
-console.log(`Position ID: ${result.positionId}`);
-```
-
-### `removeSwapLiquidity(ownerAddress, positionId, liquidity, amount0Min, amount1Min, deadline?)`
-
-Remove liquidity from a position and withdraw underlying tokens.
-
-**Parameters:**
-```typescript
-ownerAddress: string;  // Wallet address
-positionId: string;    // Position ID to remove from
-liquidity: string;     // Liquidity amount to remove (use full amount to close)
-amount0Min: string;    // Minimum Token0 to receive (slippage protection)
-amount1Min: string;    // Minimum Token1 to receive (slippage protection)
-deadline?: number;     // Deadline timestamp (unix seconds, optional)
-```
-
-**Returns:**
-```typescript
-{
-  transactionId: string;
-  status: 'PENDING' | 'COMPLETED' | 'FAILED';
-  amount0Withdrawn: string;  // Token0 received
-  amount1Withdrawn: string;  // Token1 received
-  fee0Collected: string;     // Fees collected (Token0)
-  fee1Collected: string;     // Fees collected (Token1)
-  wait(): Promise<TransactionResult>;
-}
-```
-
-**Example:**
-```typescript
-// Preview removal before executing
-const estimate = await sdk.getSwapEstimateRemoveLiquidity(
-  position.token0,
-  position.token1,
-  position.feeTier,
-  position.liquidity,
-  position.tickLower,
-  position.tickUpper
-);
-
-// Remove full liquidity and close position
-const result = await sdk.removeSwapLiquidity({
-  ownerAddress: 'eth|0x...',
-  positionId: position.positionId,
-  liquidity: position.liquidity,
-  amount0Min: estimate.amount0,  // Use estimate values
-  amount1Min: estimate.amount1,
-  deadline: Math.floor(Date.now() / 1000) + 3600  // 1 hour from now
-});
-
-console.log(`Withdrawn: ${result.amount0Withdrawn} + ${result.amount1Withdrawn}`);
-console.log(`Fees collected: ${result.fee0Collected} + ${result.fee1Collected}`);
-```
-
-### `collectSwapPositionFees(ownerAddress, positionId, amount0Max?, amount1Max?)`
-
-Collect accumulated trading fees without closing the position.
-
-**Parameters:**
-```typescript
-ownerAddress: string;    // Wallet address
-positionId: string;      // Position ID
-amount0Max?: string;     // Maximum Token0 fees (optional)
-amount1Max?: string;     // Maximum Token1 fees (optional)
-```
-
-**Returns:**
-```typescript
-{
-  transactionId: string;
-  status: 'PENDING' | 'COMPLETED' | 'FAILED';
-  amount0Collected: string;  // Token0 fees collected
-  amount1Collected: string;  // Token1 fees collected
-  wait(): Promise<TransactionResult>;
-}
-```
-
-**Example:**
-```typescript
-// Collect fees periodically without removing liquidity
-const result = await sdk.collectSwapPositionFees({
-  ownerAddress: 'eth|0x...',
-  positionId: position.positionId
-});
-
-console.log(`Collected: ${result.amount0Collected} + ${result.amount1Collected}`);
-
-// Position remains active and continues earning fees
-```
-
-### Complete Liquidity Management Workflow
-
-```typescript
-// 1. View all positions
-const positions = await sdk.getAllSwapUserLiquidityPositions('eth|0x...');
-console.log(`You have ${positions.length} active positions`);
-
-// 2. Create new position
-const newPos = await sdk.addSwapLiquidityByPrice({
-  token0: 'GALA',
-  token1: 'GUSDC',
-  fee: 3000,
-  minPrice: '0.95',
-  maxPrice: '1.05',
-  amount0Desired: '1000',
-  amount1Desired: '1000'
-});
-
-await newPos.wait();
-console.log(`Position created: ${newPos.positionId}`);
-
-// 3. Monitor fees (periodically)
-setTimeout(async () => {
-  const position = await sdk.getSwapLiquidityPositionById('eth|0x...', newPos.positionId);
-  console.log(`Fees earned: ${position.feeAmount0} + ${position.feeAmount1}`);
-}, 3600000);  // Every hour
-
-// 4. Collect fees when ready
-const fees = await sdk.collectSwapPositionFees({
-  ownerAddress: 'eth|0x...',
-  positionId: newPos.positionId
-});
-
-console.log(`Harvested: ${fees.amount0Collected} + ${fees.amount1Collected}`);
-
-// 5. Close position when desired
-const removed = await sdk.removeSwapLiquidity({
-  ownerAddress: 'eth|0x...',
-  positionId: newPos.positionId,
-  liquidity: newPos.liquidity,
-  amount0Min: '0',
-  amount1Min: '0'
-});
-
-console.log(`Closed position, received: ${removed.amount0Withdrawn} + ${removed.amount1Withdrawn}`);
-```
-
----
-
-## Pool Information
-
-### `fetchPoolDetails(tokenName)`
-
-Get detailed information about a bonding curve pool.
-
-**Parameters:**
-```typescript
-tokenName: string;  // Token symbol
-```
-
-**Returns:**
-```typescript
-{
-  tokenName: string;
-  symbol: string;
-  currentSupply: string;
-  maxSupply: string;
-  sellingTokenQuantity: string;
-  reserveGala: string;
-  saleStatus: 'Ongoing' | 'Completed';
-  createdAt: Date;
-  fees: {
-    transactionFee: string;
-    reverseBondingCurveFee: { min: string; max: string };
-  };
-}
-```
-
-**Example:**
-```typescript
-const pool = await sdk.fetchPoolDetails('anime');
-console.log(`Supply: ${pool.currentSupply}/${pool.maxSupply}`);
-console.log(`Status: ${pool.saleStatus}`);
-```
-
-### `fetchAllPools(options?)`
-
-Fetch all bonding curve pools with filtering and pagination.
-
-**Parameters:**
-```typescript
-interface FetchPoolsOptions {
-  type?: 'recent' | 'popular';  // Default: 'recent'
-  page?: number;                 // Default: 1
-  limit?: number;                // Default: 20, max: 100
-}
-```
-
-**Example:**
-```typescript
-const pools = await sdk.fetchAllPools({ type: 'popular', limit: 50 });
-pools.forEach(pool => {
-  console.log(`${pool.tokenName}: ${pool.saleStatus}`);
-});
-```
-
----
-
-## Token Management
-
-### `launchToken(options)`
-
-Create a new token on the launchpad.
-
-**Parameters:**
-```typescript
-interface TokenLaunchOptions {
-  tokenName: string;      // Token name (3-20 alphanumeric)
-  tokenSymbol: string;    // Token symbol (1-8 uppercase)
-  tokenDescription: string;  // Description (1-500 chars)
-  tokenImage: string;     // Image URL
-  websiteUrl?: string;    // Website URL (optional)
-  twitterUrl?: string;    // Twitter URL (optional)
-  telegramUrl?: string;   // Telegram URL (optional)
-  preBuyQuantity?: string; // Pre-buy token amount (default: "0")
-  reverseBondingCurveConfiguration?: {
-    minFeePortion?: string;
-    maxFeePortion?: string;
-  };
-}
-```
-
-**Returns:**
-```typescript
-{
-  tokenName: string;
-  tokenSymbol: string;
-  creatorAddress: string;
-  transactionId: string;
-  status: 'PENDING' | 'COMPLETED' | 'FAILED';
-}
-```
-
-**Example:**
-```typescript
-const result = await sdk.launchToken({
-  tokenName: 'mytoken',
-  tokenSymbol: 'MTK',
-  tokenDescription: 'A new launchpad token',
-  tokenImage: 'https://example.com/image.png',
-  websiteUrl: 'https://example.com',
-  preBuyQuantity: '1000'  // Pre-buy 1000 tokens
-});
-
-console.log(`Token created: ${result.tokenName}`);
-```
-
-### `checkTokenName(tokenName)`
-
-Check if a token name is available.
-
-**Parameters:**
-```typescript
-tokenName: string;
-```
-
-**Returns:**
-```typescript
-{
-  available: boolean;
-  tokenName: string;
-}
-```
-
-### `checkTokenSymbol(symbol)`
-
-Check if a token symbol is available.
-
-**Parameters:**
-```typescript
-symbol: string;  // 1-8 uppercase characters
-```
-
-**Returns:**
-```typescript
-{
-  available: boolean;
-  symbol: string;
-}
-```
-
-### `fetchTokenClassesWithSupply(tokenClasses)`
-
-Fetch authoritative supply information for one or more token classes from GalaChain.
-
-Queries the GalaChain network for definitive token supply data including total supply, maximum supply, burned amounts, and mint-related metrics. This method provides blockchain-verified token information.
-
-**Parameters:**
-```typescript
-tokenClasses: TokenClassKey[];  // Array of token class identifiers
-```
-
-**Returns:**
-```typescript
-Promise<Array<{
-  // Token Identification
-  collection: string;      // Token collection (e.g., 'Token')
-  category: string;        // Token category (e.g., 'Unit')
-  type: string;           // Token type (e.g., 'GALA', 'GUSDC')
-  additionalKey: string;  // Additional key/network (e.g., 'eth:0x...', 'none')
-
-  // Token Metadata
-  symbol: string;         // Token symbol
-  name: string;          // Token display name
-  decimals: number;      // Decimal precision
-
-  // Supply Information
-  totalSupply: string;             // Current total supply in circulation
-  maxSupply: string;               // Maximum possible supply
-  totalBurned: string;             // Total amount burned
-  knownMintSupply: string;         // Known mint supply
-  knownMintAllowanceSupply: string; // Known mint allowance
-}>>
-```
-
-**Example:**
-```typescript
-// Query single token
-const supplies = await sdk.fetchTokenClassesWithSupply([
-  {
-    collection: 'GALA',
-    category: 'Unit',
-    type: 'none',
-    additionalKey: 'none'
-  }
-]);
-
-console.log(`GALA Total Supply: ${supplies[0].totalSupply}`);
-console.log(`GALA Max Supply: ${supplies[0].maxSupply}`);
-console.log(`GALA Burned: ${supplies[0].totalBurned}`);
-
-// Query multiple tokens in one call
-const multiSupplies = await sdk.fetchTokenClassesWithSupply([
-  { collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' },
-  { collection: 'GUSDC', category: 'Unit', type: 'none', additionalKey: 'none' }
-]);
-
-// Analyze supply metrics
-for (const token of multiSupplies) {
-  const circulationPercent = (parseFloat(token.totalSupply) / parseFloat(token.maxSupply)) * 100;
-  const burnPercent = (parseFloat(token.totalBurned) / parseFloat(token.totalSupply)) * 100;
-
-  console.log(`${token.symbol}:`);
-  console.log(`  Circulation: ${circulationPercent.toFixed(2)}% of max`);
-  console.log(`  Burned: ${burnPercent.toFixed(2)}% of total`);
-}
-```
-
-**Use Cases:**
-- Token supply tracking and dashboards
-- Burn rate analysis and monitoring
-- Mint allowance verification
-- Token health metrics and reporting
-- Supply distribution analysis
-- Compliance and audit reporting
-
----
-
-## Portfolio & Balances
-
-### `fetchGalaBalance(address?)`
-
-Get GALA token balance for a wallet.
-
-**Parameters:**
-```typescript
-address?: string;  // Wallet address (default: authenticated wallet)
-```
-
-**Returns:**
-```typescript
-string;  // GALA balance
-```
-
-**Example:**
-```typescript
-const balance = await sdk.fetchGalaBalance();
-console.log(`GALA balance: ${balance}`);
-```
-
-### `fetchTokenBalance(tokenName, address)`
-
-Get balance for a specific launchpad token.
-
-**Parameters:**
-```typescript
-tokenName: string;  // Token symbol
-address: string;    // Wallet address
-```
-
-**Returns:**
-```typescript
-string;  // Token balance
-```
-
-### `fetchTokensHeld(options?)`
-
-Get all tokens held by a wallet with optional filtering.
-
-**Parameters:**
-```typescript
-interface FetchTokensOptions {
-  tokenName?: string;  // Exact token name filter
-  search?: string;     // Fuzzy search filter
-  page?: number;       // Default: 1
-  limit?: number;      // Default: 20, max: 20
-}
-```
-
-**Returns:**
-```typescript
-Array<{
-  tokenName: string;
-  balance: string;
-  symbol: string;
-  decimals: number;
-}>
-```
-
-**Example:**
-```typescript
-// Get specific token
-const anime = await sdk.fetchTokensHeld({ tokenName: 'anime', limit: 1 });
-
-// Search for tokens
-const dragonTokens = await sdk.fetchTokensHeld({ search: 'dragon', limit: 10 });
-```
-
-### `fetchTokensCreated(options?)`
-
-Get all tokens created by a wallet with optional filtering.
-
-**Parameters:** Same as `fetchTokensHeld()`
-
-### `fetchTokenDistribution(tokenName)`
-
-Get all token holders and distribution percentages (non-paginated).
-
-**Parameters:**
-```typescript
-tokenName: string;
-```
-
-**Returns:**
-```typescript
-{
-  holders: Array<{
-    address: string;      // Holder address
-    balance: string;      // Token balance
-    percentage: number;   // Ownership percentage
-  }>;
-  totalSupply: string;
-  totalHolders: number;
-  lastUpdated: Date;
-}
-```
-
-**Example:**
-```typescript
-const distribution = await sdk.fetchTokenDistribution('anime');
-const topHolders = distribution.holders
-  .sort((a, b) => b.percentage - a.percentage)
-  .slice(0, 5);
-
-topHolders.forEach((h, i) => {
-  console.log(`#${i + 1}: ${h.percentage.toFixed(2)}% (${h.address})`);
-});
-```
-
-### `fetchProfile(address?)`
-
-Get user profile information.
-
-**Parameters:**
-```typescript
-address?: string;  // Wallet address (default: authenticated user)
-```
-
-**Returns:**
-```typescript
-{
-  address: string;
-  fullName: string;
-  profileImage: string;
-  createdAt: Date;
-}
-```
-
-### `updateProfile(options)`
-
-Update user profile.
-
-**Parameters:**
-```typescript
-interface UpdateProfileOptions {
-  fullName: string;
-  profileImage: string;  // URL or empty string
-  address: string;       // Wallet address
-}
-```
-
----
-
-## Price History & Analytics
-
-### `fetchPriceHistory(options)`
-
-Get historical price snapshots (paginated, Node.js only).
-
-**Parameters:**
-```typescript
-interface FetchPriceHistoryOptions {
-  tokenName?: string;       // Simple token name (NEW v3.20.0)
-  tokenId?: string | TokenClassKey;  // OR full token ID
-  from?: Date | string;     // Start date (ISO 8601)
-  to?: Date | string;       // End date (ISO 8601)
-  sortOrder?: 'ASC' | 'DESC'; // Default: 'DESC' (newest first)
-  page?: number;            // Default: 1
-  limit?: number;           // Default: 10, max: 50
-}
-```
-
-**Returns:**
-```typescript
-{
-  snapshots: Array<{
-    price: string;        // Token price in GUSDC
-    timestamp: Date;      // Snapshot timestamp
-    tokenId: string;      // Token identifier
-  }>;
-  page: number;
-  limit: number;
-  total: number;
-  totalPages: number;
-  hasNext: boolean;
-  hasPrevious: boolean;
-}
-```
-
-**Example:**
-```typescript
-// Using simple token name
-const history = await sdk.fetchPriceHistory({
-  tokenName: 'anime',
-  from: new Date('2025-01-01'),
-  to: new Date('2025-01-31'),
-  limit: 50
-});
-
-console.log(`Latest price: $${history.snapshots[0].price}`);
-```
-
-### `fetchAllPriceHistory(options)`
-
-Get all historical price snapshots (auto-paginated, Node.js only).
-
-**Parameters:** Same as `fetchPriceHistory()` but without pagination parameters
-
-**Returns:** Same structure as `fetchPriceHistory()` with all snapshots combined
-
-**Example:**
-```typescript
-const allHistory = await sdk.fetchAllPriceHistory({
-  tokenName: 'anime',
-  from: '2024-01-01',
-  to: '2025-01-31'
-});
-
-console.log(`Total snapshots: ${allHistory.snapshots.length}`);
-```
-
-### `fetchTokenDetails(tokenId)`
-
-Get comprehensive token metadata from DEX API.
-
-**Parameters:**
-```typescript
-tokenId: string | {
-  collection: string;
-  category: string;
-  type: string;
-  additionalKey: string;
-};
-```
-
-**Returns:**
-```typescript
-{
-  symbol: string;
-  name: string;
-  decimals: number;
-  verified: boolean;
-  image: string;
-  description: string;
-  network: string;
-  chainId: string;
-  contractAddress: string;
-  tradingEnabled: boolean;
-  currentPrice?: string;
-  volume24h?: string;
-}
-```
-
-**Example:**
-```typescript
-const details = await sdk.fetchTokenDetails('GUSDC|Unit|none|eth:0x...');
-
-if (details.verified && details.tradingEnabled) {
-  console.log(`${details.symbol}: ${details.name}`);
-}
-```
-
----
-
-## Real-Time Features
-
-### `fetchTrades(options?)`
-
-Get trade history for your wallet.
-
-**Parameters:**
-```typescript
-interface FetchTradesOptions {
-  tokenName?: string;      // Filter by token
-  tradeType?: 'BUY' | 'SELL';  // Filter by type
-  userAddress?: string;    // Filter by user address
-  startDate?: Date;        // Start date
-  endDate?: Date;          // End date
-  sortOrder?: 'ASC' | 'DESC'; // Default: 'DESC'
-  page?: number;           // Default: 1
-  limit?: number;          // Default: 10, max: 20
-}
-```
-
-**Returns:**
-```typescript
-Array<{
-  transactionId: string;
-  type: 'BUY' | 'SELL';
-  tokenName: string;
-  inputAmount: string;
-  outputAmount: string;
-  fees: { transaction: string; gas: string };
-  timestamp: Date;
-  status: 'COMPLETED' | 'FAILED' | 'PENDING';
-}>
-```
-
-### `getBundlerTransactionResult(transactionId)`
-
-Get detailed transaction status and results.
-
-**Parameters:**
-```typescript
-transactionId: string;  // UUID format transaction ID
-```
-
-**Returns:**
-```typescript
-{
-  id: string;
-  method: string;
-  status: 'COMPLETED' | 'FAILED' | 'PENDING' | 'PROCESSING';
-  result?: {
-    transactionId: string;
-    inputAmount: string;
-    outputAmount: string;
-  };
-}
-```
-
----
-
-## Type Definitions
-
-### TokenClassKey
-```typescript
-interface TokenClassKey {
-  collection: string;     // Usually "Token"
-  category: string;       // Usually "Unit"
-  type: string;          // Token symbol (e.g., "GALA")
-  additionalKey: string; // Network/chain info or "none"
-}
-```
-
-### TokenClassWithSupply
-```typescript
-interface TokenClassWithSupply {
-  // Token Identification
-  collection: string;      // Token collection (e.g., "Token")
-  category: string;        // Token category (e.g., "Unit")
-  type: string;           // Token type (e.g., "GALA", "GUSDC")
-  additionalKey: string;  // Network/chain info (e.g., "eth:0x...", "none")
-
-  // Token Metadata
-  symbol: string;         // Token symbol
-  name: string;          // Token display name
-  decimals: number;      // Decimal precision
-
-  // Supply Information
-  totalSupply: string;             // Current total supply in circulation
-  maxSupply: string;               // Maximum possible supply
-  totalBurned: string;             // Total amount burned
-  knownMintSupply: string;         // Known mint supply
-  knownMintAllowanceSupply: string; // Known mint allowance supply
-
-  // Optional Fields
-  authorities?: Array<{   // Optional token authorities
-    address?: string;     // Authority address
-    role?: string;       // Authority role/type
-  }>;
-}
-```
-
-### TransactionResult
-```typescript
-interface TransactionResult {
-  transactionId: string;
-  status: 'COMPLETED' | 'FAILED' | 'PENDING';
-  inputAmount: string;
-  outputAmount: string;
-  actualFees: {
-    transaction: string;
-    gas: string;
-    rbc?: string;
-  };
-  timestamp: Date;
-}
-```
-
-### SwapQuote
-```typescript
-interface SwapQuote {
-  estimatedOutput: string;
-  priceImpact: number;
-  feeTier: number;
-  exchangeRate: string;
-  minimumOutput: string;
-}
-```
-
----
-
-## Error Handling
-
-The SDK throws descriptive errors for invalid operations:
-
-```typescript
-try {
-  const quote = await sdk.getSwapQuoteExactInput('GALA', 'UNKNOWN', '100');
-} catch (error) {
-  if (error.message.includes('Pool not found')) {
-    console.log('Token pair has no DEX liquidity');
-  } else if (error.message.includes('Invalid token')) {
-    console.log('Token format is not recognized');
-  } else if (error.message.includes('Wallet')) {
-    console.log('No wallet configured - set privateKey in SDK config');
-  } else {
-    console.log(`Error: ${error.message}`);
-  }
-}
-```
-
-### Common Error Scenarios
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| "Wallet not configured" | No privateKey set for signing | Add privateKey to SDK config |
-| "Pool not found" | Token pair has no DEX liquidity | Check token has graduated |
-| "Slippage exceeded" | Price moved too much | Increase slippageTolerance |
-| "Insufficient balance" | Not enough tokens to sell | Check wallet balance first |
-| "Invalid token format" | Token ID is malformed | Use correct format or simple symbol |
-
----
-
-## Version Compatibility
-
-- **SDK Version**: v3.23.0+
-- **GSwap SDK**: v0.0.7+
-- **Node.js**: 16+
-- **Browser**: Modern browsers with ES2020+ support
-
----
-
-## Additional Resources
-
-- [GalaSwap Integration Guide](../docs/gswap-integration.md)
-- [Project Instructions & Examples](../CLAUDE.md)
-- [GitHub Repository](https://github.com/GalaChain/launchpad-sdk)
-- [MCP Server Tools Reference](../packages/mcp-server/README.md)