# 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) 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"
    }
}
```