@gala-chain/launchpad-sdk 3.27.4 → 3.29.0

package/dist/services/DexPoolService.d.ts

@@ -0,0 +1,95 @@
+/**
+ * DEX Pool Discovery Service
+ *
+ * Service for querying and exploring GalaSwap DEX liquidity pools
+ * with pagination, filtering, and sorting capabilities.
+ *
+ * @packageDocumentation
+ */
+import { BaseService } from './BaseService';
+import type { HttpClient } from '../utils/http';
+import type { DexPoolsResult, FetchDexPoolsOptions } from '../types/dex-pool.dto';
+/**
+ * Service for fetching and exploring DEX pools on GalaSwap
+ *
+ * Handles pagination, filtering, and sorting of liquidity pools
+ * across all graduated tokens and base tokens.
+ *
+ * @category GSwap
+ * @since 3.28.0
+ */
+export declare class DexPoolService extends BaseService {
+    /** Base URL for DEX backend API */
+    private readonly dexBackendBaseUrl;
+    /**
+     * Create a new DexPoolService instance
+     *
+     * @param http HttpClient for making API requests
+     * @param dexBackendBaseUrl Base URL for DEX backend API
+     * @param debugMode Enable debug logging
+     */
+    constructor(http: HttpClient, dexBackendBaseUrl: string, debugMode?: boolean);
+    /**
+     * Fetch DEX pools with pagination and filtering
+     *
+     * Queries the DEX backend for available liquidity pools with support for:
+     * - Pagination (max 20 per page)
+     * - Sorting by TVL, 30-day volume, or 1-day volume
+     * - Search filtering by token symbols
+     *
+     * @param options Fetch options (all optional)
+     * @returns Promise resolving to paginated pool results
+     *
+     * @throws {Error} If HTTP request fails
+     * @throws {ValidationError} If sort options are invalid
+     *
+     * @example
+     * ```typescript
+     * // Fetch top 10 pools by volume
+     * const result = await dexPoolService.fetchDexPools({
+     *   sortBy: 'volume1d',
+     *   sortOrder: 'desc',
+     *   limit: 10,
+     *   page: 1
+     * });
+     *
+     * console.log(`Found ${result.total} total pools`);
+     * console.log(`Showing page ${result.page} of ${result.totalPages}`);
+     * ```
+     *
+     * @since 3.28.0
+     */
+    fetchDexPools(options?: FetchDexPoolsOptions): Promise<DexPoolsResult>;
+    /**
+     * Fetch ALL DEX pools with automatic pagination
+     *
+     * Convenience method that automatically handles pagination to retrieve
+     * all available DEX pools. Uses maximum page size (20) for efficiency.
+     *
+     * This is useful when you need complete pool data regardless of result size.
+     * For large result sets, consider using fetchDexPools() with explicit pagination.
+     *
+     * @param options Fetch options (no pagination fields)
+     * @returns Promise resolving to all pools with flattened pagination
+     *
+     * @example
+     * ```typescript
+     * // Fetch all pools sorted by TVL
+     * const allPools = await dexPoolService.fetchAllDexPools({
+     *   sortBy: 'tvl',
+     *   sortOrder: 'desc'
+     * });
+     *
+     * console.log(`Total pools: ${allPools.total}`);
+     *
+     * // Find top GALA pools
+     * const galaPools = allPools.pools
+     *   .filter(p => p.poolName.includes('GALA'))
+     *   .slice(0, 10);
+     * ```
+     *
+     * @since 3.28.0
+     */
+    fetchAllDexPools(options?: Omit<FetchDexPoolsOptions, 'page' | 'limit'>): Promise<DexPoolsResult>;
+}
+//# sourceMappingURL=DexPoolService.d.ts.map

package/dist/services/DexPoolService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DexPoolService.d.ts","sourceRoot":"","sources":["../../src/services/DexPoolService.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACrB,MAAM,uBAAuB,CAAC;AAG/B;;;;;;;;GAQG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAC7C,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAE3C;;;;;;OAMG;gBAED,IAAI,EAAE,UAAU,EAChB,iBAAiB,EAAE,MAAM,EACzB,SAAS,GAAE,OAAe;IAM5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,cAAc,CAAC;IAoEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,gBAAgB,CACpB,OAAO,GAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAAM,GACzD,OAAO,CAAC,cAAc,CAAC;CAuC3B"}

package/dist/services/WebSocketService.d.ts

@@ -7,6 +7,7 @@
  * @category Services
  * @since 2.0.0
  */
