Gala Launchpad SDK - Complete API Reference

Version: 9.0.0 Status: Launchpad-only reference, checked against src/LaunchpadSDK.ts and the services it delegates to. launchpad-sdk has no DEX client: the DEX is @gala-chain/gswap-sdk's (see "The DEX is gswap-sdk's"). Removed members and their new homes are listed in MIGRATING-TO-9.0.md.

Conventions: methods take one options object (the heading shows its fields). Lists are cursor-paginated: pass cursor and pageSize, and read pageInfo (the backend's hasNextPage, endCursor, hasPreviousPage, startCursor; totalCount only on fetchAll... results) from the result. A token name is letters and digits, and each method accepts the length its backend route accepts (1-25 where the name is a request field, such as fetchPools, fetchVolumeData, getTrades, fetchMessages; up to 255 where it is part of the path, such as fetchToken and the stream methods; see the TOKEN_NAME_*_CONSTRAINT exports). Amounts are decimal strings. A privateKey option, where a method has one, signs that one call with another key.

Pool Management & Discovery
Trading & Calculations
The DEX is gswap-sdk's
Balance & Portfolio
Token Creation & Management
Social & Comments
Transfers
Locks
Bridgeable Token Discovery
Price History
Utility Methods
Live Streaming
Stream Chat
Service Clients
Error Reference

Pool Management & Discovery

fetchPools(options?)

Description: Fetch one page of launchpad token pools with filtering.

Parameters:

options (FetchPoolsOptions, optional; every value is checked against what GET /v1/tokens accepts, and one it does not accept is a ValidationError, never dropped):
- type: 'RECENT' | 'POPULAR' | 'RECORDINGS' | 'SECONDS_STREAMED', any case (POOL_FETCH_TYPES; backend default: RECENT)
- tokenName: string (exact match; must be a valid token name)
- search: string (fuzzy match, at most 255 characters)
- cursor: string (the previous page's pageInfo.endCursor)
- pageSize: integer 1 to 100 (POOL_LIST_MAX_PAGE_SIZE; default 10)
- hasUpcomingShows: true for pools with a scheduled next stream (false sends nothing: the backend reads any value as true)
- language: string (ISO 639-1 code, e.g. 'en', 'zh-CN')
- recentlyStreamed: integer 1 to 720 (pools that streamed within the last N hours)
- hasRecordings: true for pools with at least one recording (false sends nothing)
- streamStatus: 'IDLE' | 'ACTIVE' | 'DISABLED', any case (POOL_STREAM_STATUSES)
- isGraduated: boolean; true for graduated pools, false for pools still on the bonding curve (both values are sent, as "true" / "false"; leave it out for no filter)
- creatorAddress: eth|<40 hex> or client|<24 hex> (pools that address created; an empty string or any other text is a ValidationError)

Returns: Promise<PoolsResult> (ListResult<PoolData>)

items: array of PoolData (token name, symbol, vault address, prices, supply, graduation flags, stream stats such as currentViewerCount and lastStreamedAt)
pageInfo: the backend's { hasNextPage, endCursor, hasPreviousPage, startCursor } (endCursor is null on the last page)

Example:

const page = await sdk.fetchPools({ type: 'popular', pageSize: 20 });

page.items.forEach(pool => {
  console.log(`${pool.tokenName}: ${pool.bondingCurvePercentage}% of the curve`);
});

// Next page
const { endCursor } = page.pageInfo;
if (page.pageInfo.hasNextPage && endCursor) {
  const next = await sdk.fetchPools({ type: 'popular', pageSize: 20, cursor: endCursor });
}

// Stream filters
const upcomingShows = await sdk.fetchPools({ hasUpcomingShows: true });
const recentlyLive = await sdk.fetchPools({ recentlyStreamed: 24 }); // last 24 hours

Errors:

ValidationError: an option the backend does not accept (tokenName, type, streamStatus, pageSize, recentlyStreamed, language, search)
NetworkError: the backend answered with an error or the request failed

MCP Tool: gala_fetch_pools MCP Prompt: /galachain-launchpad:fetch-pools Demo: npm run demo:bonding:pool-discovery, npm run demo:bonding:pagination-variants

fetchAllPools(options?)

Description: Fetch ALL launchpad pools matching a filter by walking the cursor pages (100 pools per request).

Parameters:

options (optional): the filters of fetchPools (type, tokenName, search, hasUpcomingShows, language, recentlyStreamed, hasRecordings, streamStatus, isGraduated, creatorAddress), without cursor / pageSize

Returns: Promise<PoolsResult>

items: every matching PoolData
pageInfo: { hasNextPage: false, totalCount: items.length }

Example:

// Every popular pool (walks the pages)
const all = await sdk.fetchAllPools({ type: 'popular' });
console.log(`Total pools: ${all.items.length}`);

// Find a pool by name
const myPool = all.items.find(p => p.tokenName === 'anime');
if (myPool) {
  console.log(`Supply: ${myPool.circulatingSupply}`);
}

Errors:

ValidationError: tokenName is not a valid token name
NetworkError: the backend answered with an error or the request failed

MCP Tool: gala_fetch_all_pools MCP Prompt: /galachain-launchpad:fetch-all-pools Demo: npm run demo:bonding:pool-discovery

fetchTokenDistribution(tokenName)

Description: Get the complete holder distribution of a launchpad token with ownership percentages (one request, not paginated).

Parameters:

tokenName (string): Token name

Returns: Promise<TokenDistributionResult>

holders: array of { address, balance, percentage } in the order the backend returned them (balance is a decimal string; percentage is a number on a 0-100 scale)
totalSupply: string, the sum of the holders' balances
totalHolders: number of holders returned
lastUpdated: Date, when the SDK built the result

Example:

const distribution = await sdk.fetchTokenDistribution('anime');
console.log(`Total holders: ${distribution.totalHolders}`);

const top10 = [...distribution.holders]
  .sort((a, b) => b.percentage - a.percentage)
  .slice(0, 10)
  .reduce((sum, h) => sum + h.percentage, 0);
console.log(`Top 10 holders own ${top10.toFixed(2)}%`);

const whales = distribution.holders.filter(h => h.percentage > 5);
console.log(`Whales (>5%): ${whales.length}`);

Errors:

ValidationError: tokenName is empty or not a valid token name
NetworkError: the backend answered with an error (an HTTP 500 is reported as "temporarily unavailable") or the request failed

Use Cases: Whale analysis, distribution health metrics, concentration risk assessment.

MCP Tool: gala_fetch_token_distribution MCP Prompt: /galachain-launchpad:fetch-token-distribution Demo: npm run demo:bonding:pool-analysis

fetchTokenPrice({ tokenName })

Description: Get the USD spot price of a launchpad token: from its bonding curve (priced against GALA's market price), or from the swap backend's market price once it has graduated. A token by class key (GALA, GUSDC, any DEX token) is not priced here: use gswap-sdk's gSwap.market.getPrice(tokenId). Passing tokenId is refused with a ValidationError.

Parameters:

params (FetchTokenSpotPriceParams): { tokenName: string } (launchpad token name)

Returns: Promise<TokenSpotPrice> { symbol: string; price: number } (USD price per token)

Example:

const { symbol, price } = await sdk.fetchTokenPrice({ tokenName: 'anime' });
console.log(`${symbol}: $${price}/token`);

// GALA or any DEX token: gswap-sdk's market reads
const galaPrice = await gSwap.market.getPrice('GALA|Unit|none|none');

Errors:

ValidationError (INVALID_PARAMETERS): tokenId was passed
ValidationError (REQUIRED): tokenName is missing or empty
ValidationError (INVALID_RESPONSE): a graduated token has no market price
NetworkError: the bonding-curve calculation or a price read failed

MCP Tool: gala_fetch_token_spot_price MCP Prompt: /galachain-launchpad:fetch-token-spot-price Demo: npm run demo:read-only

fetchTokenDetails(tokenId)

Description: Read a token class's metadata from GalaChain.

Parameters:

tokenId (TokenId): a pipe-delimited class key string (e.g. 'GUSDC|Unit|none|eth:0x...') or a { collection, category, type, additionalKey } object

Returns: Promise<GalaChainTokenDetails> (gala-core-sdk's type)

collection, category, type, additionalKey: the class key
symbol: token symbol
name: token name
decimals: decimal places
image: icon URL
description: string
network: string
contractAddress?: string

Example:

const gala = await sdk.fetchTokenDetails('GALA|Unit|none|none');
console.log(`${gala.name} (${gala.symbol}), ${gala.decimals} decimals`);

const sameToken = await sdk.fetchTokenDetails({
  collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none',
});

Errors:

ValidationError: tokenId cannot be parsed as a class key
NetworkError: the token class was not found (status 404) or the read failed

Use Cases: Pre-trade verification, metadata enrichment.

MCP Tool: gala_fetch_token_details MCP Prompt: /galachain-launchpad:fetch-token-details Demo: npm run demo:read-only

fetchLaunchTokenFee()

Description: Get current GALA fee required to launch a new token on launchpad.

Returns: Promise<number> GALA amount required as launch fee

Example:

const launchFee = await sdk.fetchLaunchTokenFee();
console.log(`Launch fee: ${launchFee} GALA`);

// Check if the wallet has enough GALA (fetchGalaBalance returns null for a zero balance)
const balance = await sdk.fetchGalaBalance();
const available = Number(balance?.quantity ?? '0');
if (available >= launchFee) {
  console.log('Sufficient balance to launch');
} else {
  console.log(`Need ${launchFee - available} more GALA`);
}

Errors:

NetworkError: the backend answered with an error or the request failed

Note: This fee may change - always fetch fresh before launching.

MCP Tool: gala_fetch_launch_token_fee MCP Prompt: /galachain-launchpad:fetch-launch-token-fee Demo: npm run demo:read-only, npm run demo:authenticated

fetchTokenClassesWithSupply(tokenClasses)

Description: Fetch the GalaChain token classes for a list of class keys, with their supply figures.

Parameters:

tokenClasses (GalaChainTokenClassKey[]): { collection, category, type, additionalKey } objects; must not be empty

Returns: Promise<GalaChainTokenClass[]> (gala-core-sdk's type), each with the class key plus:

symbol, name, description, image, decimals, network
totalSupply, maxSupply, maxCapacity, totalBurned, totalMintAllowance (decimal strings; "Infinity" for an uncapped capacity)
knownMintSupply?, knownMintAllowanceSupply?

Example:

const [gala] = await sdk.fetchTokenClassesWithSupply([
  { collection: 'GALA', category: 'Unit', type: 'none', additionalKey: 'none' },
]);
if (gala === undefined) throw new Error('GALA token class not returned');
console.log(`GALA total supply: ${gala.totalSupply} (max ${gala.maxSupply})`);

Errors:

ValidationError: tokenClasses is empty
NetworkError: no supply data was found for the classes (status 404) or the read failed

MCP Tool: gala_fetch_token_classes_with_supply Demo: npm run demo:token-supply

fetchPoolDetails(tokenName)

Description: Get the sale (bonding curve pool) state of a launchpad token.

Parameters:

tokenName (string): Token name

Returns: Promise<PoolDetailsData>

tokenName, vaultAddress, saleOwner
saleStatus: string; isGraduated: boolean (true when saleStatus is 'Finished'); saleStartTime?: Unix seconds
maxSupply, sellingTokenQuantity (tokens left to buy), currentSupply, nativeTokenQuantity (GALA in the vault)
basePrice, euler, exponentFactor: bonding curve parameters
reverseBondingCurveMinFeePortion, reverseBondingCurveMaxFeePortion, hasReverseBondingCurveFee
reverseBondingCurveMinFeeFactor?, reverseBondingCurveMaxFeeFactor?, reverseBondingCurveNetFeeFactor?: numbers (0.5 = 50%)
nativeToken, sellingToken: class keys

Example:

const details = await sdk.fetchPoolDetails('anime');
console.log(`Current: ${details.currentSupply} / Max: ${details.maxSupply}`);
console.log(`Status: ${details.saleStatus}, graduated: ${details.isGraduated}`);

Errors:

ValidationError: tokenName is not a valid token name
NetworkError: the backend answered with an error or the request failed

MCP Tool: gala_fetch_pool_details MCP Prompt: /galachain-launchpad:fetch-pool-details Demo: npm run demo:bonding:pool-analysis

fetchPoolDetailsForCalculation(tokenName)

Description: The sale fields a local bonding curve calculation needs, with the fee factors normalized to numbers.

Parameters:

tokenName (string): Token name

Returns: Promise<{ currentSupply, remainingTokens, maxSupply, reverseBondingCurveMaxFeeFactor, reverseBondingCurveMinFeeFactor, reverseBondingCurveNetFeeFactor }>

currentSupply, remainingTokens, maxSupply: decimal strings
reverseBondingCurveMaxFeeFactor, reverseBondingCurveMinFeeFactor, reverseBondingCurveNetFeeFactor: numbers (0.5 = 50%)

Example:

// Read once, then quote locally without further requests
const pool = await sdk.fetchPoolDetailsForCalculation('anime');
const quote = await sdk.calculateSellAmount({
  tokenName: 'anime',
  amount: '1000',
  type: 'exact',
  mode: 'local',
  currentSupply: pool.currentSupply,
  maxSupply: pool.maxSupply,
  reverseBondingCurveMaxFeeFactor: pool.reverseBondingCurveMaxFeeFactor,
  reverseBondingCurveMinFeeFactor: pool.reverseBondingCurveMinFeeFactor,
});

Errors:

NetworkError: the backend answered with an error or the request failed

MCP Tool: gala_fetch_pool_details_for_calculation MCP Prompt: /galachain-launchpad:fetch-pool-details-for-calculation Demo: npm run demo:cache, npm run demo:read-only

isTokenGraduated(tokenName)

Description: Check whether a token has completed its bonding curve and graduated to DEX trading (the isGraduated flag of fetchPoolDetails).

Parameters:

tokenName (string): Token name

Returns: Promise<boolean> True if token has graduated, false if still in bonding curve

Example:

const graduated = await sdk.isTokenGraduated('anime');
if (graduated) {
  // A graduated token trades on the DEX: quote it with gswap-sdk's GSwap client
  const classKey = await sdk.resolveTokenClassKey('anime');
  const quote = await gSwap.quoting.quoteExactInput(classKey, 'GALA|Unit|none|none', '1');
} else {
  console.log('Still in bonding curve phase');
}

Errors:

ValidationError: tokenName is not a valid token name
NetworkError: the backend answered with an error or the request failed

MCP Tool: gala_is_token_graduated MCP Prompt: /galachain-launchpad:is-token-graduated Demo: npm run demo:bonding:graduation, npm run demo:read-only

Trading & Calculations

fetchVolumeData(options)

Description: Fetch the chart data points of a launchpad token over a time range.

Parameters:

options (FetchVolumeDataOptions):
- tokenName (string): Token name
- from (number): start, a Unix timestamp (at least 173000000)
- to (number): end, a Unix timestamp (at least 173000000)
- resolution (number): resolution in seconds (at least 1)

from, to and resolution are typed optional, but the method rejects a call without all three (MISSING_GRAPH_OPTIONS). They are numbers, not Dates or strings.

Returns: Promise<GraphDataResult>

dataPoints: array of candles { startTime, openPrice, highPrice, lowPrice, closePrice, volume }
isPreviousData: whether candles older than from exist
nextTime?: when the range had no candles but older ones exist, the start time of the nearest one

Example:

const now = Math.floor(Date.now() / 1000);
const { dataPoints } = await sdk.fetchVolumeData({
  tokenName: 'anime',
  from: now - 7 * 24 * 60 * 60,
  to: now,
  resolution: 3600,
});

dataPoints.forEach(point => {
  console.log(`${point.startTime}: ${point.closePrice} (volume ${point.volume})`);
});

Errors:

ValidationError: options is malformed, from/to/resolution is missing or out of range, or tokenName is not a valid token name
NetworkError: the backend answered with an error or the request failed

Use Cases: Charting, activity monitoring.

MCP Tool: gala_fetch_volume_data MCP Prompt: /galachain-launchpad:fetch-volume-data Demo: npm run demo:read-only

fetchTrades(options)

Description: Get one page of a token's trade history.

Parameters:

options (FetchTradesOptions):
- tokenName (string): Token name (required)
- cursor (string, optional): the previous page's pageInfo.endCursor
- pageSize (number, optional): default 10, capped at 20

The options type also carries tradeType, userAddress, startDate, endDate and sortOrder, but this method sends only tokenName, cursor and pageSize to the backend. To filter by user or search, use getTrades (GetTradesOptions).

Returns: Promise<TradesResult> (ListResult<TradeInfo>)

items: array of TradeInfo (id, userAddress, tradeType, tokenAmount, vaultAddress, createdAt, updatedAt, plus other fields the backend adds)
pageInfo: the backend's { hasNextPage, endCursor, hasPreviousPage, startCursor } (endCursor is null on the last page)

Example:

const page = await sdk.fetchTrades({ tokenName: 'anime', pageSize: 20 });

page.items.forEach(trade => {
  console.log(`${trade.createdAt} ${trade.tradeType}: ${trade.tokenAmount} by ${trade.userAddress}`);
});

Errors:

ValidationError: options is malformed or tokenName is empty
NetworkError: the backend answered with an error or the request failed

MCP Tool: gala_fetch_trades MCP Prompt: /galachain-launchpad:fetch-trades Demo: npm run demo:read-only

calculateBuyAmount(options)

Description: Quote a bonding-curve buy with its fee breakdown: the tokens received for a GALA spend, or the GALA cost of an exact token amount.

Parameters:

options (CalculateBuyAmountOptions):
- tokenName (string): Token name
- amount (string): Amount in decimal format (e.g. '100')
- type ('native' | 'exact'):
  - 'native': amount is the GALA to spend; the result amount is the tokens received
  - 'exact': amount is the tokens to buy; the result amount is the GALA cost
- mode ('local' | 'external', optional): per-call override. Defaults to the SDK's calculateAmountMode config, which defaults to 'local'. 'local' computes on the client; 'external' asks the launchpad backend.
- currentSupply (string, optional): supply for 'local' mode; fetched from the pool when omitted

Returns: Promise<AmountCalculationResult>

amount: the calculated amount (tokens for 'native', GALA cost for 'exact')
transactionFee: launchpad transaction fee (GALA)
gasFee: fixed gas fee ('1' GALA)
reverseBondingCurveFee: reverse bonding curve fee (GALA; '0' for a local buy quote)

Example:

// Spend 100 GALA, get how many tokens?
const quote = await sdk.calculateBuyAmount({ tokenName: 'anime', amount: '100', type: 'native' });
console.log(`100 GALA → ${quote.amount} anime tokens`);
console.log(`Transaction fee: ${quote.transactionFee} GALA`);

// Buy exactly 1000 tokens, what does it cost?
const exactQuote = await sdk.calculateBuyAmount({ tokenName: 'anime', amount: '1000', type: 'exact' });
console.log(`1000 tokens cost ${exactQuote.amount} GALA`);

Critical Note: amount in the result is the side you did not pass: tokens for 'native', GALA for 'exact'. Pass it to buy() as expectedAmount.

Errors:

ValidationError: tokenName or amount is empty, type or mode is not one of the listed values, or currentSupply is not a number
NetworkError: an 'external' quote or the supply read failed (the backend answered with an error, or the request failed)

MCP Tool: gala_calculate_buy_amount MCP Prompt: /galachain-launchpad:calculate-buy-amount Demo: npm run demo:bonding:price-impact

calculateSellAmount(options)

Description: Quote a bonding-curve sell with its fee breakdown: the GALA received for an exact token amount, or the tokens needed to receive a GALA amount.

Parameters:

options (CalculateSellAmountOptions):
- tokenName (string): Token name
- amount (string): Amount in decimal format
- type ('exact' | 'native'):
  - 'exact': amount is the tokens to sell; the result amount is the GALA received
  - 'native': amount is the GALA to receive; the result amount is the tokens needed
- mode ('local' | 'external', optional): per-call override; defaults to the SDK's calculateAmountMode config ('local')
- currentSupply, maxSupply (strings), reverseBondingCurveMaxFeeFactor, reverseBondingCurveMinFeeFactor (numbers) (optional): the pool values for 'local' mode; fetched when omitted (see fetchPoolDetailsForCalculation)

Returns: Promise<AmountCalculationResult> (same shape as calculateBuyAmount; reverseBondingCurveFee is the fee charged on the sale)

Example:

// Sell 1000 tokens, receive how much GALA?
const quote = await sdk.calculateSellAmount({ tokenName: 'anime', amount: '1000', type: 'exact' });
console.log(`1000 anime → ${quote.amount} GALA`);

// Receive 100 GALA, how many tokens must be sold?
const nativeQuote = await sdk.calculateSellAmount({ tokenName: 'anime', amount: '100', type: 'native' });
console.log(`Sell ${nativeQuote.amount} anime to get 100 GALA`);

Errors:

ValidationError: tokenName or amount is empty, type or mode is not one of the listed values, or currentSupply is not a number
NetworkError: an 'external' quote or a pool read failed

MCP Tool: gala_calculate_sell_amount MCP Prompt: /galachain-launchpad:calculate-sell-amount Demo: npm run demo:trades

calculateBuyAmountLocal(options)

Description: Quote a buy with the client-side bonding curve formula. With currentSupply given it makes no network call; without it the supply is read from the pool first.

Parameters:

options (CalculateBuyAmountLocalOptions):
- amount (string): Amount to calculate
- type ('native' | 'exact'): 'native' = GALA to spend, 'exact' = tokens to buy
- currentSupply (string, optional): current supply in circulation
- tokenName (string, optional): required when currentSupply is omitted

Returns: Promise<AmountCalculationResult> (reverseBondingCurveFee is '0')

Example:

// Pure calculation, no request: supply supplied by the caller
const quote = await sdk.calculateBuyAmountLocal({ amount: '100', type: 'native', currentSupply: '500000' });
console.log(`100 GALA → ${quote.amount} tokens`);

// Supply read from the pool
const fromPool = await sdk.calculateBuyAmountLocal({ tokenName: 'anime', amount: '1000', type: 'exact' });

Errors:

ValidationError: amount is empty, type is invalid, currentSupply is not a number, or tokenName is missing while the supply must be fetched
NetworkError: the pool read failed

Use Cases: UI previews and repeated calculations against a supply you already hold.

MCP Tool: gala_calculate_buy_amount_local MCP Prompt: /galachain-launchpad:calculate-buy-amount-local Demo: npm run demo:trades, npm run demo:read-only

calculateSellAmountLocal(options)

Description: Quote a sell with the client-side bonding curve formula.

Parameters:

options (CalculateSellAmountLocalOptions):
- amount (string): Amount to calculate
- type ('exact' | 'native'): 'exact' = tokens to sell, 'native' = GALA to receive
- currentSupply (string, optional), maxSupply (string, optional)
- reverseBondingCurveMinFeeFactor, reverseBondingCurveMaxFeeFactor (numbers, optional): 0.5 = 50%
- tokenName (string, optional): required when any of the four pool values above is omitted (they are then fetched)

Returns: Promise<AmountCalculationResult>

Example:

const pool = await sdk.fetchPoolDetailsForCalculation('anime');
const quote = await sdk.calculateSellAmountLocal({
  amount: '1000',
  type: 'exact',
  currentSupply: pool.currentSupply,
  maxSupply: pool.maxSupply,
  reverseBondingCurveMinFeeFactor: pool.reverseBondingCurveMinFeeFactor,
  reverseBondingCurveMaxFeeFactor: pool.reverseBondingCurveMaxFeeFactor,
});

Errors:

ValidationError: amount is empty, type is invalid, currentSupply is not a number, or tokenName is missing while pool values must be fetched
NetworkError: a pool read failed

MCP Tool: gala_calculate_sell_amount_local MCP Prompt: /galachain-launchpad:calculate-sell-amount-local Demo: npm run demo:trades, npm run demo:read-only

calculateBuyAmountExternal(options)

Description: Quote a buy on the launchpad backend (always a network request, no local math). getTradeQuote({ tokenName, amount, type: 'MEME' | 'NATIVE', method: 'IN' | 'OUT' }) returns the same quote with the backend's own parameters.

Parameters:

options: { tokenName: string; amount: string; type: 'native' | 'exact' } (same meaning as in calculateBuyAmount)

Returns: Promise<AmountCalculationResult>

Example:

const quote = await sdk.calculateBuyAmountExternal({ tokenName: 'anime', amount: '100', type: 'native' });
console.log(`Backend quote: 100 GALA → ${quote.amount} anime`);

Errors:

ValidationError: tokenName or amount is empty
NetworkError: the backend answered with an error, a malformed quote, or the request failed

Use Cases: Cross-checking a local quote against the backend before executing.

MCP Tool: gala_calculate_buy_amount_external MCP Prompt: /galachain-launchpad:calculate-buy-amount-external Demo: npm run demo:trades

calculateSellAmountExternal(options)

Description: Quote a sell on the launchpad backend (always a network request).

Parameters:

options: { tokenName: string; amount: string; type: 'native' | 'exact' } (same meaning as in calculateSellAmount: 'exact' = tokens to sell, 'native' = GALA to receive)

Returns: Promise<AmountCalculationResult>

Errors:

ValidationError: tokenName or amount is empty
NetworkError: the backend answered with an error, a malformed quote, or the request failed

MCP Tool: gala_calculate_sell_amount_external MCP Prompt: /galachain-launchpad:calculate-sell-amount-external Demo: npm run demo:trades

calculateBuyAmountForGraduation(tokenNameOrOptions)

Description: Quote the cost of buying all the tokens remaining in a pool (the buy that graduates it).

Parameters:

tokenNameOrOptions (string | CalculateBuyAmountForGraduationOptions): a token name, or:
- tokenName (string): Token name
- currentSupply (string, optional): supply for local mode (derived from the sale details when omitted)
- calculateAmountMode ('local' | 'external', optional): per-call mode override

Returns: Promise<GraduationCalculationResult> (an AmountCalculationResult plus):

amount: the GALA cost of the remaining tokens
remainingTokens: the token quantity that would be bought
transactionFee, gasFee, reverseBondingCurveFee: as in calculateBuyAmount

Example:

const graduation = await sdk.calculateBuyAmountForGraduation('anime');
console.log(`Graduation cost: ${graduation.amount} GALA`);
console.log(`Tokens bought: ${graduation.remainingTokens}`);

// Graduate if the wallet can pay
const balance = await sdk.fetchGalaBalance();
if (Number(balance?.quantity ?? '0') >= Number(graduation.amount)) {
  await sdk.graduateToken({ tokenName: 'anime' });
}

Errors:

ValidationError: tokenName is invalid, or the pool has no tokens remaining (already graduated)
NetworkError: a sale-details read or an 'external' quote failed

MCP Tool: gala_calculate_buy_amount_for_graduation MCP Prompt: /galachain-launchpad:calculate-graduation-cost Demo: npm run demo:bonding:graduation, npm run demo:read-only

graduateToken(options)

Description: One-step graduation: quote the cost of the remaining tokens (calculateBuyAmountForGraduation) and execute the buy with buy(). Needs a wallet, and waits for the confirmation over the WebSocket like buy().

Parameters:

options (GraduateTokenOptions):
- tokenName (string): Token name
- slippageToleranceFactor (number, optional): e.g. 0.01 = 1%; defaults to the SDK setting
- maxAcceptableReverseBondingCurveFeeSlippageFactor (number, optional)
- calculateAmountMode ('local' | 'external', optional)
- currentSupply (string, optional): supply for local mode
- privateKey (string, optional): sign with this key instead

Returns: Promise<TradeResult>

transactionId, timestamp, blockHash?, gasUsed?
type, method, tokenName, vaultAddress
inputAmount, outputAmount, totalFees, slippageTolerance?

Example:

try {
  const result = await sdk.graduateToken({ tokenName: 'anime', slippageToleranceFactor: 0.01 });
  console.log(`Graduated, transaction: ${result.transactionId}`);
} catch (error) {
  console.error(`Graduation failed: ${error instanceof Error ? error.message : error}`);
}

Preconditions:

the wallet holds enough GALA
the token is not already graduated

Errors:

ValidationError: no wallet is configured, tokenName is invalid, or the pool is already graduated
TransactionError: the submission returned no transaction id, or the bundler failed (BUNDLE_FAILED)
TransactionFailedError / WebSocketError: the chain rejected the transaction, or the WebSocket confirmation failed
NetworkError: a read or request failed

MCP Tool: gala_graduate_token MCP Prompt: /galachain-launchpad:graduate-token Demo: npm run demo:bonding:graduation

calculateInitialBuyAmount(nativeTokenQuantity)

Description: Quote the tokens received for a GALA amount at the start of the curve (supply 0): the pre-buy of a token launch.

Parameters:

nativeTokenQuantity (string): GALA amount to spend

Returns: Promise<AmountCalculationResult> Tokens received for the initial pre-buy (amount) with the fee breakdown

Example:

const initialQuote = await sdk.calculateInitialBuyAmount('1000');
console.log(`1000 GALA in pre-buy → ${initialQuote.amount} tokens`);

Errors:

ValidationError: nativeTokenQuantity is not valid pre-mint data
NetworkError: the backend answered with an error, a malformed quote, or the request failed

Notes: Only relevant when launching a token with a preBuyQuantity.

MCP Tool: gala_calculate_initial_buy MCP Prompt: /galachain-launchpad:calculate-initial-buy Demo: npm run demo:authenticated

buy(options)

Description: Execute a token purchase on the bonding curve with slippage protection. Needs a wallet; submits the bundle, then waits for the confirmation over the WebSocket.

Parameters:

options (BuyTokenOptions):
- tokenName (string): Token name
- amount (string): GALA to spend ('native') or tokens to buy ('exact')
- type ('native' | 'exact')
- expectedAmount (string): the quote's amount from calculateBuyAmount (required)
- slippageToleranceFactor (number, optional): 0.05 = 5%; defaults to the SDK setting (0.15 unless configured)
- maxAcceptableReverseBondingCurveFee (string, optional): the quote's reverseBondingCurveFee
- maxAcceptableReverseBondingCurveFeeSlippageFactor (number, optional): slippage applied to that fee
- privateKey (string, optional): sign with this key instead

Returns: Promise<TradeResult>

transactionId, timestamp, blockHash?, gasUsed?
type, method, tokenName, vaultAddress
inputAmount, outputAmount, totalFees, slippageTolerance?

Example:

// Step 1: quote
const quote = await sdk.calculateBuyAmount({ tokenName: 'anime', amount: '100', type: 'native' });

// Step 2: execute with the quote
const result = await sdk.buy({
  tokenName: 'anime',
  amount: '100',
  type: 'native',
  expectedAmount: quote.amount,                              // the quote, not the input amount
  slippageToleranceFactor: 0.01,                             // 1%
  maxAcceptableReverseBondingCurveFee: quote.reverseBondingCurveFee,
});

console.log(`Bought ${result.outputAmount} anime`);
console.log(`Transaction: ${result.transactionId}`);

Errors:

ValidationError: no wallet is configured, expectedAmount is missing (EXPECTED_AMOUNT_REQUIRED), or the token name does not resolve (TOKEN_NOT_FOUND)
TransactionError: the submission returned no transaction id, or the bundler failed (BUNDLE_FAILED)
TransactionFailedError / WebSocketError: the chain rejected the transaction (for example the price moved past the tolerance), or the WebSocket confirmation failed
NetworkError: a request failed

If the WebSocket confirmation fails, check the outcome with getBundlerTransactionResult(transactionId).

MCP Tool: gala_buy MCP Prompt: /galachain-launchpad:buy-tokens Demo: npm run demo:trades

sell(options)

Description: Execute a token sale on the bonding curve with slippage protection. Needs a wallet; waits for the confirmation like buy().

Parameters:

options (SellTokenOptions): the fields of buy(), with type ('exact' | 'native'):
- 'exact': amount is the tokens to sell; expectedAmount is the quoted GALA received
- 'native': amount is the GALA to receive; expectedAmount is the quoted tokens to sell
When maxAcceptableReverseBondingCurveFee is omitted, the SDK quotes the fee itself and adds the fee slippage factor.

Returns: Promise<TradeResult>

Example:

// Step 1: sell quote
const quote = await sdk.calculateSellAmount({ tokenName: 'anime', amount: '1000', type: 'exact' });

// Step 2: execute
const result = await sdk.sell({
  tokenName: 'anime',
  amount: '1000',
  type: 'exact',
  expectedAmount: quote.amount,
  slippageToleranceFactor: 0.01,
  maxAcceptableReverseBondingCurveFee: quote.reverseBondingCurveFee,
});

console.log(`Sold ${result.inputAmount} anime for ${result.outputAmount} GALA`);

Errors: as buy(); also ConfigurationError when no fee ceiling is given and the SDK has no quote source to derive one.

MCP Tool: gala_sell MCP Prompt: /galachain-launchpad:sell-tokens Demo: npm run demo:trades

getBundlerTransactionResult(transactionId)

Description: Look up a bundler transaction over HTTP (useful when the WebSocket confirmation of buy()/sell() failed or timed out). It does not throw for a failed lookup: the failure is in the returned object.

Parameters:

transactionId (string): the bundler transaction id

Returns: Promise<ApiResponse>

success: boolean
data: the bundler's answer for that id, when success is true (its fields are the bundler's, not typed by the SDK)
error: string, when success is false (empty id, HTTP failure, no answer)

Example:

// A trade whose WebSocket confirmation failed: look the transaction up over HTTP
async function lookUp(transactionId: string): Promise<void> {
  const answer = await sdk.getBundlerTransactionResult(transactionId);
  if (answer.success) {
    console.log('Bundler answer:', answer.data);
  } else {
    console.log(`Lookup failed: ${answer.error}`);
  }
}

MCP Tool: gala_get_bundler_transaction_result MCP Prompt: /galachain-launchpad:get-bundler-transaction-result

The DEX is gswap-sdk's

launchpad-sdk 9.0 has no DEX client: no quotes, swaps, pools, liquidity positions, fees, market prices or leaderboard. Those are @gala-chain/gswap-sdk's GSwap client. Build it from the same key as the launchpad SDK:

import { PrivateKeySigner } from '@gala-chain/gala-core-sdk';
import { GSwap } from '@gala-chain/gswap-sdk';
const gSwap = new GSwap({
  env: 'stage',
  signer: new PrivateKeySigner(process.env.PRIVATE_KEY!),
  walletAddress: sdk.getAddress(), // the launchpad SDK built with the same key
});

env is 'stage' or 'prod'; without a signer, reads work and any write throws NO_SIGNER.

The client's namespaces are gSwap.quoting, gSwap.swaps, gSwap.pools, gSwap.positions, gSwap.assets, gSwap.market and gSwap.leaderboard (plus gSwap.symbols and gSwap.fees). Every removed launchpad DEX method and the gswap-sdk call that replaces it is listed in MIGRATING-TO-9.0.md.

A launchpad token that has graduated trades on the DEX: sdk.isTokenGraduated(tokenName) tells you, and sdk.resolveTokenClassKey(tokenName) gives the class key to pass to gSwap. The MCP server's DEX tools (for example gala_get_swap_quote_exact_input and gala_execute_swap) run on gswap-sdk.

gswap-sdk documentation:

packages/gswap-sdk/README.md
packages/gswap-sdk/examples/demos/README.md: runnable DEX demos

Balance & Portfolio

fetchGalaBalance(address?)

Description: Get the GALA balance of a wallet from GalaChain.

Parameters:

address (string, optional): eth|... or 0x... address (defaults to the SDK wallet)

Returns: Promise<TokenBalanceResult | null>

quantity: decimal string, in whole GALA
collection, category, tokenId: the class (GALA|Unit|none|none)
lockedHolds?, lockedQuantity?, inUseHolds?, inUseQuantity?, availableQuantity?: present when part of the balance is locked or in use
null when the wallet has no GALA (a zero balance) or the gateway's answer is unusable

Example:

const balance = await sdk.fetchGalaBalance('eth|1234...');
const gala = Number(balance?.quantity ?? '0');
console.log(`Balance: ${gala} GALA`);

if (gala >= 100) {
  console.log('Sufficient GALA for the transaction');
}

Errors:

ValidationError: no address was given and no wallet is configured
NetworkError: the GalaChain read failed

MCP Tool: gala_fetch_gala_balance MCP Prompt: /galachain-launchpad:fetch-gala-balance Demo: npm run demo:utilities:balance, npm run demo:read-only

fetchTokenBalance(options)

Description: Get the balance of one token for a wallet. A token given by tokenId (or a known GalaChain token name such as MUSIC) is read from GalaChain with lock details; any other tokenName is a launchpad token, read from the launchpad backend without lock details.

Parameters:

options (FetchTokenBalanceOptions):
- address (string): eth|... or 0x... wallet address (required)
- tokenId (TokenId, optional): class key string or object
- tokenName (string, optional): launchpad token name (e.g. 'anime')
- withExpired (boolean, optional): include expired holds (default false)

Pass tokenId or tokenName.

Returns: Promise<TokenBalanceResult | null>: the same shape as fetchGalaBalance; null when the wallet holds none of the token.

Example:

const anime = await sdk.fetchTokenBalance({ address: 'eth|1234...', tokenName: 'anime' });
console.log(`You hold ${anime?.quantity ?? '0'} anime tokens`);

const gusdc = await sdk.fetchTokenBalance({ address: 'eth|1234...', tokenId: 'GUSDC|Unit|none|eth:0x...' });

Errors:

ValidationError: neither tokenId nor tokenName was given
NetworkError: the GalaChain or backend read failed

MCP Tool: gala_fetch_token_balance MCP Prompt: /galachain-launchpad:fetch-token-balance Demo: npm run demo:utilities:balance, npm run demo:bonding:token-launch

fetchTokensHeld(options?)

Description: Get one page of the launchpad tokens a wallet holds.

Parameters:

options (FetchTokensHeldOptions, optional):
- address (string): eth|... address (defaults to the SDK wallet)
- tokenName (string): filter by exact token name
- search (string): fuzzy search by name
- cursor (string): the previous page's pageInfo.endCursor
- pageSize (number): default 10, capped at 20

Returns: Promise<UserTokenListResult>

tokens: array of UserTokenInfo (id, name, symbol, type, address, balance, decimals, metadata?, createdAt, updatedAt, plus other fields the backend adds)
pageInfo: the backend's { hasNextPage, endCursor, hasPreviousPage, startCursor } (endCursor is null on the last page)
total?: the totalCount, when the backend sent one

Example:

const portfolio = await sdk.fetchTokensHeld({ address: 'eth|1234...', pageSize: 20 });

console.log(`Holdings on this page: ${portfolio.tokens.length}`);
portfolio.tokens.forEach(token => {
  console.log(`${token.name}: ${token.balance}`);
});

// One token by name (the smallest payload)
const anime = await sdk.fetchTokensHeld({ address: 'eth|1234...', tokenName: 'anime', pageSize: 1 });

Errors:

ValidationError: the address is not valid, or no address was given and no wallet is configured
NetworkError: the backend answered with an error or the request failed

MCP Tool: gala_fetch_tokens_held MCP Prompt: /galachain-launchpad:tokens-held Demo: npm run demo:read-only, npm run demo:wallet-tracking:balance-monitoring

fetchTokensCreated(options?)

Description: Get one page of the launchpad tokens a wallet created.

Parameters:

options (FetchTokensCreatedOptions, optional): the fields of fetchTokensHeld, plus:
- status ('all' | 'graduated' | 'active'): filter by graduation status (default all)

An exact tokenName filter is applied locally, after a backend search for that name.

Returns: Promise<UserTokenListResult>

Example:

const created = await sdk.fetchTokensCreated({ address: 'eth|1234...', status: 'active' });

created.tokens.forEach(token => {
  console.log(`${token.name} (${token.symbol})`);
});

Errors:

ValidationError: no address was given and no wallet is configured
NetworkError: the backend answered with an error or the request failed

MCP Tool: gala_fetch_tokens_created MCP Prompt: /galachain-launchpad:fetch-tokens-created Demo: npm run demo:read-only

fetchProfile(address?)

Description: Get a user's profile from the launchpad backend by wallet address (a public read).

Parameters:

address (string, optional): eth|..., 0x... or client|... address (defaults to the SDK wallet's address)

Returns: Promise<PublicUserProfile>: the backend's profile (the data of its envelope): address, nullable fullName / profileImage / bio, stats (ProfileStats), the launchBadge / successBadge / volumeBadge / engagementBadge ladders (BadgeStatus[]), isLiveStreaming and liveStreamToken.

Example:

const profile = await sdk.fetchProfile('eth|1234...');
console.log(`Name: ${profile.fullName}`);
console.log(`Image: ${profile.profileImage}`);
console.log(`Tokens created: ${profile.stats.tokensCreated}`);

Errors:

ValidationError: no address was given and no wallet is configured, or the address is not valid
NetworkError: the backend answered with an error, the request failed, or the body is not a profile

MCP Tool: gala_fetch_profile MCP Prompt: /galachain-launchpad:profile Demo: npm run demo:read-only

updateProfile(data)

Description: Update the logged-in user's profile (name and avatar). Needs a session (sdk.login()).

Parameters:

data (UpdateProfileData):
- fullName (string): 1-100 letters: a first name and an optional last name separated by one space
- profileImage (string): image URL, or an empty string to keep the current image
- address (string): the profile's wallet address (eth|... or 0x...)
- privateKey (string, optional): sign with this key instead

Returns: Promise<void>

Example:

await sdk.updateProfile({
  fullName: 'Alice Crypto',
  profileImage: 'https://example.com/avatar.png',
  address: 'eth|1234...',
});

Errors:

ValidationError: address is not valid, or fullName is not 1-100 letters (first name and optional last name)
ConfigurationError: no login session
NetworkError: the backend answered with an error or the request failed

MCP Tool: gala_update_profile MCP Prompt: /galachain-launchpad:update-profile Demo: npm run demo:privatekey-override

Token Creation & Management

launchToken(data)

Description: Create a new token on the launchpad. Needs a wallet; submits the sale, then waits for the confirmation over the WebSocket.

Parameters:

data (LaunchTokenData):
- tokenName (string): letters and digits, at least one (the rule the chain and the bundler apply)
- tokenSymbol (string): 1-8 uppercase letters
- tokenDescription (string): 1-500 characters
- tokenImage (string): image URL; get one with uploadTokenImage. The type also admits File/Buffer, but the launch sends the value as given and does not upload it.
- websiteUrl, twitterUrl, telegramUrl, instagramUrl, facebookUrl, redditUrl, tiktokUrl (string, optional): http(s) URLs
- preBuyQuantity (string, optional): GALA to pre-buy, a non-negative decimal (default '0')
- reverseBondingCurveConfiguration (optional): { minFeePortion, maxFeePortion } decimal strings
  - defaults: { minFeePortion: '0.1', maxFeePortion: '0.5' }
  - when given, both are between 0.1 and 0.5 and maxFeePortion >= minFeePortion
- tokenCategory, tokenCollection (string, optional): default 'Unit' and 'Token'
- saleStartTime (number, optional): Unix timestamp in seconds for a delayed start (a positive integer; omitted = starts immediately)
- privateKey (string, optional): sign with this key instead

Returns: Promise<TokenLaunchResult>

transactionId, timestamp, blockHash?, gasUsed?
vaultAddress, tokenStringKey
tokenName, tokenSymbol, creatorAddress
tokenImage?, preBuyQuantity?

Example:

const result = await sdk.launchToken({
  tokenName: 'mytoken',
  tokenSymbol: 'MYT',
  tokenDescription: 'My awesome token for testing',
  tokenImage: 'https://example.com/token-icon.png',
  websiteUrl: 'https://mytoken.example.com',
  twitterUrl: 'https://twitter.com/mytoken',
  telegramUrl: 'https://t.me/mytoken'
});

console.log(`✅ Token created: ${result.tokenName}`);
console.log(`Transaction: ${result.transactionId}`);

Example with Custom Bonding Curve:

const result = await sdk.launchToken({
  tokenName: 'customfee',
  tokenSymbol: 'CFT',
  tokenDescription: 'Token with custom fee structure',
  tokenImage: 'https://example.com/token-icon.png',
  websiteUrl: 'https://customfee.example.com',
  reverseBondingCurveConfiguration: {
    minFeePortion: '0.2',  // 20% minimum fee
    maxFeePortion: '0.3'   // 30% maximum fee
  }
});
// If omitted, defaults to { minFeePortion: "0.1", maxFeePortion: "0.5" }

Requirements:

the token name and symbol are not taken (check with validateToken, isTokenNameAvailable or isTokenSymbolAvailable)
the wallet holds enough GALA for the launch fee (fetchLaunchTokenFee) plus any pre-buy

Errors:

ValidationError: no wallet is configured, or a field breaks the rules above (name, symbol, description, URLs, preBuyQuantity, fee portions, saleStartTime)
LaunchpadSDKError: signing or the bundler rejected the sale; read its code (WALLET_ACCOUNT_CHANGED the wallet's selected account is not the signer's key, WALLET_USER_REJECTED the person declined in the wallet, LAUNCHPAD_SIGNING_FAILED any other signing failure, BUNDLE_FAILED, BUNDLE_REQUEST_FAILED, INVALID_BUNDLE_RESPONSE)
TransactionFailedError / WebSocketError: the chain rejected the transaction, or the WebSocket confirmation failed

MCP Tool: gala_launch_token MCP Prompt: /galachain-launchpad:launch-token Demo: npm run demo:bonding:token-launch

uploadTokenImage(options)

Description: Upload a token image and get its URL. The image is a File (browser) or a Buffer (Node.js), not a path. Needs a login session (sdk.login(), or an app session), not a wallet: an SDK built from a signer and a wallet address uploads too.

Parameters:

options (UploadImageByTokenNameOptions):
- tokenName (string): Token name (letters and digits; the route takes the name from the path)
- options (object): { file: File | Buffer }
- privateKey (string, optional): sign in as this key's wallet instead

Returns: Promise<string>: the uploaded image's URL

Example:

import { readFile } from 'node:fs/promises';

const file = await readFile('/path/to/icon.png');
const url = await sdk.uploadTokenImage({ tokenName: 'mytoken', options: { file } });
console.log(`Image uploaded: ${url}`);

// Use it in the launch
await sdk.launchToken({
  tokenName: 'mytoken',
  tokenSymbol: 'MYT',
  tokenDescription: 'My token',
  tokenImage: url,
  websiteUrl: 'https://mytoken.example.com',
});

Limits: 1 byte to 10 MB. A File must be PNG, JPG/JPEG, GIF, WebP or SVG. A Buffer is size-checked and sent as <tokenName>.png.

Errors:

ValidationError: tokenName is not letters and digits
FileValidationError: the file is empty, over 10 MB, or not an allowed type
ConfigurationError: FormData is not available in this environment
NetworkError: the upload was rejected or returned no URL

MCP Tool: gala_upload_token_image MCP Prompt: /galachain-launchpad:upload-token-image Demo: npm run demo:core:image-uploads prints the upload pattern; it does not upload a file

uploadProfileImage(options)

Description: Upload a profile image and get its URL. The image is a File or a Buffer, not a path. Needs a login session (sdk.login()).

Parameters:

options (UploadProfileImageOptions):
- file (File | Buffer): the image
- address (string, optional): validated and left out of the request (the backend uploads for the user of the session); none is invented
- privateKey (string, optional): sign in as this key's wallet instead

Returns: Promise<string>: the uploaded image's URL (an empty string if the backend returned none)

Example:

import { readFile } from 'node:fs/promises';

const url = await sdk.uploadProfileImage({ file: await readFile('/path/to/avatar.png') });
await sdk.updateProfile({
  fullName: 'Alice Crypto',
  profileImage: url,
  address: sdk.getAddress(),
});

Errors:

ValidationError: address is not valid, or the upload failed (UPLOAD_FAILED)
ConfigurationError: no login session

MCP Tool: gala_upload_profile_image MCP Prompt: /galachain-launchpad:upload-profile-image

fetchToken(tokenName)

Description: Fetch one token's pool data, with its streaming state, as a PoolData. This is how a token's stream status is read (there is no separate stream-info method).

Parameters:

tokenName (string): Token name (required)

Returns: Promise<PoolData>

identity: tokenName, symbol, description, image, vaultAddress, creatorAddress, createdAt, and the social URLs
trading: usdPrice, galaPrice, marketCapUsd, marketCapGala, volume, volume1h, galaInPool
supply and status: circulatingSupply, bondingCurvePercentage, isGraduated, isFinalized
streaming: muxPlaybackId?, muxStreamAspectRatio?, muxStreamStatus? ('IDLE' | 'ACTIVE' | 'DISABLED'), nextLiveStreamAt?, streamLanguage?
stream stats: currentViewerCount?, peakViewerCount?, streamStartedAt?, lastStreamedAt?, recordingsCount?, totalSecondsStreamed?

Example:

const pool = await sdk.fetchToken('mytoken');

console.log(`Name: ${pool.tokenName}, Symbol: ${pool.symbol}`);
console.log(`Price: $${pool.usdPrice}`);

if (pool.muxStreamStatus === 'ACTIVE') {
  console.log(`Live now: ${pool.currentViewerCount} viewers, playback ID ${pool.playbackId}`);
}
console.log(`Streaming enabled: ${pool.streamEnabled}`);

Errors:

Error ("Token not found"): no such token (the backend answered 404 or no pool)
ValidationError: tokenName is not a valid token name
NetworkError: the request failed

MCP Tool: none for a single token (gala_fetch_pools returns PoolData in lists) Demo: npm run demo:streaming

validateToken(options)

Description: Validate token name and/or symbol availability for creation or form validation.

Parameters:

options (object, at least one field required):
- tokenName (string, optional): Token name to validate (1-50 characters, any text: the availability route takes what the form types; sent lowercased)
- symbol (string, optional): Token symbol to validate (sent uppercased; not validated locally)

Returns: Promise<ValidateTokenResponse>

nameAvailable (boolean): Whether token name is available
symbolAvailable (boolean): Whether token symbol is available
nameBlocklisted (boolean): Whether name is on blocklist
symbolBlocklisted (boolean): Whether symbol is on blocklist
errors (string[]): Validation error messages

Example (Form Validation):

// Validate single field
const nameCheck = await sdk.validateToken({ tokenName: 'mytoken' });
if (nameCheck.nameAvailable && !nameCheck.nameBlocklisted) {
  console.log('✅ Name is valid and available!');
} else if (nameCheck.nameBlocklisted) {
  console.log('❌ Name is blocklisted');
} else {
  console.log('❌ Name already taken');
}

// Validate both fields
const tokenCheck = await sdk.validateToken({
  tokenName: 'mytoken',
  symbol: 'MYT'
});

if (tokenCheck.errors.length > 0) {
  console.log(`Validation errors: ${tokenCheck.errors.join(', ')}`);
}

if (tokenCheck.nameAvailable && tokenCheck.symbolAvailable) {
  console.log('✅ Ready to launch!');
}

Example (Real-time Form Input):

// Validate as the user types (call this from your input handler)
async function checkName(name: string): Promise<'available' | 'taken' | 'blocklisted' | 'too short'> {
  if (name.length < 3) return 'too short';
  const result = await sdk.validateToken({ tokenName: name });
  if (result.nameBlocklisted) return 'blocklisted';
  return result.nameAvailable ? 'available' : 'taken';
}

Validation Rules:

Token name: 1-50 characters, unique, not blocklisted (the launch itself requires letters and digits)
Symbol: unique, not blocklisted (the launch itself requires 1-8 uppercase letters)
At least one field must be provided
The backend's validation messages are returned in errors

Errors:

Error: neither tokenName nor symbol was given, or one is an empty string
ValidationError: tokenName is not 1-50 characters
NetworkError: the request failed

Use Cases:

Real-time form validation during token creation
Pre-launch availability checks

MCP Tool: gala_validate_token Demo: Not currently available

isTokenNameAvailable(tokenName)

Description: Check if token name is available for creation.

Parameters:

tokenName (string): Token name to check

Returns: Promise<boolean> True if available, false if taken. It also returns false when the check itself fails (an invalid name or a request error): it never throws. Use validateToken to tell the cases apart.

Example:

const available = await sdk.isTokenNameAvailable('mytoken');
if (available) {
  console.log('✅ Name is available!');
} else {
  console.log('❌ Name already taken');
  const alt = await sdk.isTokenNameAvailable('mytoken2');
}

MCP Tool: gala_check_token_name MCP Prompt: /galachain-launchpad:check-token-name Demo: npm run demo:bonding:token-launch, npm run demo:read-only

isTokenSymbolAvailable(symbol)

Description: Check if token symbol is available.

Parameters:

symbol (string): Token symbol (a launch needs 1-8 uppercase letters)

Returns: Promise<boolean> True if available, false if taken or if the check itself failed: it never throws.

Example:

const available = await sdk.isTokenSymbolAvailable('MYT');
if (!available) {
  console.log('Try another symbol');
}

MCP Tool: gala_check_token_symbol MCP Prompt: /galachain-launchpad:check-token-symbol Demo: npm run demo:bonding:token-launch, npm run demo:read-only

resolveTokenClassKey(tokenName)

Description: Resolve a launchpad token name to its GalaChain class key (parsed from the token's vault address). Never build the key from the name: the type is the token's symbol on chain and additionalKey is the creator's address.

Parameters:

tokenName (string): Token name

Returns: Promise<GalaChainTokenClassKey> (the type is @gala-chain/gala-core-sdk's)

collection: 'Token' for launchpad tokens
category: 'Unit'
type: the token's symbol on chain
additionalKey: eth:0x..., the creator's address

Example:

const classKey = await sdk.resolveTokenClassKey('anime');
// { collection: 'Token', category: 'Unit', type: 'ANM', additionalKey: 'eth:0x...' }

// Use it with gswap-sdk's GSwap client (see "The DEX is gswap-sdk's")
const quote = await gSwap.quoting.quoteExactInput(classKey, 'GALA|Unit|none|none', '100');

Errors:

TransferError (TOKEN_NOT_FOUND): the name is empty, unknown, or its vault address could not be read

Use Cases: Converting a token name to a class key for DEX and balance calls.

MCP Tool: gala_resolve_token_class_key MCP Prompt: /galachain-launchpad:resolve-token-class-key Demo: npm run demo:token-info:token-name-resolution, npm run demo:read-only

resolveVaultAddress(tokenName)

Description: Get the GalaChain vault address of a launchpad token (the address that holds its bonding curve pool).

Parameters:

tokenName (string): Token name

Returns: Promise<string | null> The vault address, or null when no pool matches the name

Example:

const vaultAddr = await sdk.resolveVaultAddress('anime');
console.log(`Vault: ${vaultAddr ?? 'not found'}`);

Errors:

ValidationError: tokenName is empty
NetworkError: the pool lookup failed

Use Cases: Advanced/debugging operations, direct GalaChain interactions.

MCP Tool: gala_resolve_vault_address MCP Prompt: /galachain-launchpad:resolve-vault-address Demo: npm run demo:read-only

createComment(options)

Description: Post a comment on a token's pool discussion. Needs a login session (sdk.login()).

Parameters:

options (CreateCommentOptions):
- tokenName (string): Token name (1-25 letters and digits)
- content (string): Comment text, 1-2000 characters (trimmed)

Returns: Promise<CreateCommentResult>

comment: the created WrittenComment, as the backend answers a write (id is the NUMERIC database id; messageId is the message id string every other route takes; content, userAddress, createdAt, updatedAt, user?; no tokenName)

Example:

const { comment } = await sdk.createComment({ tokenName: 'anime', content: 'Great project!' });
console.log(`Comment posted: ${comment.id}`);

Errors:

ValidationError: tokenName is not valid, or content is empty or longer than 2000 characters
ConfigurationError: no login session
NetworkError: the request failed

MCP Tool: gala_create_comment MCP Prompt: /galachain-launchpad:create-comment Demo: npm run demo:comments

getComments(options)

Description: Get one page of comments, by token or by author. A public read.

Parameters:

options (GetCommentsOptions):
- tokenName (string, optional): filter by token
- userAddress (string, optional): filter by author (eth|... or 0x...)
- cursor (string, optional): the previous page's pageInfo.endCursor
- pageSize (number, optional): default 10, at most 50

The options type documents that at least one of tokenName and userAddress is expected; the SDK does not check it before sending.

Returns: Promise<CommentsResult>

messages: array of Message (id and messageId (the same string), tokenName, tokenImage, userAddress, user and userProfile (the same { fullName, profileImage }), content, createdAt, updatedAt (null when never edited), deletedAt, flagCount, reactions: { counts, userReacted? })
pageInfo: the backend's { hasNextPage, endCursor, hasPreviousPage, startCursor } (endCursor is null on the last page)

Example:

const page = await sdk.getComments({ tokenName: 'anime', pageSize: 20 });
page.messages.forEach(comment => {
  console.log(`${comment.userAddress}: ${comment.content}`);
  console.log(`Posted: ${comment.createdAt}`);
});

Errors:

ValidationError: tokenName is not valid
NetworkError: the request failed

MCP Tool: gala_get_comments MCP Prompt: /galachain-launchpad:get-comments Demo: npm run demo:comments

Transfers

transferGala(data)

Description: Transfer GALA to another wallet. Needs a wallet.

Parameters:

data (TransferGalaData):
- recipientAddress (string): eth|... or 0x... address
- amount (string): GALA amount as a decimal string (e.g. '100.5')
- uniqueKey (string, optional): idempotency key
- privateKey (string, optional): sign with this key instead

Returns: Promise<GalaChainTransferReceipt>

transactionId: the chain transaction hash (the gateway's x-transaction-id header)
blockNumber?: the block number, when the gateway sent one

The gateway does not echo uniqueKey: keep it yourself if you need it for correlation.

Example:

const receipt = await sdk.transferGala({
  recipientAddress: 'eth|742d35Cc6634C0532925a3b8D0Ea2c76f94C31C0',
  amount: '100.5',
  uniqueKey: 'unique-key-12345',
});

console.log(`Transaction: ${receipt.transactionId}`);

Idempotency: Use uniqueKey to avoid a duplicate transfer when you retry.

Errors:

ValidationError: data is missing required fields
TransferError: the recipient address or amount is invalid, no wallet is configured (WALLET_REQUIRED), the balance is insufficient (INSUFFICIENT_BALANCE), or the gateway rejected the transfer; read its type (TransferErrorType)

MCP Tool: gala_transfer_gala MCP Prompt: /galachain-launchpad:transfer-gala Demo: npm run demo:privatekey-override

transferToken(data)

Description: Transfer a token (by class key or launchpad token name) to another wallet. Needs a wallet.

Parameters:

data (TransferTokenData):
- to (string): recipient eth|... or 0x... address
- amount (string): decimal amount
- tokenId (TokenId, optional): class key string or object
- tokenName (string, optional): launchpad token name, used when tokenId is not given
- uniqueKey (string, optional): idempotency key (generated when omitted)
- privateKey (string, optional): sign with this key instead

Pass tokenId or tokenName.

Returns: Promise<GalaChainTransferReceipt> (transactionId, blockNumber?)

Example:

const receipt = await sdk.transferToken({
  tokenName: 'anime',
  to: 'eth|742d35Cc6634C0532925a3b8D0Ea2c76f94C31C0',
  amount: '1000',
  uniqueKey: 'anime-tx-001',
});

console.log(`Sent 1000 anime: ${receipt.transactionId}`);

Errors:

ValidationError: data is missing required fields (to, amount, and tokenId or tokenName)
TransferError: invalid recipient or amount, no wallet (WALLET_REQUIRED), the token is not found (TOKEN_NOT_FOUND), the balance is insufficient, or the gateway rejected the transfer

MCP Tool: gala_transfer_token MCP Prompt: /galachain-launchpad:transfer-token Demo: npm run demo:utilities:transfers

Locks

lockTokens(data)

Description: Lock tokens on GalaChain, one or several token types in a single transaction (all or none). Locked tokens cannot be transferred until unlocked by the lock authority. Useful for staking, escrow, and vesting mechanisms. Needs a wallet.

Parameters:

data (LockTokensData):
- tokens (LockTokenEntry[], 1 to 100): each entry:
  - tokenId (TokenId) or tokenName (string): the token
  - amount (string): decimal amount to lock
  - lockAuthority (string, optional): address that can unlock (defaults to the caller)
  - expires (number, optional): expiration timestamp in epoch milliseconds
  - name (string, optional): lock name, to match at unlock
- uniqueKey (string, optional): idempotency key
- privateKey (string, optional): sign with this key instead

One transaction carries one lockAuthority, one expires and one name: the first entry that sets each one applies to the whole batch.

Returns: Promise<LockTokensResult>

transactionId?: string
blockNumber?: number
locked: array of { tokenClassKey, quantity, lockAuthority }

Example:

// Basic lock: the caller is the lock authority
await sdk.lockTokens({ tokens: [{ tokenName: 'anime', amount: '1000' }] });

// Lock with another authority and an expiry
const result = await sdk.lockTokens({
  tokens: [{
    tokenName: 'anime',
    amount: '5000',
    lockAuthority: 'eth|742d35Cc6634C0532925a3b8D0Ea2c76f94C31C0',
    expires: Date.now() + 7 * 24 * 60 * 60 * 1000, // 1 week
    name: 'escrow-deal-123',
  }],
});
console.log(`Locked ${result.locked.length} token(s): ${result.transactionId}`);

Errors:

LockError: invalid input, no wallet (WALLET_REQUIRED), the token is not found, the balance is insufficient, or the gateway rejected the lock; read its type (LockErrorType)

Use Cases:

Staking: Lock tokens for reward programs
Escrow: Third-party holds tokens until conditions met
Vesting: Time-locked token releases

MCP Tool: gala_lock_tokens MCP Prompt: /galachain-launchpad:lock-token Demo: npm run demo:locks

unlockTokens(data)

Description: Unlock previously locked tokens on GalaChain, one or several token types in a single transaction. Must be signed by the lock authority. Needs a wallet.

Parameters:

data (UnlockTokensData):
- tokens (UnlockTokenEntry[], 1 to 100): each entry:
  - tokenId (TokenId) or tokenName (string): the token
  - amount (string): decimal amount to unlock
  - name (string, optional): match a specific lock by name
- uniqueKey (string, optional): idempotency key
- privateKey (string, optional): sign with this key instead

Returns: Promise<UnlockTokensResult>

transactionId?: string
blockNumber?: number
unlocked: array of { tokenClassKey, quantity }

Example:

// Basic unlock: must be the lock authority
await sdk.unlockTokens({ tokens: [{ tokenName: 'anime', amount: '1000' }] });

// Unlock a specific named lock
await sdk.unlockTokens({
  tokens: [{ tokenName: 'anime', amount: '5000', name: 'escrow-deal-123' }],
});

Authorization: Only the lock authority (set at lock time, or the locker if none was set) can unlock.

Errors:

LockError: invalid input, no wallet (WALLET_REQUIRED), no matching lock (LOCK_NOT_FOUND), the caller is not the authority (NOT_LOCK_AUTHORITY), or the gateway rejected the unlock; read its type (LockErrorType)

MCP Tool: gala_unlock_tokens MCP Prompt: /galachain-launchpad:unlock-token Demo: npm run demo:locks

Bridgeable Token Discovery

These methods read the DEX API's token list (canBridgeTo) through gala-core-sdk's bridge module, which the app hands to the SDK and the SDK loads on the first bridge call: new LaunchpadSDK({ ..., bridge: () => import('@gala-chain/gala-core-sdk/bridge') }) (it needs ethers, @solana/web3.js and @solana/spl-token installed). Without that loader every bridge, wrap and bridgeable-token method throws a ConfigurationError (field: 'bridge') naming it. fetchAll... results and the per-token checks are cached per network for the SDK's lifetime after the first fetch.

Errors (all seven): failures reading the token list surface as gala-core-sdk's GalaSDKError (import it from @gala-chain/gala-core-sdk): TRANSPORT_ERROR (no answer), GALACONNECT_HTTP_ERROR (HTTP error status), BRIDGE_READ_RESPONSE_INVALID (not a token list) or PAGINATION_LIMIT_EXCEEDED. The isTokenBridgeable... checks refuse a tokenId that is not a class key before any read.

fetchBridgeableTokensByNetwork(options)

Description: Fetch one page of the tokens bridgeable to a network.

Parameters:

options (FetchBridgeableTokensOptions):
- network ('ETHEREUM' | 'SOLANA'): Target network
- offset (number, optional): Pagination offset (default 0)
- limit (number, optional): Results per page (default and maximum 1000)

Returns: Promise<FetchBridgeableTokensResult>

tokens: array of BridgeableToken (symbol, name, decimals, galaChainDescriptor, stringifiedTokenClassKey, verified, supportedChains, ethereumContractAddress?, solanaContractAddress?, image?, description?)
network: the queried network
tokenCount: tokens in this result
fetchedAt: timestamp (ms) of the fetch

Example:

const result = await sdk.fetchBridgeableTokensByNetwork({
  network: 'ETHEREUM',
  limit: 50,
  offset: 0
});

console.log(`Found ${result.tokenCount} Ethereum bridgeable tokens`);
result.tokens.forEach(token => {
  console.log(`${token.symbol}: ${token.ethereumContractAddress}`);
});

MCP Tool: gala_fetch_bridgeable_tokens_by_network Demo: npm run demo:bridge:bridgeable

fetchAllBridgeableTokensByNetwork(network)

Description: Fetch ALL bridgeable tokens for a network, walking the pages (1000 per request). The result is cached per network.

Parameters:

network ('ETHEREUM' | 'SOLANA'): Target network

Returns: Promise<FetchBridgeableTokensResult> All bridgeable tokens for the network

Example:

// Fetch all Ethereum bridgeable tokens
const result = await sdk.fetchAllBridgeableTokensByNetwork('ETHEREUM');
console.log(`Total Ethereum tokens: ${result.tokenCount}`);

// Find GALA token
const gala = result.tokens.find(t => t.symbol === 'GALA');
console.log(`GALA contract: ${gala?.ethereumContractAddress}`);

MCP Tool: gala_fetch_all_bridgeable_tokens_by_network Demo: npm run demo:bridge:bridgeable

fetchAllTokensBridgeableToEthereum()

Description: Convenience method to fetch all Ethereum bridgeable tokens.

Returns: Promise<FetchBridgeableTokensResult> Equivalent to fetchAllBridgeableTokensByNetwork('ETHEREUM')

Example:

const result = await sdk.fetchAllTokensBridgeableToEthereum();
console.log(`${result.tokenCount} tokens can bridge to Ethereum`);

// List tokens with contract addresses
result.tokens.forEach(token => {
  console.log(`${token.symbol}: ${token.ethereumContractAddress}`);
});

MCP Tool: gala_fetch_all_tokens_bridgeable_to_ethereum

fetchAllTokensBridgeableToSolana()

Description: Convenience method to fetch all Solana bridgeable tokens.

Returns: Promise<FetchBridgeableTokensResult> Equivalent to fetchAllBridgeableTokensByNetwork('SOLANA')

Example:

const result = await sdk.fetchAllTokensBridgeableToSolana();
console.log(`${result.tokenCount} tokens can bridge to Solana`);

// List tokens with mint addresses
result.tokens.forEach(token => {
  console.log(`${token.symbol}: ${token.solanaContractAddress}`);
});

MCP Tool: gala_fetch_all_tokens_bridgeable_to_solana

isTokenBridgeableToNetwork(options)

Description: Check if a token can be bridged to a specific network. The token is given by class key, not by symbol.

Parameters:

options (IsTokenBridgeableOptions):
- tokenId (TokenId): class key string (e.g. 'GALA|Unit|none|none') or { collection, category, type, additionalKey }
- network ('ETHEREUM' | 'SOLANA'): Target network

Returns: Promise<IsTokenBridgeableResult>

isBridgeable: boolean
network: the checked network
tokenSymbol?: the token's symbol, only when the token is in the bridgeable list
contractAddress?: the token's contract (Ethereum) or mint (Solana) address, when bridgeable

Example:

const result = await sdk.isTokenBridgeableToNetwork({
  tokenId: 'GALA|Unit|none|none',
  network: 'ETHEREUM'
});

if (result.isBridgeable) {
  console.log(`${result.tokenSymbol} can bridge to Ethereum`);
  console.log(`Contract: ${result.contractAddress}`);
} else {
  console.log('Not bridgeable to Ethereum');
}

MCP Tool: gala_is_token_bridgeable_to_network Demo: npm run demo:bridge:bridgeable

isTokenBridgeableToEthereum(tokenId)

Description: Convenience method to check Ethereum bridgeability.

Parameters:

tokenId (TokenId): class key string or object

Returns: Promise<IsTokenBridgeableResult> Equivalent to isTokenBridgeableToNetwork({ tokenId, network: 'ETHEREUM' })

Example:

const result = await sdk.isTokenBridgeableToEthereum('GALA|Unit|none|none');

if (result.isBridgeable) {
  console.log(`GALA Ethereum contract: ${result.contractAddress}`);
}

MCP Tool: gala_is_token_bridgeable_to_ethereum Demo: npm run demo:bridge:bridgeable

isTokenBridgeableToSolana(tokenId)

Description: Convenience method to check Solana bridgeability.

Parameters:

tokenId (TokenId): class key string or object

Returns: Promise<IsTokenBridgeableResult> Equivalent to isTokenBridgeableToNetwork({ tokenId, network: 'SOLANA' })

Example:

const result = await sdk.isTokenBridgeableToSolana('GALA|Unit|none|none');

if (result.isBridgeable) {
  console.log(`GALA Solana mint: ${result.contractAddress}`);
}

MCP Tool: gala_is_token_bridgeable_to_solana Demo: npm run demo:bridge:bridgeable

Price History

fetchPriceHistory, fetchAllPriceHistory and fetchGalaPrice are not LaunchpadSDK methods any more. Price series and DEX prices are gswap-sdk's market reads:

const key = await sdk.resolveTokenClassKey('anime'); // a launchpad token's class key
const series = await gSwap.market.getPriceSeries(key, '1W'); // '1D' | '1W' | '1M' | '1Y' | 'ALL'; one read answers the whole series
const gala = await gSwap.market.getPrice('GALA|Unit|none|none'); // MarketPrice | undefined

The MCP tools gala_fetch_price_history, gala_fetch_all_price_history and gala_fetch_gala_spot_price still work (they call gswap-sdk). See MIGRATING-TO-9.0.md.

Utility Methods

cleanup()

Description: Release the SDK's resources: flushes the event batcher (waiting up to 5 seconds), cleans up the HTTP interceptors and disconnects the WebSocket connections. Call it on application shutdown. It is best-effort: a failure inside it is logged, not thrown.

Returns: Promise<void>

Example:

const sdk = createLaunchpadSDK({ wallet: process.env.PRIVATE_KEY! });
try {
  // Use the SDK...
} finally {
  await sdk.cleanup();
}

LaunchpadSDK.cleanupAll() is the static form that cleans up the shared WebSocket service across instances.

MCP Tool: gala_cleanup MCP Prompt: /galachain-launchpad:cleanup Demo: most demos end with sdk.cleanup() (for example npm run demo:comments)

Live Streaming

A token's stream state (status, playback ID, viewers, next scheduled show) is read from fetchToken(tokenName): there is no separate stream-info method.

Authentication: startStream, resetStreamKey, getRecordingDownload, deleteRecording, addSimulcastTarget and removeSimulcastTarget use the logged-in session (sdk.login()), and throw a ConfigurationError without one. enableStream and disableStream use the streamAdminApiKey config when one is set and otherwise the session. setGlobalStreamingEnabled needs streamAdminApiKey (ConfigurationError without it). getSimulcastTargets uses the session too (owner-only). getStreamRecordings and getGlobalStreamingStatus are public reads. Every method taking a tokenName throws a ValidationError for a name that is not 1-255 letters and digits (the stream routes take the name from the path and check no format), and a NetworkError when the request fails.

startStream(tokenName)

Description: Start or initialize a stream for a token pool and get its ingest credentials.

Parameters:

tokenName (string): Token name (required)

Returns: Promise<StartStreamResult>

tokenName, createdAt: ISO 8601 timestamp
playbackUrl: HLS playback URL
playbackId: string
status: 'IDLE' | 'ACTIVE' | 'DISABLED' (as a string)
streamKey: string (for OBS or another encoder)
rtmpsUrl: RTMPS ingest URL
srtUrl, srtPassphrase: SRT ingest URL and passphrase

Example:

const stream = await sdk.startStream('mytoken');
console.log(`RTMPS URL: ${stream.rtmpsUrl}`);
console.log(`Stream Key: ${stream.streamKey}`);
console.log(`Playback: ${stream.playbackUrl}`);

MCP Tool: gala_start_stream MCP Prompt: /galachain-launchpad:start-stream Demo: npm run demo:streaming, npm run demo:streaming:lifecycle

resetStreamKey(tokenName)

Description: Generate a new stream key (invalidates the old key).

Parameters:

tokenName (string): Token name

Returns: Promise<ResetStreamKeyResult>: the stream credentials (streamKey, rtmpsUrl, srtUrl, srtPassphrase, playbackId, status) plus tokenName and resetAt (ISO 8601)

MCP Tool: gala_reset_stream_key MCP Prompt: /galachain-launchpad:reset-stream-key Demo: npm run demo:streaming:key-management, npm run demo:streaming:lifecycle

getStreamRecordings(options)

Description: List the recordings of a token's streams.

Parameters:

options (FetchRecordingsOptions):
- tokenName (string): Token name

The route takes no paging: the backend lists every recording of the token.

Returns: Promise<RecordingsResult>

recordings: array of StreamRecording (id (the Mux asset ID), playbackId, status, duration seconds, createdAt, masterAccess, aspectRatio?, assets?)
tokenName

Errors: a NetworkError with statusCode 404 for a token that does not exist.

Example:

const { recordings } = await sdk.getStreamRecordings({ tokenName: 'mytoken' });
console.log(`${recordings.length} recordings`);
recordings.forEach(r => console.log(`${r.id}: ${r.duration}s (${r.status})`));

MCP Tool: gala_get_stream_recordings MCP Prompt: /galachain-launchpad:get-stream-recordings Demo: npm run demo:streaming:recordings, npm run demo:streaming:recordings-management

getRecordingDownload(tokenName, assetId)

Description: Get the download state and URL of a recording's master file.

Parameters:

tokenName (string): Token name
assetId (string): the recording's id, exactly as listed (Mux asset IDs are case-sensitive)

Returns: Promise<RecordingDownloadResult>: { status: 'none' | 'preparing' | 'ready' | 'errored', url?: string } (url only when ready)

Errors: also ValidationError for an empty assetId.

MCP Tool: gala_get_recording_download MCP Prompt: /galachain-launchpad:get-recording-download Demo: npm run demo:streaming:recordings

deleteRecording(tokenName, assetId)

Description: Delete a recording permanently.

Parameters:

tokenName (string): Token name
assetId (string): the recording's id, exactly as listed

Returns: Promise<void>

Errors: also ValidationError for an empty assetId.

MCP Tool: gala_delete_recording MCP Prompt: /galachain-launchpad:delete-recording Demo: npm run demo:streaming:recordings

getSimulcastTargets(tokenName)

Description: List the configured simulcast targets.

Parameters:

tokenName (string): Token name

Returns: Promise<SimulcastTargetsResult>: { targets: SimulcastTarget[], tokenName }. A target is { id, url, status, passthrough? } (passthrough is the platform unless one was given). Owner-only: uses the logged-in session.

MCP Tool: gala_get_simulcast_targets MCP Prompt: /galachain-launchpad:get-simulcast-targets Demo: npm run demo:streaming:simulcast

addSimulcastTarget(options)

Description: Add a simulcast destination (YouTube, Twitch, Facebook or a custom RTMP endpoint).

Parameters:

options (AddSimulcastTargetOptions):
- tokenName (string): Token name
- platform ('youtube' | 'twitch' | 'facebook' | 'custom', lowercase)
- url (string): the target's RTMP or RTMPS URL, at most 2048 characters (a ValidationError for any other, SRT included)
- streamKey (string): the target's stream key, at most 255 characters
- passthrough (string, optional): free text kept with the target, at most 255 characters

Returns: Promise<AddSimulcastTargetResult>: { target: SimulcastTarget, tokenName }

MCP Tool: gala_add_simulcast_target MCP Prompt: /galachain-launchpad:add-simulcast-target Demo: npm run demo:streaming:simulcast, npm run demo:streaming:simulcast-multi-platform

removeSimulcastTarget(tokenName, targetId)

Description: Remove a simulcast target.

Parameters:

tokenName (string): Token name
targetId (string): the target's id, exactly as listed

Returns: Promise<void>

MCP Tool: gala_remove_simulcast_target MCP Prompt: /galachain-launchpad:remove-simulcast-target Demo: npm run demo:streaming:simulcast

disableStream(tokenName)

Description: Disable streaming for a token (admin API key, or the token owner's session).

Parameters:

tokenName (string): Token name

Returns: Promise<{ enabled: boolean; tokenName: string }>

MCP Tool: gala_set_stream_enabled (with enabled: false) MCP Prompt: /galachain-launchpad:disable-stream

enableStream(tokenName)

Description: Enable streaming for a token (admin API key, or the token owner's session).

Parameters:

tokenName (string): Token name

Returns: Promise<{ enabled: boolean; tokenName: string }>

MCP Tool: gala_set_stream_enabled (with enabled: true) MCP Prompt: /galachain-launchpad:enable-stream

getGlobalStreamingStatus()

Description: Get the platform-wide streaming status.

Returns: Promise<GlobalStreamingStatus>: { enabled: boolean, updatedAt?: string, updatedBy?: string }

MCP Tool: gala_get_global_streaming_status Demo: npm run demo:streaming, npm run demo:streaming:admin

setGlobalStreamingEnabled(enabled)

Description: Enable or disable streaming platform-wide (needs the streamAdminApiKey config).

Parameters:

enabled (boolean)

Returns: Promise<GlobalStreamingStatus>

MCP Tool: gala_set_global_streaming_enabled Demo: npm run demo:streaming:admin

Stream Chat

There is no platform-wide chat switch in the SDK: chat is enabled or disabled per token.

getChatMessages(options)

Description: Get one page of chat messages, by token or by author. A public read.

Parameters:

options (GetChatMessagesOptions):
- tokenName (string, optional): filter by token
- userAddress (string, optional): filter by author
- cursor (string, optional): the previous page's pageInfo.endCursor
- pageSize (number, optional): default 10, at most 50

Returns: Promise<GetChatMessagesResult>

messages: array of Message (id and messageId (the same string), tokenName, userAddress, user, content, createdAt, updatedAt, deletedAt, flagCount, reactions: { counts, userReacted? }; a list item has no holderTier)
pageInfo: the backend's { hasNextPage, endCursor, hasPreviousPage, startCursor } (endCursor is null on the last page)

Example:

const chat = await sdk.getChatMessages({ tokenName: 'mytoken', pageSize: 20 });
chat.messages.forEach(msg => console.log(`${msg.userAddress}: ${msg.content}`));

Errors:

ValidationError: tokenName is not valid
NetworkError: the request failed

MCP Tool: gala_get_chat_messages MCP Prompt: /galachain-launchpad:get-chat-messages Demo: npm run demo:chat

sendChatMessage(options)

Description: Send a chat message through the REST API. Needs a login session (sdk.login()).

Parameters:

options (CreateChatMessageOptions):
- tokenName (string): Token name (required)
- content (string): message content, 1-500 characters

Returns: Promise<CreateChatMessageResult>: { message: SentChatMessage } (messageId, tokenName, content, userAddress, createdAt, user?, holderTier?; a send carries no database id)

Errors:

ValidationError: tokenName is not valid, or content is empty or over 500 characters
ConfigurationError: no login session
NetworkError: the request failed

MCP Tool: gala_send_chat_message MCP Prompt: /galachain-launchpad:send-chat-message Demo: npm run demo:chat

getTokenConfig(tokenName)

Description: Read a token's chat and comments switches. There is no standalone chat-status method: chatEnabled and commentsEnabled of the token configuration are the chat status. A public read.

Parameters:

tokenName (string): Token name

Returns: Promise<TokenConfigData>: { chatEnabled?: boolean, commentsEnabled?: boolean, ...other configuration fields }

Example:

const config = await sdk.getTokenConfig('mytoken');
console.log(`Chat enabled: ${config.chatEnabled}`);

Errors:

ValidationError: tokenName is empty or not valid
Error: the backend returned no configuration data
NetworkError: the request failed

MCP Tool: gala_get_chat_status (reads this configuration) MCP Prompt: /galachain-launchpad:get-chat-status Demo: npm run demo:chat

disableChat(tokenName) / enableChat(tokenName)

Description: Turn chat off or on for a token. Uses the streamAdminApiKey config when set, otherwise the token owner's session. An admin disable locks the owner out of re-enabling.

Parameters:

tokenName (string): Token name

Returns: Promise<{ enabled: boolean; tokenName: string; status?: string }>

Errors:

ValidationError: tokenName is empty or not valid
ConfigurationError: neither an admin API key nor a login session is available
NetworkError: the request failed (for example the owner enabling an admin-disabled chat)

MCP Tool: gala_set_chat_enabled MCP Prompt: /galachain-launchpad:disable-chat, /galachain-launchpad:enable-chat Demo: npm run demo:chat

connectStreamWebSocket(callbacks?)

Description: Connect to the stream WebSocket server.

Parameters:

callbacks (StreamEventCallbacks, optional): global handlers, such as onStreamStatus, onViewerCount, onChatMessage, onChatStatus

Returns: Promise<void>

Example:

await sdk.connectStreamWebSocket({
  onChatMessage: event => console.log('chat:', event),
});
console.log(`Connected: ${sdk.isStreamWebSocketConnected()}`);

Sending chat over the socket also needs await sdk.authenticateStreamWebSocket().

MCP Tool: gala_connect_stream_websocket MCP Prompt: /galachain-launchpad:connect-stream-websocket Demo: npm run demo:chat:websocket

subscribeToStream(tokenName, callbacks?)

Description: Subscribe to a token's real-time stream events.

Parameters:

tokenName (string): Token name
callbacks (StreamEventCallbacks, optional): handlers for this token (onStreamStatus, onViewerCount, onChatMessage, onChatStatus, ...)

Returns: Promise<StreamSubscribedEvent>: { room, tokenName }

MCP Tool: gala_subscribe_to_stream MCP Prompt: /galachain-launchpad:subscribe-to-stream Demo: npm run demo:chat:websocket

sendStreamChatViaWebSocket(tokenName, content)

Description: Send a chat message over the WebSocket (lower latency). Returns immediately; the socket's onChatSent and onChatError callbacks report the outcome.

Parameters:

tokenName (string): Token name
content (string): message content

Returns: void

Errors:

ValidationError: tokenName or content is empty, the WebSocket is not connected (NOT_CONNECTED), or it is not authenticated (NOT_AUTHENTICATED; call authenticateStreamWebSocket())

MCP Tool: gala_send_stream_chat_via_web_socket MCP Prompt: /galachain-launchpad:send-stream-chat-websocket Demo: npm run demo:chat:websocket

unsubscribeFromStream(tokenName)

Description: Unsubscribe from a token's stream events.

Parameters:

tokenName (string): Token name

Returns: void

MCP Tool: none Demo: npm run demo:chat:websocket

disconnectStreamWebSocket()

Description: Disconnect from the stream WebSocket server.

Returns: void

MCP Tool: none Demo: npm run demo:chat:websocket

Service Clients

Note: LaunchpadSDK has two public members beyond its methods: sdk.events and sdk.launchpad. It has no DEX client (the former sdk.dex is gone: build gswap-sdk's GSwap yourself, see "The DEX is gswap-sdk's"), and no sdk.dexBackendClient or sdk.galaChainGatewayClient accessor; the SDK's internal HTTP clients are private and have no supported direct-access path.

sdk.events

Description: The SDK's EventsBatcherService: it batches client events and sends them to the launchpad backend (lazy: created on first access).

Methods:

track(eventType, payload, options?): queue an event; options is { userAddress?, tokenName?, sessionId?, immediate? }
flush(): send the queue now
getStats(): { bufferedCount, totalQueued, totalFlushed, totalDropped, ... }
configure(options): change the batching settings
shutdown(timeoutMs = 5000): flush and stop

Example:

sdk.events.track('page_view', { path: '/tokens/anime' }, { tokenName: 'anime' });
await sdk.events.flush();

sdk.launchpad

Description: LaunchpadWrites, the SDK's write surface that returns a BundleSubmission (call .wait() on it for the result) instead of waiting for the WebSocket confirmation as launchToken, buy and sell do.

Methods:

createSale(input): create a token sale (CreateSaleInput: the launchToken fields with tokenImage as a URL)
buyWithNative(input), buyExactToken(input), sellWithNative(input), sellExactToken(input): LaunchpadTradeInput is { vaultAddress, quantity, expectedAmount, extraFees?, tokenName?, uniqueKey? }

Example:

const submission = await sdk.launchpad.buyWithNative({ vaultAddress: 'client|example-token', quantity: '100', expectedAmount: '1' });
await submission.wait();

Error Reference

Common Error Types

The classes below are exported from the package (defined in src/utils/errors.ts) and are thrown by the SDK.

NetworkError (statusCode?, originalError?, and the backend's answer: serverMessage?, serverError?, details?, body?): a request failed, or the backend answered with an error

serverMessage: the body's message, the text the launchpad backend means the user to read (its error bodies are { status, error: true, message } and { statusCode, message }); an array of validation messages is joined with ,
serverError: the body's error when it is a string (the launchpad backend's error: true is not one)
details, body: the body's details, and the whole body (parsed JSON, or the text of a non-JSON answer)
A NetworkError a service builds from the HTTP client's ("Failed to ...: HTTP GET ...") keeps the answer (and, through the services' withErrorHandling wrap, the status).

import { NetworkError } from '@gala-chain/launchpad-sdk';

try {
  const result = await sdk.fetchPools();
} catch (error) {
  if (error instanceof NetworkError) {
    console.log(`Request failed (status ${error.statusCode}): ${error.serverMessage ?? error.message}`);
  }
}

ValidationError (field?, code?): an input was rejected before or after a request

await sdk.fetchPools({ tokenName: 'x' });
// → ValidationError, field 'tokenName': not a valid token name

ConfigurationError (field?): the SDK is missing something it needs (a login session, an admin key, a client)

await sdk.startStream('mytoken'); // no sdk.login() yet
// → ConfigurationError: JWT authentication required. Call sdk.login() first.

TransactionError (transactionId?, code?): a trade or launch submission produced no transaction

await sdk.buy({ tokenName: 'anime', amount: '100', type: 'native', expectedAmount: '1' });
// → TransactionError: No transaction ID returned from buy operation

TokenRestrictedError (a ValidationError subclass) and the ERROR_CODES constants are exported too, but nothing in the SDK throws TokenRestrictedError at present.

Errors of specific operations (exported from the package; read their type or code):

Class	Thrown by
`TransferError` (`TransferErrorType`)	`transferGala`, `transferToken`, `resolveTokenClassKey`
`LockError` (`LockErrorType`)	`lockTokens`, `unlockTokens`
`LaunchpadSDKError` (`code`, `status?`)	`launchToken` (signing and bundler failures)
`TransactionFailedError`, `WebSocketError`	the WebSocket confirmation of `buy`, `sell`, `graduateToken`, `launchToken`
`FileValidationError`	`uploadTokenImage`
`GalaSDKError` (from `@gala-chain/gala-core-sdk`)	the bridgeable-token reads

Version History

v9.0.0 (current): launchpad-only: no sdk.dex, no GSwap re-export, no DEX price reads; gateway-generic pieces come from @gala-chain/gala-core-sdk (see MIGRATING-TO-9.0.md)
v6.0.0: getStreamInfo() removed; streaming fields are part of fetchToken()'s PoolData
v4.0.0: fetchLaunchpadTokenSpotPrice() deprecated in favour of fetchTokenPrice()
v3.33.0: token identifiers accepted only in delimited format (the swap methods this applied to are gswap-sdk's now)
v3.25.0: GalaSwap liquidity position management (gswap-sdk's now)
v3.12.0: CommonJS build support

The full history is in CHANGELOG.md in the package root.

Quick Reference by Category

Category	Key Methods	Common Flow
Pool Discovery	fetchPools, fetchAllPools, fetchPoolDetails, fetchToken	Discovery → Details → Action
Bonding Curve Trading	calculateBuyAmount, buy, calculateSellAmount, sell, graduateToken	Quote → Execute → Verify
Balance Checking	fetchGalaBalance, fetchTokenBalance, fetchTokensHeld	Check balance → Act
Token Creation	validateToken, uploadTokenImage, launchToken	Validate → Upload → Launch
Price Data	fetchTokenPrice (launchpad tokens); gSwap.market.getPrice, gSwap.market.getPriceSeries (gswap-sdk)	Get price → Analyze → Trade
DEX (gswap-sdk)	gSwap.quoting, gSwap.swaps, gSwap.pools, gSwap.positions	see "The DEX is gswap-sdk's"

Table of Contents​

Pool Management & Discovery​

fetchPools(options?)​

fetchAllPools(options?)​

fetchTokenDistribution(tokenName)​

fetchTokenPrice({ tokenName })​

fetchTokenDetails(tokenId)​

fetchLaunchTokenFee()​

fetchTokenClassesWithSupply(tokenClasses)​

fetchPoolDetails(tokenName)​

fetchPoolDetailsForCalculation(tokenName)​

isTokenGraduated(tokenName)​

Trading & Calculations​

fetchVolumeData(options)​

fetchTrades(options)​

calculateBuyAmount(options)​

calculateSellAmount(options)​

calculateBuyAmountLocal(options)​

calculateSellAmountLocal(options)​

calculateBuyAmountExternal(options)​

calculateSellAmountExternal(options)​

calculateBuyAmountForGraduation(tokenNameOrOptions)​

graduateToken(options)​

calculateInitialBuyAmount(nativeTokenQuantity)​

buy(options)​

sell(options)​

getBundlerTransactionResult(transactionId)​

The DEX is gswap-sdk's​

Balance & Portfolio​

fetchGalaBalance(address?)​

fetchTokenBalance(options)​

fetchTokensHeld(options?)​

fetchTokensCreated(options?)​

fetchProfile(address?)​

updateProfile(data)​

Token Creation & Management​

launchToken(data)​

uploadTokenImage(options)​

uploadProfileImage(options)​

fetchToken(tokenName)​

validateToken(options)​

isTokenNameAvailable(tokenName)​

isTokenSymbolAvailable(symbol)​

resolveTokenClassKey(tokenName)​

resolveVaultAddress(tokenName)​

Social & Comments​

createComment(options)​

getComments(options)​

Transfers​

transferGala(data)​

transferToken(data)​

Locks​

lockTokens(data)​

unlockTokens(data)​

Bridgeable Token Discovery​

fetchBridgeableTokensByNetwork(options)​

fetchAllBridgeableTokensByNetwork(network)​

fetchAllTokensBridgeableToEthereum()​

fetchAllTokensBridgeableToSolana()​

isTokenBridgeableToNetwork(options)​

isTokenBridgeableToEthereum(tokenId)​

isTokenBridgeableToSolana(tokenId)​

Price History​

Utility Methods​

cleanup()​

Live Streaming​

startStream(tokenName)​

resetStreamKey(tokenName)​

getStreamRecordings(options)​

getRecordingDownload(tokenName, assetId)​

deleteRecording(tokenName, assetId)​

getSimulcastTargets(tokenName)​

addSimulcastTarget(options)​

removeSimulcastTarget(tokenName, targetId)​

disableStream(tokenName)​

enableStream(tokenName)​

getGlobalStreamingStatus()​

setGlobalStreamingEnabled(enabled)​

Stream Chat​

getChatMessages(options)​

Table of Contents

Pool Management & Discovery

fetchPools(options?)

fetchAllPools(options?)

fetchTokenDistribution(tokenName)

fetchTokenPrice({ tokenName })

fetchTokenDetails(tokenId)

fetchLaunchTokenFee()

fetchTokenClassesWithSupply(tokenClasses)

fetchPoolDetails(tokenName)

fetchPoolDetailsForCalculation(tokenName)

isTokenGraduated(tokenName)

Trading & Calculations

fetchVolumeData(options)

fetchTrades(options)

calculateBuyAmount(options)

calculateSellAmount(options)

calculateBuyAmountLocal(options)

calculateSellAmountLocal(options)

calculateBuyAmountExternal(options)

calculateSellAmountExternal(options)

calculateBuyAmountForGraduation(tokenNameOrOptions)

graduateToken(options)

calculateInitialBuyAmount(nativeTokenQuantity)

buy(options)

sell(options)

getBundlerTransactionResult(transactionId)

The DEX is gswap-sdk's

Balance & Portfolio

fetchGalaBalance(address?)

fetchTokenBalance(options)

fetchTokensHeld(options?)

fetchTokensCreated(options?)

fetchProfile(address?)

updateProfile(data)

Token Creation & Management

launchToken(data)

uploadTokenImage(options)

uploadProfileImage(options)

fetchToken(tokenName)

validateToken(options)

isTokenNameAvailable(tokenName)

isTokenSymbolAvailable(symbol)

resolveTokenClassKey(tokenName)

resolveVaultAddress(tokenName)

Social & Comments

createComment(options)

getComments(options)

Transfers

transferGala(data)

transferToken(data)

Locks

lockTokens(data)

unlockTokens(data)

Bridgeable Token Discovery

fetchBridgeableTokensByNetwork(options)

fetchAllBridgeableTokensByNetwork(network)

fetchAllTokensBridgeableToEthereum()

fetchAllTokensBridgeableToSolana()

isTokenBridgeableToNetwork(options)

isTokenBridgeableToEthereum(tokenId)

isTokenBridgeableToSolana(tokenId)

Price History

Utility Methods

cleanup()

Live Streaming

startStream(tokenName)

resetStreamKey(tokenName)

getStreamRecordings(options)

getRecordingDownload(tokenName, assetId)

deleteRecording(tokenName, assetId)

getSimulcastTargets(tokenName)

addSimulcastTarget(options)

removeSimulcastTarget(tokenName, targetId)

disableStream(tokenName)

enableStream(tokenName)

getGlobalStreamingStatus()

setGlobalStreamingEnabled(enabled)

Stream Chat

getChatMessages(options)