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

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

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

```solidity
struct Swap {
    address tokenIn;       // Input token address
    address tokenOut;      // Output token address  
    uint8 routerIndex;     // DEX router index (1-28, 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,24) | V3 DEXs (3,4,5,8,10,12,17,19,22) | Others (6,9,11,13,14,16,20,21,23) |
| ------------- | --------------------- | -------------------------------- | --------------------------------- |
| `tokenIn`     | ✅ Required            | ✅ Required                       | ✅ Required                        |
| `tokenOut`    | ✅ Required            | ✅ Required                       | ✅ Required                        |
| `routerIndex` | ✅ Required            | ✅ Required                       | ✅ Required                        |
| `fee`         | ❌ Ignored             | ✅ Required                       | ❌ Ignored \[1]                    |
| `amountIn`    | ✅ Required            | ✅ Required                       | ✅ Required                        |
| `stable`      | ✅ Required            | ❌ Ignored                        | ❌ 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:

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