> For the complete documentation index, see [llms.txt](https://docs.liqd.ag/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.liqd.ag/liquidswap-integration/execution.md).

# Execution

Execute swaps using the `MultiHopRouter` contract. The [route finding](/liquidswap-integration/route-finding.md) API returns ready-to-use `calldata` — or you can construct calls yourself.

**MultiHopRouter:** `0x744489ee3d540777a66f2cf297479745e0852f7a`

## Execution Methods

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

### 1. Using the executeSwaps Function

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

```solidity
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      |

See [Revenue Sharing](/liquidswap-integration/overview.md#revenue-sharing) for how fees and positive slippage work.

### 2. Using the executeMultiHopSwap Function

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

```solidity
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:**

* 0.03% fee on output amount (goes entirely to protocol)
* No positive slippage sharing - you keep all
* Simpler parameter set

### 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:**

```javascript
// 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);
}
```

## 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

```solidity
struct Swap {
    address tokenIn;       // Input token address
    address tokenOut;      // Output token address  
    uint8 routerIndex;     // DEX router index (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

```typescript
// 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,18) | V3 DEXs (3,5,8,10,12,19,25,27) | Others (6,13,20,21,26,28) |
| ------------- | ------------------ | ------------------------------ | ------------------------- |
| `tokenIn`     | ✅ Required         | ✅ Required                     | ✅ Required                |
| `tokenOut`    | ✅ Required         | ✅ Required                     | ✅ Required                |
| `routerIndex` | ✅ Required         | ✅ Required                     | ✅ Required                |
| `fee`         | ❌ Ignored          | ✅ Required                     | ❌ Ignored                 |
| `amountIn`    | ✅ Required         | ✅ Required                     | ✅ Required                |
| `stable`      | ✅ Required         | ❌ Ignored                      | ❌ Ignored                 |

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:

1. **Receives WHYPE** from the final swap step
2. **Unwraps WHYPE** to native HYPE using the WHYPE contract
3. **Transfers native HYPE** directly to your wallet

### Usage Examples

**In token arrays:**

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

**In hopSwaps structure:**

```typescript
// 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.liqd.ag/liquidswap-integration/execution.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.