> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypermid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Routes

> Get multiple swap routes for comparison

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.

<ParamField query="fromChain" type="number" required>
  Source chain ID.
</ParamField>

<ParamField query="toChain" type="number" required>
  Destination chain ID.
</ParamField>

<ParamField query="fromToken" type="string" required>
  Source token contract address.
</ParamField>

<ParamField query="toToken" type="string" required>
  Destination token contract address.
</ParamField>

<ParamField query="fromAmount" type="string" required>
  Amount to swap in the smallest unit.
</ParamField>

<ParamField query="fromAddress" type="string" required>
  Sender wallet address.
</ParamField>

<ParamField query="toAddress" type="string">
  Recipient wallet address. Defaults to `fromAddress`.
</ParamField>

<ParamField query="slippage" type="number">
  Maximum slippage tolerance. Default: `0.03`.
</ParamField>

<ParamField query="maxRoutes" type="number">
  Maximum number of routes to return. Default: `5`.
</ParamField>

<ParamField query="sortBy" type="string">
  Sort routes by `output` (highest output first), `speed` (fastest first), or `gas` (lowest gas first). Default: `output`.
</ParamField>

<ResponseExample>
  ```json 200 theme={"system"}
  {
    "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
      }
    }
  }
  ```
</ResponseExample>

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  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`);
  }
  ```

  ```bash cURL theme={"system"}
  curl "https://api.hypermid.io/v1/routes?\
  fromChain=1&toChain=42161&\
  fromToken=0x0000000000000000000000000000000000000000&\
  toToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&\
  fromAmount=1000000000000000000&\
  fromAddress=0xYourAddress&\
  maxRoutes=3" \
    -H "X-API-Key: your-api-key"
  ```

  ```go Go theme={"system"}
  url := "https://api.hypermid.io/v1/routes?" +
      "fromChain=1&toChain=42161" +
      "&fromToken=0x0000000000000000000000000000000000000000" +
      "&toToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831" +
      "&fromAmount=1000000000000000000" +
      "&fromAddress=0xYourAddress"

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Set("X-API-Key", "your-api-key")
  resp, _ := http.DefaultClient.Do(req)
  ```
</CodeGroup>


## OpenAPI

````yaml GET /v1/routes
openapi: 3.0.3
info:
  title: Hypermid Partner API
  version: 1.0.0
  description: >-
    Cross-chain swap aggregator API. Supports 30+ EVM chains, Solana, Bitcoin,
    Sui, and Near Intents chains (NEAR, TON, Tron, XRP, etc.).


    ## Authentication

    Pass your API key via the `X-API-Key` header. Public endpoints work without
    a key (anonymous tier). Partner endpoints (`/v1/partner/*`) require a valid
    key.


    ## Rate Limits

    - **Anonymous**: 30 requests/minute (per IP)

    - **Partner (authenticated)**: 100 requests/minute (per API key)


    These limits are designed for human-driven widget usage and mirror our
    upstream aggregator (LiFi) limits to prevent any single user from exhausting
    shared quota.


    Rate limit info is returned in `meta.rateLimit` on every response.


    ## Response Envelope

    All responses follow the shape:

    ```json

    { "data": <T | null>, "error": <{ code, message, details? } | null>, "meta":
    { "requestId", "timestamp", "rateLimit?" } }

    ```
  contact:
    name: Hypermid
    url: https://hypermid.io
servers:
  - url: https://api.hypermid.io
    description: Production
security:
  - ApiKeyAuth: []
  - {}
tags:
  - name: Swap
    description: Cross-chain swap quoting, routing, status, and reference data
  - name: Execute
    description: Transaction execution and deposit management for Near Intents swaps
  - name: On-Ramp
    description: Fiat-to-crypto on-ramp via RampNow
  - name: Partner
    description: Partner account, analytics, and webhook management (requires X-API-Key)
  - name: Tracking
    description: Swap event tracking for partner attribution
  - name: System
    description: Health check and API metadata
paths:
  /v1/routes:
    get:
      tags:
        - Swap
      summary: Get multiple swap routes
      description: Returns multiple route options for a swap via LI.FI advanced routing.
      operationId: getRoutes
      parameters:
        - name: fromChain
          in: query
          required: true
          schema:
            type: integer
          description: Source chain ID
        - name: fromToken
          in: query
          required: true
          schema:
            type: string
          description: Source token address
        - name: fromAmount
          in: query
          required: true
          schema:
            type: string
          description: Amount in base units
        - name: toChain
          in: query
          required: true
          schema:
            type: integer
          description: Destination chain ID
        - name: toToken
          in: query
          required: true
          schema:
            type: string
          description: Destination token address
        - name: fromAddress
          in: query
          required: true
          schema:
            type: string
          description: Sender wallet address
        - name: toAddress
          in: query
          required: false
          schema:
            type: string
          description: Recipient wallet address
        - name: slippage
          in: query
          required: false
          schema:
            type: number
          description: Slippage tolerance
        - name: order
          in: query
          required: false
          schema:
            type: string
            enum:
              - RECOMMENDED
              - FASTEST
              - CHEAPEST
              - SAFEST
      responses:
        '200':
          description: Routes found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/UpstreamError'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        data:
          description: Response payload (null on error)
        error:
          nullable: true
          type: object
          properties:
            code:
              type: string
              example: INVALID_PARAMS
            message:
              type: string
              example: 'Missing required parameters: fromChain'
            details:
              type: object
              additionalProperties: true
          required:
            - code
            - message
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - data
        - error
        - meta
    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          type: integer
          description: Unix epoch seconds
        rateLimit:
          type: object
          properties:
            limit:
              type: integer
            remaining:
              type: integer
            reset:
              type: integer
              description: Unix epoch seconds when the window resets
      required:
        - requestId
        - timestamp
  responses:
    BadRequest:
      description: Invalid or missing parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
    NotFound:
      description: Resource not found or no route available
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
    UpstreamError:
      description: Upstream provider error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Partner API key. Optional for public endpoints, required for
        /v1/partner/*.

````