# Route

The XSwap Route Generation API provides optimal cross-chain and single-chain swap routes with integrated bridging capabilities. This endpoint calculates the most efficient path for token swaps across supported blockchain networks.

***

### Endpoint

```http
POST https://xswap.link/api/route/v1
Content-Type: application/json
```

All query parameters are passed as a JSON payload in the `data` query parameter, URL-encoded.

***

### Authentication

All requests **must** include your registered `integratorId` in the JSON body.\
[Contact the XSwap team](<https://forms.gle/Y6kh19Bghtayt6FZ7&#xA;>) to obtain your credentials.

***

### Request

#### Required Parameters

| Field             | Type    | Description                                                                                                                                                                                    |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `integratorId`    | string  | Your registered integrator ID                                                                                                                                                                  |
| `fromChain`       | string  | Source chain ID (e.g. `"1"`, `"137"`, `"42161"`)                                                                                                                                               |
| `toChain`         | string  | Destination chain ID (e.g. `"1"`, `"43114"`)                                                                                                                                                   |
| `fromToken`       | string  | Contract address of source token                                                                                                                                                               |
| `toToken`         | string  | Contract address of destination token                                                                                                                                                          |
| `fromAmount`      | string  | Amount in smallest unit (e.g. `"1000000000000000000"`)                                                                                                                                         |
| `fromAddress`     | string  | Wallet initiating the swap                                                                                                                                                                     |
| `toAddress`       | string  | Recipient address on destination chain                                                                                                                                                         |
| `paymentToken`    | string  | <p>Token used for paying cross-chain fees</p><blockquote><p><strong>Note:</strong> this field is only required in cross-chain transactions (<code>fromChain ≠ toChain</code>)</p></blockquote> |
| `slippage`        | number  | Max slippage % (e.g. `0.5` = 0.5%)                                                                                                                                                             |
| `expressDelivery` | boolean | Instant execution on destination (extra fee)                                                                                                                                                   |

#### Optional Parameters

| Field                          | Type    | Description                                                          |
| ------------------------------ | ------- | -------------------------------------------------------------------- |
| `infiniteApproval`             | boolean | Approve max uint256 allowance (default: `true`)                      |
| `integratorFeeReceiverAddress` | string  | <p>Address to receive</p><p><code>integratorFee</code></p>           |
| `integratorFee`                | number  | Extra fee in bps (1–10,000), requires `integratorFeeReceiverAddress` |

***

### Response

| Field                          | Type   | Description                                                      |
| ------------------------------ | ------ | ---------------------------------------------------------------- |
| `estAmountOut`                 | string | Estimated output amount in the destination token’s smallest unit |
| `minAmountOut`                 | string | Minimum guaranteed output after slippage                         |
| `transactions`                 | object | Contains transaction payloads (e.g., `swap`)                     |
| `transactions.swap.to`         | string | Target contract address for the swap                             |
| `transactions.swap.data`       | string | Encoded calldata for the swap                                    |
| `transactions.swap.value`      | string | ETH value to send with the transaction                           |
| `xSwapFees.ccipFee`            | string | Fee paid to the CCIP network                                     |
| `xSwapFees.xSwapFee.tokenFee`  | string | Fee paid in tokens                                               |
| `xSwapFees.xSwapFee.nativeFee` | string | Fee paid in native chain currency                                |
| `xSwapFees.expressDeliveryFee` | string | Additional fee if `expressDelivery` is enabled                   |

***

### Example Request

```javascript
;(async () => {
  const payload = {
    integratorId: "xxx",
    fromChain: "8453",
    toChain: "1",
    fromToken: "0x8fe815417913a93ea99049fc0718ee1647a2a07c",
    toToken: "0x8fe815417913a93ea99049fc0718ee1647a2a07c",
    fromAmount: "100000000000000000",
    fromAddress: "0x123...abc",
    toAddress: "0x123...abc",
    paymentToken: "0x0000000000000000000000000000000000000000",
    slippage: 1.5,
    expressDelivery: false,
  };

  const encoded = encodeURIComponent(JSON.stringify(payload));
  const url = `https://xswap.link/api/route/v1?data=${encoded}`;

  const res = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
  });

  if (!res.ok) {
    throw new Error(`HTTP ${res.status}: ${await res.text()}`);
  }

  const route = await res.json();
  console.log("Generated route:", route);
})();
```

### Example Response

```json
{
    "estAmountOut": "100000000000000000",
    "minAmountOut": "100000000000000000",
    "transactions": {
        "swap": {
            "to": "...",
            "data": "...",
            "value": "..."
        }
    },
    "xSwapFees": {
        "ccipFee": "1929371550307947",
        "xSwapFee": {
            "tokenFee": "0",
            "nativeFee": "246913580246913"
        },
        "expressDeliveryFee": "0"
    }
}
```


---

# Agent Instructions: 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:

```
GET https://docs.xswap.link/xswap/xpay/api-v1-reference/route.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.