Integration Guide

This guide walks you through integrating the XOXNO Aggregator API into your application.

Overview

The integration flow consists of three main steps:

1. Get a Quote - Fetch optimal routing and transaction data

2. Build Transaction - Construct the transaction with user's wallet

3. Submit Transaction - Sign and broadcast to the network

Prerequisites

• MultiversX wallet integration (xPortal, DeFi Wallet, or Web Wallet)

• Understanding of MultiversX transaction structure

• Node.js/JavaScript or equivalent HTTP client

Step 1: Get a Quote

First, request a quote for the desired swap:

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

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

  const response = await fetch(`${BASE_URL}/api/v1/quote?${queryParams}`);
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || 'Quote request failed');
  }
  
  return response.json();
}

// Example usage
const quote = await getQuote({
  tokenIn: 'WEGLD-bd4d79',
  tokenOut: 'USDC-c76f1f',
  amountIn: '1000000000000000000', // 1 EGLD
  slippage: 0.01 // 1%
});

console.log(`Expected output: ${quote.amountOutShort} USDC`);
console.log(`Minimum output: ${quote.amountOutMinShort} USDC`);

Step 2: Build the Transaction

Use the quote response to construct a transaction:

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

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

function buildSwapTransaction(quote, senderAddress) {
  const isEgldSwap = quote.from === 'EGLD' || quote.from.startsWith('WEGLD');
  
  // txData is the raw payload (function + args), use directly
  const tx = new Transaction({
    receiver: new Address(AGGREGATOR_CONTRACT),
    sender: new Address(senderAddress),
    gasLimit: 50000000 + (quote.estimatedBuiltinCalls || 3) * 5000000,
    chainID: '1', // Mainnet
    data: new TransactionPayload(quote.txData)
  });

  // Set value for EGLD swaps, or use ESDT transfer for tokens
  if (isEgldSwap) {
    tx.setValue(quote.amountIn);
  }

  return tx;
}

Step 3: Handle Token Transfers

For ESDT token swaps, you need to include the token transfer:

function buildEsdtSwapTransaction(quote, senderAddress) {
  // For ESDT tokens, use ESDTTransfer format
  // txData is the raw payload, use directly in the transfer
  const esdtTransferData = `ESDTTransfer@${toHex(quote.from)}@${toHex(quote.amountIn)}@${toHex(quote.txData)}`;
  
  return new Transaction({
    receiver: new Address(AGGREGATOR_CONTRACT),
    sender: new Address(senderAddress),
    gasLimit: 50000000 + (quote.estimatedBuiltinCalls || 3) * 5000000,
    chainID: '1',
    data: new TransactionPayload(esdtTransferData),
    value: '0'
  });
}

function toHex(value) {
  if (typeof value === 'string') {
    return Buffer.from(value).toString('hex');
  }
  return BigInt(value).toString(16).padStart(2, '0');
}

Step 4: Sign and Submit

Sign the transaction using the user's wallet and submit:

async function executeSwap(quote, wallet) {
  // Build transaction
  const tx = buildSwapTransaction(quote, wallet.address);
  
  // Get account nonce
  const account = await getAccount(wallet.address);
  tx.setNonce(account.nonce);
  
  // Sign with wallet
  const signedTx = await wallet.signTransaction(tx);
  
  // Submit to network
  const txHash = await submitTransaction(signedTx);
  
  return txHash;
}

Complete Example

Here's a full working 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 fetch(`${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 isNativeToken = quote.from === 'EGLD' || quote.from.startsWith('WEGLD');
    
    const gasLimit = 50000000 + (quote.estimatedBuiltinCalls || 3) * 5000000;
    
    // txData is the raw payload (function + args), use directly
    const tx = new Transaction({
      receiver: new Address(AGGREGATOR_CONTRACT),
      sender: new Address(senderAddress),
      gasLimit: gasLimit,
      chainID: '1',
      data: new TransactionPayload(quote.txData),
      value: isNativeToken ? quote.amountIn : '0'
    });

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

    return tx;
  }

  async executeSwap(tokenIn, tokenOut, amountIn, wallet, options = {}) {
    // Step 1: Get quote
    const quote = await this.getQuote(tokenIn, tokenOut, amountIn, options);
    
    console.log('Quote received:');
    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)}%`);
    
    // Step 2: Build transaction
    const tx = await this.buildTransaction(quote, wallet.address);
    
    // Step 3: Sign transaction
    const signedTx = await wallet.signTransaction(tx);
    
    // Step 4: Submit transaction
    const txHash = await networkProvider.sendTransaction(signedTx);
    
    console.log(`Transaction submitted: ${txHash}`);
    
    return {
      txHash,
      quote
    };
  }
}

// Usage
const aggregator = new XoxnoAggregator();

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

Error Handling

Implement robust error handling for production:

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

async function safeGetQuote(params) {
  try {
    const response = await fetch(`${BASE_URL}/api/v1/quote?${new URLSearchParams(params)}`);
    const data = await response.json();
    
    if (data.error) {
      // Categorize errors
      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);
    }
    
    return data;
  } catch (error) {
    if (error instanceof SwapError) throw error;
    throw new SwapError('NETWORK_ERROR', 'Failed to connect to aggregator API');
  }
}

Best Practices

Quote Freshness

Quotes are computed in real-time and reflect current pool states. For best execution:

// Re-fetch quote just before execution
async function executeWithFreshQuote(params, wallet) {
  const quote = await getQuote(params);
  
  // Check if quote is acceptable
  if (quote.priceImpact > 0.05) { // 5%
    throw new Error('Price impact too high');
  }
  
  // Execute immediately after getting quote
  return executeSwap(quote, wallet);
}

Gas Estimation

The API provides estimatedBuiltinCalls to help estimate gas:

function calculateGasLimit(quote) {
  const baseGas = 50000000; // 50M base
  const perCallGas = 5000000; // 5M per SC call
  const calls = quote.estimatedBuiltinCalls || 3;
  
  return baseGas + (calls * perCallGas);
}

Slippage Protection

Always set appropriate slippage based on trade size:

function recommendedSlippage(amountInUsd) {
  if (amountInUsd < 100) return 0.005; // 0.5%
  if (amountInUsd < 1000) return 0.01; // 1%
  if (amountInUsd < 10000) return 0.02; // 2%
  return 0.03; // 3% for large trades
}

Next Steps

• Response Format - Detailed response structure

• Relayer WebSocket - Real-time transaction tracking