Bridge Integration Guide
Smart Bridge Routing Integration Guide
This guide outlines the HyperFlow API endpoints for generating bridge quotes (/quote) and constructing transactions (/encode).
It focuses on providing the simplest implementation to fetch and execute bridge quotes through the API. For more advanced use cases and detailed explanations of parameters and features, please refer to the Swagger documentation.
Bridge Flow
This diagram illustrates the flow of a bridge transaction using the HyperFlow API. The subsequent steps describe how to perform each stage of the process.
Step 1: Generate a Quote
The first step in using the HyperFlow Bridge API is to generate a quote. This is done by submitting a POST request to the /v1/quote.
Required parameters:
fromChain: The source chain identifier (e.g., ethereum).fromToken: The token address on the source chain. Use the native placeholder 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for gas tokens.toChain: The destination chain identifier (e.g., hyperevm).toToken: The token address on the destination chain. Use the same native placeholder for gas tokens.amount: The amount to transfer, as a string representing the fixed-precision integer in the token’s smallest units. Example: 500000000000000000 = 0.5 ETH.protocols: Comma-separated list of protocols to consider. Supported values: kyberswap, hyperflow, wrapnative, hypercore, layerzero, hyperunit, gaszip, relay.
Optional but recommended parameters:
sender: The address of the user initiating the transfer.receiver: The address of the user who will receive the funds on the destination chain.slippage: The maximum percentage of slippage the user is willing to accept, where 100 represents 1%. Default is 100.
Note: When the sender and receiver parameters are provided, the /v1/quote endpoint returns both the quote details and a request_id, which is required to assemble the transaction using /v1/encode. In contrast, the quote API can be used solely to fetch rates when the user has not connected their wallet.
const api = "<https://bridge-ag-api.hyperflow.fun/v1>";
const params = {
fromChain: "ethereum",
fromToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
toChain: "hyperevm",
toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
amount: "500000000000000000",
protocols: "kyberswap,hyperflow,wrapnative,hypercore,layerzero,hyperunit,gaszip,relay",
sender: "0xf89d7b9c864f589bbF53a82105107622B35EaA40",
receiver: "0xf89d7b9c864f589bbF53a82105107622B35EaA40",
slippage: "100",
};
const query = new URLSearchParams(params).toString();
const quote = await fetch(`${api}/quote?${query}`).then((r) => r.json());
const amountOuts = quote.data.map(
(path) => ({amountOut: path.amountOut, bridge: path.crossProtocol.id})
);
console.log("requestId:", quote.requestId);
console.log("amountOuts:", amountOuts);# Example output:
requestId: 86ebef0d0cd6d1c7069fabcc1ca26989
amountOuts: [
{ amountOut: '8034986893632684032', bridge: 'gaszip' },
{ amountOut: '8012536653122581124', bridge: 'layerzero' },
{ amountOut: '8012260919909958289', bridge: 'layerzero' },
{ amountOut: '7923594347065026878', bridge: 'relay' },
{ amountOut: '7888846554498563072', bridge: 'mayan' }
]Step 2: Assemble the Transaction
To execute a HyperFlow quote on-chain, the transaction must first be assembled. The HyperFlow API handles this assembly automatically; manual construction is not supported. After obtaining the requestId from the quote and selecting the desired quote index, submit a POST request to the /v1/encode endpoint to retrieve the on-chain transaction data. Note that the requestId is only valid for 30 seconds after the quote is generated.
const selectedQuoteIndex = 0;
const txData = await fetch(`${api}/encode`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
requestId: quote.requestId,
quoteIdx: selectedQuoteIndex,
}),
}).then((r) => r.json());
console.log("txData:", txData);Step 3: Submit the Transaction
After retrieving the transaction details from the /v1/encode response, the transaction object can be signed and sent with an EOA wallet, or executed via a low-level smart contract call using the transaction.data field. Modifying transaction.data or manually constructing HyperFlow router function calls is not supported and should only be attempted at your own risk.
const rpc = "<https://arb1.arbitrum.io/rpc>";
const provider = new ethers.JsonRpcProvider(rpc);
const wallet = new ethers.Wallet(process.env.PRV_KEY, provider);
const txRes = await wallet.sendTransaction(transaction);
console.log("tx_hash:", txRes.hash);
const receipt = await txRes.wait();
console.log("mined_block:", receipt.blockNumber);Step 4: Get Bridge Status
Submitting a transaction on the source chain does not guarantee that the bridge is complete. To check the bridge status, call /v1/hyperbridge/orders with the src_tx (the source chain transaction hash). Possible statuses are: pending, done, refunded, or failed.
const tx_hash = "0x018c5d48906f82ca16e3eb7e0198954770ea3d275d16bd30f8b4cabf60c1b664";
const status = await fetch(`${api}/hyperbridge/orders?src_tx=${tx_hash}`).then((r) => r.json());
if (status.orders.length > 0) console.log("tx:", status.orders[0]);Need helps?
Refer to the Swagger documentation for detailed information on all endpoints, parameters, and usage.
Connect with other developers and the HyperFlow team in the Discord community.
Last updated