JavaScript / TypeScript

Complete JavaScript/TypeScript integration guide with ethers.js

This guide shows how to integrate DexAggregator API in JavaScript/TypeScript applications using ethers.js.

Prerequisites

npm install ethers@^6.0.0
# or
yarn add ethers@^6.0.0

Quick Setup

1. Install Dependencies

{
  "dependencies": {
    "ethers": "^6.10.0"
  }
}

2. Create DexAggregator Client

// dexAggregatorClient.ts
import { ethers } from 'ethers';

export class DexAggregatorClient {
  private apiUrl: string;
  private provider: ethers.Provider;
  private wallet: ethers.Wallet;

  constructor(
    apiUrl: string,
    rpcUrl: string,
    privateKey: string
  ) {
    this.apiUrl = apiUrl;
    this.provider = new ethers.JsonRpcProvider(rpcUrl);
    this.wallet = new ethers.Wallet(privateKey, this.provider);
  }

  // Build route using API
  async buildRoute(params: BuildRouteParams): Promise<RouteResponse> {
    const response = await fetch(`${this.apiUrl}/api/v1/route/build`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(params),
    });

    const data = await response.json();

    if (data.code !== 0) {
      throw new Error(`API Error: ${data.message}`);
    }

    return data.data;
  }

  // Execute swap
  async executeSwap(
    routeData: RouteResponse,
    orderId: string
  ): Promise<ethers.TransactionReceipt> {
    // 1. Approve token if needed
    if (routeData.value === '0') {
      await this.approveToken(
        routeData.tokenIn,
        routeData.aggregatorAddress,
        routeData.amountIn
      );
    }

    // 2. Execute swap
    const aggregatorABI = [
      'function smartSwapByOrderId(bytes32 orderId, address executor, bytes calldata data) external payable',
    ];

    const aggregator = new ethers.Contract(
      routeData.aggregatorAddress,
      aggregatorABI,
      this.wallet
    );

    const tx = await aggregator.smartSwapByOrderId(
      orderId,
      routeData.executorAddress,
      routeData.executorData,
      {
        value: routeData.value,
        gasLimit: routeData.gas,
      }
    );

    console.log(`Transaction sent: ${tx.hash}`);
    const receipt = await tx.wait();
    console.log(`Transaction confirmed in block ${receipt.blockNumber}`);

    return receipt;
  }

  // Approve ERC20 token
  private async approveToken(
    tokenAddress: string,
    spender: string,
    amount: string
  ): Promise<void> {
    const erc20ABI = [
      'function approve(address spender, uint256 amount) external returns (bool)',
      'function allowance(address owner, address spender) external view returns (uint256)',
    ];

    const token = new ethers.Contract(tokenAddress, erc20ABI, this.wallet);

    // Check current allowance
    const currentAllowance = await token.allowance(
      this.wallet.address,
      spender
    );

    if (BigInt(currentAllowance) >= BigInt(amount)) {
      console.log('Token already approved');
      return;
    }

    // Approve
    console.log('Approving token...');
    const approveTx = await token.approve(spender, amount);
    await approveTx.wait();
    console.log('Token approved');
  }

  // Get contract addresses
  async getContracts(chain: string) {
    const response = await fetch(
      `${this.apiUrl}/api/v1/contracts?chain=${chain}`
    );
    return response.json();
  }

  // Health check
  async healthCheck() {
    const response = await fetch(`${this.apiUrl}/health`);
    return response.json();
  }
}

// Types
export interface BuildRouteParams {
  chain: string;
  tokenIn: string;
  tokenOut: string;
  amountIn: string;
  sender: string;
  recipient: string;
  slippageTolerance?: number;
  deadline?: number;
  includedSources?: string[];
  gasPrice?: string;
}

export interface RouteResponse {
  tokenIn: string;
  tokenOut: string;
  amountIn: string;
  amountOut: string;
  minAmountOut: string;
  gas: string;
  gasPrice: string;
  gasUsd: number;
  amountInUsd: number;
  amountOutUsd: number;
  aggregatorAddress: string;
  executorAddress: string;
  executorData: string;
  value: string;
  swapType: string;
  routeInfo: any;
}

Complete Example: Swap WBNB to USDT

// example.ts
import { ethers } from 'ethers';
import { DexAggregatorClient } from './dexAggregatorClient';

