@gala-chain/launchpad-sdk 3.31.2 → 4.0.1-beta.0

package/dist/{LaunchpadSDK.d.ts → src/LaunchpadSDK.d.ts}

@@ -1,15 +1,20 @@
 import { Wallet } from 'ethers';
 import { SDKConfig, AddressFormat, TokenClassKey, TokenId } from './types/common';
 import { PoolDetailsData } from './types/trade.dto';
-import { LaunchTokenData, TokenSpotPrice, FetchPoolsOptions, PoolsResult, GalaChainTokenDetails, PoolData } from './types/launchpad.dto';
+import { LaunchTokenData, TokenSpotPrice, FetchPoolsOptions, PoolsResult, GalaChainTokenDetails, PoolData, TokenClassWithSupply, DexSeason, LeaderboardResult, DexAggregatedVolumeSummary } from './types/launchpad.dto';
 import { UpdateProfileData, UploadProfileImageOptions, FetchTokenBalanceOptions } from './types/user.dto';
 import { TransferGalaData, TransferTokenData } from './types/transfer.dto';
+import { LockTokenData, UnlockTokenData } from './types/lock.dto';
 import { TokenLaunchResult, TradeResult } from './types/result.types';
 import { WebSocketError, WebSocketTimeoutError, TransactionFailedError } from './utils/websocket-errors';
 export { WebSocketError, WebSocketTimeoutError, TransactionFailedError, };
 import { FetchCommentsOptions, PostCommentOptions, FetchVolumeDataOptions, FetchTradesOptions, CalculateBuyAmountOptions, CalculateSellAmountOptions, CalculateBuyAmountLocalOptions, CalculateSellAmountLocalOptions, BuyTokenOptions, SellTokenOptions, UploadImageByTokenNameOptions, FetchTokensHeldOptions, FetchTokensCreatedOptions, GraduateTokenOptions, FetchLaunchpadTokenSpotPriceOptions, FetchTokenSpotPriceParams, CalculateBuyAmountForGraduationOptions } from './types/options.dto';
 import { FetchPriceHistoryOptions, PriceHistoryResult } from './types/priceHistory.dto';
 import { FetchDexPoolsOptions, DexPoolsResult, DexPoolData } from './types/dex-pool.dto';
+import { GSwapPosition, PoolPriceData, GetLiquidityPositionsOptions, GetLiquidityPositionsResult } from './types/gswap.dto';
+import type { FetchCompositePoolDataOptions, CompositePoolDataResult, CalculateDexPoolQuoteOptions, DexPoolQuoteResult } from './types/composite-pool.dto';
+import type { SubscribeSwapOptions, SwapMonitorConfig, CleanupFunction, SwapEventCallback } from './types/swap-monitor.dto';
+import type { LiquidityChangedCallback, LiquidityCleanupFunction, SubscribeLiquidityOptions } from './types/liquidity-monitor.dto';
 /**
  * Configuration for initializing the Launchpad SDK
  *
@@ -72,6 +77,22 @@ export interface LaunchpadSDKConfig extends SDKConfig {
      * @default 'local'
      */
     calculateAmountMode?: 'local' | 'external';
+    /**
+     * Optional network timeout for DEX quote API calls (in milliseconds).
+     * Use for rate-limited APIs or networks with high latency.
+     * @default 30000 (30 seconds)
+     * @min 1000
+     * @max 300000
+     * @example
+     * ```typescript
+     * // Increase timeout for rate-limited API
+     * const sdk = new LaunchpadSDK({
+     *   wallet,
+     *   dexQuoteNetworkTimeout: 60000 // 60 seconds
+     * });
+     * ```
+     */
+    dexQuoteNetworkTimeout?: number;
 }
 /**
  * Main Launchpad SDK class providing access to all Gala Launchpad functionality
@@ -151,9 +172,11 @@ export declare class LaunchpadSDK {
     private readonly dexApiHttp;
     private readonly dexBackendHttp;
     private readonly config;
+    private readonly environment;
     private readonly slippageToleranceFactor;
     private readonly maxAcceptableReverseBondingCurveFeeSlippageFactor;
     private readonly calculateAmountMode;
+    private readonly pricingConcurrency;
     private readonly logger;
     private readonly tokenResolverService;
     private readonly launchpadService;
@@ -164,6 +187,7 @@ export declare class LaunchpadSDK {
     private readonly priceHistoryService;
     private readonly gswapService;
     private readonly dexPoolService;
+    private readonly dexQuoteService;
     private readonly cache;
     private readonly launchpadAPI;
     constructor(config: LaunchpadSDKConfig);
@@ -413,7 +437,9 @@ export declare class LaunchpadSDK {
      * }
      * ```
      */
