Route Finding (Start Here)

🚀 Start Here - Your First Revenue-Generating API Call

The Route Finding API is your gateway to integrating LiquidSwap and earning revenue from every trade. This endpoint calculates optimal swap routes across all DEXs while allowing you to collect fees automatically.

⚡ Quick Start

# Get a route with 0.1% revenue sharing
curl "https://api.liqd.ag/v2/route?tokenIn=0x5555555555555555555555555555555555555555&tokenOut=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&amountIn=100&feeBps=10&feeRecipient=YOUR_WALLET_ADDRESS"

What you get:

  • ✅ Optimal swap route across all 9 DEXs

  • ✅ Ready-to-use transaction calldata

  • ✅ 0.1% fee automatically collected for you

  • ✅ Detailed routing breakdown and price impact analysis

About This Endpoint

Endpoint: GET /v2/route

This enhanced API provides ready-to-use transaction calldata, detailed token information, and comprehensive routing analysis. Most importantly, it includes built-in revenue sharing that lets you earn from every swap.

Parameters

Required Parameters

Name
Type
Description
Required

tokenIn

address

Address of the input token (what you're swapping from)

Yes

tokenOut

address

Address of the output token (what you're swapping to)

Yes

amountIn

number

Amount of input token (human readable, e.g., 100)

Yes*

amountOut

number

Desired output amount (for exact output swaps)

Yes*

*You must provide either amountIn OR amountOut, but not both.

Optional Parameters

Name
Type
Description
Default

multiHop

boolean

Enable multi-hop routing through intermediate tokens

false

slippage

number

Slippage tolerance as percentage 0-100

1.0

unwrapWHYPE

boolean

Automatically unwrap WHYPE to native HYPE

false

excludeDexes

string

Comma-separated DEX indices to exclude (e.g., "1,3,5")

none

feeBps

number

Your fee percentage in basis points (100 = 1%, max 100)

0

feeRecipient

address

Your wallet address to receive fee payments

none

Available DEXs

Index
DEX Name

1

KittenSwapV2

2

HyperSwapV2

3

HyperSwapV3

4

LaminarV3

5

KittenSwapV3

6

Valantis

7

HybraFinanceV2

8

HybraFinanceV3

9

Gliquid

Revenue Sharing

Quick Overview:

  • Use feeBps to charge up to 1% (100 basis points) on each swap

  • Set feeRecipient to your wallet address to receive payments

  • You keep 97.5% of collected fees, LiquidSwap keeps 2.5%

📚 Learn More: For complete details on revenue sharing, positive slippage capture, and monetization strategies, see our Revenue Sharing Guide.

Example Requests

Basic Exact Input Swap:

GET https://api.liqd.ag/v2/route?tokenIn=0x5555555555555555555555555555555555555555&tokenOut=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&amountIn=100

Multi-hop with Custom Slippage:

GET https://api.liqd.ag/v2/route?multiHop=true&tokenIn=0x5555555555555555555555555555555555555555&tokenOut=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&amountIn=100&slippage=1.5

Exact Output with WHYPE Unwrapping:

GET https://api.liqd.ag/v2/route?multiHop=true&tokenIn=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&tokenOut=0x5555555555555555555555555555555555555555&amountOut=100&unwrapWHYPE=true

Exclude Specific DEXs:

GET https://api.liqd.ag/v2/route?multiHop=true&tokenIn=0x5555555555555555555555555555555555555555&tokenOut=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&amountIn=100&excludeDexes=1,3,5

With Revenue Sharing (0.1% fee):

GET https://api.liqd.ag/v2/route?multiHop=true&tokenIn=0x5555555555555555555555555555555555555555&tokenOut=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&amountIn=69&feeBps=10&feeRecipient=0xaC7d51dB236fae22Ceb6453443da248F3A53f94d

Response Format

TypeScript Interface

interface SwapRouteV2Response {
  success: boolean;
  tokens: {
    tokenIn: {
      address: string;
      symbol: string;
      name: string;
      decimals: number;
    };
    tokenOut: {
      address: string;
      symbol: string;
      name: string;
      decimals: number;
    };
    intermediate?: {
      address: string;
      symbol: string;
      name: string;
      decimals: number;
    };
  };
  amountIn: string;
  amountOut: string;
  averagePriceImpact: string;
  execution: {
    to: string;
    calldata: string;
    details: {
      path: string[];
      amountIn: string;
      amountOut: string;
      minAmountOut: string;
      feeBps?: number;
      feeRecipient?: string;
      feePercentage?: string;
      hopSwaps: Array<Array<{
        tokenIn: string;
        tokenOut: string;
        routerIndex: number;
        routerName: string;
        fee: number;
        amountIn: string;
        amountOut: string;
        stable: boolean;
        priceImpact: string;
      }>>;
    };
  } | null;
}

Example Response

{
  "success": true,
  "tokens": {
    "tokenIn": {
      "address": "0x5555555555555555555555555555555555555555",
      "symbol": "WHYPE",
      "name": "Wrapped HYPE",
      "decimals": 18
    },
    "tokenOut": {
      "address": "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb",
      "symbol": "USD₮0",
      "name": "USD₮0",
      "decimals": 6
    }
  },
  "amountIn": "100",
  "amountOut": "3800.915112",
  "averagePriceImpact": "0.030406%",
  "execution": {
    "to": "0x744489ee3d540777a66f2cf297479745e0852f7a",
    "calldata": "0xc63113ad00000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000056bc75e2d6310000000000000000000000000000000000000000000000000000000000000e049636800000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000000020000000000000000000000005555555555555555555555555555555555555555000000000000000000000000b8ce59fc3717ada4c02eadf9682a9e934f625ebb0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000040000000000000000000000005555555555555555555555555555555555555555000000000000000000000000b8ce59fc3717ada4c02eadf9682a9e934f625ebb000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000000000000000000000000000000001f4000000000000000000000000000000000000000000000002b5e3af16b188000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000005555555555555555555555555555555555555555000000000000000000000000b8ce59fc3717ada4c02eaDF9682A9e934F625ebb000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000009c40000000000000000000000000000000000000000000000015af1d78b58c4000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000005555555555555555555555555555555555555555000000000000000000000000b8ce59fc3717ada4c02eaDF9682A9e934F625ebb000000000000000000000000000000000000000000000000000000000000000500000000000000000000000000000000000000000000000000000000000000c80000000000000000000000000000000000000000000000004563918244f4000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000005555555555555555555555555555555555555555000000000000000000000000b8ce59fc3717ada4c02eaDF9682A9e934F625ebb00000000000000000000000000000000000000000000000000000000000000090000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001158e460913d000000000000000000000000000000000000000000000000000000000000000000000",
    "details": {
      "path": ["0x5555555555555555555555555555555555555555", "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb"],
      "amountIn": "100000000000000000000",
      "amountOut": "3800915112",
      "minAmountOut": "3762905960",
      "hopSwaps": [[
        {
          "tokenIn": "0x5555555555555555555555555555555555555555",
          "tokenOut": "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb",
          "routerIndex": 3,
          "routerName": "HyperSwapV3",
          "fee": 500,
          "amountIn": "50000000000000000000",
          "amountOut": "1900657052",
          "stable": false,
          "priceImpact": "0.041439%"
        },
        {
          "tokenIn": "0x5555555555555555555555555555555555555555",
          "tokenOut": "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb",
          "routerIndex": 8,
          "routerName": "HybraFinanceV3",
          "fee": 2500,
          "amountIn": "25000000000000000000",
          "amountOut": "950080907",
          "stable": false,
          "priceImpact": "0.014007%"
        },
        {
          "tokenIn": "0x5555555555555555555555555555555555555555",
          "tokenOut": "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb",
          "routerIndex": 5,
          "routerName": "KittenSwapV3",
          "fee": 200,
          "amountIn": "5000000000000000000",
          "amountOut": "189991255",
          "stable": false,
          "priceImpact": "0.001813%"
        },
        {
          "tokenIn": "0x5555555555555555555555555555555555555555",
          "tokenOut": "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb",
          "routerIndex": 9,
          "routerName": "Gliquid",
          "fee": 0,
          "amountIn": "20000000000000000000",
          "amountOut": "760185898",
          "stable": false,
          "priceImpact": "0.030470%"
        }
      ]]
    }
  }
}

Understanding the Response

Token Information

  • tokens: Complete metadata for input, output, and any intermediate tokens

  • amountIn/amountOut: Human-readable amounts (e.g., "100" means 100 tokens)

  • averagePriceImpact: Overall price impact across all routes

Execution Data

  • execution.to: Contract address to send the transaction to

  • execution.calldata: Ready-to-use transaction data for your swap

  • execution.details.path: Token addresses in the swap path

  • execution.details.minAmountOut: Minimum output considering slippage

  • execution.details.hopSwaps: Detailed breakdown of each routing step

Route Analysis

Each entry in hopSwaps shows:

  • routerIndex/routerName: Which DEX handles this portion

  • fee: Trading fee in basis points (500 = 0.5%)

  • amountIn/amountOut: Portion of trade allocated to this route

  • priceImpact: Price impact for this specific route

  • stable: Whether this is a stable pair optimized route

Key V2 Improvements

  • Ready-to-use calldata: Execute trades directly with the provided transaction data

  • Enhanced token metadata: Full token information including names and symbols

  • Detailed routing breakdown: See exactly how your trade is split across DEXs

  • Price impact analysis: Individual and average price impact calculations

  • Flexible configuration: Custom slippage, DEX exclusions, and WHYPE unwrapping

PreviousAPI OverviewNextSmart Contract Integration

Last updated