async function main() {
  // Initialize client
  const client = new DexAggregatorClient(
    'http://localhost:8081',
    'https://bsc-dataseed1.binance.org',
    process.env.PRIVATE_KEY!
  );

  // Check health
  const health = await client.healthCheck();
  console.log('API Status:', health.status);

  // Build route
  const routeData = await client.buildRoute({
    chain: 'bsc',
    tokenIn: '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c', // WBNB
    tokenOut: '0x55d398326f99059fF775485246999027B3197955', // USDT
    amountIn: ethers.parseEther('0.1').toString(), // 0.1 WBNB
    sender: await client.wallet.getAddress(),
    recipient: await client.wallet.getAddress(),
    slippageTolerance: 50, // 0.5%
  });

  console.log('Route found:');
  console.log(`  Swap Type: ${routeData.swapType}`);
  console.log(`  Expected Output: ${ethers.formatUnits(routeData.amountOut, 18)} USDT`);
  console.log(`  Min Output: ${ethers.formatUnits(routeData.minAmountOut, 18)} USDT`);
  console.log(`  Gas: ${routeData.gas}`);

  // Generate order ID (use your own logic)
  const orderId = ethers.keccak256(
    ethers.toUtf8Bytes(`order-${Date.now()}`)
  );

  // Execute swap
  const receipt = await client.executeSwap(routeData, orderId);
  console.log(`✅ Swap successful! TX: ${receipt.hash}`);
}

main().catch(console.error);

Advanced Features

1. Price Comparison

async function comparePrices(
  client: DexAggregatorClient,
  tokenIn: string,
  tokenOut: string,
  amount: string
) {
  const routes = await Promise.all([
    client.buildRoute({
      chain: 'bsc',
      tokenIn,
      tokenOut,
      amountIn: amount,
      sender: '0xYourAddress',
      recipient: '0xYourAddress',
      includedSources: ['pancake', 'pancake-v3'],
    }),
    client.buildRoute({
      chain: 'bsc',
      tokenIn,
      tokenOut,
      amountIn: amount,
      sender: '0xYourAddress',
      recipient: '0xYourAddress',
      includedSources: ['uniswap', 'uniswapv3'],
    }),
  ]);

  const bestRoute = routes.reduce((best, current) =>
    BigInt(current.amountOut) > BigInt(best.amountOut) ? current : best
  );

  return bestRoute;
}

2. Slippage Monitor

async function checkSlippage(routeData: RouteResponse) {
  const expectedOutput = BigInt(routeData.amountOut);
  const minOutput = BigInt(routeData.minAmountOut);
  const slippage = Number((expectedOutput - minOutput) * 10000n / expectedOutput) / 100;

  console.log(`Slippage Protection: ${slippage.toFixed(2)}%`);

  if (slippage > 1.0) {
    console.warn('⚠️ High slippage detected!');
  }
}

3. Retry Logic with Exponential Backoff

