Swap Quotes

Get swap quotes from multiple DEX aggregators in one request.

Try it Live

Open in Swagger UI → to test these endpoints interactively.

Endpoints

Endpoint	Description	Price
GET /api/swap/quote	Get swap quote	$0.002
GET /api/swap/routes	Compare routes	$0.005
GET /api/swap/tokens	Supported tokens	FREE

---

GET /api/swap/quote

Get the best swap quote across multiple DEX aggregators.

Request

curl "https://api.web3identity.com/api/swap/quote?\
fromToken=ETH&\
toToken=USDC&\
amount=1&\
chainId=1"

Query Parameters

Param	Type	Required	Description
fromToken	string	Yes	Source token (symbol or address)
toToken	string	Yes	Destination token
amount	string	Yes	Amount to swap (in token units)
chainId	number	No	Chain ID (default: 1)
slippage	number	No	Max slippage % (default: 0.5)
sender	string	No	Sender address (for gas estimate)

Response

{
  "fromToken": {
    "symbol": "ETH",
    "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
    "decimals": 18
  },
  "toToken": {
    "symbol": "USDC",
    "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "decimals": 6
  },
  "fromAmount": "1000000000000000000",
  "toAmount": "3245670000",
  "toAmountFormatted": "3245.67",
  "rate": 3245.67,
  "priceImpact": "0.02%",
  "route": {
    "source": "1inch",
    "path": ["WETH", "USDC"],
    "pools": ["Uniswap V3 0.05%"]
  },
  "gas": {
    "estimate": 150000,
    "priceGwei": 25,
    "costUSD": 12.50
  },
  "validUntil": "2026-02-08T04:35:00Z"
}

SDK

const quote = await client.getSwapQuote({
  fromToken: 'ETH',
  toToken: 'USDC',
  amount: '1',
  chainId: 1
});

console.log(`1 ETH = ${quote.toAmountFormatted} USDC`);
console.log(`Price impact: ${quote.priceImpact}`);

JavaScript

const BASE_URL = 'https://api.web3identity.com';

async function getSwapQuote({ fromToken, toToken, amount, chainId = 1 }) {
  const params = new URLSearchParams({
    fromToken,
    toToken,
    amount: amount.toString(),
    chainId: chainId.toString()
  });
  
  const response = await fetch(`${BASE_URL}/api/swap/quote?${params}`);
  
  if (!response.ok) {
    throw new Error(`Quote failed: ${response.status}`);
  }
  
  return response.json();
}

// Example: Get ETH → USDC quote
const quote = await getSwapQuote({
  fromToken: 'ETH',
  toToken: 'USDC',
  amount: 1
});

console.log(`Rate: 1 ETH = $${quote.rate.toFixed(2)}`);
console.log(`You receive: ${quote.toAmountFormatted} USDC`);
console.log(`Gas cost: ~$${quote.gas.costUSD.toFixed(2)}`);

Python

import requests

BASE_URL = "https://api.web3identity.com"

def get_swap_quote(from_token: str, to_token: str, amount: float, chain_id: int = 1) -> dict:
    response = requests.get(
        f"{BASE_URL}/api/swap/quote",
        params={
            "fromToken": from_token,
            "toToken": to_token,
            "amount": str(amount),
            "chainId": chain_id
        }
    )
    response.raise_for_status()
    return response.json()

# Get quote
quote = get_swap_quote("ETH", "USDC", 1.0)
print(f"1 ETH → {quote['toAmountFormatted']} USDC")
print(f"Via: {quote['route']['source']}")

cURL

# Get ETH to USDC quote with formatting
curl -s "https://api.web3identity.com/api/swap/quote?\
fromToken=ETH&\
toToken=USDC&\
amount=1&\
chainId=1" | jq '{
  from: "\(.fromToken.symbol)",
  to: "\(.toToken.symbol)", 
  rate: .rate,
  receive: .toAmountFormatted,
  gasCost: "$\(.gas.costUSD)",
  source: .route.source
}'