-    getConfig(): Omit<LaunchpadSDKConfig, 'wallet'>;
+    getConfig(): Omit<LaunchpadSDKConfig, 'wallet'> & {
+        environment: 'STAGE' | 'PROD';
+    };
     /**
      * Get the SDK version
      *
@@ -685,7 +711,170 @@ export declare class LaunchpadSDK {
      */
     fetchAllDexPools(options?: Omit<FetchDexPoolsOptions, 'page' | 'limit'>): Promise<DexPoolsResult>;
     /**
-     * Fetch token distribution information
+     * Fetch composite pool data from GalaChain for offline DEX quote calculations
+     *
+     * Retrieves complete pool state including liquidity, tick data, token balances, and decimals.
+     * This data is required for offline quote calculations using local bonding curve math.
+     *
+     * The composite pool data can be fetched once and reused for multiple quote calculations,
+     * making it efficient for bulk pricing operations.
+     *
+     * @param options Pool identification options with token pair and fee tier
+     * @returns CompositePoolDataResult containing complete pool state for offline calculations
+     * @throws DexPoolNotFoundError if the pool does not exist
+     * @throws DexQuoteError on API or conversion errors
+     * @since 3.32.0
+     * @category DEX Quotes
+     *
+     * @example Fetch and reuse composite pool data
+     * ```typescript
+     * // Step 1: Fetch composite data (one network call)
+     * const composite = await sdk.fetchCompositePoolData({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'Token|Unit|BENE|client:5c806869e7fd0e2384461ce9',
+     *   fee: 3000  // 0.30%
+     * });
+     *
+     * // Step 2: Calculate multiple quotes using same composite data (instant, local)
+     * const quote1 = await sdk.calculateDexPoolQuoteExactAmountLocal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:5c806869e7fd0e2384461ce9',
+     *   amount: '100'
+     * });
+     *
+     * const quote2 = await sdk.calculateDexPoolQuoteExactAmountLocal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:5c806869e7fd0e2384461ce9',
+     *   amount: '500'
+     * });
+     *
+     * // Step 3: Compare with real-time quote from chain
+     * const liveQuote = await sdk.calculateDexPoolQuoteExactAmountExternal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:5c806869e7fd0e2384461ce9',
+     *   amount: '100'
+     * });
+     * ```
+     */
+    fetchCompositePoolData(options: FetchCompositePoolDataOptions): Promise<CompositePoolDataResult>;
+    /**
+     * Calculate DEX pool quote using LOCAL client-side calculation
+     *
+     * Instant quotes without network calls using pre-fetched composite pool data and
+     * the @gala-chain/dex bonding curve math library.
+     *
+     * Perfect for bulk pricing operations, simulations, and price discovery where
+     * network latency is unacceptable.
+     *
+     * @param options Quote calculation options (must include pre-fetched compositePoolData)
+     * @returns DexPoolQuoteResult with input/output amounts and execution prices
+     * @throws DexQuoteError on calculation errors
+     * @since 3.32.0
+     * @category DEX Quotes
+     *
+     * @example Fast bulk pricing
+     * ```typescript
+     * const composite = await sdk.fetchCompositePoolData({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'Token|Unit|BENE|client:123',
+     *   fee: 3000
+     * });
+     *
+     * // Get 100 instant quotes without any network calls
+     * const amounts = ['10', '50', '100', '500', '1000'];
+     * const quotes = await Promise.all(
+     *   amounts.map(amount =>
+     *     sdk.calculateDexPoolQuoteExactAmountLocal({
+     *       compositePoolData: composite,
+     *       fromToken: 'GALA|Unit|none|none',
+     *       toToken: 'Token|Unit|BENE|client:123',
+     *       amount
+     *     })
+     *   )
+     * );
+     * ```
+     */
+    calculateDexPoolQuoteExactAmountLocal(options: CalculateDexPoolQuoteOptions): Promise<DexPoolQuoteResult>;
+    /**
+     * Calculate DEX pool quote using EXTERNAL GalaChain network call
+     *
+     * Real-time quotes directly from the blockchain. Slower than local calculation
+     * but always reflects current pool state and is useful for final price verification.
+     *
+     * @param options Quote calculation options (compositePoolData provides token metadata)
+     * @returns DexPoolQuoteResult with current chain state
+     * @throws DexQuoteError on network or calculation errors
+     * @since 3.32.0
+     * @category DEX Quotes
+     *
+     * @example Verify quote with live chain data
+     * ```typescript
+     * const composite = await sdk.fetchCompositePoolData({
+     *   token0: 'GALA|Unit|none|none',
+     *   token1: 'Token|Unit|BENE|client:123',
+     *   fee: 3000
+     * });
+     *
+     * // Local estimate (instant)
+     * const estimate = await sdk.calculateDexPoolQuoteExactAmountLocal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '1000'
+     * });
+     *
+     * // Live verification from chain
+     * const liveQuote = await sdk.calculateDexPoolQuoteExactAmountExternal({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '1000'
+     * });
+     *
+     * console.log(`Difference: ${estimate.amount1} vs ${liveQuote.amount1}`);
+     * ```
+     */
+    calculateDexPoolQuoteExactAmountExternal(options: CalculateDexPoolQuoteOptions): Promise<DexPoolQuoteResult>;
+    /**
+     * Calculate DEX pool quote with automatic mode selection
+     *
+     * Main quote calculation method that delegates to local or external based on mode parameter.
+     * Defaults to local (instant) calculation.
+     *
+     * @param options Quote calculation options
+     * @param mode 'local' (instant, client-side) or 'external' (real-time, chain) - defaults to 'local'
+     * @returns DexPoolQuoteResult with amounts and prices
+     * @since 3.32.0
+     * @category DEX Quotes
+     *
+     * @example Using default local mode
+     * ```typescript
+     * const quote = await sdk.calculateDexPoolQuoteExactAmount({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '1000'
+     * });
+     * // Returns instant local quote
+     * ```
+     *
+     * @example Explicit external mode for real-time
+     * ```typescript
+     * const liveQuote = await sdk.calculateDexPoolQuoteExactAmount({
+     *   compositePoolData: composite,
+     *   fromToken: 'GALA|Unit|none|none',
+     *   toToken: 'Token|Unit|BENE|client:123',
+     *   amount: '1000'
+     * }, 'external');
+     * // Returns real-time quote from chain
+     * ```
+     */
+    calculateDexPoolQuoteExactAmount(options: CalculateDexPoolQuoteOptions, mode?: 'local' | 'external'): Promise<DexPoolQuoteResult>;
+    /**
+     * Token distribution information
      *
      * @param tokenName Token name to fetch distribution for
      * @returns Promise<TokenDistributionResult>
@@ -786,7 +975,7 @@ export declare class LaunchpadSDK {
      * and trading capabilities.
      *
      * Supports flexible token identification using either string or object format:
-     * - String: `'Token|Unit|GUSDC|eth:0x...'` (pipe-delimited)
+     * - String: `'GUSDC|Unit|none|eth:0x...'` (pipe-delimited)
      * - Object: `{ collection, category, type, additionalKey }`
      *
      * @param tokenId Token identifier in flexible format
@@ -794,7 +983,7 @@ export declare class LaunchpadSDK {
      *
      * @example String format
      * ```typescript
-     * const details = await sdk.fetchTokenDetails('Token|Unit|GUSDC|eth:0x...');
+     * const details = await sdk.fetchTokenDetails('GUSDC|Unit|none|none');
      * console.log(details.symbol);      // 'GUSDC'
      * console.log(details.decimals);    // 6
      * console.log(details.verified);    // true
@@ -804,10 +993,10 @@ export declare class LaunchpadSDK {
      * @example Object format
      * ```typescript
      * const details = await sdk.fetchTokenDetails({
-     *   collection: 'Token',
+     *   collection: 'GUSDC',
      *   category: 'Unit',
-     *   type: 'GUSDC',
-     *   additionalKey: 'eth:0x...'
+     *   type: 'none',
+     *   additionalKey: 'none'
      * });
      * ```
      *
@@ -815,6 +1004,156 @@ export declare class LaunchpadSDK {
      * @throws {NetworkError} If API request fails or token not found
      */
     fetchTokenDetails(tokenId: TokenId): Promise<GalaChainTokenDetails>;
+    /**
+     * Fetch all available DEX leaderboard seasons
+     *
+     * Returns all season configurations with time ranges. Use season IDs
+     * to fetch specific leaderboards with `fetchDexLeaderboardBySeasonId()`.
+     *
+     * @category DEX Leaderboard
+     * @returns Promise<DexSeason[]> Array of all seasons
+     * @throws {NetworkError} If API request fails
+     * @since 3.X.0
+     *
+     * @example
+     * ```typescript
+     * const seasons = await sdk.fetchAllDexSeasons();
+     * console.log(`Found ${seasons.length} seasons`);
+     * seasons.forEach(s => {
+     *   console.log(`${s.name}: ${s.start} to ${s.end}`);
+     * });
+     * ```
+     */
+    fetchAllDexSeasons(): Promise<DexSeason[]>;
+    /**
+     * Find the currently active DEX leaderboard season
+     *
+     * Determines which season is active based on current time falling
+     * between season start and end dates. Returns null if no season
+     * is currently active.
+     *
+     * @category DEX Leaderboard
+     * @returns Promise<DexSeason | null> Current season or null
+     * @throws {NetworkError} If API request fails
+     * @since 3.X.0
+     *
+     * @example
+     * ```typescript
+     * const current = await sdk.fetchCurrentDexSeason();
+     * if (current) {
+     *   console.log(`Active: ${current.name} (ID: ${current.id})`);
+     * } else {
+     *   console.log('No active season');
+     * }
+     * ```
+     */
+    fetchCurrentDexSeason(): Promise<DexSeason | null>;
+    /**
+     * Fetch DEX leaderboard for a specific season
+     *
+     * Returns complete leaderboard rankings with XP metrics and achievement titles.
+     * Non-paginated response includes all entries (typically 100 participants).
+     *
+     * **XP Metrics:**
+     * - `totalXp`: Combined liquidity + trading XP
+     * - `liquidityXp`: Points from providing liquidity
+     * - `tradingXp`: Points from trading volume
+     *
+     * **Achievement Titles:**
+     * - Liquidity titles: Pool Explorer, Flow Enabler, Yield Artisan, etc.
+     * - Trading titles: Novice Trader, Rookie Trader, Elite Trader, etc.
+     * - Order indicates tier (1 = entry level, higher = more advanced)
+     *
+     * @category DEX Leaderboard
+     * @param seasonId Season identifier number (must be positive integer)
+     * @returns Promise<LeaderboardResult> Complete leaderboard with rankings and metrics
+     * @throws {RequiredFieldError} If seasonId is invalid
+     * @throws {NetworkError} If API request fails
+     * @since 3.X.0
+     *
+     * @example
+     * ```typescript
+     * // Fetch specific season leaderboard
+     * const leaderboard = await sdk.fetchDexLeaderboardBySeasonId(4);
+     *
+     * // Display top trader
+     * const topTrader = leaderboard.entries[0];
+     * console.log(`Rank 1: ${topTrader.wallet}`);
+     * console.log(`Total XP: ${topTrader.totalXp}`);
+     * console.log(`Distribution: ${topTrader.distributionPercent}%`);
+     *
+     * // Find users with specific titles
+     * const whales = leaderboard.entries.filter(entry =>
+     *   entry.masteryTitles.some(t => t.name === 'Protocol Whale')
+     * );
+     * ```
+     */
+    fetchDexLeaderboardBySeasonId(seasonId: number): Promise<LeaderboardResult>;
+    /**
+     * Fetch leaderboard for the currently active season
+     *
+     * Convenience method that automatically determines the current season
+     * and fetches its leaderboard. Returns null if no season is active.
+     *
+     * Equivalent to:
+     * ```typescript
+     * const season = await sdk.fetchCurrentDexSeason();
+     * return season ? sdk.fetchDexLeaderboardBySeasonId(season.id) : null;
+     * ```
+     *
+     * @category DEX Leaderboard
+     * @returns Promise<LeaderboardResult | null> Current leaderboard or null
+     * @throws {NetworkError} If API request fails
+     * @since 3.X.0
+     *
+     * @example
+     * ```typescript
+     * // Get current leaderboard in one call
+     * const leaderboard = await sdk.fetchCurrentDexLeaderboard();
+     *
+     * if (leaderboard) {
+     *   console.log(`Season ${leaderboard.seasonId} leaders:`);
+     *   leaderboard.entries.slice(0, 10).forEach(entry => {
+     *     console.log(`${entry.rank}. ${entry.wallet}: ${entry.totalXp} XP`);
+     *   });
+     * } else {
+     *   console.log('No active season');
+     * }
+     * ```
+     */
+    fetchCurrentDexLeaderboard(): Promise<LeaderboardResult | null>;
+    /**
+     * Fetch DEX aggregated volume summary with trend metrics
+     *
+     * Returns platform-wide trading volume statistics across all DEX pools with
+     * 1-day, 7-day, and 30-day comparisons and percentage changes.
+     *
+     * **Use Cases:**
+     * - Monitor overall DEX trading activity
+     * - Identify volume trends and patterns
+     * - Compare performance across time periods
+     * - Detect market changes (increases/decreases)
+     *
+     * @category DEX Analytics
+     * @returns Promise<DexAggregatedVolumeSummary> Volume metrics with deltas
+     * @throws {NetworkError} If API request fails
+     * @since 4.0.0
+     *
+     * @example
+     * ```typescript
+     * const summary = await sdk.fetchDexAggregatedVolumeSummary();
+     * console.log(`Today's volume: $${summary.volume1d.toFixed(2)}`);
+     * console.log(`7-day change: ${(summary.volume7dDelta * 100).toFixed(2)}%`);
+     *
+     * // Analyze trend direction
+     * if (summary.volume1dDelta > 0) {
+     *   console.log('✅ Volume increasing');
+     * } else {
+     *   console.log('📉 Volume decreasing');
+     * }
+     * ```
+     */
+    fetchDexAggregatedVolumeSummary(): Promise<DexAggregatedVolumeSummary>;
     /**
      * Fetch the current launchpad token launch fee
      *
@@ -840,6 +1179,44 @@ export declare class LaunchpadSDK {
      * ```
      */
     fetchLaunchTokenFee(): Promise<number>;
