Integration Guide

This guide walks through integrating the XOXNO Aggregator API into an application, from fetching quotes to submitting on-chain transactions.

Prerequisites

MultiversX wallet integration (xPortal, DeFi Wallet, or Web Wallet)
Familiarity with MultiversX transaction structure
Node.js or equivalent HTTP client

Overview

The integration flow consists of three main steps:

Validate the pair — Check token support and retrieve decimal metadata
Get a quote — Fetch optimal routing and transaction data
Build, sign, and submit — Construct the transaction and broadcast it

Token Amounts

All amounts in the API are expressed in the token's smallest unit (integer, no decimals).

To convert a human-readable amount to smallest units:

function toSmallestUnits(amount, decimals) {
  // Use BigInt to avoid floating-point precision loss
  return (BigInt(Math.round(amount * 1e9)) * BigInt(10 ** decimals) / BigInt(1e9)).toString();
}

// 1 WEGLD (18 decimals) → "1000000000000000000"
toSmallestUnits(1, 18);

// 100 USDC (6 decimals) → "100000000"
toSmallestUnits(100, 6);

To convert back to a human-readable amount:

function fromSmallestUnits(amount, decimals) {
  const divisor = BigInt(10 ** decimals);
  const whole = BigInt(amount) / divisor;
  const remainder = BigInt(amount) % divisor;
  return Number(whole) + Number(remainder) / 10 ** decimals;
}

Always retrieve token decimals from the pair-config endpoint rather than hardcoding them. Pass amounts as strings (not numbers) to avoid integer overflow with large values.

Step 1: Validate the Pair

Before requesting a quote, verify that the pair is supported and retrieve decimal metadata:

const BASE_URL = 'https://swap.xoxno.com';

async function validatePair(tokenIn, tokenOut) {
  const response = await fetch(
    `${BASE_URL}/api/v1/pair-config?from=${tokenIn}&to=${tokenOut}`
  );
  const config = await response.json();

  if (!config.supported) {
    throw new Error(`Pair not supported: ${config.error}`);
  }

  return config; // { decimalsIn, decimalsOut, minAmountIn, ... }
}

Step 2: Get a Quote

async function getQuote(params) {
  const queryParams = new URLSearchParams({
    from: params.tokenIn,
    to: params.tokenOut,
    amountIn: params.amountIn,
    slippage: (params.slippage || 0.01).toString()
  });

  const response = await fetch(`${BASE_URL}/api/v1/quote?${queryParams}`);
  const data = await response.json();

  if (data.error) {
    throw new Error(data.error);
  }

  return data;
}

const quote = await getQuote({
  tokenIn: 'WEGLD-bd4d79',
  tokenOut: 'USDC-c76f1f',
  amountIn: '1000000000000000000', // 1 WEGLD in smallest units
  slippage: 0.01
});

console.log(`Expected output: ${quote.amountOutShort} USDC`);
console.log(`Minimum output: ${quote.amountOutMinShort} USDC`);
console.log(`Price impact: ${(quote.priceImpact * 100).toFixed(3)}%`);

Step 3: Build the Transaction

EGLD / WEGLD Swaps

import {
  Transaction,
  Address,
  TransactionPayload
} from '@multiversx/sdk-core';

const AGGREGATOR_CONTRACT = 'erd1qqqqqqqqqqqqqpgq...'; // Aggregator contract address

function buildSwapTransaction(quote, senderAddress) {
  return new Transaction({
    receiver: new Address(AGGREGATOR_CONTRACT),
    sender: new Address(senderAddress),
    gasLimit: calculateGasLimit(quote),
    chainID: '1',
    data: new TransactionPayload(quote.txData),
    value: quote.amountIn // Send EGLD value with the transaction
  });
}

ESDT Token Swaps

For non-native tokens, wrap the payload in an ESDTTransfer call:

