Bridge Integration

This guide covers the HyperFlow Bridge API endpoints for generating bridge quotes (/quote) and constructing transactions (/encode), with the simplest path to fetch and execute a bridge. For advanced use cases, see the OpenAPI spec (open it in the viewer of your choice, e.g. Swagger UI — a third-party viewer).

Base URL: https://bridge-ag-api.hyperflow.fun/v1 — all endpoints serve mainnet only; there is no public testnet environment. No API key is required; for partner access, contact the team on Discord.

Bridge flow

Four steps: 1 Quote (GET /quote — compare routes, get requestId), 2 Encode within 30 seconds (POST /encode — assemble the transaction), 3 Submit (sign and send on the source chain), 4 Track (GET /hyperbridge/orders until done or refunded).
1

Generate a quote

Submit a request to /quote with:

Required parameters

ParameterDescription
fromChainSource chain identifier (e.g. ethereum)
fromTokenToken address on the source chain. Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native gas tokens
toChainDestination chain identifier (e.g. hyperevm)
toTokenToken address on the destination chain (same native placeholder applies)
amountTransfer amount as a fixed-precision integer string in the token’s smallest unit (e.g. 500000000000000000 = 0.5 ETH)
protocolsComma-separated protocol ids to consider — see the table below; pass the full list to compare all routes

Optional (recommended)

ParameterDescription
senderAddress initiating the transfer
receiverAddress receiving funds on the destination chain
slippageMax slippage where 100 = 1% (default 100)
sourcePartner code for points attribution and CoreWriter flows — see Points Integration

Protocol ids

idRole
layerzeroBridge rail — USD₮0 / USDe canonical transfers
hyperunitBridge rail — native-asset rails (UETH, UBTC, USOL, UPUMP)
relayBridge rail — fast, low-cost transfers
mayanBridge rail — cross-chain swaps at size
gaszipBridge rail — small transfers and gas top-ups
hypercoreHyperliquid-native bridge — direct USDC via Hyperliquid’s bridge
hypercorespotHyperliquid-native swap leg — HyperCore spot order book
kyberswapSwap leg on EVM chains
hyperflowSwap leg — HyperFlow DEX aggregator on HyperEVM
wrapnativeSwap leg — wrap/unwrap the native token

The app’s “HyperFlow Prefunding” route is an app-level rail and has no public protocol id.

Chain identifiers (lowercase): ethereum, arbitrum, optimism, base, unichain, hypercore, flare, plasma, hyperevm.

When sender and receiver are provided, /quote returns both the quote details and a requestId, which is required to assemble the transaction with /encode. Without them, /quote can still be used purely to fetch rates before a wallet is connected.

1const api = "https://bridge-ag-api.hyperflow.fun/v1";
2const params = {
3 fromChain: "ethereum",
4 fromToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
5 toChain: "hyperevm",
6 toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
7 amount: "500000000000000000",
8 protocols: "kyberswap,hyperflow,wrapnative,hypercore,layerzero,hyperunit,gaszip,relay",
9 sender: "0xf89d7b9c864f589bbF53a82105107622B35EaA40",
10 receiver: "0xf89d7b9c864f589bbF53a82105107622B35EaA40",
11 slippage: "100",
12};
13
14const query = new URLSearchParams(params).toString();
15const quote = await fetch(`${api}/quote?${query}`).then((r) => r.json());
16const amountOuts = quote.data.map(
17 (path) => ({amountOut: path.amountOut, bridge: path.crossProtocol.id})
18);
19console.log("requestId:", quote.requestId);
20console.log("amountOuts:", amountOuts);

Example output:

1{
2 "requestId": "86ebef0d0cd6d1c7069fabcc1ca26989",
3 "amountOuts": [
4 { "amountOut": "8034986893632684032", "bridge": "gaszip" },
5 { "amountOut": "8012536653122581124", "bridge": "layerzero" },
6 { "amountOut": "8012260919909958289", "bridge": "layerzero" },
7 { "amountOut": "7923594347065026878", "bridge": "relay" },
8 { "amountOut": "7888846554498563072", "bridge": "mayan" }
9 ]
10}
2

Assemble the transaction

The HyperFlow API assembles the on-chain transaction — manual construction is not supported. Submit the requestId and your chosen quote index to /encode.

The requestId expires 30 seconds after the quote is generated.

1const selectedQuoteIndex = 0;
2const txData = await fetch(`${api}/encode`, {
3 method: "POST",
4 headers: { "Content-Type": "application/json" },
5 body: JSON.stringify({
6 requestId: quote.requestId,
7 quoteIdx: selectedQuoteIndex,
8 }),
9}).then((r) => r.json());
10console.log("txData:", txData);

/encode returns the transaction under data:

1{
2 "status": "ok",
3 "data": {
4 "to": "0xb4580138102bda0c7e8c9a05529ba5f70cdf1e93",
5 "value": "10000000000000000000",
6 "data": "0xb4c95169…"
7 },
8 "requestId": "52a26c2b01f0feadbb968869f7d40c82"
9}

data contains only to, value, and data — set the chain via your provider (connect to the source-chain RPC) and let your wallet estimate gas. Note that /encode returns a new requestId, distinct from the quote’s.

3

Submit the transaction

Sign and send txData.data with an EOA wallet, or execute it via a low-level contract call using the txData.data.data calldata. Modifying the calldata or hand-crafting HyperFlow router calls is unsupported and at your own risk.

1import { ethers } from "ethers"; // ^6
2
3const rpc = "https://ethereum-rpc.publicnode.com"; // RPC of the SOURCE chain (fromChain)
4const provider = new ethers.JsonRpcProvider(rpc);
5const wallet = new ethers.Wallet(process.env.PRV_KEY, provider);
6
7const txRes = await wallet.sendTransaction(txData.data); // { to, value, data }
8console.log("tx_hash:", txRes.hash);
9const receipt = await txRes.wait();
10console.log("mined_block:", receipt.blockNumber);
4

Track the bridge status

A confirmed source-chain transaction does not mean the bridge is complete. Poll /hyperbridge/orders with the source transaction hash. Each order’s state field can be pending, done, refunded, or failed.

1const status = await fetch(`${api}/hyperbridge/orders?src_tx=${txRes.hash}`).then((r) => r.json());
2if (status.orders.length > 0) console.log("order state:", status.orders[0].state);

Errors

Errors are returned as {"error": "<message>"}:

ResponseMeaning
400 {"error":"no quotes found"}The requestId is expired or unknown — re-quote and call /encode within 30 seconds
400 {"error":"chain not found"}Unrecognized chain identifier

Need help?