+    /**
+     * Fetch supply information for token classes from GalaChain
+     *
+     * Queries GalaChain for authoritative token supply data including:
+     * - Total supply and maximum supply
+     * - Total burned amount
+     * - Mint-related supply metrics
+     * - Token metadata (symbol, decimals, name)
+     *
+     * @param tokenClasses Array of token class keys to query
+     * @returns Promise<TokenClassWithSupply[]> Array of token classes with supply information
+     * @throws {ValidationError} if tokenClasses array is empty
+     * @throws {Error} if network request fails
+     *
+     * @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}`);
+     *
+     * // Query multiple tokens
+     * const multiSupplies = await sdk.fetchTokenClassesWithSupply([
+     *   { collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' },
+     *   { collection: 'GUSDC', category: 'Unit', type: 'none', additionalKey: 'eth:0x...' }
+     * ]);
+     *
+     * // Print supply summary
+     * for (const token of multiSupplies) {
+     *   console.log(`${token.symbol}: ${token.totalSupply} (max: ${token.maxSupply})`);
+     * }
+     * ```
+     *
+     * @category Token Data
+     * @since 3.32.0
+     */
+    fetchTokenClassesWithSupply(tokenClasses: TokenClassKey[]): Promise<TokenClassWithSupply[]>;
     /**
      * Fetch pool details for a token - returns complete bonding curve pool state
      *
@@ -1495,10 +1872,10 @@ export declare class LaunchpadSDK {
      * // Fetch price history for a DEX token
      * const history = await sdk.fetchPriceHistory({
      *   tokenClassKey: {
-     *     collection: 'Token',
+     *     collection: 'GUSDC',
      *     category: 'Unit',
-     *     type: 'GUSDC',
-     *     additionalKey: 'eth:...'
+     *     type: 'none',
+     *     additionalKey: 'none'
      *   },
      *   from: new Date('2024-01-01'),
      *   to: new Date('2024-01-31'),
@@ -1534,10 +1911,10 @@ export declare class LaunchpadSDK {
      * // Fetch all price history for a DEX token (automatic pagination)
      * const allHistory = await sdk.fetchAllPriceHistory({
      *   tokenId: {
-     *     collection: 'Token',
+     *     collection: 'GUSDC',
      *     category: 'Unit',
-     *     type: 'GUSDC',
-     *     additionalKey: 'eth:...'
+     *     type: 'none',
+     *     additionalKey: 'none'
      *   },
      *   from: new Date('2024-01-01'),
      *   to: new Date('2024-12-31')
@@ -1628,6 +2005,88 @@ export declare class LaunchpadSDK {
      * @throws {TransferError} When token name cannot be resolved
      */
     resolveTokenClassKey(tokenName: string): Promise<TokenClassKey>;
+    /**
+     * Lock tokens on GalaChain
+     *
+     * Places a hold on tokens, preventing them from being transferred until unlocked.
+     * Useful for staking, escrow, vesting, or other hold scenarios.
+     *
+     * The lock operation creates a hold that can only be released by the lock authority
+     * (defaults to the caller's address if not specified).
+     *
+     * @param data Lock token parameters
+     * @param data.tokenId Flexible token identifier (string, TokenClassKey, or TokenInstanceKey)
+     * @param data.tokenName Token name for lookup (used if tokenId not provided)
+     * @param data.amount Amount of tokens to lock in decimal format
+     * @param data.lockAuthority Address that can manage/unlock (defaults to caller)
+     * @param data.expires Optional expiration timestamp (epoch milliseconds)
+     * @param data.name Optional lock name/identifier for matching during unlock
+     * @param data.uniqueKey Optional unique key for idempotency
+     * @param data.privateKey Optional private key override for this operation
+     * @returns Transaction ID of the lock operation
+     *
+     * @example Lock tokens with default authority
+     * ```typescript
+     * const txId = await sdk.lockToken({
+     *   tokenName: 'anime',
+     *   amount: '1000'
+     * });
+     * console.log('Tokens locked, txId:', txId);
+     * ```
+     *
+     * @example Lock with expiration and custom authority
+     * ```typescript
+     * const txId = await sdk.lockToken({
+     *   tokenName: 'anime',
+     *   amount: '500',
+     *   lockAuthority: 'eth|OtherWalletAddress',
+     *   expires: Date.now() + 7 * 24 * 60 * 60 * 1000, // 7 days
+     *   name: 'staking-lock-001'
+     * });
+     * ```
+     *
+     * @throws {TransferError} When token cannot be found or lock fails
+     * @throws {ValidationError} When wallet is not configured
+     */
+    lockToken(data: LockTokenData): Promise<string>;
+    /**
+     * Unlock previously locked tokens on GalaChain
+     *
+     * Releases a token hold, making the tokens available for transfer again.
+     * Must be signed by the lock authority (the address that locked the tokens
+     * or was designated as lock authority during the lock operation).
+     *
+     * @param data Unlock token parameters
+     * @param data.tokenId Flexible token identifier (string, TokenClassKey, or TokenInstanceKey)
+     * @param data.tokenName Token name for lookup (used if tokenId not provided)
+     * @param data.amount Amount of tokens to unlock in decimal format
+     * @param data.name Optional lock name to match (if used during lock)
+     * @param data.uniqueKey Optional unique key for idempotency
+     * @param data.privateKey Optional private key override for this operation
+     * @returns Transaction ID of the unlock operation
+     *
+     * @example Unlock tokens
+     * ```typescript
+     * const txId = await sdk.unlockToken({
+     *   tokenName: 'anime',
+     *   amount: '1000'
+     * });
+     * console.log('Tokens unlocked, txId:', txId);
+     * ```
+     *
+     * @example Unlock with lock name matching
+     * ```typescript
+     * const txId = await sdk.unlockToken({
+     *   tokenName: 'anime',
+     *   amount: '500',
+     *   name: 'staking-lock-001' // Match specific lock
+     * });
+     * ```
+     *
+     * @throws {TransferError} When token or lock cannot be found, or unlock fails
+     * @throws {ValidationError} When wallet is not configured
+     */
+    unlockToken(data: UnlockTokenData): Promise<string>;
     /**
      * Resolve vault address for a token name
      *
@@ -1733,6 +2192,28 @@ export declare class LaunchpadSDK {
      * Queries GalaSwap DEX for a quote when swapping from one token to another,
      * specifying the exact amount you want to spend.
      *
+     * Current Implementation (v3.32.0):
+     * - Delegates to GSwapService which uses GSwap SDK quoting engine
+     * - Handles automatic token format conversion (symbols → TokenClassKey)
+     * - Returns quote with estimated output, fee tier, and price impact
+     * - Automatically selects optimal liquidity pool for best pricing
+     *
+     * Phase 2 Migration Plan:
+     * This method will be migrated to eliminate GSwap SDK dependency by:
+     * 1. Implementing quote calculation directly in BundlerService
+     * 2. Fetching pool state directly from GalaChain (Slot0, liquidity, ticks)
+     * 3. Implementing Uniswap V3 quote algorithm locally
+     * 4. Adding intelligent route finding for multi-hop swaps
+     * 5. Adding quote result caching for performance
+     * 6. Maintaining backward-compatible API while removing SDK dependency
+     *
+     * Benefits of Phase 2 Migration:
+     * - Eliminates external GSwap SDK dependency
+     * - Enables offline quote calculations
+     * - Adds quote caching for repeated queries
+     * - Better control over quote accuracy and staleness
+     * - Foundation for more advanced routing strategies
+     *
      * @category DEX Trading
      * @param fromToken Source token symbol (e.g., "GALA", "GUSDC")
      * @param toToken Destination token symbol (e.g., "GALA", "GUSDC")
@@ -1748,13 +2229,36 @@ export declare class LaunchpadSDK {
      * console.log(`Price impact: ${quote.priceImpact}%`);
      * ```
      */
