> 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.