# Route Finding ## Endpoint `GET https://api.liqd.ag/v2/route` Calculates optimal swap routes across all DEXs with built-in revenue sharing. **Authentication**: None required **Rate Limits**: None ## 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) | **Note**: Provide either `amountIn` OR `amountOut`, not both. ### 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...` | ## 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 | Hyperpie | | 24 | HyperpieDex | | 25 | HybraFinanceV4 | | 26 | LiquidCore | | 27 | RamsesV3Legacy | | 28 | NestExchange | > 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 ```typescript 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>; }; } | null; } ``` ### Example Response ```json { "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