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
Example

tokenIn

address

Contract address of the input token (0x format)

Yes

0x5555555555555555555555555555555555555555 (WHYPE)

tokenOut

address

Contract address of the output token (0x format)

Yes

0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb (USDT)

amountIn

number

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

Yes*

1000 (for 1000 WHYPE)

amountOut

number

Desired output amount (human readable, for exact output swaps)

Yes*

50000 (for exactly 50,000 USDT)

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

Token Address Formats

  • Use contract addresses: 0x prefixed 40-character hex strings

  • Examples: WHYPE (0x555...), USDC (0xB8C...), custom tokens

  • Don't use: Symbol names (WHYPE) or checksummed addresses

  • Pro tip: Always verify addresses on the blockchain explorer

Optional Parameters

Name
Type
Description
Default
Example

multiHop

boolean

Enable multi-hop routing through intermediate tokens

false

true

slippage

number

Slippage tolerance as percentage (0.1-5.0 recommended)

1.0

0.5

unwrapWHYPE

boolean

Automatically unwrap WHYPE to native HYPE

false

true

excludeDexes

string

Comma-separated DEX indices to exclude from routing

none

1,3,5

includeDexes

string

Comma-separated DEX indices to include only (overrides excludeDexes)

none

1,5,15

feeBps

number

Your fee in basis points (100 = 1%, max 100) - you keep 97.5% of this

0

50

feeRecipient

address

Your wallet address to receive fee payments and positive slippage

none

0xaC7d...

Parameter Details

multiHop: true | false

  • When to use: Always use true for best rates, especially for exotic pairs

  • Impact: Enables routing through intermediate tokens (WHYPE, USDC, etc.)

  • Gas cost: Slightly higher due to additional transactions

  • Recommendation: Enable for all swaps unless gas cost is critical

slippage: 0.1 to 5.0

  • What it does: Maximum price movement you're willing to accept

  • Recommended: 0.5% for normal tokens, 1-2% for volatile pairs

  • Too low: Transaction may fail due to normal price movements

  • Too high: You risk getting much worse rates than quoted

excludeDexes/includeDexes: Comma-separated numbers

  • Use cases: Avoid failing DEXs, force specific routing, compliance

  • DEX Index Reference: See Available DEXs table below

  • Note: includeDexes overrides excludeDexes if both provided

  • Performance: Excluding DEXs may reduce available liquidity

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

15

KittenSwapV4

16

HXFinance

17

UpheavalV3

18

UltraSolidV2

19

UltraSolidV3

20

CurveStableswapNG

21

CurveTwoCryptoNG

22

FunnelV3

23

HyperpieMeme

24

HyperpieV2

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

Include Only Specific DEXs:

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

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