> ## 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 Quote

> Get the best swap quote for a token pair

Returns the best available quote for swapping tokens between chains. Hypermid compares routes across all available providers and returns the optimal one.

<ParamField query="fromChain" type="number" required>
  Source chain ID (e.g., `1` for Ethereum).
</ParamField>

<ParamField query="toChain" type="number" required>
  Destination chain ID (e.g., `42161` for Arbitrum).
</ParamField>

<ParamField query="fromToken" type="string" required>
  Source token contract address. Use `0x0000000000000000000000000000000000000000` for native tokens on EVM chains.
</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 (e.g., wei for ETH). Must be a string to handle large numbers.
</ParamField>

<ParamField query="fromAddress" type="string" required>
  Sender wallet address on the source chain.
</ParamField>

<ParamField query="toAddress" type="string">
  Recipient wallet address on the destination chain. Defaults to `fromAddress` if not provided.
</ParamField>

<ParamField query="slippage" type="number">
  Maximum acceptable slippage as a decimal (e.g., `0.03` for 3%). Default: `0.03`.
</ParamField>

<ParamField query="tools" type="string">
  Comma-separated list of tools to consider (e.g., `stargate,hop`). Default: all available tools.
</ParamField>

<ParamField query="denyTools" type="string">
  Comma-separated list of tools to exclude (e.g., `across`).
</ParamField>

<ParamField query="preferredTool" type="string">
  Preferred tool to use if available (e.g., `stargate`).
</ParamField>

## PulseChain Swaps

PulseChain (chain ID `369`) works with the same endpoint — no special configuration. Just set `fromChain` or `toChain` to `369`.

Some routes return a `steps` array instead of a single `transactionRequest`. Check the [Execute Swap](/api-reference/execute) page for how to handle both.

For examples and a walkthrough, see the [PulseChain Swaps guide](/guides/superswap).

<Warning>
  **ERC20 approvals — approve `estimate.approvalAddress`.** Before broadcasting
  `transactionRequest`, approve the quote's **`estimate.approvalAddress`** (not
  `transactionRequest.to`) as the spender for `fromAmount`. For SuperSwap
  cross-chain quotes this is the source-chain Hypermid **DiamondShell** — and the
  backend may report it as a different address than `transactionRequest.to`.
  Approving the wrong address leaves the real spender without allowance and the
  swap reverts. Native-token inputs (zero address) need no approval. On wallets
  that support **EIP-5792 / EIP-7702** you can batch the approval and the swap
  into a single `wallet_sendCalls` interaction — see the
  [1-Tap Approve + Swap guide](/guides/batched-approval).
</Warning>

<ResponseExample>
  ```json 200 theme={"system"}
  {
    "data": {
      "id": "quote_abc123",
      "type": "lifi",
      "tool": "stargate",
      "action": {
        "fromChainId": 1,
        "toChainId": 42161,
        "fromToken": {
          "address": "0x0000000000000000000000000000000000000000",
          "symbol": "ETH",
          "decimals": 18,
          "priceUSD": "3250.00"
        },
        "toToken": {
          "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
          "symbol": "USDC",
          "decimals": 6,
          "priceUSD": "1.00"
        },
        "fromAmount": "1000000000000000000",
        "fromAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "toAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "slippage": 0.03
      },
      "estimate": {
        "fromAmount": "1000000000000000000",
        "fromAmountUSD": "3250.00",
        "toAmount": "3237500000",
        "toAmountUSD": "3237.50",
        "toAmountMin": "3140375000",
        "gasCosts": [
          {
            "type": "SEND",
            "amount": "5000000000000000",
            "amountUSD": "16.25",
            "token": {
              "symbol": "ETH",
              "decimals": 18
            }
          }
        ],
        "feeCosts": [
          {
            "name": "Bridge Fee",
            "amount": "3250000",
            "amountUSD": "3.25",
            "percentage": "0.001"
          }
        ],
        "executionDuration": 120
      }
    },
    "error": null,
    "meta": {
      "requestId": "f6a7b8c9-d0e1-2345-f012-456789012345",
      "timestamp": 1711234572,
      "rateLimit": {
        "limit": 2000,
        "remaining": 1994,
        "reset": 1711234627
      }
    }
  }
  ```

  ```json 404 theme={"system"}
  {
    "data": null,
    "error": {
      "code": "NO_ROUTE_FOUND",
      "message": "No route found for the given parameters",
      "details": {
        "fromChain": 1,
        "toChain": 42161,
        "fromToken": "0x...",
        "toToken": "0x..."
      }
    },
    "meta": {
      "requestId": "g7b8c9d0-e1f2-3456-0123-567890123456",
      "timestamp": 1711234573,
      "rateLimit": {
        "limit": 2000,
        "remaining": 1993,
        "reset": 1711234627
      }
    }
  }
  ```

  ```json SuperSwap Direct Inbound theme={"system"}
  {
    "data": {
      "quote": {
        "id": "superswap_abc123",
        "provider": "superswap",
        "tool": "superswap",
        "fromChainId": 8453,
        "toChainId": 369,
        "fromToken": {
          "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "symbol": "USDC",
          "decimals": 6
        },
        "toToken": {
          "address": "0xA1077a294dDE1B09bB078844df40758a5D0f9a27",
          "symbol": "WPLS",
          "decimals": 18
        },
        "fromAmount": "5000000",
        "fee": "15000",
        "feePercentage": "0.0030",
        "bridgeAmount": "4985000",
        "estimatedOutput": "332333333333333333333333",
        "minOutput": "322466333333333333333333",
        "bridgeGasEstimate": "10000000000000000",
        "estimatedDuration": 300,
        "senderContract": "0xAd96Fb4bEe3ca08Fb481B554f1819CCb1388CF79",
        "transactionRequest": {
          "to": "0xAd96Fb4bEe3ca08Fb481B554f1819CCb1388CF79",
          "data": "0x...",
          "value": "0x2386f26fc10000",
          "chainId": 8453,
          "gasLimit": "350000"
        }
      },
      "provider": "superswap",
      "feeBps": 30
    }
  }
  ```

  ```json SuperSwap Multi-step Inbound theme={"system"}
  {
    "data": {
      "quote": {
        "id": "superswap_multi_def456",
        "type": "multi-step",
        "provider": "superswap",
        "totalSteps": 1,
        "singleSignature": true,
        "estimate": {
          "fromAmount": "1000000000000000",
          "toAmount": "332333333333333333333333",
          "toAmountMin": "306000000000000000000000",
          "executionDuration": 360
        },
        "steps": [
          {
            "step": 1,
            "type": "lifi",
            "description": "Swap ETH → USDC on Base",
            "transactionRequest": {
              "to": "0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE",
              "data": "0x...",
              "value": "0x38d7ea4c68000",
              "chainId": 8453
            }
          },
          {
            "step": 2,
            "type": "superswap-automatic",
            "automated": true,
            "description": "Automatic: Bridge USDC → WPLS on PulseChain"
          }
        ],
        "instructions": {
          "step1": "Sign and broadcast the swap transaction on Base",
          "step2": "After Step 1 confirms, call POST /v1/inbound-receiver/register",
          "step3": "Done! Backend bridges USDC → WPLS automatically (~5 min)"
        },
        "afterStep1": {
          "action": "POST /v1/inbound-receiver/register",
          "signatureRequired": true,
          "eip712": {
            "domain": { "name": "HypermidInboundReceiver", "version": "1", "chainId": 8453 },
            "types": {
              "RegisterDeposit": [
                { "name": "txHash", "type": "bytes32" },
                { "name": "toAddress", "type": "address" },
                { "name": "outputToken", "type": "address" },
                { "name": "destinationDomain", "type": "uint32" }
              ]
            },
            "primaryType": "RegisterDeposit"
          }
        }
      }
    }
  }
  ```
