> 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/route-finding.md).

# Route Finding

`GET https://api.liqd.ag/v2/route`

Calculates optimal swap routes across available liquidity. Returns token metadata, quoted amounts, and ready-to-use calldata for [execution](/liquidswap-integration/execution.md).

## Parameters

### Required Parameters

| Name        | Type    | Description                                                      | Required | Example                                      |
| ----------- | ------- | ---------------------------------------------------------------- | -------- | -------------------------------------------- |
| `tokenIn`   | address | Contract address of the input token (0x format)                  | Yes      | `0x5555555555555555555555555555555555555555` |
| `tokenOut`  | address | Contract address of the output token (0x format)                 | Yes      | `0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb` |
| `amountIn`  | number  | Amount of input token (human readable, e.g., 100 for 100 tokens) | Yes\*    | `1000`                                       |
| `amountOut` | number  | Desired output amount (human readable, for exact output swaps)   | Yes\*    | `50000`                                      |
| `chainId`   | number  | Chain to route on (`999` = HyperEVM, `4663` = Robinhood Chain)   | Yes      | `999`                                        |

**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`       |
| `unwrapNative` | boolean | Unwrap to native token (HYPE on HyperEVM, ETH on Robinhood Chain)             | false   | `true`      |
| `excludeDexes` | string  | Comma-separated `routerIndex` values to exclude from routing                  | none    | `1,3`       |
| `includeDexes` | string  | Comma-separated `routerIndex` values to include only (overrides excludeDexes) | none    | `1,2`       |
| `feeBps`       | number  | Your fee in basis points (100 = 1%, max 100) — you keep 97.5% of this         | 0       | `50`        |
| `feeRecipient` | address | Wallet to receive fee payments and positive slippage                          | none    | `0xaC7d...` |

Resolve `routerIndex` values via [`GET /dexes?chainId=...`](/liquidswap-integration/dexes.md).

## Example Requests

**HyperEVM exact input:**

```
GET https://api.liqd.ag/v2/route?tokenIn=0x5555555555555555555555555555555555555555&tokenOut=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&amountIn=100&chainId=999
```

**Robinhood Chain exact input:**

```
GET https://api.liqd.ag/v2/route?tokenIn=0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73&tokenOut=0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168&amountIn=0.01&chainId=4663
```

**Multi-hop with custom slippage:**

```
GET https://api.liqd.ag/v2/route?multiHop=true&tokenIn=0x5555555555555555555555555555555555555555&tokenOut=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&amountIn=100&slippage=1.5&chainId=999
```

**Exact output with native unwrapping:**

```
GET https://api.liqd.ag/v2/route?multiHop=true&tokenIn=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&tokenOut=0x5555555555555555555555555555555555555555&amountOut=100&unwrapNative=true&chainId=999
```

**Exclude specific sources:**

```
GET https://api.liqd.ag/v2/route?multiHop=true&tokenIn=0x5555555555555555555555555555555555555555&tokenOut=0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb&amountIn=100&excludeDexes=1,3&chainId=999
```

**Include only specific sources:**

```
GET https://api.liqd.ag/v2/route?tokenIn=0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73&tokenOut=0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168&amountIn=0.01&includeDexes=1,2&chainId=4663
```

**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&chainId=999
```

## Response Fields

| Field                                      | Description                                                       |
| ------------------------------------------ | ----------------------------------------------------------------- |
| `success`                                  | Whether a route was found                                         |
| `tokens.tokenIn` / `tokens.tokenOut`       | Token metadata: `address`, `symbol`, `name`, `decimals`           |
| `tokens.intermediates`                     | Intermediate tokens for multi-hop routes (empty for direct swaps) |
| `amountIn` / `amountOut`                   | Human-readable amounts                                            |
| `averagePriceImpact`                       | Overall price impact across the route                             |
| `execution.to`                             | RouterV2 address for this chain — send the transaction here       |
| `execution.calldata`                       | Ready-to-use transaction data                                     |
| `execution.details.path`                   | Token addresses in the swap path                                  |
| `execution.details.amountIn` / `amountOut` | Amounts in base units                                             |
| `execution.details.minAmountOut`           | Minimum output after slippage (base units)                        |
| `execution.details.hopSwaps`               | Per-hop routing breakdown (array of parallel swap arrays)         |

### `hopSwaps[][]` fields

| Field                        | Description                                                                                  |
| ---------------------------- | -------------------------------------------------------------------------------------------- |
| `tokenIn` / `tokenOut`       | Token addresses for this leg                                                                 |
| `poolAddress`                | Pool used for this leg                                                                       |
| `routerIndex` / `routerName` | Liquidity source — indexes from [`GET /dexes?chainId=...`](/liquidswap-integration/dexes.md) |
| `fee`                        | Pool fee (when applicable)                                                                   |
| `stable`                     | Whether a stable pool is used (when applicable)                                              |
| `data`                       | Opaque per-pool data blob (may be `0x`)                                                      |
| `amountIn` / `amountOut`     | Amounts for this leg in base units                                                           |
| `priceImpact`                | Price impact for this leg                                                                    |


---

# 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/route-finding.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.