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

"0" means no route was found.

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[] | null

Array of internal swap legs.

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"
  }
}

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.

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

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 plain-text response body describes the issue.
`404`	Chain ID not supported.

See Errors for the full error format.