FAQ

Frequently asked questions about DexAggregator API

General Questions

What is DexAggregator?

DexAggregator is a Go-based API service that integrates KyberSwap's routing algorithm with custom DexAggregator smart contracts. It provides optimal token swap routes and ready-to-use encoded transaction data.

Is it free to use?

Yes, the open-source version is free. You can host your own instance or use a hosted service.

Which blockchains are supported?

Currently supported:

• Binance Smart Chain (BSC)

• Ethereum Mainnet

More chains can be added by configuring contract addresses.

Which DEXes are supported?

• UniswapV2 / V3 / V4

• PancakeSwapV2 / V3

• More can be added via custom adapters

API Questions

How do I get started?

See our Quickstart Guide for a 5-minute setup tutorial.

Do I need an API key?

No, the default API doesn't require authentication. For production, you may want to implement API keys.

What are the rate limits?

Default: 100 requests/minute. Can be configured in your deployment.

How long are routes valid?

Routes are typically valid for 30-60 seconds due to market volatility. Always fetch a fresh route before executing.

Can I cache routes?

Not recommended. Market prices change rapidly. Always fetch a new route immediately before swapping.

Swap Questions

What is slippage tolerance?

Slippage tolerance is the maximum price movement you're willing to accept. It's expressed in basis points:

• 50 = 0.5%

• 100 = 1%

• 500 = 5%

How is minAmountOut calculated?

minAmountOut = amountOut * (1 - slippageTolerance / 10000)

Example:

• amountOut = 100 USDT

• slippageTolerance = 50 (0.5%)

• minAmountOut = 100 * (1 - 50/10000) = 99.5 USDT

What happens if I receive less than minAmountOut?

The transaction will revert, and no swap will occur. You keep your original tokens.

What are the gas costs?

Gas costs vary by swap type:

• Simple: ~100k-150k gas

• Batch: ~150k-250k gas

• Multi-Hop: ~200k-300k gas

• Parallel Multi-Hop: ~300k-500k gas

Do I need to approve tokens?

Yes, for ERC-20 tokens. Native tokens (ETH/BNB) don't require approval.

Technical Questions

What is executorData?

executorData is ABI-encoded calldata ready for smart contract execution. It contains all swap parameters encoded for the DexAggregator contract.

Can I decode executorData?

Yes, but it's not necessary. The data is already formatted for the contract. If you need to inspect it:

import { ethers } from 'ethers';

// Example decoding (format varies by swap type)
const iface = new ethers.Interface([
  'function executeSwap(bytes32 swapType, address tokenIn, address tokenOut, ...)'
]);

const decoded = iface.parseTransaction({ data: executorData });
console.log(decoded);

What is the deadline parameter?

Unix timestamp (seconds) after which the transaction is invalid. Prevents stale transactions from executing at bad prices.

// 20 minutes from now
const deadline = Math.floor(Date.now() / 1000) + 1200;

How do I generate orderId?

The orderId is a unique identifier for your swap order. Generate it based on your system's logic:

import { ethers } from 'ethers';

// Option 1: Hash of timestamp + user
const orderId = ethers.keccak256(
  ethers.toUtf8Bytes(`${userAddress}-${Date.now()}`)
);

// Option 2: Random bytes32
const orderId = ethers.randomBytes(32);

// Option 3: Your custom logic
const orderId = ethers.keccak256(
  ethers.AbiCoder.defaultAbiCoder().encode(
    ['address', 'uint256'],
    [userAddress, nonce]
  )
);

Error Handling

"No route found" error

Causes:

• Token pair doesn't have liquidity

• Swap amount too large

• DEX sources filtered out

Solutions:

• Check token addresses are correct

• Reduce swap amount

• Remove includedSources filter

"KyberSwap API error"

Causes:

• KyberSwap API temporarily down

• Network connectivity issues

• Rate limiting

Solutions:

• Implement retry logic with exponential backoff

• Check KyberSwap status

• Verify internet connection

"Gas estimation failed"

Causes:

• RPC endpoint issues

• Transaction would revert

• Insufficient token balance

Solutions:

• Verify RPC endpoint is working

• Check wallet has sufficient balance

• Ensure token is approved

