Overview

Complete API reference for DexAggregator endpoints

DexAggregator provides a RESTful API for optimal token swap routing. All endpoints return JSON responses and follow standard HTTP status codes.

Base URL

http://localhost:8081  # Local development
https://api.yourdomain.com  # Production

API Endpoints Overview

Endpoint	Method	Description
/api/v1/route/build	POST	Build optimal swap route automatically
/api/v1/route/custom	POST	Build custom swap route manually
/api/v1/chains	GET	Get supported blockchain networks
/api/v1/contracts	GET	Get contract addresses for a chain
/health	GET	Health check endpoint

Response Format

All API responses follow this structure:

Success Response

{
  "code": 0,
  "message": "success",
  "data": {
    // Response data
  }
}

Error Response

{
  "code": 1000,
  "message": "error description",
  "data": null
}

Common Parameters

Chain Identifiers

Chain	Identifier	Chain ID
Binance Smart Chain	bsc	56
Ethereum	ethereum	1

Token Addresses

All token addresses must be:

• Valid ERC-20 contract addresses

• Checksummed (0x with proper casing)

• 42 characters long (including 0x prefix)

Amount Format

All token amounts must be in wei (smallest unit):

• 1 token with 18 decimals = 1000000000000000000 wei

• 0.5 tokens = 500000000000000000 wei

Conversion:

// JavaScript
const amountInWei = ethers.utils.parseUnits("1.0", 18);
// Result: "1000000000000000000"

// Python
from web3 import Web3
amount_in_wei = Web3.to_wei(1.0, 'ether')
# Result: 1000000000000000000

Slippage Tolerance

Expressed in basis points (1 basis point = 0.01%):

• 10 = 0.1%

• 50 = 0.5%

• 100 = 1%

• 500 = 5%

Deadline

Unix timestamp in seconds:

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

// Python
import time
deadline = int(time.time()) + 1200

Rate Limiting

Current Rate Limits

• Free tier: 100 requests per minute

• With API key: 1000 requests per minute

Contact us for higher limits.

Authentication

Currently, the API does not require authentication for public endpoints. For production deployments, consider implementing:

• API keys

• IP whitelisting

• OAuth 2.0

CORS

CORS is enabled for all origins in development. For production, configure allowed origins in your deployment.

Pagination

Pagination is not currently required as responses are single-item or small lists.

Versioning

The API uses URL versioning:

• Current version: /api/v1/

• Future versions: /api/v2/, etc.

Breaking changes will always result in a new version number.

Error Codes

See the Error Codes page for a complete list of error codes and their meanings.

Next Steps

Explore specific endpoints:

• Build Route (Auto) - Main endpoint for optimal routing

• Custom Route - Manual route configuration

• Get Chains - Supported networks

• Get Contracts - Contract addresses

• Health Check - Service status

Code Examples

Quick examples in different languages:

JavaScript / TypeScript

const response = await fetch('http://localhost:8081/api/v1/route/build', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    chain: 'bsc',
    tokenIn: '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c',
    tokenOut: '0x55d398326f99059fF775485246999027B3197955',
    amountIn: '1000000000000000000',
    sender: '0xYourAddress',
    recipient: '0xYourAddress',
    slippageTolerance: 50
  })
});

const data = await response.json();

Python

import requests

response = requests.post('http://localhost:8081/api/v1/route/build', json={
    'chain': 'bsc',
    'tokenIn': '0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c',
    'tokenOut': '0x55d398326f99059fF775485246999027B3197955',
    'amountIn': '1000000000000000000',
    'sender': '0xYourAddress',
    'recipient': '0xYourAddress',
    'slippageTolerance': 50
})

data = response.json()

Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

type BuildRequest struct {
    Chain             string `json:"chain"`
    TokenIn           string `json:"tokenIn"`
    TokenOut          string `json:"tokenOut"`
    AmountIn          string `json:"amountIn"`
    Sender            string `json:"sender"`
    Recipient         string `json:"recipient"`
    SlippageTolerance int    `json:"slippageTolerance"`
}

func main() {
    req := BuildRequest{
        Chain:             "bsc",
        TokenIn:           "0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c",
        TokenOut:          "0x55d398326f99059fF775485246999027B3197955",
        AmountIn:          "1000000000000000000",
        Sender:            "0xYourAddress",
        Recipient:         "0xYourAddress",
        SlippageTolerance: 50,
    }

    jsonData, _ := json.Marshal(req)
    resp, _ := http.Post(
        "http://localhost:8081/api/v1/route/build",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    defer resp.Body.Close()
}

Need Help?

Check our FAQ or report an issue.