async function buildRouteWithRetry(
  client: DexAggregatorClient,
  params: BuildRouteParams,
  maxRetries = 3
): Promise<RouteResponse> {
  let lastError: Error;

  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.buildRoute(params);
    } catch (error) {
      lastError = error as Error;
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      console.log(`Retry ${i + 1}/${maxRetries} after ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  throw lastError!;
}

4. Gas Price Optimization

import { ethers } from 'ethers';

async function getOptimalGasPrice(provider: ethers.Provider): Promise<string> {
  const feeData = await provider.getFeeData();

  // Use 110% of current gas price for faster confirmation
  const gasPrice = (feeData.gasPrice! * 110n) / 100n;

  return gasPrice.toString();
}

// Usage
const gasPrice = await getOptimalGasPrice(client.provider);
const routeData = await client.buildRoute({
  // ... other params
  gasPrice,
});

5. Transaction Monitoring

async function monitorTransaction(
  provider: ethers.Provider,
  txHash: string
): Promise<void> {
  console.log(`Monitoring transaction: ${txHash}`);

  provider.on(txHash, (tx) => {
    console.log('Transaction mined:', tx);
  });

  const receipt = await provider.waitForTransaction(txHash, 2); // 2 confirmations

  if (receipt?.status === 1) {
    console.log('✅ Transaction successful');
  } else {
    console.log('❌ Transaction failed');
  }
}

React Integration

Custom Hook

// useSwap.ts
import { useState } from 'react';
import { DexAggregatorClient, RouteResponse } from './dexAggregatorClient';

export function useSwap(client: DexAggregatorClient) {
  const [loading, setLoading] = useState(false);
  const [route, setRoute] = useState<RouteResponse | null>(null);
  const [error, setError] = useState<string | null>(null);

  const buildRoute = async (params: BuildRouteParams) => {
    setLoading(true);
    setError(null);

    try {
      const data = await client.buildRoute(params);
      setRoute(data);
      return data;
    } catch (err) {
      const message = err instanceof Error ? err.message : 'Unknown error';
      setError(message);
      throw err;
    } finally {
      setLoading(false);
    }
  };

  const executeSwap = async (orderId: string) => {
    if (!route) throw new Error('No route available');

    setLoading(true);
    try {
      const receipt = await client.executeSwap(route, orderId);
      return receipt;
    } catch (err) {
      const message = err instanceof Error ? err.message : 'Unknown error';
      setError(message);
      throw err;
    } finally {
      setLoading(false);
    }
  };

  return { buildRoute, executeSwap, loading, route, error };
}

Component Example

// SwapComponent.tsx
import React, { useState } from 'react';
import { ethers } from 'ethers';
import { useSwap } from './useSwap';

export function SwapComponent({ client }) {
  const { buildRoute, executeSwap, loading, route, error } = useSwap(client);
  const [amount, setAmount] = useState('1.0');

  const handleSwap = async () => {
    // Build route
    await buildRoute({
      chain: 'bsc',
      tokenIn: '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c',
      tokenOut: '0x55d398326f99059fF775485246999027B3197955',
      amountIn: ethers.parseEther(amount).toString(),
      sender: await client.wallet.getAddress(),
      recipient: await client.wallet.getAddress(),
      slippageTolerance: 50,
    });
  };

  const handleExecute = async () => {
    const orderId = ethers.keccak256(
      ethers.toUtf8Bytes(`order-${Date.now()}`)
    );
    await executeSwap(orderId);
  };

  return (
    <div>
      <input
        type="number"
        value={amount}
        onChange={(e) => setAmount(e.target.value)}
        placeholder="Amount"
      />

      <button onClick={handleSwap} disabled={loading}>
        Get Quote
      </button>

      {route && (
        <div>
          <p>Expected Output: {ethers.formatUnits(route.amountOut, 18)}</p>
          <p>Min Output: {ethers.formatUnits(route.minAmountOut, 18)}</p>
          <p>Gas: {route.gas}</p>

          <button onClick={handleExecute} disabled={loading}>
            Execute Swap
          </button>
        </div>
      )}

      {error && <p style={{ color: 'red' }}>{error}</p>}
    </div>
  );
}

Error Handling

async function safeExecuteSwap(
  client: DexAggregatorClient,
  params: BuildRouteParams
) {
  try {
    // Build route
    const route = await client.buildRoute(params);

    // Validate route
    if (BigInt(route.amountOut) === 0n) {
      throw new Error('Invalid route: zero output');
    }

    // Check slippage
    const slippagePercent =
      Number((BigInt(route.amountOut) - BigInt(route.minAmountOut)) * 10000n / BigInt(route.amountOut)) / 100;

    if (slippagePercent > 5) {
      console.warn(`High slippage: ${slippagePercent.toFixed(2)}%`);
    }

    // Execute
    const orderId = ethers.keccak256(ethers.toUtf8Bytes(`order-${Date.now()}`));
    const receipt = await client.executeSwap(route, orderId);

    return { success: true, receipt };
  } catch (error) {
    if (error.code === 'INSUFFICIENT_FUNDS') {
      return { success: false, error: 'Insufficient balance' };
    } else if (error.code === 'UNPREDICTABLE_GAS_LIMIT') {
      return { success: false, error: 'Transaction would fail' };
    } else {
      return { success: false, error: error.message };
    }
  }
}

Testing

// test.ts
import { describe, it, expect } from '@jest/globals';
import { DexAggregatorClient } from './dexAggregatorClient';

describe('DexAggregatorClient', () => {
  const client = new DexAggregatorClient(
    'http://localhost:8081',
    'https://bsc-dataseed1.binance.org',
    'test-private-key'
  );

  it('should build route successfully', async () => {
    const route = await client.buildRoute({
      chain: 'bsc',
      tokenIn: '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c',
      tokenOut: '0x55d398326f99059fF775485246999027B3197955',
      amountIn: '1000000000000000000',
      sender: '0xTestAddress',
      recipient: '0xTestAddress',
    });

    expect(route).toHaveProperty('amountOut');
    expect(route).toHaveProperty('executorData');
    expect(BigInt(route.amountOut)).toBeGreaterThan(0n);
  });
});

Next Steps

• Python Integration - Python examples

• Go Integration - Go examples

• Smart Contract Integration - Direct contract calls

• Gas Optimization - Reduce transaction costs

Production Checklist

• Store private keys securely (use environment variables)

• Implement proper error handling and retries

• Add transaction monitoring and notifications

• Test on testnet before mainnet deployment

• Set up logging and monitoring