function buildEsdtSwapTransaction(quote, senderAddress) {
  const tokenHex = Buffer.from(quote.from).toString('hex');
  const amountHex = BigInt(quote.amountIn).toString(16).padStart(2, '0');
  const payloadHex = Buffer.from(quote.txData).toString('hex');

  const data = `ESDTTransfer@${tokenHex}@${amountHex}@${payloadHex}`;

  return new Transaction({
    receiver: new Address(AGGREGATOR_CONTRACT),
    sender: new Address(senderAddress),
    gasLimit: calculateGasLimit(quote),
    chainID: '1',
    data: new TransactionPayload(data),
    value: '0'
  });
}

Step 4: Sign and Submit

import { ApiNetworkProvider } from '@multiversx/sdk-core';

const networkProvider = new ApiNetworkProvider('https://api.multiversx.com');

async function executeSwap(quote, wallet) {
  const tx = buildSwapTransaction(quote, wallet.address);

  const account = await networkProvider.getAccount(new Address(wallet.address));
  tx.setNonce(account.nonce);

  const signedTx = await wallet.signTransaction(tx);
  const txHash = await networkProvider.sendTransaction(signedTx);

  return txHash;
}

Gas Estimation

The API provides estimatedBuiltinCalls to assist gas estimation. Use the following formula as a baseline:

Route Type

Estimated Gas

Single-hop (1 pool)

~8M gas

Multi-hop (2–3 pools)

~16–24M gas

Split route (complex)

~50M gas

function calculateGasLimit(quote) {
  const BASE_GAS = 8_000_000;            // Base overhead
  const PER_HOP_GAS = 8_000_000;        // Per pool swap
  const PER_CALL_GAS = 5_000_000;       // Per additional SC call

  const calls = quote.estimatedBuiltinCalls || 3;

  // Generous ceiling: base + per-hop contribution + extra SC calls
  return BASE_GAS + (calls * PER_HOP_GAS) + (calls * PER_CALL_GAS);
}

For split routes with maxSplits > 4, add an additional buffer of 10–20M gas. MultiversX charges refunds on unused gas, so over-estimating is safe.

Error Handling

Retry Logic

Apply exponential backoff for transient errors (429, 503):

async function fetchWithRetry(url, options = {}, maxRetries = 3) {
  let lastError;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429 || response.status === 503) {
        // Transient — back off and retry
        const delay = 200 * Math.pow(2, attempt); // 200ms, 400ms, 800ms
        await new Promise(resolve => setTimeout(resolve, delay));
        lastError = new Error(`HTTP ${response.status}`);
        continue;
      }

      return response;
    } catch (err) {
      lastError = err;
      const delay = 200 * Math.pow(2, attempt);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  throw lastError;
}

Error Classification

class SwapError extends Error {
  constructor(type, message, details = {}) {
    super(message);
    this.type = type;
    this.details = details;
  }
}

async function safeGetQuote(params) {
  const response = await fetchWithRetry(
    `${BASE_URL}/api/v1/quote?${new URLSearchParams(params)}`
  );
  const data = await response.json();

  if (data.error) {
    if (data.error.includes('unknown token')) {
      throw new SwapError('INVALID_TOKEN', data.error);
    }
    if (data.error.includes('no path')) {
      throw new SwapError('NO_ROUTE', 'No trading route available for this pair');
    }
    if (data.error.includes('amount')) {
      throw new SwapError('INVALID_AMOUNT', data.error);
    }
    throw new SwapError('QUOTE_ERROR', data.error);
  }

  if (!response.ok) {
    throw new SwapError('HTTP_ERROR', `Request failed with status ${response.status}`);
  }

  return data;
}

See Error Reference for a complete list of error codes, HTTP status codes, and resolution guidance.

Complete Example

import {
  Transaction,
  Address,
  TransactionPayload,
  ApiNetworkProvider
} from '@multiversx/sdk-core';

const AGGREGATOR_API = 'https://swap.xoxno.com';
const AGGREGATOR_CONTRACT = 'erd1qqqqqqqqqqqqqpgq...';
const networkProvider = new ApiNetworkProvider('https://api.multiversx.com');

