🔍Route Finding

🚀 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.

About This Endpoint

Endpoint: GET https://api.liqd.ag/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.

Authentication: None required - all endpoints are publicly accessible

Rate Limits: No rate limits - use as needed for your application

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

10

RamsesV3

11

HyperCat

12

ProjectX

13

LiquidLaunch

14

HyperBrick

Note: This mapping may change over time. Use routerName in API responses when displaying protocol names.

Revenue Sharing

Fee Collection:

  • feeBps is optional — set to 0 for no trading fees

  • Charge up to 1% (100 bps) per swap via feeBps

  • Set feeRecipient to your wallet; fees are sent there directly during execution

  • 97.5% of your configured fee goes to feeRecipient; 2.5% goes to protocol

Positive Slippage Sharing:

  • When swaps perform better than expected, 50% of positive slippage is captured

  • If feeRecipient is set: 50% of captured slippage is sent to feeRecipient, 50% to protocol

  • If feeRecipient is not set or zero address: all captured positive slippage goes to protocol

  • You can set feeBps=0 and still receive positive slippage by providing feeRecipient

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;
    };
    intermediates?: Array<{
      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": "0xfDD22Ce6D1F66bc0Ec89b20BF16CcB6670F55A5a",
      "symbol": "thBILL",
      "name": "thBILL",
      "decimals": 6
    },
    "tokenOut": {
      "address": "0x1Ecd15865D7F8019D546f76d095d9c93cc34eDFa",
      "symbol": "LIQD",
      "name": "LiquidLaunch",
      "decimals": 18
    },
    "intermediates": [
      {
        "address": "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb",
        "symbol": "USD₮0",
        "name": "USD₮0",
        "decimals": 6
      },
      {
        "address": "0x5555555555555555555555555555555555555555",
        "symbol": "WHYPE",
        "name": "Wrapped HYPE",
        "decimals": 18
      }
    ]
  },
  "amountIn": "10000",
  "amountOut": "753541.728649388075275823",
  "averagePriceImpact": "0.505265%",
  "execution": {
    "to": "0x744489ee3d540777a66f2cf297479745e0852f7a",
    "calldata": "0xa22c27fe000000000000000000000000",
    "details": {
      "path": ["0xfDD22Ce6D1F66bc0Ec89b20BF16CcB6670F55A5a", "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb", "0x5555555555555555555555555555555555555555", "0x1Ecd15865D7F8019D546f76d095d9c93cc34eDFa"],
      "amountIn": "10000000000",
      "amountOut": "753541728649388075275823",
      "minAmountOut": "746006311362894194523064",
      "hopSwaps": [
        [
          {
            "tokenIn": "0xfDD22Ce6D1F66bc0Ec89b20BF16CcB6670F55A5a",
            "tokenOut": "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb",
            "routerIndex": 12,
            "routerName": "ProjectX",
            "fee": 100,
            "amountIn": "10000000000",
            "amountOut": "10014572870",
            "stable": false,
            "priceImpact": "0.000258%"
          }
        ],
        [
          {
            "tokenIn": "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb",
            "tokenOut": "0x5555555555555555555555555555555555555555",
            "routerIndex": 3,
            "routerName": "HyperSwapV3",
            "fee": 500,
            "amountIn": "10014572870",
            "amountOut": "219800801986029147619",
            "stable": false,
            "priceImpact": "0.004508%"
          }
        ],
        [
          {
            "tokenIn": "0x5555555555555555555555555555555555555555",
            "tokenOut": "0x1Ecd15865D7F8019D546f76d095d9c93cc34eDFa",
            "routerIndex": 8,
            "routerName": "HybraFinanceV3",
            "fee": 7500,
            "amountIn": "118714413152654342629",
            "amountOut": "407121827043060257927478",
            "stable": false,
            "priceImpact": "1.648423%"
          },
          {
            "tokenIn": "0x5555555555555555555555555555555555555555",
            "tokenOut": "0x1Ecd15865D7F8019D546f76d095d9c93cc34eDFa",
            "routerIndex": 12,
            "routerName": "ProjectX",
            "fee": 10000,
            "amountIn": "56137124827231844301",
            "amountOut": "193024057532473137391357",
            "stable": false,
            "priceImpact": "1.172092%"
          }
        ]
      ]
    }
  }
}

Understanding the Response

Token Information

  • tokens.tokenIn: Complete metadata for the input token (what you're swapping from)

  • tokens.tokenOut: Complete metadata for the output token (what you're swapping to)

  • tokens.intermediates: Array of intermediate tokens used in multi-hop routes (only present for multi-hop swaps)

  • 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

PreviousOpen Access PhilosophyNextExecution

Last updated