Advanced Routes

Get multiple route options for comparison. This endpoint returns all available routes sorted by your preference (output, time, cost, etc.).

If you want to learn more about how to use this endpoint, please have a look at our guide.

API

Endpoint Details

POST /v1/advanced/routes

Get multiple route options for comparison. This endpoint returns all available routes sorted by your preference (output, time, cost, etc.).

Request

Headers

X-API-Keystring

The apiKey allows you to authenticate on the API (optional)

Content-Typestringrequired

Must be `application/json`

Request Body

fromChainIdstringrequired

Source chain ID

Example: 1

fromTokenAddressstringrequired

Source token address

Example: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

toChainIdstringrequired

Destination chain ID

Example: 137

toTokenAddressstringrequired

Destination token address

Example: 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174

fromAmountstringrequired

Amount to swap (with decimals)

Example: 1000000

fromAddressstring

Sender wallet address

Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

toAddressstring

Recipient wallet address

Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

▼optionsobject

Advanced routing options

slippagenumber

Slippage tolerance (0.005 = 0.5%)

Example: 0.005

orderstring

Sort order: OUTPUT, TIME, GAS, COST, SAFETY

Example: OUTPUT

maxRoutesnumber

Maximum number of routes to return (default: 10)

Example: 5

▼bridgesobject

Bridge filtering options

allowstring[]

Only use these bridges

Example: ["stargate", "across"]

denystring[]

Never use these bridges

Example: ["hop"]

preferstring[]

Prefer these bridges (affects sorting)

Example: ["stargate"]

Response

Status Code: 200 OK
Content Type: application/json

Response

▼routesobject[]required

Array of available routes, sorted by the specified order

idstringrequired

Unique route identifier

toolstringrequired

Bridge or DEX used for this route

▼estimateobjectrequired

Route estimate details

toAmountstringrequired

Expected amount to receive

executionDurationnumber

Estimated execution time in seconds

feeCostsobject[]

Array of fee costs

gasCostsobject[]

Array of gas costs

transactionRequestobject

Transaction data ready to be sent

Route Comparison

The routes are sorted based on the order parameter:

Order	Sorts By	Best For
OUTPUT	Highest output amount	Maximum received tokens
TIME	Fastest execution	Quick transactions
GAS	Lowest gas cost	Minimizing transaction fees
COST	Lowest total cost (gas + fees)	Overall cheapest option
SAFETY	Fewest steps + reliable bridges	Risk-averse users

Example Request

curl --request POST \
  --url https://xplore.api.v2.routerprotocol.com/v1/advanced/routes \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: your-api-key-here' \
  --data '{
    "fromChainId": "1",
    "fromTokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "toChainId": "137",
    "toTokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
    "fromAmount": "1000000",
    "fromAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "toAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "options": {
      "slippage": 0.005,
      "order": "OUTPUT",
      "maxRoutes": 5,
      "bridges": {
        "allow": ["stargate", "across", "relay"]
      }
    }
  }'

Example Response

Status Code: 200 OK

{
  "routes": [
    {
      "id": "route-uuid-1",
      "type": "lifi",
      "tool": "stargate",
      "toolDetails": {
        "key": "stargate",
        "name": "Stargate",
        "logoURI": "https://..."
      },
      "action": {
        "fromChainId": "1",
        "toChainId": "137",
        "fromToken": {
          "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          "chainId": "1",
          "symbol": "USDC",
          "decimals": 6,
          "name": "USD Coin"
        },
        "toToken": {
          "address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
          "chainId": "137",
          "symbol": "USDC",
          "decimals": 6,
          "name": "USD Coin"
        },
        "fromAmount": "1000000"
      },
      "estimate": {
        "fromAmount": "1000000",
        "toAmount": "995000",
        "toAmountMin": "990025",
        "executionDuration": 120
      },
      "transactionRequest": {
        "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "to": "0x8731d54E9D02c286767d56ac03e8037C07e01e98",
        "chainId": "1",
        "data": "0x...",
        "value": "0x0"
      }
    },
    {
      "id": "route-uuid-2",
      "type": "lifi",
      "tool": "across",
      "estimate": {
        "toAmount": "993000",
        "executionDuration": 180
      }
    }
  ]
}

Code Examples

JavaScript/TypeScript

interface AdvancedRoutesParams {
  fromChainId: string;
  fromTokenAddress: string;
  toChainId: string;
  toTokenAddress: string;
  fromAmount: string;
  fromAddress?: string;
  toAddress?: string;
  options?: {
    slippage?: number;
    order?: 'OUTPUT' | 'TIME' | 'GAS' | 'COST' | 'SAFETY';
    maxRoutes?: number;
    bridges?: {
      allow?: string[];
      deny?: string[];
      prefer?: string[];
    };
  };
}

async function getAdvancedRoutes(params: AdvancedRoutesParams) {
  const response = await fetch(
    'https://xplore.api.v2.routerprotocol.com/v1/advanced/routes',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'your-api-key-here'
      },
      body: JSON.stringify(params)
    }
  );

  return await response.json();
}

// Usage
const routes = await getAdvancedRoutes({
  fromChainId: '1',
  fromTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  toChainId: '137',
  toTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
  fromAmount: '1000000',
  options: {
    order: 'OUTPUT',
    maxRoutes: 5,
    bridges: {
      allow: ['stargate', 'across']
    }
  }
});

// Get the fastest route
const fastest = routes.routes.find(r => 
  r.estimate.executionDuration === Math.min(...routes.routes.map(r => r.estimate.executionDuration))
);

Python

import requests

def get_advanced_routes(from_chain_id, from_token_address, to_chain_id, 
                        to_token_address, from_amount, from_address=None,
                        to_address=None, options=None):
    payload = {
        'fromChainId': from_chain_id,
        'fromTokenAddress': from_token_address,
        'toChainId': to_chain_id,
        'toTokenAddress': to_token_address,
        'fromAmount': from_amount,
    }
    
    if from_address:
        payload['fromAddress'] = from_address
    if to_address:
        payload['toAddress'] = to_address
    if options:
        payload['options'] = options
    
    response = requests.post(
        'https://xplore.api.v2.routerprotocol.com/v1/advanced/routes',
        json=payload,
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': 'your-api-key-here'
        }
    )
    return response.json()

# Usage
routes = get_advanced_routes(
    from_chain_id=1,
    from_token_address='0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    to_chain_id=137,
    to_token_address='0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
    from_amount='1000000',
    options={
        'order': 'OUTPUT',
        'maxRoutes': 5,
        'bridges': {
            'allow': ['stargate', 'across']
        }
    }
)

# Get the fastest route
fastest = min(routes['routes'], key=lambda r: r['estimate']['executionDuration'])