-    getSwapQuoteExactInput(fromToken: string, toToken: string, amount: string): Promise<import(".").SwapQuoteResult>;
+    getSwapQuoteExactInput(fromToken: string, toToken: string, amount: string): Promise<import("./types/gswap.dto").SwapQuoteResult>;
     /**
      * Get a swap quote for exact output amount
      *
      * Queries GalaSwap DEX for a quote when swapping from one token to another,
      * specifying the exact amount you want to receive.
      *
+     * Current Implementation (v3.32.0):
+     * - Delegates to GSwapService which uses GSwap SDK quoting engine
+     * - Calculates required input amount for exact output target
+     * - Handles automatic token format conversion (symbols → TokenClassKey)
+     * - Returns quote with required input, fee tier, and price impact
+     * - Ensures amount constraints are satisfied with slippage buffer
+     *
+     * Phase 2 Migration Plan:
+     * This method will be migrated to eliminate GSwap SDK dependency by:
+     * 1. Implementing quote calculation directly in BundlerService
+     * 2. Fetching pool state directly from GalaChain (Slot0, liquidity, ticks)
+     * 3. Implementing reverse Uniswap V3 quote algorithm locally
+     * 4. Adding intelligent route finding for multi-hop swaps
+     * 5. Adding quote result caching for performance
+     * 6. Maintaining backward-compatible API while removing SDK dependency
+     *
+     * Benefits of Phase 2 Migration:
+     * - Eliminates external GSwap SDK dependency
+     * - Enables offline quote calculations
+     * - Adds quote caching for repeated queries
+     * - Better control over quote accuracy and staleness
+     * - Foundation for more advanced routing strategies
+     *
      * @category DEX Trading
      * @param fromToken Source token symbol (e.g., "GALA", "GUSDC")
      * @param toToken Destination token symbol (e.g., "GALA", "GUSDC")
@@ -1770,7 +2274,7 @@ export declare class LaunchpadSDK {
      * console.log(`Price impact: ${quote.priceImpact}%`);
      * ```
      */
-    getSwapQuoteExactOutput(fromToken: string, toToken: string, amount: string): Promise<import(".").SwapQuoteResult>;
+    getSwapQuoteExactOutput(fromToken: string, toToken: string, amount: string): Promise<import("./types/gswap.dto").SwapQuoteResult>;
     /**
      * Execute a token swap on GalaSwap DEX
      *
@@ -1807,7 +2311,7 @@ export declare class LaunchpadSDK {
      * console.log(`Transaction: ${result.transactionId}`);
      * ```
      */
-    executeSwap(fromToken: string, toToken: string, inputAmount: string, estimatedOutput: string, feeTier: number, slippageTolerance?: number): Promise<import(".").ExecuteSwapResult>;
+    executeSwap(fromToken: string, toToken: string, inputAmount: string, estimatedOutput: string, feeTier: number, slippageTolerance?: number): Promise<import("./types/gswap.dto").ExecuteSwapResult>;
     /**
      * Get user's token assets/balances from GalaSwap
      *
@@ -1826,7 +2330,12 @@ export declare class LaunchpadSDK {
      * });
      * ```
      */
-    getSwapUserAssets(walletAddress: string): Promise<import(".").UserAsset[]>;
+    getSwapUserAssets(walletAddress: string): Promise<import("./types/gswap.dto").UserAsset[]>;
+    /**
+     * Get all user assets across all pages (auto-paginated)
+     * Automatically handles pagination to fetch all assets a user holds.
+     */
+    getAllSwapUserAssets(walletAddress: string): Promise<import("./types/gswap.dto").UserAsset[]>;
     /**
      * Get pool information for a token pair
      *
@@ -1846,34 +2355,133 @@ export declare class LaunchpadSDK {
      * console.log(`Active swaps: ${poolInfo.swapCount}`);
      * ```
      */
-    getSwapPoolInfo(tokenA: string, tokenB: string): Promise<import(".").PoolInfo>;
+    getSwapPoolInfo(tokenA: string, tokenB: string): Promise<import("./types/gswap.dto").PoolInfo>;
     /**
-     * Get all liquidity positions for a wallet
+     * Get current market price for a DEX pool
+     *
+     * Fetches the current pool state (sqrtPrice and tick) from the GalaChain Gateway
+     * and calculates the token1/token0 price ratio. This is useful for determining
+     * the current price and whether a liquidity position is in-range.
+     *
+     * @category DEX Market Data
+     * @since 3.31.0
+     *
+     * @param token0 - First token symbol (e.g., "GALA")
+     * @param token1 - Second token symbol (e.g., "GUSDC")
+     * @param fee - Fee tier in basis points (500, 3000, or 10000)
+     * @returns PoolPriceData with current price, sqrtPrice, tick, and liquidity
      *
-     * Retrieves all open liquidity positions for the specified wallet address.
+     * @example Get current pool price
+     * ```typescript
+     * const priceData = await sdk.getSwapPoolPrice('GALA', 'GUSDC', 3000);
+     * console.log(`Current price: ${priceData.price} GUSDC per GALA`);
+     * console.log(`Current tick: ${priceData.tick}`);
+     * console.log(`Pool liquidity: ${priceData.liquidity}`);
+     *
+     * // Determine if position is in-range
+     * const position = await sdk.getSwapLiquidityPositionById(ownerAddress, positionId);
+     * const inRange = priceData.tick >= position.tickLower && priceData.tick <= position.tickUpper;
+     * console.log(`Position in-range: ${inRange}`);
+     * ```
+     */
+    getSwapPoolPrice(token0: string, token1: string, fee: number): Promise<PoolPriceData>;
+    /**
+     * Get liquidity positions for a wallet (single page)
+     *
+     * Retrieves a single page of liquidity positions for the specified wallet address.
      * Includes position details like token pair, liquidity amount, and accumulated fees.
+     * Optionally fetches real-time pricing for each position's pool.
+     *
+     * For complete enumeration across all pages, use getAllSwapUserLiquidityPositions().
      *
      * @category DEX Liquidity Management
      * @since 3.25.0
      *
      * @param ownerAddress - Wallet address (eth|0x... format or standard 0x...)
-     * @param limit - Optional limit on number of positions to return
-     * @param bookmark - Optional pagination bookmark from previous response
-     * @returns Array of liquidity positions with all position details
+     * @param limit - Optional limit on number of positions to return per page
+     * @param bookmarkOrOptions - Optional pagination bookmark (deprecated) or options object
+     * @param options - Optional options object with pricing configuration
+     * @returns Object with items array (liquidity positions), optional nextBookmark for pagination, and optional prices map
      *
-     * @example Get all positions
+     * @example Get single page of positions
      * ```typescript
-     * const positions = await sdk.getSwapUserLiquidityPositions('eth|0x123...');
-     * console.log(`Open positions: ${positions.length}`);
-     * positions.forEach(pos => {
+     * const result = await sdk.getSwapUserLiquidityPositions('eth|0x123...');
+     * console.log(`Positions on page: ${result.items.length}`);
+     * result.items.forEach(pos => {
      *   console.log(`Position ${pos.positionId}:`);
      *   console.log(`  Tokens: ${pos.token0} / ${pos.token1}`);
      *   console.log(`  Liquidity: ${pos.liquidity}`);
      *   console.log(`  Fee0: ${pos.feeAmount0}, Fee1: ${pos.feeAmount1}`);
      * });
+     *
+     * // Fetch next page if bookmark available
+     * if (result.nextBookmark) {
+     *   const nextPage = await sdk.getSwapUserLiquidityPositions('eth|0x123...', undefined, result.nextBookmark);
+     * }
+     * ```
+     *
+     * @example Get positions with real-time pricing (5 concurrent requests)
+     * ```typescript
+     * const result = await sdk.getSwapUserLiquidityPositions('eth|0x123...', 10, { withPrices: true });
+     * result.items.forEach(pos => {
+     *   const poolKey = `${pos.token0}|${pos.token1}|${pos.feeTier}`;
+     *   const price = result.prices?.get(poolKey);
+     *   if (price) {
+     *     console.log(`Current price: 1 ${pos.token0} = ${price.currentPrice} ${pos.token1}`);
+     *   }
+     * });
      * ```
      */