---

GET /api/swap/routes

Compare quotes from multiple aggregators.

Request

curl "https://api.web3identity.com/api/swap/routes?\
fromToken=ETH&\
toToken=USDC&\
amount=10&\
chainId=1"

Response

{
  "fromToken": "ETH",
  "toToken": "USDC",
  "amount": "10",
  "routes": [
    {
      "source": "1inch",
      "toAmount": "32456.70",
      "rate": 3245.67,
      "gas": 150000,
      "priceImpact": "0.05%"
    },
    {
      "source": "paraswap",
      "toAmount": "32445.20",
      "rate": 3244.52,
      "gas": 165000,
      "priceImpact": "0.06%"
    },
    {
      "source": "0x",
      "toAmount": "32440.00",
      "rate": 3244.00,
      "gas": 145000,
      "priceImpact": "0.05%"
    }
  ],
  "best": {
    "byAmount": "1inch",
    "byGas": "0x"
  }
}

Use Case: Best Execution

const routes = await fetch(
  'https://api.web3identity.com/api/swap/routes?fromToken=ETH&toToken=USDC&amount=10'
).then(r => r.json());

// Find best by net output (amount - gas cost)
const bestRoute = routes.routes.reduce((best, route) => {
  const netValue = parseFloat(route.toAmount) - (route.gas * 0.00003 * 3200); // rough ETH gas cost
  return netValue > best.netValue ? { ...route, netValue } : best;
}, { netValue: 0 });

console.log(`Best route: ${bestRoute.source}`);

---

GET /api/swap/tokens

Get list of supported tokens for swaps.

Request

curl "https://api.web3identity.com/api/swap/tokens?chainId=1"

Response

{
  "chainId": 1,
  "tokens": [
    {
      "symbol": "ETH",
      "name": "Ethereum",
      "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "decimals": 18,
      "logoURI": "https://..."
    },
    {
      "symbol": "USDC",
      "name": "USD Coin",
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "decimals": 6,
      "logoURI": "https://..."
    }
  ],
  "count": 5000
}

---

Supported Chains

Chain	ID	Status
Ethereum	1	✅
Arbitrum	42161	✅
Optimism	10	✅
Base	8453	✅
Polygon	137	✅

---

Quote Sources

We aggregate from:

Source	Specialty
1inch	Best overall routing
ParaSwap	MEV protection
0x	Professional traders
Uniswap	Direct pool access
Cowswap	Gasless trades

---

Error Handling

Code	HTTP	Description
INSUFFICIENT_LIQUIDITY	400	Not enough liquidity for amount
TOKEN_NOT_FOUND	404	Token not supported
INVALID_CHAIN	400	Chain ID not supported
QUOTE_EXPIRED	410	Quote no longer valid

Error Response

{
  "error": true,
  "code": "INSUFFICIENT_LIQUIDITY",
  "message": "Insufficient liquidity for 1000 ETH → USDC swap"
}

---

Best Practices

1. Always Check Price Impact

const quote = await getSwapQuote({ fromToken: 'ETH', toToken: 'USDC', amount: 100 });

if (parseFloat(quote.priceImpact) > 1) {
  console.warn('High price impact! Consider smaller trade.');
}

2. Use Fresh Quotes

// Quotes expire quickly - fetch just before executing
const quote = await getSwapQuote(params);

if (new Date(quote.validUntil) < new Date()) {
  // Refetch
  quote = await getSwapQuote(params);
}

3. Include Gas in Calculations

const netOutput = parseFloat(quote.toAmountFormatted) - quote.gas.costUSD;
console.log(`Net output after gas: $${netOutput.toFixed(2)}`);

---

Related Endpoints

• Token Prices — Current market prices
• Wallet Balances — Check holdings before swap
• Gas Prices — Current gas costs
• DeFi TVL — Protocol liquidity

---

Try It Now

💱 Open Swagger UI →