+import { Socket } from 'socket.io-client';
 import { SDKTransactionStatus } from '../types/websocket.types';
 export interface TransactionStatus {
     transactionId: string;
@@ -66,5 +67,19 @@ export declare class WebSocketService {
      * Check connection status
      */
     isConnected(): boolean;
+    /**
+     * Get the underlying Socket.IO socket instance for custom event subscriptions
+     *
+     * @returns The Socket.IO socket instance, or null if not connected
+     *
+     * @example
+     * const socket = webSocketService.getSocket();
+     * if (socket) {
+     *   socket.on('custom-event', (data) => {
+     *     console.log('Event received:', data);
+     *   });
+     * }
+     */
+    getSocket(): Socket | null;
 }
 //# sourceMappingURL=WebSocketService.d.ts.map

package/dist/services/WebSocketService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebSocketService.d.ts","sourceRoot":"","sources":["../../src/services/WebSocketService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAEL,oBAAoB,EAErB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,SAAS,CACL;IACZ,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,mBAAmB,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAAS;gBAErB,MAAM,EAAE,eAAe,EAAE,KAAK,GAAE,OAAe;IAc3D;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAiBjC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmE9B;;OAEG;IACG,kBAAkB,CACtB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,GAC5C,OAAO,CAAC,IAAI,CAAC;IAoIhB;;OAEG;IACG,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAY3E;;OAEG;IACH,OAAO,CAAC,eAAe;IAKvB;;OAEG;YACW,eAAe;IAmB7B;;OAEG;IACH,UAAU,IAAI,IAAI;IA4BlB;;OAEG;IACH,WAAW,IAAI,OAAO;CAGvB"}
+{"version":3,"file":"WebSocketService.d.ts","sourceRoot":"","sources":["../../src/services/WebSocketService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAM,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAEL,oBAAoB,EAErB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,SAAS,CACL;IACZ,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,mBAAmB,CAAU;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAAS;gBAErB,MAAM,EAAE,eAAe,EAAE,KAAK,GAAE,OAAe;IAc3D;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAiBjC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAmE9B;;OAEG;IACG,kBAAkB,CACtB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,GAC5C,OAAO,CAAC,IAAI,CAAC;IAoIhB;;OAEG;IACG,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAY3E;;OAEG;IACH,OAAO,CAAC,eAAe;IAKvB;;OAEG;YACW,eAAe;IAmB7B;;OAEG;IACH,UAAU,IAAI,IAAI;IA4BlB;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;;;;;;;;;;;OAYG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;CAG3B"}

package/dist/types/dex-pool.dto.d.ts

@@ -0,0 +1,174 @@
+/**
+ * DEX Pool Discovery Types
+ *
+ * Types for querying and exploring GalaSwap DEX liquidity pools.
+ * Supports pagination, filtering, and sorting across all available pools.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Complete DEX pool data structure (19 fields from backend)
+ *
+ * Represents a single liquidity pool on the GalaSwap DEX with full metrics.
+ */
+export interface DexPoolData {
+    /** Pool identifier (e.g., "GALA|Unit|none|none/GUSDC|Unit|none|none/10000") */
+    poolPair: string;
+    /** Unique pool hash identifier */
+    poolHash: string;
+    /** First token symbol (e.g., "GALA") */
+    token0: string;
+    /** Second token symbol (e.g., "GUSDC") */
+    token1: string;
+    /** First token image URL */
+    token0Image: string;
+    /** Second token image URL */
+    token1Image: string;
+    /** First token price in terms of second token */
+    token0Price: string;
+    /** Second token price in terms of first token */
+    token1Price: string;
+    /** Human-readable pool name (e.g., "GALA/GUSDC") */
+    poolName: string;
+    /** Fee tier as percentage string (e.g., "0.3", "1") */
+    fee: string;
+    /** 24-hour fees collected (USD) */
+    fee24h: number;
+    /** First token TVL (in token units) */
+    token0Tvl: number;
+    /** Second token TVL (in token units) */
+    token1Tvl: number;
+    /** First token TVL in USD */
+    token0TvlUsd: number;
+    /** Second token TVL in USD */
+    token1TvlUsd: number;
+    /** Total value locked in pool (USD) */
+    tvl: number;
+    /** 1-day trading volume (USD) */
+    volume1d: number;
+    /** 30-day trading volume (USD) */
+    volume30d: number;
+    /** Volume-to-TVL ratio (volume1d / tvl) */
+    dayPerTvl: number;
+    /** 1-day APR percentage (calculated from fees) */
+    apr1d: number;
+}
+/**
+ * Backend-validated sort field options
+ *
+ * Only these three fields can be used for sorting. The backend validates
+ * and rejects any other sortBy values.
+ *
+ * @see {@link FetchDexPoolsOptions}
+ */
+export type DexPoolSortBy = 'tvl' | 'volume30d' | 'volume1d';
+/**
+ * Sort order direction
+ *
+ * Lowercase for user-facing SDK (converted to uppercase for backend API)
+ */
+export type DexPoolSortOrder = 'asc' | 'desc';
+/**
+ * Options for fetching DEX pools with pagination and filtering
+ *
+ * Follows SDK standard pagination conventions matching other paginated methods
+ * like fetchPools(), fetchTrades(), etc.
+ *
+ * @example
+ * ```typescript
+ * // Fetch top 10 pools by volume
+ * const result = await sdk.fetchDexPools({
+ *   sortBy: 'volume1d',
+ *   sortOrder: 'desc',
+ *   limit: 10,
+ *   page: 1
+ * });
+ *
+ * // Search for GALA pools
+ * const galaPools = await sdk.fetchDexPools({
+ *   search: 'GALA',
+ *   limit: 20
+ * });
+ * ```
+ */
+export interface FetchDexPoolsOptions {
+    /**
+     * Search filter for token symbols in pool pair
+     *
+     * Performs fuzzy search (case-insensitive) across token symbols
+     * and pool names. Example: "GALA", "GUSDC", "GALA/GUSDC"
+     *
+     * @optional
+     */
+    search?: string;
+    /**
+     * Field to sort results by
+     *
+     * Default: 'tvl' (total value locked)
+     * Backend-validated to only allow: 'tvl', 'volume30d', 'volume1d'
+     *
+     * @optional
+     */
+    sortBy?: DexPoolSortBy;
+    /**
+     * Sort order direction
+     *
+     * Default: 'desc' (highest to lowest)
+     *
+     * @optional
+     */
+    sortOrder?: DexPoolSortOrder;
+    /**
+     * Page number (1-based pagination)
+     *
+     * Default: 1
+     *
+     * @optional
+     */
+    page?: number;
+    /**
+     * Number of results per page
+     *
+     * Default: 10
+     * Maximum enforced by backend: 20
+     *
+     * @optional
+     */
+    limit?: number;
+}
+/**
+ * Clean result for paginated DEX pool queries
+ *
+ * Follows SDK standard pagination result structure with 7 metadata fields
+ * matching fetchPools(), fetchTrades(), fetchComments(), etc.
+ *
+ * @example
+ * ```typescript
+ * const result = await sdk.fetchDexPools({ limit: 20 });
+ *
+ * console.log(`Page ${result.page} of ${result.totalPages}`);
+ * console.log(`Total pools: ${result.total}`);
+ * console.log(`Pools in this page: ${result.pools.length}`);
+ *
+ * result.pools.forEach(pool => {
+ *   console.log(`${pool.poolName}: $${pool.tvl.toFixed(2)} TVL`);
+ * });
+ * ```
+ */
+export interface DexPoolsResult {
+    /** Array of DEX pool data */
+    pools: DexPoolData[];
+    /** Current page number (1-based) */
+    page: number;
+    /** Number of items per page */
+    limit: number;
+    /** Total number of pools */
+    total: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Whether there are additional pages after current */
+    hasNext: boolean;
+    /** Whether there are pages before current */
+    hasPrevious: boolean;
+}
+//# sourceMappingURL=dex-pool.dto.d.ts.map

package/dist/types/dex-pool.dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dex-pool.dto.d.ts","sourceRoot":"","sources":["../../src/types/dex-pool.dto.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IAEjB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IAEjB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IAEf,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IAEf,4BAA4B;IAC5B,WAAW,EAAE,MAAM,CAAC;IAEpB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IAEpB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IAEpB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IAEpB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IAEjB,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IAEZ,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IAEf,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAElB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAElB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IAErB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;IAErB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IAEZ,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IAEjB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAElB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAElB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,WAAW,GAAG,UAAU,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IAEvB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAE7B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,KAAK,EAAE,WAAW,EAAE,CAAC;IAErB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IAEb,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IAEd,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IAEd,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IAEnB,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IAEjB,6CAA6C;IAC7C,WAAW,EAAE,OAAO,CAAC;CACtB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gala-chain/launchpad-sdk",
-  "version": "3.27.4",
-  "description": "TypeScript SDK for Gala Launchpad Backend API - 64 methods supporting optional wallet (read-only and full-access modes). Production-ready DeFi token launchpad integration with AgentConfig setup, GalaChain trading, GSwap DEX integration, price history, token creation, and comprehensive user operations. Multi-format output (ESM, CJS, UMD).",
+  "version": "3.29.0",
+  "description": "TypeScript SDK for Gala Launchpad Backend API - 66 methods supporting optional wallet (read-only and full-access modes). Production-ready DeFi token launchpad integration with AgentConfig setup, GalaChain trading, GSwap DEX integration, price history, token creation, DEX pool discovery, and comprehensive user operations. Multi-format output (ESM, CJS, UMD).",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
   "types": "dist/index.d.ts",
@@ -47,6 +47,10 @@
     "demo:liquidity:detailed": "tsx examples/demo-liquidity-detailed.ts",
     "demo:cache": "tsx examples/demo-cache.ts",
     "demo:fetch-all-pools": "tsx examples/demo-fetch-all-pools.ts",
+    "demo:dex-trades": "tsx examples/demo-dex-trades.ts",
+    "demo:dex-pool-discovery": "tsx examples/demo-dex-pool-discovery.ts",
+    "demo:watch-pools": "tsx examples/demo-watch-pools.ts",
+    "demo:watch-tokens": "tsx examples/demo-watch-tokens.ts",
     "lint": "eslint src tests scripts --ext .ts,.tsx --fix",
     "lint:check": "eslint src tests scripts --ext .ts,.tsx",
     "typecheck": "tsc --noEmit",