-    getSwapUserLiquidityPositions(ownerAddress: string, limit?: number, bookmark?: string): Promise<import("./types/gswap.dto").LiquidityPosition[]>;
+    getSwapUserLiquidityPositions(ownerAddress: string, limit?: number, bookmarkOrOptions?: string | GetLiquidityPositionsOptions, options?: GetLiquidityPositionsOptions): Promise<GetLiquidityPositionsResult>;
+    /**
+     * Get ALL user liquidity positions with automatic pagination
+     *
+     * Fetches all liquidity positions for a wallet across all pages automatically.
+     * This is the recommended method for complete position enumeration.
+     * Optionally fetches real-time pricing for each position's pool.
+     *
+     * @category DEX Liquidity Management
+     * @since 3.31.3
+     *
+     * @param ownerAddress - User's wallet address
+     * @param options - Optional options object with pricing configuration
+     * @returns Array of all liquidity positions (auto-paginated) or result object with positions and pricing
+     *
+     * @example Get all positions automatically
+     * ```typescript
+     * const allPositions = await sdk.getAllSwapUserLiquidityPositions('eth|0x123...');
+     * console.log(`Total positions: ${allPositions.length}`);
+     * allPositions.forEach(pos => {
+     *   console.log(`Position ${pos.positionId}:`);
+     *   console.log(`  Tokens: ${pos.token0} / ${pos.token1}`);
+     *   console.log(`  Liquidity: ${pos.liquidity}`);
+     *   console.log(`  Fees: ${pos.feeAmount0} ${pos.token0}, ${pos.feeAmount1} ${pos.token1}`);
+     * });
+     * ```
+     *
+     * @example Get all positions with real-time pricing (default 5 concurrent requests)
+     * ```typescript
+     * const result = await sdk.getAllSwapUserLiquidityPositions('eth|0x123...', { withPrices: true });
+     * console.log(`Total positions: ${result.items.length}`);
+     * result.items.forEach(pos => {
+     *   const poolKey = `${pos.token0}|${pos.token1}|${pos.feeTier}`;
+     *   const price = result.prices?.get(poolKey);
+     *   if (price) {
+     *     console.log(`Current price: 1 ${pos.token0} = ${price.currentPrice} ${pos.token1}`);
+     *     console.log(`Price Impact: ${price.priceImpact}%`);
+     *   }
+     * });
+     * ```
+     *
+     * @example Get all positions with custom concurrency (10 concurrent pricing requests)
+     * ```typescript
+     * const result = await sdk.getAllSwapUserLiquidityPositions('eth|0x123...', {
+     *   withPrices: true,
+     *   pricingConcurrency: 10  // Speed up pricing with more concurrent requests
+     * });
+     * ```
+     */
+    getAllSwapUserLiquidityPositions(ownerAddress: string, options?: GetLiquidityPositionsOptions): Promise<GSwapPosition[] | GetLiquidityPositionsResult>;
     /**
      * Get specific liquidity position by token pair
      *
@@ -1911,23 +2519,78 @@ export declare class LaunchpadSDK {
      * Get liquidity position by position ID
      *
      * Retrieves a specific liquidity position by its unique identifier.
+     * Optionally accepts token information for more efficient compound key lookups.
      *
      * @category DEX Liquidity Management
      * @since 3.25.0
      *
      * @param ownerAddress - Wallet address
      * @param positionId - Unique position identifier
+     * @param token0 - Optional token0 for compound key lookup (improves lookup reliability)
+     * @param token1 - Optional token1 for compound key lookup (improves lookup reliability)
+     * @param feeTier - Optional fee tier for compound key lookup (improves lookup reliability)
+     * @param tickLower - Optional lower tick boundary for compound key lookup
+     * @param tickUpper - Optional upper tick boundary for compound key lookup
      * @returns Liquidity position details
      *
-     * @example Get position by ID
+     * @example Get position by ID with token information
      * ```typescript
      * const position = await sdk.getSwapLiquidityPositionById(
      *   'eth|0x123...',
-     *   'pos-abc123'
+     *   'pos-abc123',
+     *   'GALA',
+     *   'GUSDC',
+     *   3000,
+     *   -1080,  // tickLower
+     *   900     // tickUpper
      * );
      * ```
      */
-    getSwapLiquidityPositionById(ownerAddress: string, positionId: string): Promise<import("./types/gswap.dto").LiquidityPosition>;
+    getSwapLiquidityPositionById(ownerAddress: string, positionId: string, token0?: string | Record<string, any>, token1?: string | Record<string, any>, feeTier?: number, tickLower?: number, tickUpper?: number): Promise<import("./types/gswap.dto").LiquidityPosition>;
+    /**
+     * Fetch a single liquidity position using ONLY the compound key (most efficient)
+     *
+     * Makes a direct HTTP call to GalaChain Gateway using token0, token1, fee, and tick range.
+     * This is the most efficient method when you already have all position parameters.
+     *
+     * @param params - Position lookup parameters (all required):
+     *   - token0: First token (e.g., "GALA" or "GALA|Unit|none|none")
+     *   - token1: Second token (e.g., "GUSDC" or "GUSDC|Unit|none|none")
+     *   - fee: Fee tier (500, 3000, or 10000 basis points)
+     *   - tickLower: Lower tick boundary
+     *   - tickUpper: Upper tick boundary
+     *   - owner: Wallet address (e.g., "eth|0x...")
+     * @returns Detailed liquidity position information
+     *
+     * @example
+     * ```typescript
+     * const position = await sdk.fetchSwapPositionDirect({
+     *   token0: 'GALA',
+     *   token1: 'GUSDC',
+     *   fee: 3000,
+     *   tickLower: -26440,
+     *   tickUpper: -22390,
+     *   owner: 'eth|A278F228BB9Ea280C537763974FF1c1d427c85bb'
+     * });
+     * ```
+     *
+     * @category DEX Liquidity Queries
+     * @since 3.35.0
+     *
+     * @remarks
+     * - Single direct HTTP call (most efficient path)
+     * - Does NOT require or accept positionId
+     * - No GSwap SDK dependency
+     * - All parameters are required
+     */
+    fetchSwapPositionDirect(params: {
+        token0: string;
+        token1: string;
+        fee: number;
+        tickLower: number;
+        tickUpper: number;
+        owner: string;
+    }): Promise<GSwapPosition>;
     /**
      * Estimate tokens to receive when removing liquidity
      *
@@ -1961,7 +2624,7 @@ export declare class LaunchpadSDK {
         liquidity: string;
         tickLower: number;
         tickUpper: number;
-    }): Promise<any>;
+    }): Promise<import("./types/gswap-responses.types").GSwapEstimateRemoveLiquidityResult>;
     /**
      * Add liquidity using price range
      *
@@ -1991,7 +2654,10 @@ export declare class LaunchpadSDK {
      * console.log(`Position created: ${result.positionId}`);
      * ```
      */
-    addSwapLiquidityByPrice(args: any): Promise<any>;
+    addSwapLiquidityByPrice(args: any): Promise<import("./types/gswap-responses.types").GSwapAddLiquidityResult & {
+        timestamp?: Date;
+        wait?: (timeoutMs?: number) => Promise<void>;
+    }>;
     /**
      * Add liquidity using tick range
      *
@@ -2017,7 +2683,10 @@ export declare class LaunchpadSDK {
      * });
      * ```
      */
-    addSwapLiquidityByTicks(args: any): Promise<any>;
+    addSwapLiquidityByTicks(args: any): Promise<import("./types/gswap-responses.types").GSwapAddLiquidityResult & {
+        timestamp?: Date;
+        wait?: (timeoutMs?: number) => Promise<void>;
+    }>;
     /**
      * Remove liquidity from a position
      *
@@ -2042,7 +2711,7 @@ export declare class LaunchpadSDK {
      * });
      * ```
      */
