Get a swap quote
curl --request GET \
--url https://api.hypermid.io/v1/quote \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hypermid.io/v1/quote"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.hypermid.io/v1/quote', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hypermid.io/v1/quote",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.hypermid.io/v1/quote"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.hypermid.io/v1/quote")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hypermid.io/v1/quote")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"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
}
}
}
{
"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
}
}
}
{
"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
}
}
{
"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"
}
}
}
}
}
Swap
Get Quote
Get the best swap quote for a token pair
GET
/
v1
/
quote
Get a swap quote
curl --request GET \
--url https://api.hypermid.io/v1/quote \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hypermid.io/v1/quote"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.hypermid.io/v1/quote', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hypermid.io/v1/quote",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.hypermid.io/v1/quote"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.hypermid.io/v1/quote")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hypermid.io/v1/quote")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"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
}
}
}
{
"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
}
}
}
{
"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
}
}
{
"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"
}
}
}
}
}
Returns the best available quote for swapping tokens between chains. Hypermid compares routes across all available providers and returns the optimal one.
Source chain ID (e.g.,
1 for Ethereum).Destination chain ID (e.g.,
42161 for Arbitrum).Source token contract address. Use
0x0000000000000000000000000000000000000000 for native tokens on EVM chains.Destination token contract address.
Amount to swap in the smallest unit (e.g., wei for ETH). Must be a string to handle large numbers.
Sender wallet address on the source chain.
Recipient wallet address on the destination chain. Defaults to
fromAddress if not provided.Maximum acceptable slippage as a decimal (e.g.,
0.03 for 3%). Default: 0.03.Comma-separated list of tools to consider (e.g.,
stargate,hop). Default: all available tools.Comma-separated list of tools to exclude (e.g.,
across).Preferred tool to use if available (e.g.,
stargate).PulseChain Swaps
PulseChain (chain ID369) 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.
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.{
"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
}
}
}
{
"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
}
}
}
{
"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
}
}
{
"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"
}
}
}
}
}
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");
}
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"
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)
SuperSwap Refunds & Fallback
Quotes for PulseChain destinations can returnprovider: "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
Partner API key. Optional for public endpoints, required for /v1/partner/*.
Query Parameters
Source chain ID
Source token address (use 'native' or the zero address for native tokens)
Amount in base units (wei, lamports, etc.)
Destination chain ID
Destination token address
Sender wallet address
Recipient wallet address. Omit for a dry (indicative) quote.
Slippage tolerance. Values < 1 are treated as decimal (0.005 = 0.5%), otherwise as basis points. Default: 50 bps (0.5%).
Route ranking preference
Available options:
RECOMMENDED, FASTEST, CHEAPEST ⌘I