@wowmax/sdk

TypeScript client for the WOWMAX Open Aggregation API — non-custodial DEX & bridge routing across 20+ chains, including Stellar (synthetic chain id 100000148).

• Typed quote / swap / token / price endpoints
• Non-custodial — buildSwap returns an unsigned transaction (EVM calldata or a Stellar XDR). The SDK never holds keys, signs, or submits.
• Zero dependencies — uses the global fetch (Node.js ≥ 18 or any modern browser). Works in backends, browsers, and edge runtimes.

Quickstart (≈ 5 minutes)

1. Install

npm install @wowmax/sdk

2. Create a client

import { WowmaxClient, STELLAR_CHAIN_ID } from '@wowmax/sdk';

const wowmax = new WowmaxClient();
// Defaults to https://api-gateway.wowmax.exchange.
// Pass { baseUrl, apiKey, timeoutMs, fetch } to override.

3. Get a quote

Format note (important): the request amount is human-readable ('100' = 100 XLM, '1.5' = 1.5 ETH), but the response amountOut comes back in base units (stroops / wei). Use fromBaseUnits(amount, decimals) to display it — to.decimals is on the quote. Token ids on Stellar are native (XLM) or CODE:ISSUER.

import { WowmaxClient, STELLAR_CHAIN_ID, fromBaseUnits } from '@wowmax/sdk';

const wowmax = new WowmaxClient();

// 100 XLM -> USDC on Stellar
const quote = await wowmax.getQuote(STELLAR_CHAIN_ID, {
  from: 'native',
  to: 'USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
  amount: '100',
});

console.log('amountOut (base units):', quote.amountOut); // e.g. '189691892'
console.log('amountOut (human):', fromBaseUnits(quote.amountOut, quote.to.decimals)); // '18.9691892'
console.log('price impact:', quote.priceImpact);

4. Build an UNSIGNED swap

buildSwap needs the account that will sign and send. The response is an unsigned transaction — the SDK does not sign it.

const tx = await wowmax.buildSwap(STELLAR_CHAIN_ID, {
  from: 'native',
  to: 'USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN',
  amount: '100',
  account: 'G...your-stellar-public-key',
  slippage: 0.5, // percent
});

// Stellar -> sign this XDR with the user's wallet:
console.log(tx.transactionXdr, tx.networkPassphrase, tx.kind);

5. Sign & submit with your own wallet

The SDK stops at the unsigned payload. You sign and broadcast — for example:

Stellar (with @stellar/stellar-sdk + the user's secret, or a wallet kit):

import { TransactionBuilder, Networks, Keypair, Horizon } from '@stellar/stellar-sdk';

const txEnvelope = TransactionBuilder.fromXDR(tx.transactionXdr!, tx.networkPassphrase!);
txEnvelope.sign(Keypair.fromSecret(process.env.STELLAR_SECRET!));
const horizon = new Horizon.Server('https://horizon.stellar.org');
await horizon.submitTransaction(txEnvelope);

EVM — buildSwap returns { contract, data, value }; sign and send with ethers/viem/wallet:

const quote = await wowmax.getQuote(1, {
  from: '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', // native ETH
  to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',   // USDC
  amount: '1', // 1 ETH
});

const tx = await wowmax.buildSwap(1, { ...sameParams, account: '0xYourAddress' });
// signer.sendTransaction({ to: tx.contract, data: tx.data, value: tx.value })

That's the whole loop: quote → build unsigned tx → sign with your wallet → broadcast.

API

new WowmaxClient(options?: {
  baseUrl?: string;     // default https://api-gateway.wowmax.exchange
  apiKey?: string;      // sent as X-API-KEY when set
  timeoutMs?: number;   // default 15000
  fetch?: typeof fetch; // custom fetch for runtimes without a global one
})

| Method | Returns | | --- | --- | | getChains() | supported chains | | getTokens(chainId) | tradable tokens on a chain | | getToken(chainId, address) | a single token | | getQuote(chainId, params) | best-output quote (amountOut in base units) | | buildSwap(chainId, params) | unsigned transaction (EVM calldata or Stellar XDR) | | getPrices(chainId) | token USD prices | | fromBaseUnits(value, decimals) | base-unit string → human-readable decimal string |

params: { from, to, amount, account?, network?, slippage? }. account is required for buildSwap. Non-2xx responses throw WowmaxApiError carrying { status, url, body }.

Constants

• STELLAR_CHAIN_ID = 100000148
• DEFAULT_BASE_URL = https://api-gateway.wowmax.exchange

Non-custodial guarantee

@wowmax/sdk is a routing client only. It returns unsigned transactions and never sees private keys, signs, or submits. Key custody and broadcast stay entirely with the integrator and the end user.

License

MIT © WOWMAX