Skip to main content

Getting Started

Install​

npm install @gala-chain/gswap-sdk @gala-chain/gala-core-sdk

These docs describe 2.0. Pin an exact version in an app build. @gala-chain/gala-core-sdk is a peer dependency (range ^1.0.0) that provides the signers and the signing, transport and wallet helpers.

The SDK supports Node.js and browser bundlers. For a server application, use PrivateKeySigner; for Gala Wallet use GalaWalletSigner; for an EIP-1193 provider such as MetaMask use BrowserWalletSigner. All three are imported from @gala-chain/gala-core-sdk.

Configure an environment​

env: 'stage' selects the staging swap backend and env: 'prod' selects the production swap backend. When env is omitted the client uses prod, so a client built without it and given a real key sends real transactions. The SDK sends every read and write through that backend. dexBackendBaseUrl overrides the preset, which is useful for tests and private deployments.

PresetBackend
stageThe staging swap backend (the preset sets dexBackendBaseUrl)
prodhttps://dex-backend-prod1.defi.gala.com

The swap backend is the only host used by the SDK; it does not call public GalaChain gateway hosts directly.

import { GSwap } from '@gala-chain/gswap-sdk';
import { PrivateKeySigner } from '@gala-chain/gala-core-sdk';

const gSwap = new GSwap({
  env: 'stage',
  signer: new PrivateKeySigner(process.env.GALACHAIN_PRIVATE_KEY!),
  walletAddress: process.env.GALACHAIN_ADDRESS,
});

walletAddress is the account's eth|<EIP-55 digits> address (or its client| alias). Swaps work without it, but confirming any liquidity write needs it (NO_WALLET_ADDRESS otherwise).

Keep private keys in environment variables or a secret manager. Never commit a key or use a production key in a test.

Read, quote, and write​

Tokens may be a registered trading symbol (GALA) or a full class key (GALA|Unit|none|none). The SDK resolves symbols and canonicalizes token ordering for the caller. Quotes are read-only and run against the backend's offline v2 engine. The examples on this page continue from the gSwap client above and run in an ES module (top-level await):

import BigNumber from 'bignumber.js'; // a dependency of the SDK; install it in your own app too

const quote = await gSwap.quoting.quoteExactInput('GALA', 'GUSDC', '100');
console.log(quote.feeTier, quote.amountOut);

// amountOutMinimum is the least you accept, not the quote: a swap is applied a few seconds after the
// quote, and a bound equal to the quote is rejected whenever the price moves in between.
const tx = await gSwap.swaps.swap('GALA', 'GUSDC', quote.feeTier, {
  exactIn: '100',
  amountOutMinimum: new BigNumber(quote.amountOut).multipliedBy('0.99').toFixed(), // 1% tolerance
});
console.log(tx.mode, tx.uniqueKey, tx.transactionId, tx.result);
const applied = await tx.confirm();
console.log(applied.result);

Swap writes are queued: tx.mode is 'queued', tx.result is undefined, and the acknowledgement means the chain accepted the request, not that it has executed. await tx.confirm() reads the applied trade or chain rejection from the durable uniqueKey; liquidity operations continue to re-read the affected position. See Transaction Status.

Browser setup​

import { GSwap } from '@gala-chain/gswap-sdk';
import { BrowserWalletSigner } from '@gala-chain/gala-core-sdk';

// `window.ethereum` is the EIP-1193 provider your wallet injects (typed by your wallet typings).
const provider = window.ethereum;
const [address] = (await provider.request({ method: 'eth_requestAccounts' })) as [string];
const gSwap = new GSwap({
  env: 'stage',
  signer: new BrowserWalletSigner(provider, address),
  walletAddress: address,
});

BrowserWalletSigner uses personal_sign. Gala Wallet integrations should use GalaWalletSigner, which uses native gala_signChainDto. There is no automatic personal-sign fallback. See Signing and Identity.

Next steps​