@gala-chain/launchpad-sdk 3.23.0 → 3.24.1

package/API.md

@@ -0,0 +1,955 @@
+# Gala Launchpad SDK - API Reference
+
+Complete API documentation for the Gala Launchpad SDK (v3.23.0+).
+
+## Table of Contents
+
+- [SDK Initialization](#sdk-initialization)
+- [Bonding Curve Trading (Launchpad Tokens)](#bonding-curve-trading)
+- [DEX Trading (Graduated Tokens)](#dex-trading-galaswap)
+- [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)
+
+---
+
+## 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 ("GALA", "GUSDC", or pipe-delimited format)
+toToken: string;    // Destination token ("GALA", "GUSDC", or pipe-delimited format)
+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?
+const quote = await sdk.getSwapQuoteExactInput('GALA', 'GUSDC', '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(', ')}`);
+```
+
+---
+
+## 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;
+}
+```
+
+---
+
+## 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('Token|Unit|GUSDC|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"
+}
+```
+
+### 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)