@gala-chain/launchpad-sdk
Version:
TypeScript SDK for Gala Launchpad Backend API - Production-ready DeFi token launchpad integration with wallet-based authentication, GalaChain trading, and comprehensive user operations. 100% tested (22/22 endpoints working).
933 lines • 36.5 kB
TypeScript
import { Wallet } from 'ethers';
import { SDKConfig, AddressFormat, TokenClassKey } from './types/common';
import { PoolDetailsData } from './types/trade.dto';
import { LaunchTokenData, TokenSpotPrice, FetchPoolsOptions } from './types/launchpad.dto';
import { UpdateProfileData, UploadProfileImageOptions, FetchTokenBalanceOptions } from './types/user.dto';
import { TransferGalaData, TransferTokenData } from './types/transfer.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, BuyTokenOptions, SellTokenOptions, UploadImageByTokenNameOptions, FetchTokensHeldOptions, FetchTokensCreatedOptions, GraduateTokenOptions } from './types/options.dto';
/**
* Configuration for initializing the Launchpad SDK
*
* @category Configuration
* @since 1.0.0
* @agent-capability Enables SDK initialization with wallet authentication
* @agent-prerequisites Valid ethers.js Wallet instance with private key
* @agent-example
* ```typescript
* import { Wallet } from 'ethers';
* import { LaunchpadSDK } from '@gala-chain/launchpad-sdk';
*
* const wallet = new Wallet(process.env.PRIVATE_KEY);
*
* // Environment-based configuration (recommended)
* const config: LaunchpadSDKConfig = {
* wallet,
* env: 'STAGE', // or 'PROD'
* timeout: 30000,
* debug: false
* };
*
* // With URL overrides
* const configWithOverrides: LaunchpadSDKConfig = {
* wallet,
* env: 'PROD',
* galaChainBaseUrl: 'https://custom-gateway.example.com'
* };
* ```
*/
export interface LaunchpadSDKConfig extends SDKConfig {
/** The ethers wallet for authentication - must be a valid ethers.js Wallet instance */
wallet: Wallet;
/** Optional GalaChain gateway URL override - defaults based on main API environment */
galaChainBaseUrl?: string;
/** Optional Bundle service URL override - defaults based on main API environment */
bundleBaseUrl?: string;
/** Optional WebSocket URL override for transaction monitoring - defaults based on main API environment */
webSocketUrl?: string;
/** Optional DEX API URL override for launchpad token balances - defaults based on main API environment */
dexApiBaseUrl?: string;
/** Optional Launchpad Frontend URL override - defaults based on main API environment */
launchpadFrontendUrl?: string;
/** Optional global slippage tolerance factor (e.g., 0.05 = 5% slippage tolerance) - defaults to 0.15 */
slippageToleranceFactor?: number;
/** Optional global reverse bonding curve fee slippage factor (e.g., 0.01 = 1% fee slippage) - defaults to 0.01 */
maxAcceptableReverseBondingCurveFeeSlippageFactor?: number;
}
/**
* Main Launchpad SDK class providing access to all Gala Launchpad functionality
*
* This is the primary entry point for interacting with the Gala Launchpad backend.
* It provides a clean, type-safe interface for all API operations including pool creation,
* token trading, and user management.
*
* Features:
* - Automatic signature-based authentication
* - Type-safe API interfaces
* - Built-in error handling and retry logic
* - Address format conversion (eth|xxx ↔ 0xxxx)
* - Bonding curve trading for launchpad tokens
* - EIP-712 signature generation for all wallet types
* - Bundle transaction processing
* - Real-time transaction monitoring via WebSocket
* - Comprehensive validation
*
* @category Main SDK
* @since 1.0.0
* @agent-capability Primary interface for all Gala Launchpad operations including token creation, trading, and user management
* @agent-prerequisites Initialized with valid LaunchpadSDKConfig containing wallet
* @agent-errors
* - WALLET_001: Invalid wallet configuration - Reinitialize with valid ethers.js Wallet
* - NETWORK_001: Connection timeout - Check network and retry with higher timeout
* - AUTH_001: Authentication failed - Verify wallet has valid private key
* @agent-example
* ```typescript
* import { Wallet } from 'ethers';
* import { LaunchpadSDK, createWallet } from '@gala-chain/launchpad-sdk';
*
* // Generate or import wallet
* const wallet = createWallet(process.env.PRIVATE_KEY).wallet;
*
* // Initialize SDK
* const sdk = new LaunchpadSDK({
* wallet,
* debug: true
* });
*
* // Verify setup
* console.log('SDK Address:', sdk.getAddress()); // eth|{address}
* console.log('Ethereum Address:', sdk.getEthereumAddress()); // 0x{address}
*
* // SDK is ready for operations
* const balance = await sdk.fetchGalaBalance(sdk.getAddress());
* ```
*
* @example Error handling pattern
* ```typescript
* try {
* const transactionId = await sdk.launchToken(tokenData);
* console.log('Token launched successfully:', transactionId);
* return transactionId;
* } catch (error) {
* console.error('Operation failed:', error.message);
* // Implement retry logic or alternative action
* }
* ```
*/
export declare class LaunchpadSDK {
/** Default slippage tolerance factor (15%) - Higher for volatile bonding curve tokens */
static readonly DEFAULT_SLIPPAGE_TOLERANCE_FACTOR = 0.15;
/** Default reverse bonding curve fee slippage factor (1%) - Applied to maxAcceptableReverseBondingCurveFee */
static readonly DEFAULT_MAX_ACCEPTABLE_REVERSE_BONDING_CURVE_FEE_SLIPPAGE_FACTOR = 0.01;
private readonly auth;
private readonly http;
private readonly galaChainHttp;
private readonly bundleHttp;
private readonly dexApiHttp;
private readonly config;
private readonly slippageToleranceFactor;
private readonly maxAcceptableReverseBondingCurveFeeSlippageFactor;
private readonly logger;
private readonly tokenResolverService;
private readonly launchpadService;
private readonly galaChainService;
private readonly dexService;
private readonly bundleService;
private readonly websocketService;
private readonly launchpadAPI;
constructor(config: LaunchpadSDKConfig);
/**
* Creates a temporary SDK instance with a different wallet for privateKey override operations.
* This allows signing operations with a different wallet without modifying the main SDK instance.
*
* @private
* @param privateKey The private key to use for the temporary SDK instance (format: '0x' + 64 hex chars)
* @returns A temporary SDK instance configured with the override wallet
* @throws Error if privateKey format is invalid
*/
private createOverrideSdk;
/**
* Gets the authenticated user's address in backend format
*
* Returns the wallet address formatted for backend API calls.
* The backend expects addresses in the format "eth|{40-hex-chars}"
* without the standard "0x" prefix.
*
* @category Address Management
* @returns The address in eth|{40-hex-chars} format required by the backend
* @since 1.0.0
*
* @example Get backend address format
* ```typescript
* const sdk = new LaunchpadSDK({ wallet });
* const backendAddress = sdk.getAddress();
* console.log(backendAddress); // "eth|742d35Cc6634C0532925a3b8D0Ea2c76f94C31C0"
* ```
*
* @example Use in API calls
* ```typescript
* const address = sdk.getAddress();
* const pools = await sdk.launchpad.fetchPools({
* creatorAddress: address,
* page: 1,
* limit: 10
* });
* ```
*
* @see {@link getEthereumAddress} - Get standard Ethereum address format
*/
getAddress(): AddressFormat;
/**
* Gets the authenticated user's Ethereum address in standard format
*
* Returns the wallet address in standard Ethereum format with "0x" prefix.
* This is the format typically used in frontend displays and external tools.
*
* @category Address Management
* @returns Standard Ethereum address with 0x prefix
* @since 1.0.0
*
* @example Display user address
* ```typescript
* const sdk = new LaunchpadSDK({ wallet });
* const ethAddress = sdk.getEthereumAddress();
* console.log(`User: ${ethAddress}`); // "User: 0x742d35Cc6634C0532925a3b8D0Ea2c76f94C31C0"
* ```
*
* @example Address consistency check
* ```typescript
* const ethAddr = sdk.getEthereumAddress();
* const backendAddr = sdk.getAddress();
*
* // Verify they represent the same address
* const ethHex = ethAddr.replace('0x', '');
* const backendHex = backendAddr.replace('eth|', '');
* console.log('Same address:', ethHex.toLowerCase() === backendHex.toLowerCase());
* ```
*
* @see {@link getAddress} - Get backend-compatible address format
*/
getEthereumAddress(): string;
/**
* Gets the current SDK configuration
*
* Returns a copy of the SDK configuration with sensitive data removed.
* The wallet instance is excluded for security reasons.
*
* @category Configuration
* @returns SDK configuration object without the wallet property
* @since 1.0.0
*
* @example Inspect SDK configuration
* ```typescript
* const sdk = new LaunchpadSDK({
* wallet,
* baseUrl: 'https://api.example.com',
* timeout: 45000,
* debug: true
* });
*
* const config = sdk.getConfig();
* console.log('Base URL:', config.baseUrl);
* console.log('Timeout:', config.timeout);
* console.log('Debug mode:', config.debug);
* // wallet property is not included for security
* ```
*
* @example Configuration validation
* ```typescript
* const config = sdk.getConfig();
* if (config.debug) {
* console.log('Debug mode is enabled - detailed logging active');
* }
* if (config.timeout < 30000) {
* console.warn('Timeout is quite low, consider increasing for stability');
* }
* ```
*/
getConfig(): Omit<LaunchpadSDKConfig, 'wallet'>;
/**
* Get the frontend URL for a specific token
*
* Constructs the launchpad frontend URL for viewing/trading a specific token.
* The base URL is determined by the environment configuration or can be
* overridden in the SDK config.
*
* @category Utility
* @param tokenName Token name to generate URL for
* @returns Complete frontend URL for the token
* @since 3.1.0
*
* @example Get token URL
* ```typescript
* const sdk = new LaunchpadSDK({ wallet, env: 'PROD' });
* const url = sdk.getUrlByTokenName('dragnrkti');
* console.log(url);
* // Output: https://lpad-frontend-prod1.defi.gala.com/buy-sell/dragnrkti
* ```
*
* @example With custom frontend URL
* ```typescript
* const sdk = new LaunchpadSDK({
* wallet,
* env: 'STAGE',
* launchpadFrontendUrl: 'https://custom-frontend.example.com'
* });
* const url = sdk.getUrlByTokenName('mytoken');
* console.log(url);
* // Output: https://custom-frontend.example.com/buy-sell/mytoken
* ```
*
* @example Generate URLs for multiple tokens
* ```typescript
* const tokens = ['dragnrkti', 'rocketri', 'unicornri'];
* const urls = tokens.map(token => ({
* token,
* url: sdk.getUrlByTokenName(token)
* }));
* console.log(urls);
* ```
*/
getUrlByTokenName(tokenName: string): string;
/**
* Fetch pools with optional filters
*
* @param options Optional filters for pool fetching
* @returns Promise<PoolsResult>
*/
fetchPools(options?: FetchPoolsOptions): Promise<import("./types/launchpad.dto").PoolsResult>;
/**
* Fetch token distribution information
*
* @param tokenName Token name to fetch distribution for
* @returns Promise<TokenDistributionResult>
*/
fetchTokenDistribution(tokenName: string): Promise<import("./types/launchpad.dto").TokenDistributionResult>;
/**
* Fetch token badges
*
* @param tokenName Token name to fetch badges for
* @returns Promise<TokenBadgesResult>
*/
fetchTokenBadges(tokenName: string): Promise<import("./types/launchpad.dto").TokenBadgesResult>;
/**
* Fetch current USD spot prices for one or more DEX token symbols
*
* Uses the DEX API to retrieve current pricing information for tokens.
* Returns simplified spot price format with symbol and price only.
*
* @param symbols Single symbol string or array of symbols (e.g., 'GALA', ['GALA', 'SILK'])
* @returns Promise<TokenSpotPrice[]> Array of simplified token spot prices
*
* @example Single token price
* ```typescript
* const prices = await sdk.fetchTokenSpotPrice('GALA');
* console.log(`${prices[0].symbol}: $${prices[0].price}`); // GALA: $0.01463269
* ```
*
* @example Multiple token prices
* ```typescript
* const prices = await sdk.fetchTokenSpotPrice(['GALA', 'SILK', 'MUSIC']);
* prices.forEach(price => {
* console.log(`${price.symbol}: $${price.price.toFixed(6)}`);
* });
* ```
*
* @throws Error if DEX API client not configured
* @throws Error if no valid symbols provided
* @throws Error if API request fails
*/
fetchTokenSpotPrice(symbols: string | string[]): Promise<TokenSpotPrice[]>;
/**
* Fetch current GALA token USD spot price
*
* Convenience method for fetching GALA price specifically.
* Returns the TokenSpotPrice object directly, not wrapped in an array.
*
* @returns Promise<TokenSpotPrice> GALA spot price data
*
* @example
* ```typescript
* const galaPrice = await sdk.fetchGalaSpotPrice();
* console.log(`GALA: $${galaPrice.price.toFixed(6)}`);
* ```
*
* @throws Error if GALA price not available
* @throws Error if DEX API client not configured
*/
fetchGalaSpotPrice(): Promise<TokenSpotPrice>;
/**
* Calculate spot price for a launchpad token in USD
*
* Calculates the USD price of a launchpad token by determining how many tokens
* you get for 1 GALA and converting based on current GALA USD price.
*
* @param tokenName Token name (e.g., 'dragnrkti', 'rocketri', 'unicornri')
* @returns Promise<TokenSpotPrice> Spot price with symbol and USD price
*
* @example
* ```typescript
* const price = await sdk.fetchLaunchpadTokenSpotPrice('dragnrkti');
* console.log(`${price.symbol}: $${price.price.toFixed(6)}`);
* // Output: DRAGNRKTI: $0.000123
* ```
*
* @throws Error if token not found
* @throws Error if price calculation fails
* @throws Error if GALA price unavailable
*/
fetchLaunchpadTokenSpotPrice(tokenName: string): Promise<TokenSpotPrice>;
/**
* Fetch the current launchpad token launch fee
*
* Returns the GALA fee amount required to launch a new token.
* This fee is dynamic and may vary based on network conditions.
* Call this before launching a token to ensure you have sufficient balance.
*
* @returns Promise<number> The current launch fee in GALA (e.g., 0.001)
* @throws {Error} Network errors from connection failures or timeouts
* @throws {Error} Authentication errors if wallet credentials are invalid
* @throws {Error} API errors when the GalaChain response indicates failure
*
* @example
* ```typescript
* const fee = await sdk.fetchLaunchTokenFee();
* console.log(`Token launch fee: ${fee} GALA`);
*
* // Check if wallet has sufficient balance
* const balance = await sdk.fetchGalaBalance();
* if (parseFloat(balance.quantity) >= fee) {
* console.log('Sufficient balance to launch token');
* }
* ```
*/
fetchLaunchTokenFee(): Promise<number>;
/**
* Fetch pool details for a token - returns complete bonding curve pool state
*
* @param tokenName Token name to fetch pool details for
* @returns Promise<PoolDetailsData>
*/
fetchPoolDetails(tokenName: string): Promise<PoolDetailsData>;
/**
* Fetch volume data for a token
*
* @param options Volume data options with required tokenName
* @returns Promise<GraphDataResult>
*/
fetchVolumeData(options: FetchVolumeDataOptions): Promise<import("./types/launchpad.dto").GraphDataResult>;
/**
* Fetch trade history with filters
*
* @param options Trade fetching options with required tokenName
* @returns Promise<TradesResult>
*/
fetchTrades(options: FetchTradesOptions): Promise<import("./types/trade.dto").TradesResult>;
/**
* Fetch GALA balance for a user
*
* @param address Optional wallet address (0x... or eth|... format), defaults to current user
* @returns Promise<GalaBalanceResult>
*/
fetchGalaBalance(address?: string): Promise<import("./types/user.dto").TokenBalanceResult | null>;
/**
* Fetch token balance from GalaChain (published tokens) or DEX API (launchpad tokens)
*
* This method queries either the GalaChain gateway directly for published tokens
* or the DEX API for launchpad tokens, providing reliable results.
*
* @param options Token balance options with flexible token identification
* @returns Promise<TokenBalanceResult | null>
*
* @example
* ```typescript
* // Using string format
* const galaBalance = await sdk.fetchTokenBalance({
* address: sdk.getAddress(),
* tokenId: "GALA|Unit|none|none"
* });
*
* // Using TokenClassKey object
* const tokenClass = await sdk.resolveTokenClassKey('unicorn');
* const unicornBalance = await sdk.fetchTokenBalance({
* address: sdk.getAddress(),
* tokenClassKey: tokenClass
* });
*
* // Using TokenInstanceKey object
* const unicornBalance2 = await sdk.fetchTokenBalance({
* address: sdk.getAddress(),
* tokenId: {
* collection: "Token",
* category: "Unit",
* type: "UNI",
* additionalKey: "eth:9401b171307bE656f00F9e18DF756643FD3a91dE",
* instance: "0"
* }
* });
*
* // Using token name for convenience
* const unicornBalance3 = await sdk.fetchTokenBalance({
* address: sdk.getAddress(),
* tokenName: "unicorn"
* });
* ```
*/
fetchTokenBalance(options: FetchTokenBalanceOptions): Promise<import("./types/user.dto").TokenBalanceResult | {
quantity: any;
collection: any;
category: string;
tokenId: string;
symbol: string;
name: string;
} | null>;
/**
* Fetch comments for a token
*
* @param options Comment fetching options with required tokenName
* @returns Promise<CommentsResult>
*/
fetchComments(options: FetchCommentsOptions): Promise<import(".").CommentsResult>;
/**
* Calculate buy amount for a token purchase
*
* @param options Calculation options with required tokenName
* @returns Promise<AmountCalculationResult>
*/
calculateBuyAmount(options: CalculateBuyAmountOptions): Promise<import("./types/launchpad.dto").AmountCalculationResult>;
/**
* Calculate sell amount for a token sale
*
* @param options Calculation options with required tokenName
* @returns Promise<AmountCalculationResult>
*/
calculateSellAmount(options: CalculateSellAmountOptions): Promise<import("./types/launchpad.dto").AmountCalculationResult>;
/**
* Calculate buy amount needed to graduate a token pool
*
* Convenience method that fetches pool details and calculates the exact
* cost to buy all remaining tokens. Returns standard AmountCalculationResult.
*
* @param tokenName Token name to check graduation cost for
* @returns Promise<AmountCalculationResult> Same result as calculateBuyAmount
* @throws ValidationError if token not found or already graduated
*/
calculateBuyAmountForGraduation(tokenName: string): Promise<import("./types/launchpad.dto").AmountCalculationResult>;
/**
* Graduate a token pool by buying all remaining tokens
*
* Convenience method that combines calculateBuyAmountForGraduation + buy
* to graduate a token in a single call with WebSocket confirmation.
*
* @param options Graduation options with tokenName and optional slippage protection
* @returns Promise<TradeResult> Transaction result from buying all remaining tokens
* @throws ValidationError if token already graduated or parameters invalid
*/
graduateToken(options: GraduateTokenOptions): Promise<TradeResult>;
/**
* Calculate initial buy amount (pre-mint phase)
*
* @param nativeTokenQuantity Amount of native token (GALA) to spend
* @returns Promise<PreMintCalculationResult>
*/
calculateInitialBuyAmount(nativeTokenQuantity: string): Promise<import("./types/launchpad.dto").AmountCalculationResult>;
/**
* Buy tokens with confirmation
*
* Executes a buy order and waits for blockchain confirmation, returning
* complete trade details including actual amounts traded and fees paid.
*
* @param options Buy options with required tokenName and expectedAmount
* @returns Promise<TradeResult> Complete trade result with amounts and fees
* @since 3.0.0 - Now returns TradeResult instead of basic response
*
* @example
* ```typescript
* const result = await sdk.buy({
* tokenName: 'mytoken',
* amount: '100',
* type: 'native',
* expectedAmount: '1000',
* slippageToleranceFactor: 0.05
* });
*
* console.log('Bought tokens:', result.outputAmount);
* console.log('Spent GALA:', result.inputAmount);
* console.log('Fees paid:', result.totalFees);
* ```
*/
buy(options: BuyTokenOptions): Promise<TradeResult>;
/**
* Sell tokens with confirmation
*
* Executes a sell order and waits for blockchain confirmation, returning
* complete trade details including actual amounts traded and fees paid.
*
* @param options Sell options with required tokenName and expectedAmount
* @returns Promise<TradeResult> Complete trade result with amounts and fees
* @since 3.0.0 - Now returns TradeResult instead of basic response
*
* @example
* ```typescript
* const result = await sdk.sell({
* tokenName: 'mytoken',
* amount: '500',
* type: 'exact',
* expectedAmount: '50',
* slippageToleranceFactor: 0.05
* });
*
* console.log('Sold tokens:', result.inputAmount);
* console.log('Received GALA:', result.outputAmount);
* console.log('Fees paid:', result.totalFees);
* ```
*/
sell(options: SellTokenOptions): Promise<TradeResult>;
/**
* Get bundle transaction result
*
* Returns a lightweight status check for a bundle transaction via HTTP (not WebSocket).
* Useful for checking transaction status when WebSocket monitoring times out or to
* get a definitive answer on transaction state.
*
* Response format: `{ id: string, method: string, status: string }`
*
* @param transactionId Transaction ID from buy(), sell(), or launchToken()
* @returns Promise with transaction result containing id, method, and status
*
* @example
* ```typescript
* // Check status of a transaction
* const result = await sdk.getBundlerTransactionResult('3c7d9f79-a496-4794-abaf-d6bd13473ff7');
*
* console.log('Status:', result.data.status); // "COMPLETED", "FAILED", "PENDING", "PROCESSING"
* console.log('Method:', result.data.method); // "SellExactToken", "BuyWithNative", etc.
* ```
*/
getBundlerTransactionResult(transactionId: string): Promise<import("./types/common").ApiResponse<any>>;
/**
* Post a comment on a token
*
* @param options Comment options with required tokenName and content
* @returns Promise<void>
*/
postComment(options: PostCommentOptions): Promise<void>;
/**
* Launch a new token
*
* Creates a new token with bonding curve and returns complete launch details
* after blockchain confirmation. This method now blocks until the transaction
* is confirmed, providing rich data about the created token.
*
* @param data Token launch data
* @returns Promise<TokenLaunchResult> Complete token launch result with vault address and metadata
* @since 3.0.0 - Now returns TokenLaunchResult instead of transaction ID
*
* @example
* ```typescript
* const result = await sdk.launchToken({
* tokenName: 'mytoken',
* tokenSymbol: 'MTK',
* tokenDescription: 'My amazing token',
* tokenImage: 'https://example.com/image.png',
* preBuyQuantity: '100'
* });
*
* console.log('Token created:', result.tokenName);
* console.log('Vault address:', result.vaultAddress);
* console.log('Creator:', result.creatorAddress);
* console.log('Transaction:', result.transactionId);
* ```
*/
launchToken(data: LaunchTokenData): Promise<TokenLaunchResult>;
/**
* Upload an image for a token
*
* @param options Upload options with required tokenName
* @returns Promise<string>
*/
uploadTokenImage(options: UploadImageByTokenNameOptions): Promise<string>;
/**
* Check if token name is available
*
* @param tokenName Token name to check
* @returns Promise<boolean>
*/
isTokenNameAvailable(tokenName: string): Promise<boolean>;
/**
* Check if token symbol is available
*
* @param symbol Token symbol to check
* @returns Promise<boolean>
*/
isTokenSymbolAvailable(symbol: string): Promise<boolean>;
/**
* Get user profile information
*
* @param address Optional wallet address (defaults to SDK wallet address)
* @returns Promise<any> User profile information
*/
fetchProfile(address?: string): Promise<any>;
/**
* Update user profile information
*
* @param data Profile update data
* @returns Promise<void> No return data - throws on failure
*/
updateProfile(data: UpdateProfileData): Promise<void>;
/**
* Upload a profile image
*
* @param options Profile image upload options
* @returns Promise<string> Upload result with image URL
*/
uploadProfileImage(options: UploadProfileImageOptions): Promise<string>;
/**
* Retrieve GALA from faucet to user wallet
* Backend provides a fixed amount (5 GALA) - amount parameter is not used
*
* @param address Optional wallet address override (defaults to SDK's authenticated wallet)
* @returns Promise<void> Faucet retrieval result
*/
retrieveGalaFromFaucet(address?: string): Promise<void>;
/**
* Fetch tokens held by user with optional filtering
*
* Retrieves a paginated list of tokens held by the authenticated user.
* Supports both exact matching (tokenName) and fuzzy search (search) for efficient filtering.
*
* @param options - Token list options with filtering support
* @param options.page - Page number (1-based), defaults to 1
* @param options.limit - Items per page, defaults to 10
* @param options.tokenName - Exact match filter (case-sensitive, strict equality). Backend filtering reduces payload by ~99% for single-token lookups.
* @param options.search - Fuzzy search filter (case-insensitive, partial matching). Use for discovery and exploration.
* @returns Promise<UserTokenListResult> User's token holdings with pagination metadata
*
* @example
* ```typescript
* // Fetch all tokens with pagination
* const allTokens = await sdk.fetchTokensHeld({ page: 1, limit: 20 });
*
* // Exact match for a specific token (most efficient)
* const anime = await sdk.fetchTokensHeld({ tokenName: 'anime', limit: 1 });
*
* // Fuzzy search for exploration
* const dragons = await sdk.fetchTokensHeld({ search: 'dragon', limit: 10 });
* ```
*
* @remarks
* - Use `tokenName` for exact lookups when you know the token name (fastest)
* - Use `search` for discovery when exploring available tokens
* - Both parameters use backend filtering for optimal performance
* - Passing both parameters together is discouraged (tokenName takes precedence)
*/
fetchTokensHeld(options?: FetchTokensHeldOptions): Promise<import("./types/user.dto").UserTokenListResult>;
/**
* Fetch tokens created by the current user with optional filtering
*
* Retrieves a paginated list of tokens created by the authenticated user.
* Supports both exact matching (tokenName) and fuzzy search (search) for efficient filtering.
*
* @param options - Token list options with filtering support
* @param options.page - Page number (1-based), defaults to 1
* @param options.limit - Items per page, defaults to 10
* @param options.tokenName - Exact match filter (case-sensitive, strict equality). Backend filtering reduces payload by ~99% for single-token lookups.
* @param options.search - Fuzzy search filter (case-insensitive, partial matching). Use for discovery and exploration.
* @returns Promise<UserTokenListResult> User's created tokens with pagination metadata
*
* @example
* ```typescript
* // Fetch all created tokens with pagination
* const myTokens = await sdk.fetchTokensCreated({ page: 1, limit: 20 });
*
* // Exact match for a specific created token (most efficient)
* const myToken = await sdk.fetchTokensCreated({ tokenName: 'mytoken', limit: 1 });
*
* // Fuzzy search through created tokens
* const testTokens = await sdk.fetchTokensCreated({ search: 'test', limit: 10 });
* ```
*
* @remarks
* - Use `tokenName` for exact lookups when you know the token name (fastest)
* - Use `search` for discovery when exploring your created tokens
* - Both parameters use backend filtering for optimal performance
* - Passing both parameters together is discouraged (tokenName takes precedence)
*/
fetchTokensCreated(options?: FetchTokensCreatedOptions): Promise<import("./types/user.dto").UserTokenListResult>;
/**
* Transfer GALA tokens between wallets
*
* Transfers GALA tokens from the authenticated wallet to another wallet
* using GalaChain with EIP-712 signature authentication.
*
* @param data Transfer data including recipient address and amount
* @returns Promise<string> Transaction ID from successful transfer
*
* @example
* ```typescript
* // Transfer 1 GALA to another wallet
* const transactionId = await sdk.transferGala({
* recipientAddress: 'eth|1234567890abcdef1234567890abcdef12345678',
* amount: '1' // 1 GALA in decimal format
* });
*
* console.log('GALA transfer successful!');
* console.log('Transaction ID:', transactionId);
* ```
*/
transferGala(data: TransferGalaData): Promise<string>;
/**
* Transfer launchpad tokens between wallets
*
* Transfers launchpad tokens from the authenticated wallet to another wallet
* using GalaChain with EIP-712 signature authentication.
*
* @param data Transfer data including recipient address, token name, and amount
* @returns Promise<string> Transaction ID from successful transfer
*
* @example
* ```typescript
* // Transfer 100 TINYEVIL tokens to another wallet
* const transactionId = await sdk.transferToken({
* to: 'eth|9876543210fedcba9876543210fedcba98765432',
* tokenName: 'tinyevil',
* amount: '100' // Amount in decimal format
* });
*
* console.log('Token transfer successful!');
* console.log('Transaction ID:', transactionId);
* ```
*/
transferToken(data: TransferTokenData): Promise<string>;
/**
* Resolve token class key from token name
*
* Public method to resolve a token name to its TokenClassKey object for caching or optimization patterns.
* Uses the same resolution logic as transferToken internally.
*
* @param tokenName Token name to resolve (e.g., 'unicorn', 'tinyevil')
* @returns Promise<TokenClassKey> The resolved token class key object
*
* @example
* ```typescript
* const tokenClassKey = await sdk.resolveTokenClassKey('unicorn');
* // Returns: {
* // collection: "Token",
* // category: "Unit",
* // type: "UNI",
* // additionalKey: "eth:9401b171307bE656f00F9e18DF756643FD3a91dE"
* // }
*
* // Can be cached and used later for direct operations
* await sdk.transferToken({
* to: 'eth|...',
* tokenId: tokenClassKey, // Direct, no lookup
* amount: '1'
* });
*
* await sdk.fetchTokenBalance({
* address: sdk.getAddress(),
* tokenClassKey: tokenClassKey // Same object format
* });
* ```
*
* @throws {TransferError} When token name cannot be resolved
*/
resolveTokenClassKey(tokenName: string): Promise<TokenClassKey>;
/**
* Resolve vault address for a token name
*
* @param tokenName Token name to resolve
* @returns Promise<string | null> Vault address or null if not found
*/
resolveVaultAddress(tokenName: string): Promise<string | null>;
/**
* Validates configuration parameters for safety and correctness
* @private
*/
private validateConfiguration;
/**
* Safely parses slippage tolerance factor with validation
* @private
*/
private parseSlippageToleranceFactor;
/**
* Safely parses reverse bonding curve fee slippage factor with validation
* @private
*/
private parseFeeSlippageFactor;
/**
* Ensures WebSocket connection is established
* @private
*/
private ensureWebSocketConnection;
/**
* Internal helper to wait for WebSocket confirmation and transform the result
*
* Note: WebSocket connection must be established BEFORE calling this method.
* All public methods (buy, sell, launchToken) pre-connect to avoid race conditions.
*
* @private
*/
private waitForConfirmation;
/**
* Cleanup SDK resources and connections
*
* Releases WebSocket references and performs cleanup of SDK resources.
* Should be called when the SDK instance is no longer needed to prevent
* memory leaks and ensure proper resource management.
*
* @category Resource Management
* @since 2.1.0
*
* @example Basic cleanup
* ```typescript
* const sdk = new LaunchpadSDK({ wallet });
*
* // Use SDK for operations...
* await sdk.launchToken({...});
*
* // Cleanup when done
* await sdk.cleanup();
* ```
*
* @example Cleanup in application shutdown
* ```typescript
* process.on('SIGINT', async () => {
* console.log('Shutting down...');
* await sdk.cleanup();
* process.exit(0);
* });
* ```
*/
cleanup(): Promise<void>;
/**
* Cleanup all SDK instances and shared resources
*
* Forces cleanup of all shared WebSocket connections and resources
* across all SDK instances. Use this for application-wide cleanup
* or testing teardown.
*
* @category Resource Management
* @param debug Enable debug logging
* @since 2.1.0
*
* @example Application shutdown
* ```typescript
* // Cleanup all SDK instances and shared resources
* LaunchpadSDK.cleanupAll(true);
* ```
*
* @example Test cleanup
* ```typescript
* afterEach(() => {
* // Ensure clean state between tests
* LaunchpadSDK.cleanupAll();
* });
* ```
*/
static cleanupAll(debug?: boolean): void;
}
//# sourceMappingURL=LaunchpadSDK.d.ts.map