Get Swap Route

GET/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

chain_idreqinteger

EVM-compatible chain ID (path parameter).

srcreqstring

Contract address of the input token. Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for the chain's native token (ETH, MATIC, BNB, etc.).

dstreqstring

Contract address of the output token. Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE to receive the chain's native token.

amountreqstring

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.

fromreqstring

Wallet address that will receive the output tokens.

slippagenumber

Slippage tolerance in percent. Default: 0.5.

convenienceFeenumber

Convenience fee in percent to be added. Default: 0.

convenienceFeeRecipientstring

Address to receive the convenience fee.

Request

curl 'https://api.nordstern.finance/aggregator/8453?src=0x4200000000000000000000000000000000000006&dst=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&amount=1000000000000000000&from=0xYourWalletAddress&slippage=0.5' \
  -H "Referer: https://yourdomain.com"

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);

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())

Response

srcstring

Source token address (echoes request param).

dststring

Destination token address (echoes request param).

fromAmountstring

Input amount in the token's base units. Matches the request amount.

toAmountstring

Expected output amount in the destination token's base units. Always non-zero — when no route is found the API responds with 422 instead (see Errors).

gasEstimatestring

Estimated gas units the transaction will consume. Add a 20% buffer when using this as a gas limit. Do not pass it directly.

simulationBlockinteger

Block number at which the route was simulated. Revalidate if more than 1–2 blocks have elapsed before submission.

swapsobject[]

Array of internal swap legs. Always contains at least one entry.

txobject

Ready-to-submit EVM transaction. Pass this directly to your wallet or provider.

The `tx` object

tx.fromstring

Sender wallet address (echoes request from param).

tx.tostring

Guard Contract address for this chain.

tx.datastring

Encoded transaction calldata. Submit as-is. Do not modify.

tx.valuestring

"0" for ERC-20 inputs. Non-zero when src is 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE. Pass it directly when submitting the transaction.

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

Error handling

A 200 response always contains a usable route: non-zero toAmount and a tx object. Every failure — no route found, simulation revert, invalid parameters — returns an HTTP error status with a JSON {"error": "..."} body instead, so check the status code before reading the route:

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Route request failed (${response.status}): ${error}`);
}
const route = await response.json();

Note:

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

Errors

Code	Meaning
`400`	Missing or invalid parameter. The JSON response body describes the issue.
`403`	Disallowed parameter combination (e.g. convenience fee above 10%, invalid fee-exempt key).
`404`	Chain ID not supported.
`422`	No swap route found (unknown token, insufficient liquidity), or the route reverted in simulation. Not retryable with the same inputs.
`500`	Unexpected server error.
`502`	The RPC node backing the simulation failed. Safe to retry.
`503`	Liquidity state behind the requested `minimumBlock`, or server overloaded. Retry after a short delay.
`504`	Request timed out before routing finished. Safe to retry.

See Errors for the full error format.