@gala-chain/launchpad-sdk 4.0.4-beta.0 → 4.0.5

package/dist/src/services/TokenMetadataService.d.ts

@@ -1,15 +1,81 @@
 /**
- * TokenMetadataService - Proper Token Metadata Resolution
+ * TokenMetadataService - Authoritative Token Metadata Resolution
  *
- * This service provides authoritative token metadata by querying the GalaChain network
- * for real token data. It should be used instead of trying to infer metadata from
- * token format strings.
+ * Provides verified token metadata from GalaChain blockchain, including symbols,
+ * decimals, supply caps, and verification status. Uses time-based caching to
+ * minimize network calls while ensuring data freshness.
  *
- * Key Responsibilities:
- * - Query GalaChain for real token metadata via GalaChainService
- * - Cache results to minimize network calls
- * - Handle token resolution for both native and wrapped tokens
- * - Provide clean interface for symbol, decimals, and other metadata
+ * ## Core Responsibility
+ *
+ * Fetch REAL token metadata from blockchain, never infer from strings:
+ * - **Symbol**: Official ticker (ANIME, GDOG, GALA)
+ * - **Decimals**: Precision (8 or 18 typically)
+ * - **Max Supply**: Token supply cap
+ * - **Verification**: Gala verification status
+ * - **Name**: Full token name
+ *
+ * ## Why This Matters
+ *
+ * **❌ WRONG: Inferring from format strings**
+ * ```typescript
+ * // DON'T DO THIS
+ * const symbol = tokenString.split('|')[2]; // Unreliable!
+ * const decimals = 18; // Guessing!
+ * ```
+ *
+ * **✅ CORRECT: Query blockchain**
+ * ```typescript
+ * // DO THIS
+ * const metadata = await tokenMetadataService.resolveTokenMetadata('anime');
+ * const symbol = metadata.symbol; // "ANIME" (verified from chain)
+ * const decimals = metadata.decimals; // 8 (actual value from chain)
+ * ```
+ *
+ * ## Metadata Immutability
+ *
+ * **Critical Blockchain Property:**
+ * - Token metadata CANNOT be changed after creation
+ * - Maximizes trust and predictability
+ * - Enables aggressive caching (default 1 hour TTL)
+ * - Symbol, decimals, maxSupply are permanent
+ *
+ * ## Caching Strategy
+ *
+ * **Time-Based Expiry (default 1 hour):**
+ * - First request: Fetch from blockchain (~100ms)
+ * - Cached requests: In-memory read (~1ms)
+ * - Auto-refresh after TTL expires
+ * - Manual cache clearing available
+ *
+ * **Why Not Permanent Cache:**
+ * - New tokens may be created
+ * - Verification status can change
+ * - Conservative approach for safety
+ * - Configurable TTL for different use cases
+ *
+ * ## Decimals Importance
+ *
+ * **Amount Formatting:**
+ * ```typescript
+ * // On-chain amount: "100000000" (8 decimals)
+ * // User-friendly: "1.00" tokens
+ * // Conversion: amount / 10^decimals
+ *
+ * const metadata = await service.resolveTokenMetadata('anime');
+ * const onChainAmount = "100000000";
+ * const userAmount = Number(onChainAmount) / Math.pow(10, metadata.decimals);
+ * console.log(userAmount); // 1.0
+ * ```
+ *
+ * **Common Decimal Values:**
+ * - GALA: 8 decimals (Bitcoin-style precision)
+ * - GUSDC: 6 decimals (matches USDC standard)
+ * - WETH: 18 decimals (Ethereum standard)
+ * - Launchpad tokens: 8 decimals (default)
+ *
+ * @packageDocumentation
+ * @category Services
+ * @since 3.0.0
  */
 import { LoggerBase } from './BaseService';
 import type { TokenClass } from '../types/gswap.dto';