"Transaction failed" after execution

Causes:

• Slippage exceeded

• Insufficient gas

• Deadline passed

Solutions:

• Increase slippage tolerance

• Set higher gas limit

• Fetch a fresh route

Integration Questions

Can I use this in a React app?

Yes! See our JavaScript Integration Guide for React examples.

Does it work with Wagmi/RainbowKit?

Yes, you can integrate with any Web3 library. Example:

import { useAccount, useWalletClient } from 'wagmi';

function MySwapComponent() {
  const { address } = useAccount();
  const { data: walletClient } = useWalletClient();

  // Use DexAggregator API
  const route = await buildRoute({
    sender: address,
    recipient: address,
    // ... other params
  });

  // Execute with wagmi
  await walletClient.writeContract({
    address: route.aggregatorAddress,
    abi: AGGREGATOR_ABI,
    functionName: 'smartSwapByOrderId',
    args: [orderId, route.executorAddress, route.executorData],
    value: route.value,
  });
}

Can I integrate without ethers.js?

Yes, use any Web3 library (web3.js, viem, etc.) or make raw JSON-RPC calls.

Do I need to run my own server?

No, you can use a hosted instance. But running your own gives you more control and no rate limits.

Smart Contract Questions

Where are the smart contracts?

Contract addresses are chain-specific. Get them via:

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

Are the contracts audited?

Check the GitHub repository for audit reports.

Can I add custom DEX adapters?

Yes! Create an adapter contract following the IAdapter interface and configure it in your deployment.

What is the difference between Aggregator and Executor?

• Aggregator: Main contract that receives user transactions

• Executor: Logic contract that executes the swap routing

The separation allows for upgradeability and gas optimization.

Deployment Questions

How do I deploy my own instance?

See the Deployment Guide.

What are the system requirements?

• Go 1.21+

• 2GB RAM (minimum)

• 10GB disk space

• Stable internet connection

Can I deploy on Docker?

Yes! Example Dockerfile:

FROM golang:1.21-alpine

WORKDIR /app
COPY . .

RUN go mod download
RUN go build -o server examples/kyberswap_api_server.go

EXPOSE 8081
CMD ["./server"]

How do I configure for a new chain?

Edit the contracts configuration:

contracts := map[string]kyberswap.ContractAddresses{
    "polygon": {
        Aggregator: "0xYourAggregatorAddress",
        Executor:   "0xYourExecutorAddress",
        Adapters: kyberswap.AdapterMapping{
            UniswapV2: "0xYourAdapterAddress",
            // ... more adapters
        },
        RpcURL: "https://polygon-rpc-endpoint",
    },
}

Performance Questions

How fast is the API?

Typical response times:

• Route building: 1-3 seconds

• Gas estimation (if enabled): +0.5-1 second

Can I cache contract addresses?

Yes! Contract addresses are static and safe to cache.

Should I use connection pooling?

Yes, for production deployments. Use HTTP keep-alive and connection pooling.

How can I reduce latency?

1. Deploy server close to users

2. Use fast RPC endpoints

3. Disable gas estimation if not needed

4. Implement request caching (carefully!)

Security Questions

Is it safe to use?

The API itself doesn't handle private keys. You're responsible for secure key management in your application.

Should I validate responses?

Yes! Always validate:

• Token addresses match your request

• amountOut is reasonable

• minAmountOut is acceptable

What about MEV (front-running)?

Use:

• Private transaction relayers (Flashbots, MEV-Blocker)

• Adequate slippage protection

• Short deadlines

How do I secure my API endpoint?

Implement:

• API key authentication

• Rate limiting

• IP whitelisting

• HTTPS/TLS

Troubleshooting

Logs show "connection refused"

The RPC endpoint is unreachable. Check:

• RPC URL is correct

• Network connectivity

• RPC service is running

Swaps keep failing on-chain

Common issues:

• Insufficient token balance

• Token not approved

• Slippage too tight

• Deadline expired

API returns empty routes

• Token pair may not exist

• Liquidity is zero

• Check token addresses

Still Have Questions?

• 📖 Read the full Documentation

• 💻 Check Integration Guides

• 🐛 Report Issues

• 💬 Join our community channels