</ResponseExample>

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const quote = await client.getQuote({
    fromChain: 1,
    toChain: 42161,
    fromToken: "0x0000000000000000000000000000000000000000",
    toToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    fromAmount: "1000000000000000000",
    fromAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    slippage: 0.03,
  });

  if (quote.data) {
    console.log("Output:", quote.data.estimate.toAmountUSD, "USD");
    console.log("Via:", quote.data.tool);
    console.log("Time:", quote.data.estimate.executionDuration, "seconds");
  }
  ```

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

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

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

## SuperSwap Refunds & Fallback

Quotes for PulseChain destinations can return `provider: "superswap"` in either a direct or multi-step shape. If the DEX leg later fails at execution time, the protocol automatically returns the bridged USDCh to the user's wallet — the user always ends up with spendable funds on PulseChain, even in the failure case.

See the [Safety & Fallback guide](/guides/safety-fallback) for the state machine, all failure modes, and what to display on each terminal state.


## OpenAPI

````yaml GET /v1/quote
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/quote:
    get:
      tags:
        - Swap
      summary: Get a swap quote
      description: >-
        Returns the best swap route for a given token pair. The API
        automatically chooses the provider:


        - **Near Intents** for Near Intents-only chains (TON, Tron, XRP,
        Bitcoin, Stellar, etc.)

        - **SuperSwap** for routes to/from PulseChain (369). Two sub-variants:
          - *Direct* (source is USDC on a Sender chain) — single tx, user signs HypermidSender.superSwap() directly. Response includes `senderContract` and `transactionRequest`.
          - *Multi-step* (source is NOT USDC) — LiFi swaps source → USDC routed into the InboundReceiver, then the backend bridges + swaps on PulseChain. Response carries `type: "multi-step"`, `steps[0].transactionRequest` for the user to sign, and an `afterStep1` payload the frontend must POST to `/v1/inbound-receiver/register` after confirmation.
        - **LI.FI** for all other EVM ↔ EVM routes (with partner fee injection).


        All responses include a `provider` field. Multi-step SuperSwap responses
        additionally carry `type: "multi-step"`, `singleSignature: true`,
        `totalSteps`, `intermediateChainId`, `intermediateToken`, `estimate: {
        toAmount, toAmountMin, executionDuration }`, `steps: [lifi,
        superswap-automatic]`, and `afterStep1: { eip712, body }`. See
        `/guides/safety-fallback` for the end-to-end flow including what happens
        when the automatic leg fails.
      operationId: getQuote
      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 (use 'native' or the zero address for native
            tokens)
        - name: fromAmount
          in: query
          required: true
          schema:
            type: string
          description: Amount in base units (wei, lamports, etc.)
        - 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. Omit for a dry (indicative) quote.
        - name: slippage
          in: query
          required: false
          schema:
            type: number
          description: >-
            Slippage tolerance. Values < 1 are treated as decimal (0.005 =
            0.5%), otherwise as basis points. Default: 50 bps (0.5%).
        - name: order
          in: query
          required: false
          schema:
            type: string
            enum:
              - RECOMMENDED
              - FASTEST
              - CHEAPEST
          description: Route ranking preference
      responses:
        '200':
          description: Quote found
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/QuoteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '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
    QuoteResponse:
      type: object
      properties:
        quote:
          type: object
          description: Provider-specific quote payload
        provider:
          type: string
          enum:
            - lifi
            - near-intents
        feeBps:
          type: integer
          description: Partner fee in basis points
          example: 30
        isDryQuote:
          type: boolean
          description: True when no toAddress was provided
    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'
    RateLimited:
      description: Rate limit exceeded
      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/*.

````