Quickstart

Get started with DexAggregator API in 5 minutes

This guide will help you make your first API call to DexAggregator and execute an optimal token swap.

Prerequisites

• Basic understanding of blockchain and token swaps

• API client (curl, Postman, or code)

• Wallet address for testing

Step 1: Server Setup (Optional)

If you're running your own instance:

# Clone the repository
git clone https://github.com/YourOrg/DexAggregator-go-server.git
cd DexAggregator-go-server

# Install dependencies
go mod download

# Run the server
go run examples/kyberswap_api_server.go

The server will start on http://localhost:8081 by default.

Using a hosted instance? Skip this step and use your API endpoint URL.

Step 2: Check Server Health

Verify the API is running:

curl http://localhost:8081/health

Response:

{
  "status": "healthy",
  "time": {
    "unix": 1703001234
  }
}

Step 3: Get Supported Chains

curl http://localhost:8081/api/v1/chains

Response:

{
  "chains": ["bsc", "ethereum"]
}

Step 4: Get Contract Addresses

Get the smart contract addresses for your chain:

curl http://localhost:8081/api/v1/contracts?chain=bsc

Response:

{
  "chain": "bsc",
  "contracts": {
    "Aggregator": "0x27e33A8286d5Fd2956E24C2BcD62Fdd410c5bDf9",
    "Executor": "0x184F9066D8899C2216b05827B6279A851e859e7E",
    "Adapters": {
      "UniswapV2": "0x90e1C85D0542B8963906330825ddE2dec66b78C3",
      "UniswapV3": "0x1EAe07d4997Ce9A1C87aFAE924c257fdb7813607",
      "PancakeSwapV2": "0x71d40ECfc8F034bCba9EF50Fa0439086a470c41c",
      "PancakeSwapV3": "0x38BF57A209b9CAeCd3525B08B0CB1BCC7a598E4B"
    }
  }
}

Step 5: Build Your First Swap Route

Now let's swap 1 WBNB to USDT on BSC:

curl -X POST http://localhost:8081/api/v1/route/build \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "bsc",
    "tokenIn": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
    "tokenOut": "0x55d398326f99059fF775485246999027B3197955",
    "amountIn": "1000000000000000000",
    "sender": "0xYourWalletAddress",
    "recipient": "0xYourWalletAddress",
    "slippageTolerance": 50,
    "deadline": 1735689600
  }'

Response:

{
  "code": 0,
  "message": "success",
  "data": {
    "tokenIn": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
    "tokenOut": "0x55d398326f99059fF775485246999027B3197955",
    "amountIn": "1000000000000000000",
    "amountOut": "580123456789012345678",
    "minAmountOut": "577222222222222222222",
    "gas": "150000",
    "gasPrice": "5000000000",
    "gasUsd": 0.0234,
    "amountInUsd": 580.12,
    "amountOutUsd": 579.89,
    "aggregatorAddress": "0x27e33A8286d5Fd2956E24C2BcD62Fdd410c5bDf9",
    "executorAddress": "0x799F4A8586aa32EeA7CFd5a6cba85A8e0aDC4a5E",
    "executorData": "0x00bb4cdb...",
    "value": "0",
    "swapType": "batch",
    "routeInfo": {
      "routes": [
        {
          "adapter": "PancakeSwapV3",
          "percentage": 60,
          "path": ["0xbb4c...", "0x55d3..."]
        },
        {
          "adapter": "UniswapV2",
          "percentage": 40,
          "path": ["0xbb4c...", "0x55d3..."]
        }
      ]
    }
  }
}

Step 6: Execute the Swap

Use the returned data to execute the swap on-chain:

Using Web3.js (JavaScript)

const Web3 = require('web3');
const web3 = new Web3('https://bsc-rpc-endpoint');

const response = /* ... response from Step 5 ... */;

// Approve token (if not ETH/BNB)
const tokenContract = new web3.eth.Contract(ERC20_ABI, response.data.tokenIn);
await tokenContract.methods
  .approve(response.data.aggregatorAddress, response.data.amountIn)
  .send({ from: yourAddress });

// Execute swap
const aggregatorContract = new web3.eth.Contract(
  AGGREGATOR_ABI,
  response.data.aggregatorAddress
);

const tx = await aggregatorContract.methods
  .smartSwapByOrderId(
    orderId, // Get from your system
    response.data.executorAddress,
    response.data.executorData
  )
  .send({
    from: yourAddress,
    value: response.data.value, // Only for native token swaps
    gas: response.data.gas
  });

console.log('Swap executed:', tx.transactionHash);

Using ethers.js (TypeScript)

import { ethers } from 'ethers';

const provider = new ethers.providers.JsonRpcProvider('https://bsc-rpc-endpoint');
const wallet = new ethers.Wallet(privateKey, provider);

const response = /* ... response from Step 5 ... */;

// Approve token
const tokenContract = new ethers.Contract(
  response.data.tokenIn,
  ERC20_ABI,
  wallet
);

await tokenContract.approve(
  response.data.aggregatorAddress,
  response.data.amountIn
);

// Execute swap
const aggregatorContract = new ethers.Contract(
  response.data.aggregatorAddress,
  AGGREGATOR_ABI,
  wallet
);

const tx = await aggregatorContract.smartSwapByOrderId(
  orderId,
  response.data.executorAddress,
  response.data.executorData,
  {
    value: response.data.value,
    gasLimit: response.data.gas
  }
);

await tx.wait();
console.log('Swap executed:', tx.hash);

Understanding the Response

Field	Description
amountOut	Expected output amount (best case)
minAmountOut	Minimum output after slippage tolerance
executorData	ABI-encoded calldata ready for contract execution
swapType	Type of swap: simple, batch, multihop, or parallel_multihop
gas	Estimated gas units needed
routeInfo	Breakdown of which DEXes and routes are used

Parameter Explanation

Required Parameters

• chain: Chain identifier (bsc, ethereum)

• tokenIn: Input token contract address

• tokenOut: Output token contract address

• amountIn: Input amount in wei (18 decimals for most tokens)

• sender: Your wallet address

• recipient: Receiving wallet address

Optional Parameters

• slippageTolerance: Max acceptable slippage in basis points (50 = 0.5%)

• deadline: Unix timestamp for transaction validity

• includedSources: Array of DEX names to include (default: all supported)

• gasPrice: Custom gas price in wei

Common Token Addresses

BSC Mainnet

{
  "WBNB": "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
  "USDT": "0x55d398326f99059fF775485246999027B3197955",
  "BUSD": "0xe9e7CEA3DedcA5984780Bafc599bD69ADd087D56",
  "USDC": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d"
}

Ethereum Mainnet

{
  "WETH": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
  "USDT": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "USDC": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "DAI": "0x6B175474E89094C44Da98b954EedeAC495271d0F"
}

Next Steps

• 📚 Explore all API endpoints

• 🔄 Learn about swap types

• 💻 Check integration guides

• 🎯 View more examples

Congratulations! You've successfully integrated DexAggregator API. 🎉

Production Checklist

• Use environment variables for private keys

• Implement proper error handling

• Set appropriate slippage tolerance for your use case

• Monitor gas prices and adjust deadlines

• Test thoroughly on testnet first