⚡Execution

The route data from the V2 API can be used directly with the MultiHopRouter smart contract. The V2 API provides ready-to-use transaction calldata, making execution simple.

Contract Address

0x744489ee3d540777a66f2cf297479745e0852f7a

Execution Methods

There are three primary ways to execute swaps with the MultiHopRouter:

1. Using the executeSwaps Function

The executeSwaps function provides advanced features including positive slippage capture (50% capture rate) and custom fee collection:

function executeSwaps(
    address[] calldata tokens,
    uint256 amountIn,
    uint256 minAmountOut,
    uint256 expectedAmountOut,
    Swap[][] calldata hopSwaps,
    uint256 feeBps,
    address feeRecipient
) external payable nonReentrant returns (uint256 userAmountOut)

Required Parameters

Name

Type

Description

Required

tokens

address[]

Array of token addresses representing the swap path

Yes

amountIn

uint256

Amount of input tokens to swap

Yes

minAmountOut

uint256

Minimum amount of output tokens expected (slippage protection)

Yes

expectedAmountOut

uint256

Expected amount of output tokens (used for positive slippage calculation)

Yes

hopSwaps

Swap[][]

Array of swap configurations for each hop (obtained from the V2 API response)

Yes

feeBps

uint256

Fee in basis points (e.g., 100 = 1%) - automatically capped at 1% max

Yes

feeRecipient

address

Address to receive the fee (97.5% of fee goes here, 2.5% goes to protocol)

Yes

Features:

Positive Slippage Capture: Captures 50% of any positive slippage
- If feeRecipient is specified: half of captured slippage goes to your wallet, half to protocol
- If no feeRecipient is specified: protocol keeps all captured positive slippage
- You can set feeBps=0 and still receive positive slippage by providing feeRecipient
Custom Fee Collection: Set your own fees up to 1% (100 basis points), or set to 0 for no fees
Revenue Sharing: You keep 97.5% of collected fees, protocol keeps 2.5%
Automatic Fee Handling: If feeBps is 0 or feeRecipient is zero address, no fee is taken. When fees are taken, your share (97.5%) is sent directly to feeRecipient during execution; the protocol share (2.5%) is sent to the protocol address.

2. Using the executeMultiHopSwap Function

The executeMultiHopSwap function is designed for searchers, arbitragers, and advanced traders who build routes off-chain and don't want to share positive slippage:

function executeMultiHopSwap(
    address[] calldata tokens,
    uint256 amountIn,
    uint256 minAmountOut,
    Swap[][] calldata hopSwaps
) external payable nonReentrant returns (uint256 totalAmountOut)

Required Parameters

Name

Type

Description

Required

tokens

address[]

Array of token addresses representing the swap path

Yes

amountIn

uint256

Amount of input tokens to swap

Yes

minAmountOut

uint256

Minimum amount of output tokens expected (slippage protection)

Yes

hopSwaps

Swap[][]

Array of swap configurations for each hop

Yes

Features:

Flat Fee: 0.03% fee on output amount (goes entirely to protocol)
No Positive Slippage Sharing: You keep all positive slippage
No Expected Amount Required: Simpler parameter set for advanced users
Off-Chain Route Building: Perfect for custom routing strategies

Ideal For:

Searchers and MEV bots
Arbitrage strategies
Advanced traders with custom routing logic
Users who prefer not to share positive slippage

3. Using Calldata Directly from V2 Route

The V2 API response includes ready-to-use transaction calldata in the execution.calldata field. This calldata can be sent directly to the contract without manually constructing function calls.

Example using the calldata:

// Get route from V2 API
const response = await fetch('https://api.liqd.ag/v2/route?tokenIn=0x5555...&tokenOut=0xB8CE...&amountIn=100');
const routeData = await response.json();

// Execute using the provided calldata
if (routeData.success && routeData.execution) {
    const transaction = {
        to: routeData.execution.to,           // Contract address
        data: routeData.execution.calldata,   // Ready-to-use calldata
        value: 0                              // Add ETH value if swapping from native token
    };
    
    // Send transaction using your preferred method (ethers, web3, etc.)
    const result = await signer.sendTransaction(transaction);
}

Benefits of using calldata directly:

Simplified Integration: No need to manually construct function parameters
Guaranteed Compatibility: Calldata is generated by the same system that will execute it
Reduced Errors: Eliminates parameter formatting mistakes
Future-Proof: Automatically uses the optimal execution method

