Skip to main content
GET
/
v1
/
quote
Get a swap quote
curl --request GET \
  --url https://api.hypermid.io/v1/quote \
  --header 'X-API-Key: <api-key>'
{
  "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
    }
  }
}

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.

Returns the best available quote for swapping tokens between chains. Hypermid compares routes across all available providers and returns the optimal one.
​
fromChain
number
required
Source chain ID (e.g., 1 for Ethereum).
​
toChain
number
required
Destination chain ID (e.g., 42161 for Arbitrum).
​
fromToken
string
required
Source token contract address. Use 0x0000000000000000000000000000000000000000 for native tokens on EVM chains.
​
toToken
string
required
Destination token contract address.
​
fromAmount
string
required
Amount to swap in the smallest unit (e.g., wei for ETH). Must be a string to handle large numbers.
​
fromAddress
string
required
Sender wallet address on the source chain.
​
toAddress
string
Recipient wallet address on the destination chain. Defaults to fromAddress if not provided.
​
slippage
number
Maximum acceptable slippage as a decimal (e.g., 0.03 for 3%). Default: 0.03.
​
tools
string
Comma-separated list of tools to consider (e.g., stargate,hop). Default: all available tools.
​
denyTools
string
Comma-separated list of tools to exclude (e.g., across).
​
preferredTool
string
Preferred tool to use if available (e.g., stargate).

​
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 page for how to handle both. For examples and a walkthrough, see the PulseChain Swaps guide. 
{
  "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
    }
  }
}

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

​
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 for the state machine, all failure modes, and what to display on each terminal state.

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 (use 'native' or the zero address for native tokens)

​
fromAmount
string
required

Amount in base units (wei, lamports, etc.)

​
toChain
integer
required

Destination chain ID

​
toToken
string
required

Destination token address

​
fromAddress
string
required

Sender wallet address

​
toAddress
string

Recipient wallet address. Omit for a dry (indicative) quote.

​
slippage
number

Slippage tolerance. Values < 1 are treated as decimal (0.005 = 0.5%), otherwise as basis points. Default: 50 bps (0.5%).

​
order
enum<string>

Route ranking preference

Available options:
RECOMMENDED,
FASTEST,
CHEAPEST

Response

Quote found

​
data
object
required

Response payload (null on error)

​
error
object
required
​
meta
object
required