Skip to main content
GET
/
v1
/
routes
Get multiple swap routes
curl --request GET \
  --url https://api.hypermid.io/v1/routes \
  --header 'X-API-Key: <api-key>'
{
  "data": {
    "routes": [
      {
        "id": "route_1",
        "tool": "stargate",
        "estimate": {
          "toAmount": "3237500000",
          "toAmountUSD": "3237.50",
          "gasCosts": [{ "amountUSD": "16.25" }],
          "executionDuration": 120
        },
        "tags": ["BEST_OUTPUT"]
      },
      {
        "id": "route_2",
        "tool": "across",
        "estimate": {
          "toAmount": "3235000000",
          "toAmountUSD": "3235.00",
          "gasCosts": [{ "amountUSD": "12.50" }],
          "executionDuration": 60
        },
        "tags": ["FASTEST"]
      },
      {
        "id": "route_3",
        "tool": "hop",
        "estimate": {
          "toAmount": "3230000000",
          "toAmountUSD": "3230.00",
          "gasCosts": [{ "amountUSD": "10.00" }],
          "executionDuration": 180
        },
        "tags": ["CHEAPEST"]
      }
    ]
  },
  "error": null,
  "meta": {
    "requestId": "h8c9d0e1-f2a3-4567-1234-678901234567",
    "timestamp": 1711234574,
    "rateLimit": {
      "limit": 2000,
      "remaining": 1992,
      "reset": 1711234627
    }
  }
}
Returns multiple available routes for a swap, allowing you to compare options and let the user choose. Unlike /v1/quote which returns only the best route, this endpoint returns all viable routes. You can also use POST /v1/routes with a JSON body for complex queries.
​
fromChain
number
required
Source chain ID.
​
toChain
number
required
Destination chain ID.
​
fromToken
string
required
Source token contract address.
​
toToken
string
required
Destination token contract address.
​
fromAmount
string
required
Amount to swap in the smallest unit.
​
fromAddress
string
required
Sender wallet address.
​
toAddress
string
Recipient wallet address. Defaults to fromAddress.
​
slippage
number
Maximum slippage tolerance. Default: 0.03.
​
maxRoutes
number
Maximum number of routes to return. Default: 5.
​
sortBy
string
Sort routes by output (highest output first), speed (fastest first), or gas (lowest gas first). Default: output.
{
  "data": {
    "routes": [
      {
        "id": "route_1",
        "tool": "stargate",
        "estimate": {
          "toAmount": "3237500000",
          "toAmountUSD": "3237.50",
          "gasCosts": [{ "amountUSD": "16.25" }],
          "executionDuration": 120
        },
        "tags": ["BEST_OUTPUT"]
      },
      {
        "id": "route_2",
        "tool": "across",
        "estimate": {
          "toAmount": "3235000000",
          "toAmountUSD": "3235.00",
          "gasCosts": [{ "amountUSD": "12.50" }],
          "executionDuration": 60
        },
        "tags": ["FASTEST"]
      },
      {
        "id": "route_3",
        "tool": "hop",
        "estimate": {
          "toAmount": "3230000000",
          "toAmountUSD": "3230.00",
          "gasCosts": [{ "amountUSD": "10.00" }],
          "executionDuration": 180
        },
        "tags": ["CHEAPEST"]
      }
    ]
  },
  "error": null,
  "meta": {
    "requestId": "h8c9d0e1-f2a3-4567-1234-678901234567",
    "timestamp": 1711234574,
    "rateLimit": {
      "limit": 2000,
      "remaining": 1992,
      "reset": 1711234627
    }
  }
}

const routes = await client.getRoutes({
  fromChain: 1,
  toChain: 42161,
  fromToken: "0x0000000000000000000000000000000000000000",
  toToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  fromAmount: "1000000000000000000",
  fromAddress: "0xYourAddress",
  sortBy: "output",
  maxRoutes: 3,
});

for (const route of routes.data.routes) {
  console.log(`${route.tool}: ${route.estimate.toAmountUSD} USD, ` +
    `${route.estimate.executionDuration}s, ` +
    `gas: ${route.estimate.gasCosts[0].amountUSD} USD`);
}

Authorizations

​
X-API-Key
string
header
required

Partner API key. Optional for public endpoints, required for /v1/partner/*.

Query Parameters

​
fromChain
integer
required

Source chain ID

​
fromToken
string
required

Source token address

​
fromAmount
string
required

Amount in base units

​
toChain
integer
required

Destination chain ID

​
toToken
string
required

Destination token address

​
fromAddress
string
required

Sender wallet address

​
toAddress
string

Recipient wallet address

​
slippage
number

Slippage tolerance

​
order
enum<string>
Available options:
RECOMMENDED,
FASTEST,
CHEAPEST,
SAFEST

Response

Routes found

​
data
any
required

Response payload (null on error)

​
error
object
required
​
meta
object
required