@@ -34,45 +100,292 @@ export declare class TokenMetadataService extends LoggerBase {
     private cacheExpiry;
     constructor(debugMode?: boolean);
     /**
-     * Resolve token metadata from a token reference
+     * Resolve token metadata from GalaChain blockchain
+     *
+     * Queries GalaChain for authoritative token metadata including symbol, decimals,
+     * supply cap, and verification status. Uses time-based caching (default 1 hour)
+     * to minimize network calls while ensuring data freshness.
+     *
+     * ## Supported Input Formats
+     *
+     * **Simple Symbol:**
+     * ```typescript
+     * await service.resolveTokenMetadata('GALA');
+     * await service.resolveTokenMetadata('anime');
+     * ```
+     *
+     * **Full Format String:**
+     * ```typescript
+     * await service.resolveTokenMetadata('GALA|Unit|none|none');
+     * await service.resolveTokenMetadata('Token|Unit|ANIME|eth:0x...');
+     * ```
+     *
+     * **TokenClass Object:**
+     * ```typescript
+     * await service.resolveTokenMetadata({
+     *   collection: 'Token',
+     *   category: 'Unit',
+     *   type: 'ANIME',
+     *   additionalKey: 'eth:0x...'
+     * });
+     * ```
+     *
+     * ## Return Value
      *
-     * Supports multiple input formats:
-     * - Simple symbol: "GALA"
-     * - OG coin format: "GALA|Unit|none|none"
-     * - TokenClass object: { collection: "GALA", ... }
-     * - Graduated token format: "Token|Unit|BENE|client:xxxx"
+     * ```typescript
+     * {
+     *   symbol: "ANIME",        // Official ticker
+     *   decimals: 8,            // Precision
+     *   name: "Anime Token",    // Full name
+     *   maxSupply: "1000000000",// Supply cap
+     *   verified: true,         // Gala verification
+     *   collection: "Token",
+     *   category: "Unit",
+     *   type: "ANIME",
+     *   additionalKey: "eth:0x..."
+     * }
+     * ```
      *
-     * ⚠️ CRITICAL NOTE: This method should be used when you need REAL token metadata
-     * from blockchain. For format conversion only, use TokenFormatConverter.
+     * ## Caching Behavior
+     *
+     * - **First request**: Fetch from blockchain (~100ms)
+     * - **Cached requests**: In-memory read (~1ms)
+     * - **Cache expiry**: 1 hour (configurable)
+     * - **Auto-refresh**: After TTL expires
+     *
+     * ## Why Use This vs String Parsing
+     *
+     * **❌ WRONG: Inferring from strings**
+     * ```typescript
+     * // Unreliable and error-prone!
+     * const parts = tokenString.split('|');
+     * const symbol = parts[2]; // Might be wrong!
+     * const decimals = 18; // Guessing!
+     * ```
+     *
+     * **✅ CORRECT: Query blockchain**
+     * ```typescript
+     * // Verified and accurate!
+     * const metadata = await service.resolveTokenMetadata('anime');
+     * const symbol = metadata.symbol; // "ANIME" (from chain)
+     * const decimals = metadata.decimals; // 8 (from chain)
+     * ```
      *
      * @param token Token reference (symbol, format string, or TokenClass object)
-     * @returns Token metadata with verified symbol and decimals from blockchain
+     * @returns Verified token metadata from blockchain
+     *
+     * @example
+     * ```typescript
+     * // Resolve by symbol
+     * const metadata = await service.resolveTokenMetadata('anime');
+     * console.log('Symbol:', metadata.symbol); // "ANIME"
+     * console.log('Decimals:', metadata.decimals); // 8
+     *
+     * // Format on-chain amount for display
+     * const onChainAmount = "100000000"; // 8 zeros
+     * const userAmount = Number(onChainAmount) / Math.pow(10, metadata.decimals);
+     * console.log('User amount:', userAmount); // 1.0
+     * ```
+     *
+     * @category Metadata Resolution
+     * @since 3.0.0
      */
     resolveTokenMetadata(token: string | TokenClass): Promise<TokenMetadata>;
     /**
-     * Get symbol for a token
+     * Get token symbol from blockchain
+     *
+     * Convenience method that resolves full metadata and returns only the symbol.
+     * Uses the same caching as `resolveTokenMetadata()`.
+     *
+     * ## Why This Matters
+     *
+     * **✅ CORRECT approach (this method):**
+     * ```typescript
+     * const symbol = await service.getTokenSymbol('anime');
+     * console.log(symbol); // "ANIME" (verified from chain)
+     * ```
      *
-     * ✅ This is the CORRECT way to get token symbols
-     * ❌ WRONG: Trying to infer from token format string
-     * ✅ CORRECT: Query GalaChain via fetchTokenClassFromChain()
+     * **❌ WRONG approach (string parsing):**
+     * ```typescript
+     * const parts = tokenString.split('|');
+     * const symbol = parts[2]; // Unreliable! Might be type, not symbol!
+     * ```
      *
-     * @param token Token reference
-     * @returns Real token symbol from blockchain
+     * ## Symbol Use Cases
+     *
+     * - Display token ticker in UI
+     * - Trading pair notation (ANIME/GALA)
+     * - Portfolio listings
+     * - Search and filtering
+     *
+     * @param token Token reference (symbol, format string, or TokenClass)
+     * @returns Official token symbol from blockchain
+     *
+     * @example
+     * ```typescript
+     * const symbol = await service.getTokenSymbol('anime');
+     * console.log(`Trading ${symbol}/GALA`); // "Trading ANIME/GALA"
+     * ```
+     *
+     * @category Metadata Resolution
+     * @since 3.0.0
      */
     getTokenSymbol(token: string | TokenClass): Promise<string>;
     /**
-     * Get decimals for a token
+     * Get token decimals from blockchain
+     *
+     * Convenience method that resolves full metadata and returns only the decimals.
+     * Critical for amount formatting and on-chain → user-friendly conversions.
+     *
+     * ## Decimals Usage
+     *
+     * **Amount Conversion:**
+     * ```typescript
+     * const decimals = await service.getTokenDecimals('anime');
+     * const onChainAmount = "100000000"; // 8 zeros
+     * const userAmount = Number(onChainAmount) / Math.pow(10, decimals);
+     * console.log(userAmount); // 1.0
+     * ```
+     *
+     * **Common Decimal Values:**
+     * - GALA: 8 decimals (Bitcoin-style)
+     * - GUSDC: 6 decimals (USDC standard)
+     * - WETH: 18 decimals (Ethereum standard)
+     * - Launchpad tokens: 8 decimals (default)
+     *
+     * ## Why Decimals Matter
+     *
+     * **Display Accuracy:**
+     * - 8 decimals: Can show 0.00000001 precision
+     * - 18 decimals: Can show 0.000000000000000001 precision
+     * - Wrong decimals = wrong amounts shown to users
      *
-     * @param token Token reference
-     * @returns Token decimals from blockchain
+     * **Trading Precision:**
+     * - On-chain amounts are integers (no floating point)
+     * - Decimals define the scaling factor
+     * - 1 token = 10^decimals smallest units
+     *
+     * @param token Token reference (symbol, format string, or TokenClass)
+     * @returns Token decimal precision from blockchain
+     *
+     * @example
+     * ```typescript
+     * // Get decimals for amount formatting
+     * const decimals = await service.getTokenDecimals('anime');
+     * console.log('Decimals:', decimals); // 8
+     *
+     * // Convert on-chain to user-friendly
+     * function formatAmount(onChainAmount: string, decimals: number): string {
+     *   const amount = Number(onChainAmount) / Math.pow(10, decimals);
+     *   return amount.toFixed(decimals);
+     * }
+     *
+     * const formatted = formatAmount("100000000", decimals);
+     * console.log(formatted); // "1.00000000"
+     * ```
+     *
+     * @category Metadata Resolution
+     * @since 3.0.0
      */
     getTokenDecimals(token: string | TokenClass): Promise<number>;
     /**
-     * Clear cache to force fresh queries
+     * Clear metadata cache to force fresh blockchain queries
+     *
+     * Removes cached metadata entries. Can clear entire cache or a specific token.
+     * Next request for cleared tokens will fetch fresh data from blockchain.
+     *
+     * ## Use Cases
+     *
+     * **Clear All:**
+     * - Testing scenarios (fresh state)
+     * - Memory management (rare)
+     * - Major blockchain upgrade events
+     *
+     * **Clear Specific:**
+     * - Token verification status changed
+     * - Suspected stale data
+     * - Debugging metadata issues
+     *
+     * ## When NOT to Clear
+     *
+     * **Metadata is immutable:**
+     * - Symbol never changes
+     * - Decimals never change
+     * - Max supply never changes
+     * - Cache clearing rarely needed
+     *
+     * **Performance impact:**
+     * - Next request requires blockchain call (~100ms)
+     * - Only clear if absolutely necessary
+     *
+     * @param tokenKey Optional token key to clear (clears all if omitted)
+     *
+     * @example
+     * ```typescript
+     * // Clear entire cache
+     * service.clearCache();
+     * console.log('All metadata cache cleared');
+     *
+     * // Clear specific token
+     * service.clearCache('anime');
+     * console.log('Cleared cache for anime token');
+     * ```
+     *
+     * @category Cache Management
+     * @since 3.0.0
      */
     clearCache(tokenKey?: string): void;
     /**
-     * Get cache statistics
+     * Get cache statistics for monitoring and debugging
+     *
+     * Returns cache metrics including size and all cached token keys.
+     * Useful for monitoring cache health and verifying cache behavior.
+     *
+     * ## Metrics Provided
+     *
+     * - **size**: Number of cached tokens
+     * - **entries**: Array of all cached token keys
+     *
+     * ## Use Cases
+     *
+     * **Cache Monitoring:**
+     * ```typescript
+     * const stats = service.getCacheStats();
+     * console.log(`Cache size: ${stats.size} tokens`);
+     * console.log(`Memory: ~${stats.size * 0.5}KB`); // Rough estimate
+     * ```
+     *
+     * **Cache Health:**
+     * ```typescript
+     * // Monitor cache growth
+     * setInterval(() => {
+     *   const stats = service.getCacheStats();
+     *   if (stats.size > 500) {
+     *     console.warn('Large metadata cache, consider clearing');
+     *   }
+     * }, 300000); // Every 5 minutes
+     * ```
+     *
+     * **Debugging:**
+     * ```typescript
+     * const stats = service.getCacheStats();
+     * console.log('Cached tokens:', stats.entries);
+     * const hasAnime = stats.entries.includes('anime');
+     * console.log('Anime cached:', hasAnime);
+     * ```
+     *
+     * @returns Cache statistics with size and entry keys
+     *
+     * @example
+     * ```typescript
+     * const stats = service.getCacheStats();
+     * console.log('Cache size:', stats.size);
+     * console.log('Cached tokens:', stats.entries.join(', '));
+     * // Output: "anime, gala, gusdc"
+     * ```
+     *
+     * @category Cache Management
+     * @since 3.0.0
      */
     getCacheStats(): {
         size: number;
@@ -105,8 +418,71 @@ export declare class TokenMetadataService extends LoggerBase {
      */
     private isCacheExpired;
     /**
-     * Set cache expiry duration
-     * @param ms Milliseconds before cache expires (default: 1 hour)
+     * Set cache expiry duration (time-to-live)
+     *
+     * Configures how long metadata remains cached before requiring refresh.
+     * Default is 1 hour (3,600,000ms). Adjust based on your application's
+     * requirements for data freshness vs. performance.
+     *
+     * ## Recommended TTL Values
+     *
+     * **Conservative (1 hour - default):**
+     * ```typescript
+     * service.setCacheExpiry(3600000); // 1 hour
+     * // Good balance of freshness and performance
+     * // Suitable for most applications
+     * ```
+     *
+     * **Aggressive (1 day):**
+     * ```typescript
+     * service.setCacheExpiry(86400000); // 24 hours
+     * // Maximum performance, minimal refreshes
+     * // Safe because metadata is immutable
+     * // Best for production apps
+     * ```
+     *
+     * **Fresh (5 minutes):**
+     * ```typescript
+     * service.setCacheExpiry(300000); // 5 minutes
+     * // Frequent refreshes for changing data
+     * // Use if verification status updates frequently
+     * ```
+     *
+     * **No Cache (for testing):**
+     * ```typescript
+     * service.setCacheExpiry(0); // Immediate expiry
+     * // Every request fetches from blockchain
+     * // Only use for testing/debugging
+     * ```
+     *
+     * ## Trade-offs
+     *
+     * **Longer TTL (hours/days):**
+     * - Pros: Better performance, fewer API calls
+     * - Cons: Slightly stale data (verification status)
+     * - Safe: Core metadata (symbol, decimals) never changes
+     *
+     * **Shorter TTL (minutes):**
+     * - Pros: Fresher data, catches status changes
+     * - Cons: More API calls, higher latency
+     * - Rare benefit: Metadata rarely changes
+     *
+     * @param ms Cache expiry in milliseconds (default: 3600000 = 1 hour)
+     *
+     * @example
+     * ```typescript
+     * // Production: Long cache (metadata immutable)
+     * service.setCacheExpiry(86400000); // 24 hours
+     *
+     * // Development: Short cache (debugging)
+     * service.setCacheExpiry(60000); // 1 minute
+     *
+     * // Testing: No cache
+     * service.setCacheExpiry(0); // Immediate expiry
+     * ```
+     *
+     * @category Cache Management
+     * @since 3.0.0
      */
     setCacheExpiry(ms: number): void;
 }

package/dist/src/services/TokenMetadataService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TokenMetadataService.d.ts","sourceRoot":"","sources":["../../../src/services/TokenMetadataService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG;QACb,IAAI,EAAE,aAAa,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,WAAW,CAAmB;gBAE1B,SAAS,GAAE,OAAe;IAItC;;;;;;;;;;;;;;OAcG;IACG,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAyB9E;;;;;;;;;OASG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAKjE;;;;;OAKG;IACG,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAKnE;;OAEG;IACH,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAUnC;;OAEG;IACH,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE;IAQpD;;;OAGG;IAEH,OAAO,CAAC,WAAW;IAYnB;;;;;;;OAOG;IAEH,OAAO,CAAC,eAAe;IAyDvB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAItB;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAIjC"}
+{"version":3,"file":"TokenMetadataService.d.ts","sourceRoot":"","sources":["../../../src/services/TokenMetadataService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG;QACb,IAAI,EAAE,aAAa,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,qBAAa,oBAAqB,SAAQ,UAAU;IAClD,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,WAAW,CAAmB;gBAE1B,SAAS,GAAE,OAAe;IAItC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0FG;IACG,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAyB9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAKjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuDG;IACG,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAKnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACH,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAUnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;IACH,aAAa,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE;IAQpD;;;OAGG;IAEH,OAAO,CAAC,WAAW;IAYnB;;;;;;;OAOG;IAEH,OAAO,CAAC,eAAe;IAyDvB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAItB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkEG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAIjC"}

package/dist/src/services/TradeService.d.ts

@@ -16,33 +16,195 @@ import { FetchTradesOptions } from '../types/options.dto';
  * Provides methods for:
  * - Fetching trade history with pagination
  * - Filtering trades by token, user, type, date range
+ * - Trade statistics and analysis
+ * - Buy/sell volume tracking
  *
- * @example
+ * @category Services
+ * @since 3.6.0
+ *
+ * @example Basic trade history
  * ```typescript
  * const tradeService = new TradeService(httpClient);
  *
  * // Get first page of trades for a token
- * const trades = await tradeService.fetchTrades({ tokenName: "dragnrkti" });
+ * const trades = await tradeService.fetchTrades({ tokenName: "anime" });
+ * console.log(`Found ${trades.totalResults} trades across ${trades.totalPages} pages`);
+ * ```
  *
+ * @example Paginated trade fetching
+ * ```typescript
  * // Get specific page with custom limit
  * const moreTrades = await tradeService.fetchTrades({
- *   tokenName: "dragnrkti",
+ *   tokenName: "GDOG",
  *   page: 2,
  *   limit: 20
  * });
+ *
+ * // Process trades
+ * moreTrades.trades.forEach(trade => {
+ *   console.log(`${trade.type}: ${trade.amount} at ${trade.price}`);
+ * });
+ * ```
+ *
+ * @example Filter by trade type
+ * ```typescript
+ * // Get only buy trades
+ * const buys = await tradeService.fetchTrades({
+ *   tokenName: "GUSDC",
+ *   tradeType: "buy",
+ *   limit: 50
+ * });
+ *
+ * // Calculate total buy volume
+ * const totalBuyVolume = buys.trades.reduce((sum, t) => sum + parseFloat(t.amount), 0);
  * ```
  */
 export declare class TradeService extends BaseService {
+    /**
+     * Creates a TradeService instance
+     *
+     * @param http Configured HttpClient with authentication
+     * @param debugMode Enable debug logging (default: false)
+     *
+     * @example
+     * ```typescript
+     * const httpClient = new HttpClient(config);
+     * const tradeService = new TradeService(httpClient, true);
+     * ```
+     */
     constructor(http: HttpClient, debugMode?: boolean);
     /**
      * Gets trades for a token by its tokenName with pagination
      *
+     * Fetches trade history for a specific token with comprehensive pagination
+     * support. Returns normalized trade data with metadata including price,
+     * amount, timestamp, and trader information.
+     *
      * This method provides a clean, intuitive API for fetching token trades
-     * using the token name. Follows the same pattern as CommentAPI.
+     * using the token name. Follows the same pattern as CommentAPI for consistency.
+     *
+     * Response includes:
+     * - Trade details (type, amount, price, timestamp)
+     * - Trader addresses and wallet information
+     * - Transaction hashes for verification
+     * - Full pagination metadata (page, totalPages, hasNext, hasPrevious)
+     *
+     * Filtering options (optional):
+     * - tradeType: Filter by 'buy' or 'sell'
+     * - userAddress: Filter by specific trader
+     * - startDate/endDate: Filter by date range
+     * - sortOrder: Sort by timestamp (asc/desc)
      *
      * @param options Trade fetching options
-     * @returns Promise<TradesResult> Clean trades with full pagination
-     * @throws ValidationError if token name is invalid or not found
+     * @param options.tokenName Token name to fetch trades for (required)
+     * @param options.page Page number (default: 1)
+     * @param options.limit Results per page (default: 10, max: 100)
+     * @param options.tradeType Filter by trade type ('buy' | 'sell')
+     * @param options.userAddress Filter by trader address
+     * @param options.startDate Filter by start date
+     * @param options.endDate Filter by end date
+     * @param options.sortOrder Sort order ('asc' | 'desc')
+     * @returns Promise resolving to trades with full pagination metadata
+     * @throws {ValidationError} If token name is invalid or empty
+     * @throws {ValidationError} If options object is invalid format
+     * @throws {ValidationError} If pagination parameters are invalid
+     * @throws {ValidationError} If no response from trade service
+     *
+     * @category Trade Operations
+     * @since 3.6.0
+     *
+     * @example Basic trade history
+     * ```typescript
+     * const result = await tradeService.fetchTrades({ tokenName: "anime" });
+     *
+     * console.log(`Page ${result.page} of ${result.totalPages}`);
+     * console.log(`Total trades: ${result.totalResults}`);
+     *
+     * result.trades.forEach(trade => {
+     *   console.log(`${trade.type}: ${trade.amount} @ ${trade.price} GALA`);
+     *   console.log(`Trader: ${trade.traderAddress}`);
+     *   console.log(`Time: ${new Date(trade.timestamp).toLocaleString()}`);
+     * });
+     * ```
+     *
+     * @example Paginated trade fetching
+     * ```typescript
+     * const limit = 20;
+     * let page = 1;
+     * const allTrades = [];
+     *
+     * while (true) {
+     *   const result = await tradeService.fetchTrades({
+     *     tokenName: "GDOG",
+     *     page,
+     *     limit
+     *   });
+     *
+     *   allTrades.push(...result.trades);
+     *   if (!result.hasNext) break;
+     *   page++;
+     * }
+     *
+     * console.log(`Fetched ${allTrades.length} total trades`);
+     * ```
+     *
+     * @example Filter by trade type
+     * ```typescript
+     * // Get only buy trades
+     * const buys = await tradeService.fetchTrades({
+     *   tokenName: "GUSDC",
+     *   tradeType: "buy",
+     *   limit: 50
+     * });
+     *
+     * // Calculate total buy volume
+     * const totalBuyVolume = buys.trades.reduce(
+     *   (sum, trade) => sum + parseFloat(trade.amount),
+     *   0
+     * );
+     * console.log(`Total buy volume: ${totalBuyVolume} GUSDC`);
+     * ```
+     *
+     * @example Filter by date range
+     * ```typescript
+     * const startDate = new Date('2025-01-01');
+     * const endDate = new Date('2025-01-31');
+     *
+     * const januaryTrades = await tradeService.fetchTrades({
+     *   tokenName: "anime",
+     *   startDate,
+     *   endDate,
+     *   limit: 100
+     * });
+     *
+     * console.log(`January trades: ${januaryTrades.totalResults}`);
+     * ```
+     *
+     * @example Filter by user address
+     * ```typescript
+     * const userTrades = await tradeService.fetchTrades({
+     *   tokenName: "GDOG",
+     *   userAddress: "eth|0x123...",
+     *   limit: 100
+     * });
+     *
+     * console.log(`User has ${userTrades.totalResults} trades`);
+     *
+     * // Calculate user P&L
+     * let totalSpent = 0;
+     * let totalReceived = 0;
+     *
+     * userTrades.trades.forEach(trade => {
+     *   const value = parseFloat(trade.amount) * parseFloat(trade.price);
+     *   if (trade.type === 'buy') {
+     *     totalSpent += value;
+     *   } else {
+     *     totalReceived += value;
+     *   }
+     * });
+     *
+     * console.log(`P&L: ${totalReceived - totalSpent} GALA`);
+     * ```
      */
     fetchTrades(options: FetchTradesOptions): Promise<TradesResult>;
 }

package/dist/src/services/TradeService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TradeService.d.ts","sourceRoot":"","sources":["../../../src/services/TradeService.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAO3C,OAAO,EAEL,YAAY,EAEb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAwB,MAAM,sBAAsB,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,YAAa,SAAQ,WAAW;gBAC/B,IAAI,EAAE,UAAU,EAAE,SAAS,GAAE,OAAe;IAIxD;;;;;;;;;OASG;IACG,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;CA2DtE"}
+{"version":3,"file":"TradeService.d.ts","sourceRoot":"","sources":["../../../src/services/TradeService.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAO3C,OAAO,EAEL,YAAY,EAEb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAwB,MAAM,sBAAsB,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBAAa,YAAa,SAAQ,WAAW;IAC3C;;;;;;;;;;;OAWG;gBACS,IAAI,EAAE,UAAU,EAAE,SAAS,GAAE,OAAe;IAIxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoIG;IACG,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;CA2DtE"}