> Treat every fee rate, margin ratio, order limit, minimum and address in this documentation as an illustration of the shape of the value, never as a constant to hardcode - the live values are served by GET /markets and GET /config on the Perps API.

# Bridge Integration

> Quote, encode, and execute cross-chain transfers through the HyperFlow Bridge API.

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](https://bridge-ag-api.hyperflow.fun/v1/swagger) (open it in the viewer of your choice, e.g. [Swagger UI](https://petstore.swagger.io/?url=https://bridge-ag-api.hyperflow.fun/v1/swagger) — 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](https://discord.gg/GGDmD4K9CK).

## 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).](/_fern-files/hyperflowdefi.docs.buildwithfern.com/b1ee8fd52ee25c188d21bf1246167411096da4a9dbd0b6d6ca91319c6353e920/docs/assets/diagrams/bridge-flow.svg)

### Generate a quote

Submit a request to `/quote` with:

**Required parameters**

| Parameter   | Description                                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| `fromChain` | Source chain identifier (e.g. `ethereum`)                                                                              |
| `fromToken` | Token address on the source chain. Use `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` for native gas tokens              |
| `toChain`   | Destination chain identifier (e.g. `hyperevm`)                                                                         |
| `toToken`   | Token address on the destination chain (same native placeholder applies)                                               |
| `amount`    | Transfer amount as a fixed-precision integer string in the token's smallest unit (e.g. `500000000000000000` = 0.5 ETH) |
| `protocols` | Comma-separated protocol ids to consider — see the table below; pass the full list to compare all routes               |

**Optional (recommended)**

| Parameter  | Description                                                                                                         |
| ---------- | ------------------------------------------------------------------------------------------------------------------- |
| `sender`   | Address initiating the transfer                                                                                     |
| `receiver` | Address receiving funds on the destination chain                                                                    |
| `slippage` | Max slippage where `100` = 1% (default `100`)                                                                       |
| `source`   | Partner code for points attribution and CoreWriter flows — see [Points Integration](/developers/points-integration) |

**Protocol ids**

| id              | Role                                                             |
| --------------- | ---------------------------------------------------------------- |
| `layerzero`     | Bridge rail — USD₮0 / USDe canonical transfers                   |
| `hyperunit`     | Bridge rail — native-asset rails (UETH, UBTC, USOL, UPUMP)       |
| `relay`         | Bridge rail — fast, low-cost transfers                           |
| `mayan`         | Bridge rail — cross-chain swaps at size                          |
| `gaszip`        | Bridge rail — small transfers and gas top-ups                    |
| `hypercore`     | Hyperliquid-native bridge — direct USDC via Hyperliquid's bridge |
| `hypercorespot` | Hyperliquid-native swap leg — HyperCore spot order book          |
| `kyberswap`     | Swap leg on EVM chains                                           |
| `hyperflow`     | Swap leg — HyperFlow DEX aggregator on HyperEVM                  |
| `wrapnative`    | Swap 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**, always lowercase:

```
ethereum · arbitrum · optimism · base · unichain · flare · plasma · hyperevm · hypercore
```

> **Note**
>
> 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.

```javascript
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: "0xYourWalletAddress",
  receiver: "0xYourWalletAddress",
  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:

```json
{
  "requestId": "86ebef0d0cd6d1c7069fabcc1ca26989",
  "amountOuts": [
    { "amountOut": "8034986893632684032", "bridge": "gaszip" },
    { "amountOut": "8012536653122581124", "bridge": "layerzero" },
    { "amountOut": "8012260919909958289", "bridge": "layerzero" },
    { "amountOut": "7923594347065026878", "bridge": "relay" },
    { "amountOut": "7888846554498563072", "bridge": "mayan" }
  ]
}
```

### 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`.

> **Warning**
>
> The `requestId` expires **30 seconds** after the quote is generated.

```javascript
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);
```

`/encode` returns the transaction under `data`:

```json
{
  "status": "ok",
  "data": {
    "to": "0xb4580138102bda0c7e8c9a05529ba5f70cdf1e93",
    "value": "10000000000000000000",
    "data": "0xb4c95169…"
  },
  "requestId": "52a26c2b01f0feadbb968869f7d40c82"
}
```

`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.

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

```javascript
import { ethers } from "ethers"; // ^6

const rpc = "https://ethereum-rpc.publicnode.com"; // RPC of the SOURCE chain (fromChain)
const provider = new ethers.JsonRpcProvider(rpc);
const wallet = new ethers.Wallet(process.env.PRV_KEY, provider);

const txRes = await wallet.sendTransaction(txData.data); // { to, value, data }
console.log("tx_hash:", txRes.hash);
const receipt = await txRes.wait();
console.log("mined_block:", receipt.blockNumber);
```

### 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`.

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

## Errors

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

| Response                          | Meaning                                                                               |
| --------------------------------- | ------------------------------------------------------------------------------------- |
| `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?

* [OpenAPI spec](https://bridge-ag-api.hyperflow.fun/v1/swagger) for all endpoints and parameters.
* Bridging into HyperCore? See the [CoreWriter Integration](/developers/corewriter-integration).
* Swapping on HyperEVM only? See the [DEX Aggregator API](/developers/dex-aggregator).
* Join the developer community on [Discord](https://discord.gg/GGDmD4K9CK).