# Get Swap Route (/swap-route)



<Endpoint method="GET" path="/aggregator/{chain_id}" />

The core endpoint. Returns the optimal split-route across all available liquidity sources for the
given chain. Routes are simulation-verified and the response includes ready-to-use calldata for
direct on-chain execution via the Nordstern Guard Contract.

## Parameters [#parameters]

<Properties>
  <Property name="chain_id" type="integer">
    EVM-compatible chain ID (path parameter).
  </Property>

  <Property name="src" type="string">
    Contract address of the input token. Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for the
    chain's native token (ETH, MATIC, BNB, etc.).
  </Property>

  <Property name="dst" type="string">
    Contract address of the output token. Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` to
    receive the chain's native token.
  </Property>

  <Property name="amount" type="string">
    Amount of the input token in its base units (e.g. `1000000000000000000` for 1 ETH, `1000000`
    for 1 USDC). Use string format to safely handle uint256 values.
  </Property>

  <Property name="from" type="string">
    Wallet address that will receive the output tokens.
  </Property>

  <Property name="slippage" type="number">
    Slippage tolerance in percent. Default: 0.5.
  </Property>

  <Property name="convenienceFee" type="number">
    Convenience fee in percent to be added. Default: 0.
  </Property>

  <Property name="convenienceFeeRecipient" type="string">
    Address to receive the convenience fee.
  </Property>
</Properties>

## Request [#request]

<Tabs items="['cURL', 'JavaScript', 'Python']">
  <Tab value="cURL">
    ```bash
    curl 'https://api.nordstern.finance/aggregator/8453?src=0x4200000000000000000000000000000000000006&dst=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&amount=1000000000000000000&from=0xYourWalletAddress&slippage=0.5' \
      -H "Referer: https://yourdomain.com"
    ```
  </Tab>

  <Tab value="JavaScript">
    ```js
    const params = new URLSearchParams({
      src: "0x4200000000000000000000000000000000000006",
      dst: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      amount: "1000000000000000000",
      from: "0xYourWalletAddress",
      slippage: "0.5",
    });

    const response = await fetch(
      `https://api.nordstern.finance/aggregator/8453?${params}`,
      { headers: { "Referer": "https://yourdomain.com" } }
    );
    const route = await response.json();
    console.log(route);
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import requests

    url = "https://api.nordstern.finance/aggregator/8453"
    params = {
        "src": "0x4200000000000000000000000000000000000006",
        "dst": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "amount": "1000000000000000000",
        "from": "0xYourWalletAddress",
        "slippage": 0.5,
    }
    headers = {"Referer": "https://yourdomain.com"}
    response = requests.get(url, params=params, headers=headers)
    print(response.json())
    ```
  </Tab>
</Tabs>

## Response [#response]

<Properties>
  <Property name="src" type="string">
    Source token address (echoes request param).
  </Property>

  <Property name="dst" type="string">
    Destination token address (echoes request param).
  </Property>

  <Property name="fromAmount" type="string">
    Input amount in the token's base units. Matches the request amount.
  </Property>

  <Property name="toAmount" type="string">
    `"0"` means no route was found.
  </Property>

  <Property name="gasEstimate" type="string">
    Estimated gas units the transaction will consume. Add a 20% buffer when using this as a gas
    limit. Do not pass it directly.
  </Property>

  <Property name="simulationBlock" type="integer">
    Block number at which the route was simulated. Revalidate if more than 1–2 blocks have elapsed
    before submission.
  </Property>

  <Property name="swaps" type="object[] | null">
    Array of internal swap legs.
  </Property>

  <Property name="tx" type="object">
    Ready-to-submit EVM transaction. Pass this directly to your wallet or provider.
  </Property>
</Properties>

### The `tx` object [#the-tx-object]

<Properties>
  <Property name="tx.from" type="string">
    Sender wallet address (echoes request `from` param).
  </Property>

  <Property name="tx.to" type="string">
    Guard Contract address for this chain.
  </Property>

  <Property name="tx.data" type="string">
    Encoded transaction calldata. Submit as-is. Do not modify.
  </Property>

  <Property name="tx.value" type="string">
    `"0"` for ERC-20 inputs. Non-zero when `src` is
    `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`. Pass it directly when submitting the transaction.
  </Property>
</Properties>

```json
{
  "src": "0x4200000000000000000000000000000000000006",
  "dst": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "fromAmount": "1000000000000000000",
  "toAmount": "2120362157",
  "gasEstimate": "1045694",
  "simulationBlock": 46334743,
  "swaps": ...,
  "tx": {
    "from": "0xYourWalletAddress",
    "to": "0xC87De04e2EC1F4282dFF2933A2D58199f688fC3d",
    "data": "0x3f0bde25...",
    "value": "0"
  }
}
```

## Before submitting [#before-submitting]

The API always returns `200`. `toAmount` must be non-zero and `route.tx` must exist. Otherwise the
route was not found or simulation failed.

```js
if (!route.tx || route.toAmount === "0") {
  throw new Error("No valid route available");
}
```

<Note>
  Before submitting the transaction, approve the Guard Contract (<C>tx.to</C>) to spend your input
  token. Call <C>approve(routerAddress, amount)</C> on the ERC-20 contract. If the allowance is
  already sufficient, skip this step.
</Note>

## Errors [#errors]

| Code  | Meaning                                                                         |
| ----- | ------------------------------------------------------------------------------- |
| `400` | Missing or invalid parameter. The plain-text response body describes the issue. |
| `404` | Chain ID not supported.                                                         |

See [Errors](/errors) for the full error format.