Skip to main content

Agent guide: launchpad-sdk

This page is for an AI agent (or a developer working with one) that writes code against @gala-chain/launchpad-sdk, the client of the Gala Launchpad backend: pools, bonding-curve buys and sells, token creation, balances, transfers and real-time events. Every recipe compiles against the package's built types (the docs build fails otherwise), and every invariant names the test that enforces it.

Which package for which job​

JobPackage
Launchpad pools, buy and sell on the bonding curve, create a token, balances, transfers@gala-chain/launchpad-sdk (this package)
Trade a token after it graduates to the DEX, quotes, liquidity@gala-chain/gswap-sdk (this package has no DEX client)
Signers, wallet providers, bridge, plain gateway reads and writes@gala-chain/gala-core-sdk (the peer dependency of this package)
The same abilities as MCP tools (GALA_TOOLSETS=core,launchpad)@gala-chain/gala-mcp-server

Install with npm install @gala-chain/launchpad-sdk@next and the peers next to it (core range >=1.0.0-rc.7 <2).

Recipes​

Read pools without a wallet​

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

const sdk = createLaunchpadSDK({ env: 'stage' });
const recent = await sdk.fetchPools({ type: 'recent', pageSize: 10 });
for (const pool of recent.items) console.log(pool.tokenName, pool.symbol);

Quote and buy a bonding-curve token​

Quote first: the quote's amount and reverse-fee bound go into the buy so the transaction carries slippage protection.

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

const sdk = createLaunchpadSDK({ env: 'stage', wallet: process.env.WALLET_PRIVATE_KEY! });
const quote = await sdk.calculateBuyAmount({ tokenName: 'anime', amount: '100', type: 'native' });
const result = await sdk.buy({
  tokenName: 'anime',
  amount: '100',
  type: 'native',
  expectedAmount: quote.amount,
  maxAcceptableReverseBondingCurveFee: quote.reverseBondingCurveFee,
  slippageToleranceFactor: 0.01,
});
console.log(result.transactionId, result.outputAmount);

Quote and sell​

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

const sdk = createLaunchpadSDK({ env: 'stage', wallet: process.env.WALLET_PRIVATE_KEY! });
const quote = await sdk.calculateSellAmount({ tokenName: 'anime', amount: '100', type: 'exact' });
const result = await sdk.sell({
  tokenName: 'anime',
  amount: '100',
  type: 'exact',
  expectedAmount: quote.amount,
  maxAcceptableReverseBondingCurveFee: quote.reverseBondingCurveFee,
  slippageToleranceFactor: 0.01,
});
console.log(result.transactionId, result.outputAmount);

Create a token​

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

const sdk = createLaunchpadSDK({ env: 'stage', wallet: process.env.WALLET_PRIVATE_KEY! });
const available = (await sdk.isTokenNameAvailable('anime')) && (await sdk.isTokenSymbolAvailable('ANIME'));
if (!available) throw new Error('Name or symbol is taken');
const fee = await sdk.fetchLaunchTokenFee();
console.log('launch fee:', fee);
const created = await sdk.launchToken({
  tokenName: 'anime',
  tokenSymbol: 'ANIME',
  tokenDescription: 'Example token',
  tokenImage: 'https://example.test/anime.png',
});
console.log(created.transactionId);

Write through the bundler and wait for it​

The sdk.launchpad writes are submitted to the bundler: the submission exposes bundleId, uniqueKey and wait(). Acknowledgement is not confirmation: wait() resolves when the bundle is applied.

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

const sdk = createLaunchpadSDK({ env: 'stage', wallet: process.env.WALLET_PRIVATE_KEY! });
const submission = await sdk.launchpad.buyWithNative({
  vaultAddress: 'client|example-token',
  quantity: '1',
  expectedAmount: '1',
});
const result = await submission.wait();
console.log(submission.bundleId, submission.uniqueKey, result);

Transfer GALA​

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

const sdk = createLaunchpadSDK({ env: 'stage', wallet: process.env.WALLET_PRIVATE_KEY! });
const { transactionId, blockNumber } = await sdk.transferToken({
  to: 'eth|9876543210987654321098765432109876543210',
  tokenId: 'GALA|Unit|none|none',
  amount: '1',
});
console.log(transactionId, blockNumber);

After a token graduates, trade it with @gala-chain/gswap-sdk using its class key, not with buy.

Invariants​

  • A launchpad token name is 1 to 25 letters and digits: the DTO schema refuses an empty name, a longer one and any other character (a pipe-delimited class key is not a name). Enforced by packages/launchpad-sdk/tests/dto-token-name-schema.test.ts ("refuses 26 characters with the cap in the message, and an empty or non-alphanumeric name").
  • A token sale's pre-buy is signed as a plain decimal string in the canonical spelling the chain parses. Enforced by packages/launchpad-sdk/tests/create-sale-preflight.test.ts ("signs a plain decimal pre-buy in the canonical spelling the chain parses").
  • A user address is eth|<EIP-55 checksummed 40 hex digits> (or a client| alias): every Ethereum spelling is converted to it. Enforced by packages/launchpad-sdk/tests/user_identity_wire.test.ts ("sends every Ethereum spelling as eth|").
  • eth|0x<hex> is REFUSED with a ValidationError naming the field and the correct spelling, before anything is signed or sent; a bare 0x<40 hex> is converted. Enforced by packages/launchpad-sdk/tests/user_identity_wire.test.ts ("refuses eth|0x, a wrong checksum, partial and foreign spellings with a ValidationError naming the field").
  • A bundle write signs a uniqueKey with the galaswap-operation- prefix and at most 64 characters, with no spaces. Enforced by packages/launchpad-sdk/tests/bundle-service-trading.test.ts ("signs a uniqueKey matching the galaswap-operation- prefix and length constraint").
  • A bundle submission's wait() is the confirmation: a failed confirmation read does not end a wait the socket can still settle, and a wait that never settles ends at its deadline naming the last failure. Enforced by packages/launchpad-sdk/tests/bundle-wait-resilience.test.ts ("BundleSubmission.wait: a failed confirmation read does not end a wait the socket can settle") and packages/launchpad-sdk/tests/bundle-wait-resilience.test.ts ("a read failure ends the wait only at the deadline, with the last failure named in the timeout error").
  • A client built without a wallet refuses to buy and to sell (the call throws; the read methods keep working). Enforced by packages/launchpad-sdk/tests/launchpad-sdk-methods.test.ts ("should require wallet").

Errors​

The SDK throws typed errors (ValidationError, ConfigurationError, NetworkError and the others exported by the package); branch on the class or on error.code, never on message text. A signing or transport failure of a gateway write is a core GalaSDKError with a catalog code, listed at /errors.json.

FailureMeaningFix
ValidationError naming a fieldAn input failed the SDK's checks before anything was sent.Correct the named field; nothing was submitted.
ValidationError('WALLET_REQUIRED')A write was attempted on a client with no wallet.Build the client with wallet (or setWallet).
ConfigurationError naming bridgeA bridge or wrap method was called without the bridge loader option.Pass bridge: () => import('@gala-chain/gala-core-sdk/bridge').
Bundle wait() timeoutThe bundle was submitted but its confirmation was not seen in time.Read the submission's uniqueKey status again; do not submit a second bundle.