-    removeSwapLiquidity(args: any): Promise<any>;
+    removeSwapLiquidity(args: any): Promise<import("./types/gswap-responses.types").GSwapAddLiquidityResult>;
     /**
      * Collect accumulated position fees
      *
@@ -2064,7 +2733,7 @@ export declare class LaunchpadSDK {
      * console.log(`Collected: ${result.amount0} token0, ${result.amount1} token1`);
      * ```
      */
-    collectSwapPositionFees(args: any): Promise<any>;
+    collectSwapPositionFees(args: any): Promise<import("./types/gswap-responses.types").GSwapAddLiquidityResult>;
     /**
      * Connect to WebSocket for real-time events
      *
@@ -2257,6 +2926,633 @@ export declare class LaunchpadSDK {
         intervalMs?: number;
         creatorAddress?: string;
     }): () => void;
+    private static readonly TOKEN_CREATION_SOCKET_WAIT_ATTEMPTS;
+    private static readonly TOKEN_CREATION_SOCKET_POLL_INTERVAL_MS;
+    private static readonly DEX_POOL_SOCKET_WAIT_ATTEMPTS;
+    private static readonly DEX_POOL_SOCKET_POLL_INTERVAL_MS;
+    /**
+     * Normalize fee tier to standard format (500, 3000, or 10000)
+     *
+     * Handles various fee formats: percentage strings ("0.3", "1"), basis points (500, 3000, 10000)
+     *
+     * @param value - Fee value in any format
+     * @returns Normalized fee tier (500, 3000, 10000) or null if invalid
+     * @private
+     */
+    private normalizeFee;
+    /**
+     * Extract a field from an object with multiple possible key names
+     *
+     * @param obj - Object to search
+     * @param keys - Possible key names to try in order
+     * @returns Value of first matching key or empty string
+     * @private
+     */
+    private extractField;
+    /**
+     * Check if a string looks like a pool pair format
+     *
+     * Format: "token0/token1/fee" or full format with class keys
+     *
+     * @param value - Value to check
+     * @returns Normalized pool pair string or null
+     * @private
+     */
+    private looksLikePoolPair;
+    /**
+     * Build pool pair from object with token and fee fields
+     *
+     * Tries multiple field name patterns to extract token0, token1, and fee
+     *
+     * @param obj - Object potentially containing pool data
+     * @returns Pool pair string or null
+     * @private
+     */
+    private buildPoolPairFromObject;
+    /**
+     * Parse pool pair string into token0, token1, and fee
+     *
+     * Format: "token0ClassKey/token1ClassKey/feeTier"
+     * Example: "GALA|Unit|none|none/GUSDC|Unit|none|none/10000"
+     *
+     * @param poolPairString - Pool pair string
+     * @returns Pool data or null if invalid
+     * @private
+     */
+    private parsePoolPairString;
+    /**
+     * Serialize balance token object to classKey format
+     * Used by buildPoolPairFromBalances to convert balance objects to token symbols
+     *
+     * Format: "collection|category|type|additionalKey"
+     * Example: "GALA|Unit|none|none"
+     *
+     * @param balance - Balance object with collection, category, type fields
+     * @returns Serialized token string or empty string if invalid
+     * @private
+     */
+    private serializeBalanceToken;
+    /**
+     * Build pool pair from balance delta objects
+     * Handles extraction from swap and liquidity events that include balance changes
+     *
+     * Looks for:
+     * - userBalanceDelta, balanceDelta, or delta objects
+     * - token0Balance/token0/baseBalance/primaryBalance fields
+     * - token1Balance/token1/quoteBalance/secondaryBalance fields
+     * - Fee from poolFee, feeTier, fee, feeTierBps, or liquidityFeeBps
+     *
+     * @param obj - Object that may contain balance delta data
+     * @returns Pool pair string or null if extraction failed
+     * @private
+     */
+    private buildPoolPairFromBalances;
+    /**
+     * Extract pool data from WebSocket event payload
+     *
+     * Tries multiple patterns in order to find pool data:
+     * 1. Direct poolPair string
+     * 2. Direct poolPair field
+     * 3. Balance delta patterns (from swap/liquidity events) - CRITICAL for event detection
+     * 4. Object fields (token0, token1, fee)
+     * 5. Nested pool object
+     *
+     * Order matches reference implementation (newPoolsWatch.js) for maximum compatibility
+     *
+     * @param payload - WebSocket event payload
+     * @returns Pool data or null if not found
+     * @private
+     */
+    private extractPoolDataFromPayload;
+    /**
+     * Check if a pool matches the optional filters
+     *
+     * Implements position-independent token matching:
+     * - tokenFilter matches if token appears in EITHER position (token0 OR token1)
+     * - pairTokens matches if BOTH tokens are present regardless of order
+     * - feeTierFilter matches the fee tier
+     *
+     * @param pool - Pool data to check
+     * @param options - Optional filters
+     * @returns true if pool matches all specified filters
+     * @private
+     */
+    private matchesPoolFilter;
+    /**
+     * Check if a token creation event matches the optional creator filter
+     *
+     * Extracted for testability and maintainability.
+     *
+     * @param token - Token data from event
+     * @param creatorFilter - Optional creator address filter
+     * @returns true if token matches filter (or no filter specified)
+     * @private
+     */
+    private matchesCreatorFilter;
+    /**
+     * Subscribe to real-time token creation broadcasts
+     *
+     * Listens to WebSocket broadcasts for ALL token creations globally.
+     * Provides real-time notifications with ~1-2 second latency (vs 15-30s polling).
+     *
+     * **Architecture:**
+     * The backend broadcasts transaction confirmation events to ALL connected Socket.IO clients.
+     * This listener captures "CreateSale" events which indicate token creation.
+     *
+     * **Key Difference from onLaunchpadTokenCreation():**
+     * - `subscribeToTokenCreations()` - WebSocket broadcasts (instant, <2s latency)
+     * - `onLaunchpadTokenCreation()` - REST API polling (slow, 15-30s latency)
+     *
+     * **Connection Management:**
+     * - If WebSocket is already connected, listener is registered immediately
+     * - If not connected, automatically initiates connection with 3-second timeout
+     * - Connection failures are logged and can be handled via error callback
+     *
+     * **Cleanup Function:**
+     * - Safe to call multiple times (idempotent)
+     * - Removes listener and cleans up tracking state
+     * - Returns immediately if listener was never registered
+     *
+     * @param callback - Called when any token is created
+     * @param options - Optional filtering and error handling
+     * @param options.creatorFilter - Only receive tokens from specific creator address
+     * @param options.onError - Called if WebSocket connection fails
+     * @returns Cleanup function to stop listening - safe to call multiple times
+     *
+     * @category Real-time Monitoring
+     * @since 4.1.0
+     *
+     * @throws Error if WebSocket service not initialized
+     *
+     * @example Basic usage - listen to all token creations
+     * ```typescript
+     * const cleanup = sdk.subscribeToTokenCreations((token) => {
+     *   console.log(`Token created: ${token.tokenName} by ${token.creatorAddress}`);
+     * });
+     *
+     * // Stop listening when done
+     * cleanup();
+     * ```
+     *
+     * @example Filter to specific creator
+     * ```typescript
+     * const cleanup = sdk.subscribeToTokenCreations(
+     *   (token) => console.log(`My token: ${token.tokenName}`),
+     *   {
+     *     creatorFilter: sdk.getAddress(),
+     *     onError: (error) => console.error('Connection failed:', error)
+     *   }
+     * );
+     * ```
+     *
+     * @example Monitor for competitor tokens with error handling
+     * ```typescript
+     * const cleanup = sdk.subscribeToTokenCreations(
+     *   (token) => {
+     *     console.log(`New token: ${token.tokenName} - ${token.symbol}`);
+     *     // Could trigger automatic buy/analysis
+     *   },
+     *   {
+     *     onError: (error) => {
+     *       console.error('Real-time monitoring failed:', error);
+     *       // Fallback to polling
+     *     }
+     *   }
+     * );
+     * ```
+     */
+    subscribeToTokenCreations(callback: (token: {
+        tokenName: string;
+        symbol: string;
+        creatorAddress: string;
+        description: string;
+        image: string;
+        vaultAddress: string;
+        tokenStringKey: string;
+        preBuyQuantity: string;
+        websiteUrl: string;
+        telegramUrl: string;
+        twitterUrl: string;
+        isFinalized: boolean;
+    }) => void, options?: {
+        creatorFilter?: string;
+        onError?: (error: Error) => void;
+    }): () => void;
+    /**
+     * Recursively walk WebSocket event payload to find all pools
+     *
+     * Exhaustively searches through entire payload tree, including nested objects.
+     * Matches reference implementation (newPoolsWatch.js walkPayload) for complete event coverage.
+     *
+     * Uses WeakSet to track visited objects and prevent infinite loops on circular references.
+     * Deduplicates pools using the provided seenPools Set.
+     *
+     * @param payload - Event payload to walk (can be string, object, or any value)
+     * @param seenPools - Set of already-seen pool pair strings (for deduplication)
+     * @param visited - WeakSet of visited objects (to prevent circular reference loops)
+     * @returns Array of newly discovered pool data objects
+     * @private
+     */
+    private walkPayloadForPools;
+    /**
+     * Subscribe to real-time DEX pool creation broadcasts
+     *
+     * Listens to WebSocket broadcasts for DEX pool creation events globally.
+     * Provides real-time notifications when new liquidity pools are added (~1-2 second latency).
+     *
+     * **Use Case:**
+     * Monitor for graduated tokens becoming swappable on the DEX. When a token graduates from
+     * bonding curve to DEX, a pool is created and this subscription notifies in real-time.
+     *
+     * **Position-Independent Token Matching:**
+     * Token filters work regardless of position (token0 vs token1):
+     * - `tokenFilter: 'GALA'` matches both GALA/USDC and USDC/GALA pools
+     * - `pairTokens: ['GALA', 'USDC']` matches the specific pair in any order
+     *
+     * **Connection Management:**
+     * - If WebSocket is already connected, listener is registered immediately
+     * - If not connected, automatically initiates connection with 3-second timeout
+     * - Connection failures are logged and can be handled via error callback
+     *
+     * **Cleanup Function:**
+     * - Safe to call multiple times (idempotent)
+     * - Removes listener and cleans up tracking state
+     * - Returns immediately if listener was never registered
+     *
+     * @param callback - Called when a new DEX pool is created
+     * @param options - Optional filtering and error handling
+     * @param options.tokenFilter - Only receive pools containing this token (in either position)
+     * @param options.pairTokens - Only receive pools with this specific token pair (order-independent)
+     * @param options.feeTierFilter - Only receive pools with this fee tier (500, 3000, or 10000)
+     * @param options.onError - Called if WebSocket connection fails
+     * @returns Cleanup function to stop listening - safe to call multiple times
+     *
+     * @category Real-time Monitoring
+     * @since 4.1.0
+     *
+     * @throws Error if WebSocket service not initialized
+     *
+     * @example Listen to all new pools
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexPoolAdded((pool) => {
+     *   console.log(`New pool: ${pool.token0}/${pool.token1} (${pool.fee}% fee)`);
+     * });
+     *
+     * // Stop listening when done
+     * cleanup();
+     * ```
+     *
+     * @example Listen for GALA pools only
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexPoolAdded(
+     *   (pool) => {
+     *     if (pool.token0 === 'GALA' || pool.token1 === 'GALA') {
+     *       console.log(`GALA pool created: ${pool.poolPair}`);
+     *     }
+     *   },
+     *   { tokenFilter: 'GALA' }
+     * );
+     * ```
+     *
+     * @example Monitor specific pair with fee tier
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexPoolAdded(
+     *   (pool) => {
+     *     console.log(`GALA/GUSDC 0.3% pool created!`);
+     *   },
+     *   {
+     *     pairTokens: ['GALA', 'GUSDC'],
+     *     feeTierFilter: 3000,  // 0.3%
+     *     onError: (error) => console.error('Connection failed:', error)
+     *   }
+     * );
+     * ```
+     *
+     * @example Monitor graduated tokens (all pools, real-time)
+     * ```typescript
+     * // Watch for ANY new pools - indicates graduated tokens
+     * const cleanup = sdk.subscribeToDexPoolAdded(
+     *   (pool) => {
+     *     console.log(`Graduated token detected: ${pool.token0}/${pool.token1}`);
+     *     // Could trigger automatic trading strategies
+     *   }
+     * );
+     * ```
+     */
+    subscribeToDexPoolAdded(callback: (pool: {
+        token0: string;
+        token1: string;
+        fee: string;
+        poolPair: string;
+    }) => void, options?: {
+        tokenFilter?: string;
+        pairTokens?: [string, string];
+        feeTierFilter?: string | number;
+        onError?: (error: Error) => void;
+    }): () => void;
+    /**
+     * Subscribe to real-time DEX swap execution events
+     *
+     * Monitors all completed swaps on the DEX globally with real-time notifications (~1-2 second latency).
+     * Provides offline price predictions and delta-based pool state updates for arbitrage bot use cases.
+     *
+     * **Architecture:**
+     * The backend broadcasts transaction confirmation events for completed swaps to ALL connected clients.
+     * This listener captures "ExecuteSwap" events and provides:
+     * - Real-time swap transaction data (tokens, amounts, fees)
+     * - Offline price quotes using cached pool state (~25-50ms vs network requests)
+     * - Delta-based pool updates (~15-25ms vs full refetch ~200-400ms)
+     * - Performance metrics (latency percentiles, cache hit rates, throughput)
+     *
+     * **Position-Independent Token Matching:**
+     * Token filters work regardless of position (token0 vs token1):
+     * - `tokenFilter: 'GALA'` matches both GALA/USDC and USDC/GALA swaps
+     * - `pairTokens: ['GALA', 'USDC']` matches the specific pair in any order
+     *
+     * **Connection Management:**
+     * - If WebSocket is already connected, listener is registered immediately
+     * - If not connected, automatically initiates connection with 3-second timeout
+     * - Connection failures are logged and can be handled via error callback
+     *
+     * **Cleanup Function:**
+     * - Safe to call multiple times (idempotent)
+     * - Removes listener and cleans up tracking state
+     * - Returns immediately if listener was never registered
+     *
+     * @param callback - Called when a swap completes with enriched swap data
+     * @param options - Optional filtering, configuration, and error handling
+     * @param options.tokenFilter - Only receive swaps containing this token (in either position)
+     * @param options.pairTokens - Only receive swaps with this specific token pair (order-independent)
+     * @param options.feeTierFilter - Only receive swaps with this fee tier (500, 3000, or 10000)
+     * @param options.userFilter - Only receive swaps from this wallet address
+     * @param options.memoryProfile - Cache memory profile: 'conservative' (55MB), 'moderate' (250MB), 'aggressive' (530MB)
+     * @param options.maxPools - Maximum pools to cache (default: 500)
+     * @param options.enableDeltaOptimization - Use delta updates instead of full refetch (default: true)
+     * @param options.enableOfflineQuotes - Calculate offline quotes for known pools (default: true)
+     * @param options.debug - Enable debug logging (default: false)
+     * @param options.onError - Called if WebSocket connection fails
+     * @returns Cleanup function to stop listening - safe to call multiple times
+     *
+     * @category Real-time Monitoring
+     * @since 4.2.0
+     *
+     * @throws Error if WebSocket service not initialized
+     *
+     * @example Listen to all swaps globally
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexSwapExecuted((swap) => {
+     *   console.log(`Swap: ${swap.token0} → ${swap.token1}`);
+     *   console.log(`Amount: ${swap.amount0} / ${swap.amount1}`);
+     *   if (swap.estimatedPrice) {
+     *     console.log(`Price: ${swap.estimatedPrice}`);
+     *   }
+     * });
+     *
+     * // Stop listening when done
+     * cleanup();
+     * ```
+     *
+     * @example Arbitrage bot - monitor GALA/GUSDC swaps with offline pricing
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexSwapExecuted(
+     *   async (swap) => {
+     *     if (swap.estimatedPrice && swap.poolStateUpdated) {
+     *       // Price calculated instantly using cached pool state
+     *       console.log(`Arbitrage opportunity: ${swap.estimatedPrice}`);
+     *
+     *       // Trigger trading logic
+     *       await executeArbitrageStrategy(swap);
+     *     }
+     *   },
+     *   {
+     *     pairTokens: ['GALA', 'GUSDC'],
+     *     memoryProfile: 'aggressive',    // Max cache for arbitrage
+     *     enableDeltaOptimization: true,  // Fast updates
+     *     enableOfflineQuotes: true,      // Instant pricing
+     *     onError: (error) => console.error('Swap monitoring failed:', error)
+     *   }
+     * );
+     * ```
+     *
+     * @example Monitor specific token with fee tier
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexSwapExecuted(
+     *   (swap) => {
+     *     console.log(`GALA 0.3% pool swap: ${swap.amount0}`);
+     *   },
+     *   {
+     *     tokenFilter: 'GALA',
+     *     feeTierFilter: 3000,  // 0.3% fee tier
+     *   }
+     * );
+     * ```
+     *
+     * @example Health monitoring for swap monitoring system
+     * ```typescript
+     * let swapMonitor: MultiPoolStateManager | null = null;
+     *
+     * const cleanup = sdk.subscribeToDexSwapExecuted(
+     *   (swap) => {
+     *     console.log(`Swap processed in <50ms:`, swap.poolStateUpdated);
+     *   },
+     *   {
+     *     memoryProfile: 'moderate',
+     *     onError: (error) => console.error('Connection failed:', error)
+     *   }
+     * );
+     *
+     * // Can get health metrics
+     * // const health = swapMonitor?.getHealth();
+     * // console.log(`Cache hit rate: ${health.metrics.cacheHitRate}%`);
+     * ```
+     */
+    subscribeToDexSwapExecuted(callback: SwapEventCallback, options?: SubscribeSwapOptions & SwapMonitorConfig): CleanupFunction;
+    /**
+     * Subscribe to real-time DEX liquidity addition events
+     *
+     * Monitors all liquidity additions on the DEX globally with real-time notifications.
+     * All liquidity events are broadcast to all connected clients - you can monitor
+     * market-wide liquidity activity, not just your own transactions.
+     *
+     * **Use Cases:**
+     * - LP position tracking: Monitor when users add liquidity to positions
+     * - Whale watching: Detect large liquidity additions
+     * - Market analysis: Track overall DEX liquidity growth
+     * - Position management: React to liquidity changes in pools you care about
+     *
+     * **Position-Independent Token Matching:**
+     * Token filters work regardless of position (token0 vs token1):
+     * - `tokenFilter: 'GALA'` matches liquidity additions to any GALA pool
+     * - `pairTokens: ['GALA', 'GUSDC']` matches the specific pair in any order
+     *
+     * @param callback - Called when liquidity is added with event data
+     * @param options - Optional filtering and error handling
+     * @param options.positionId - Only receive events for this LP position NFT
+     * @param options.poolHash - Only receive events for this pool
+     * @param options.tokenFilter - Only receive events containing this token (in either position)
+     * @param options.pairTokens - Only receive events with this specific token pair (order-independent)
+     * @param options.feeTierFilter - Only receive events with this fee tier (500, 3000, or 10000)
+     * @param options.userFilter - Only receive events from this wallet address
+     * @param options.minAmount - Only receive events where at least one amount exceeds this value
+     * @param options.onError - Called if WebSocket connection fails
+     * @returns Cleanup function to stop listening - safe to call multiple times
+     *
+     * @category Real-time Monitoring
+     * @since 4.3.0
+     *
+     * @throws Error if WebSocket service not initialized
+     *
+     * @example Listen to all liquidity additions
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityAdded((event) => {
+     *   console.log(`Liquidity added: ${event.amounts[0]} / ${event.amounts[1]}`);
+     *   console.log(`Position: ${event.positionId}`);
+     *   console.log(`Pool: ${event.poolHash}`);
+     * });
+     *
+     * // Stop listening when done
+     * await cleanup();
+     * ```
+     *
+     * @example Track specific pool liquidity
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityAdded(
+     *   (event) => {
+     *     console.log(`GALA/GUSDC liquidity: +${event.amounts[0]} GALA`);
+     *   },
+     *   {
+     *     pairTokens: ['GALA', 'GUSDC'],
+     *     feeTierFilter: 3000,  // 0.3% fee tier
+     *   }
+     * );
+     * ```
+     *
+     * @example Whale watching
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityAdded(
+     *   (event) => {
+     *     console.log(`🐋 Large liquidity add detected!`);
+     *     console.log(`Amount: ${event.amounts[0]} / ${event.amounts[1]}`);
+     *     console.log(`User: ${event.userAddress}`);
+     *   },
+     *   { minAmount: '10000' }  // Only large additions
+     * );
+     * ```
+     */
+    subscribeToDexLiquidityAdded(callback: LiquidityChangedCallback, options?: SubscribeLiquidityOptions): LiquidityCleanupFunction;
+    /**
+     * Subscribe to real-time DEX liquidity removal events
+     *
+     * Monitors all liquidity removals on the DEX globally with real-time notifications.
+     * All liquidity events are broadcast to all connected clients - you can monitor
+     * market-wide liquidity activity, not just your own transactions.
+     *
+     * **Use Cases:**
+     * - LP exit tracking: Monitor when users remove liquidity from positions
+     * - Whale watching: Detect large liquidity withdrawals
+     * - Market analysis: Track overall DEX liquidity changes
+     * - Risk management: React to liquidity decreases in pools you trade
+     *
+     * @param callback - Called when liquidity is removed with event data
+     * @param options - Optional filtering and error handling
+     * @param options.positionId - Only receive events for this LP position NFT
+     * @param options.poolHash - Only receive events for this pool
+     * @param options.tokenFilter - Only receive events containing this token (in either position)
+     * @param options.pairTokens - Only receive events with this specific token pair (order-independent)
+     * @param options.feeTierFilter - Only receive events with this fee tier (500, 3000, or 10000)
+     * @param options.userFilter - Only receive events from this wallet address
+     * @param options.minAmount - Only receive events where at least one amount exceeds this value
+     * @param options.onError - Called if WebSocket connection fails
+     * @returns Cleanup function to stop listening - safe to call multiple times
+     *
+     * @category Real-time Monitoring
+     * @since 4.3.0
+     *
+     * @throws Error if WebSocket service not initialized
+     *
+     * @example Listen to all liquidity removals
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityRemoved((event) => {
+     *   console.log(`Liquidity removed: ${event.amounts[0]} / ${event.amounts[1]}`);
+     *   console.log(`Position: ${event.positionId}`);
+     * });
+     *
+     * await cleanup();
+     * ```
+     *
+     * @example Track position exits
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityRemoved(
+     *   (event) => {
+     *     console.log(`Position ${event.positionId} reduced liquidity`);
+     *   },
+     *   { positionId: 'my-position-id' }
+     * );
+     * ```
+     */
+    subscribeToDexLiquidityRemoved(callback: LiquidityChangedCallback, options?: SubscribeLiquidityOptions): LiquidityCleanupFunction;
+    /**
+     * Subscribe to all DEX liquidity changes
+     *
+     * Monitors all liquidity operations on the DEX globally with real-time notifications.
+     * The backend broadcasts position change events without distinguishing between
+     * add and remove operations.
+     *
+     * **Use Cases:**
+     * - Complete liquidity tracking: Monitor all LP activity in a pool
+     * - Position monitoring: Track changes to specific positions
+     * - Dashboard displays: Show real-time liquidity activity feed
+     *
+     * @param callback - Called when liquidity changes with event data
+     * @param options - Optional filtering and error handling
+     * @returns Cleanup function to stop listening - safe to call multiple times
+     *
+     * @category Real-time Monitoring
+     * @since 4.3.0
+     *
+     * @throws Error if WebSocket service not initialized
+     *
+     * @example Monitor all liquidity activity
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityChanged((event) => {
+     *   console.log(`Liquidity changed: ${event.amounts[0]} / ${event.amounts[1]}`);
+     *   console.log(`Pool: ${event.poolHash}`);
+     *   console.log(`Position: ${event.positionId}`);
+     * });
+     *
+     * await cleanup();
+     * ```
+     *
+     * @example Track specific pool liquidity
+     * ```typescript
+     * const cleanup = sdk.subscribeToDexLiquidityChanged(
+     *   (event) => {
+     *     console.log(`Pool activity: ${event.amounts[0]} / ${event.amounts[1]}`);
+     *     console.log(`User: ${event.userAddress}`);
+     *   },
+     *   { pairTokens: ['GALA', 'GUSDC'] }
+     * );
+     * ```
+     */
+    subscribeToDexLiquidityChanged(callback: LiquidityChangedCallback, options?: SubscribeLiquidityOptions): LiquidityCleanupFunction;
+    /**
+     * Internal method for subscribing to liquidity events
+     *
+     * @internal
+     */
+    private subscribeToDexLiquidityEvents;
+    /**
+     * Check if a liquidity event matches the specified filters
+     *
+     * @internal
+     */
+    private matchesLiquidityFilter;
+    /**
+     * Normalize fee tier to basis points
+     *
+     * @internal
+     */
+    private normalizeFeeTier;
     /**
      * Cleanup SDK resources and connections
      *