Which Method to Choose?

Use calldata directly for simpler integration and guaranteed compatibility
Use executeSwaps function when you need custom fee collection, positive slippage sharing, and have an expected output amount
Use executeMultiHopSwap function for searchers, arbitragers, and advanced use cases where you want to keep all positive slippage

All methods execute optimized routing strategies, but executeSwaps and calldata use the V2 API routing, while executeMultiHopSwap is designed for custom route construction.

Integrator Fee Payouts

Where fees go: When feeBps > 0 and feeRecipient is set, 97.5% of the fee amount is transferred directly to feeRecipient and 2.5% to the protocol address during the swap.
Zero-fee but capture slippage: You can set feeBps = 0 and still receive 50% of captured positive slippage by providing feeRecipient.
Zero recipient: If feeRecipient is unset or zero address, no custom fee is taken and any captured positive slippage goes fully to the protocol.

Hop Swaps Data Structure

For developers building their own routes or using the executeMultiHopSwap function, you need to understand the hop swaps data structure. This is also the same structure returned in the V2 API response under execution.details.hopSwaps:

Swap Struct

struct Swap {
    address tokenIn;       // Input token address
    address tokenOut;      // Output token address  
    uint8 routerIndex;     // DEX router index (1-14, see route-finding.md for DEX table)
    uint24 fee;            // Trading fee in basis points (used by V3 DEXs)
    uint256 amountIn;      // Amount of input tokens for this specific swap
    bool stable;           // Whether to use stable pool (used by V2 DEXs like KittenSwap)
}

Hop Swaps Array Structure

// Each hop contains an array of swaps that execute in parallel
// Supports unlimited hops for complex multi-token routing
Swap[][] hopSwaps = [
    [swap1, swap2, swap3], // First hop: multiple swaps from tokenA to tokenB
    [swap4, swap5],        // Second hop: multiple swaps from tokenB to tokenC  
    [swap6],               // Third hop: single swap from tokenC to tokenD
    [swap7, swap8, swap9]  // Fourth hop: multiple swaps from tokenD to tokenE
];

Field Usage by DEX Type

Field

V2 DEXs (1,2,7)

V3 DEXs (3,4,5,8,10,12)

Others (6,9,11,13,14)

tokenIn

✅ Required

tokenOut

✅ Required

routerIndex

✅ Required

fee

❌ Ignored

✅ Required

❌ Ignored [1]

amountIn

✅ Required

stable

✅ Required

❌ Ignored

[1] For router index 14 (HyperBrick Liquidity Book), the fee field is used as the bin step (defaults to 25 if not provided).

This structure allows for complex multi-hop routing where each hop can split across multiple DEXs for optimal execution.

Native HYPE Unwrapping

When using the unwrapWHYPE=true parameter in the V2 API, the system automatically handles conversion from WHYPE to native HYPE at the end of swaps. This uses a special address convention:

Dead Address for Native HYPE

Address: 0x000000000000000000000000000000000000dEaD

When the dead address (0x000000000000000000000000000000000000dEaD) appears as the final tokenOut in your swap path, it represents native HYPE. The MultiHopRouter contract automatically:

Receives WHYPE from the final swap step
Unwraps WHYPE to native HYPE using the WHYPE contract
Transfers native HYPE directly to your wallet

Usage Examples

In token arrays:

// Swap from USDT to native HYPE
tokens = [
    "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb", // USDT (input)
    "0x5555555555555555555555555555555555555555", // WHYPE (intermediate)
    "0x000000000000000000000000000000000000dEaD"  // Native HYPE (output)
];

In hopSwaps structure:

// Final hop unwraps WHYPE to native HYPE
hopSwaps = [
    [...], // Previous hops
    [{
        tokenIn: "0x5555555555555555555555555555555555555555", // WHYPE
        tokenOut: "0x000000000000000000000000000000000000dEaD", // Native HYPE
        routerIndex: 0, // Special unwrap operation
        // ... other fields
    }]
];

Key Points

Automatic Detection: When the dead address is detected as the final output token, unwrapping is triggered automatically
No Manual Unwrapping: You don't need to call separate unwrap functions - the router handles everything
Gas Efficiency: Unwrapping happens in the same transaction as your swap
API Integration: Set unwrapWHYPE=true in V2 API calls to enable this feature automatically

PreviousRoute Finding NextFind Pools

Last updated 5 days ago