class XoxnoAggregator {
  async getQuote(tokenIn, tokenOut, amountIn, options = {}) {
    const params = new URLSearchParams({
      from: tokenIn,
      to: tokenOut,
      amountIn: amountIn.toString(),
      slippage: (options.slippage || 0.01).toString(),
      includePaths: (options.includePaths ?? true).toString()
    });

    const response = await fetchWithRetry(`${AGGREGATOR_API}/api/v1/quote?${params}`);
    const data = await response.json();

    if (data.error) {
      throw new Error(data.error);
    }

    return data;
  }

  async buildTransaction(quote, senderAddress) {
    const isNative = quote.from === 'EGLD' || quote.from.startsWith('WEGLD');

    const tx = new Transaction({
      receiver: new Address(AGGREGATOR_CONTRACT),
      sender: new Address(senderAddress),
      gasLimit: calculateGasLimit(quote),
      chainID: '1',
      data: new TransactionPayload(quote.txData),
      value: isNative ? quote.amountIn : '0'
    });

    const account = await networkProvider.getAccount(new Address(senderAddress));
    tx.setNonce(account.nonce);

    return tx;
  }

  async executeSwap(tokenIn, tokenOut, amountIn, wallet, options = {}) {
    const quote = await this.getQuote(tokenIn, tokenOut, amountIn, options);

    console.log(`Input:        ${quote.amountInShort} ${tokenIn}`);
    console.log(`Output:       ${quote.amountOutShort} ${tokenOut}`);
    console.log(`Min output:   ${quote.amountOutMinShort} ${tokenOut}`);
    console.log(`Price impact: ${(quote.priceImpact * 100).toFixed(3)}%`);

    const tx = await this.buildTransaction(quote, wallet.address);
    const signedTx = await wallet.signTransaction(tx);
    const txHash = await networkProvider.sendTransaction(signedTx);

    console.log(`Transaction: ${txHash}`);
    return { txHash, quote };
  }
}

// Usage
const aggregator = new XoxnoAggregator();

const result = await aggregator.executeSwap(
  'WEGLD-bd4d79',
  'USDC-c76f1f',
  '1000000000000000000',
  userWallet,
  { slippage: 0.01 }
);

Best Practices

Quote Freshness

Quotes reflect pool state at the moment of the request. Re-fetch the quote immediately before constructing the transaction to avoid executing against stale prices:

async function executeWithFreshQuote(params, wallet) {
  const quote = await getQuote(params);

  if (quote.priceImpact > 0.05) {
    throw new Error(`Price impact too high: ${(quote.priceImpact * 100).toFixed(2)}%`);
  }

  return executeSwap(quote, wallet);
}

Slippage Guidelines

Trade size (USD)

Recommended slippage

< $100

0.5%

$100 – $1,000

$1,000 – $10,000

> $10,000

High-Frequency Polling

For applications that poll prices frequently (e.g., price displays):

Use includePaths=false to reduce response payload and server-side work
Respect the 100 req/s rate limit per IP; implement a local token bucket or queue
Handle HTTP 429 with exponential backoff (see Error Handling)

Quote Endpoint — Full parameter and response reference
Pair Configuration — Token validation and decimal metadata
Error Reference — Complete error codes and resolution guidance

PreviousPair Configuration NextError Reference

Last updated 1 month ago

Was this helpful?

hashtagPrerequisites

hashtagOverview

hashtagToken Amounts

hashtagStep 1: Validate the Pair

hashtagStep 2: Get a Quote

hashtagStep 3: Build the Transaction

hashtagEGLD / WEGLD Swaps

hashtagESDT Token Swaps

hashtagStep 4: Sign and Submit

hashtagGas Estimation

hashtagError Handling

hashtagRetry Logic

hashtagError Classification

hashtagComplete Example

hashtagBest Practices

hashtagQuote Freshness

hashtagSlippage Guidelines

hashtagHigh-Frequency Polling

hashtagRelated Topics

Prerequisites

Overview

Token Amounts

Step 1: Validate the Pair

Step 2: Get a Quote

Step 3: Build the Transaction

EGLD / WEGLD Swaps

ESDT Token Swaps

Step 4: Sign and Submit

Gas Estimation

Error Handling

Retry Logic

Error Classification

Complete Example

Best Practices

Quote Freshness

Slippage Guidelines

High-Frequency Polling

Related Topics