Bridge Quote

​

Query parameters

​

Response

{
  "data": {
    "intentId": "a3b4ba1-e34523c-324",
    "deadline": 1764032100,
    "typedData": { /* EIP-712 payload to sign — see Signed-quote flow */ },
    "signatureRequired": true,
    "prediction": { "persisted": false },
    "estimatedAmountOut": "0.68421052",
    "estimatedAmountOutUsd": "1.99",
    "recommendedSlippage": 1.5,
    "fees": {
      "bridgeFeeBps": 5,
      "bridgeFeeUsd": "0.0010",
      "destFillGasUsd": "0.0800",
      "gasFeeUsd": "0.0800",
      "totalFeeUsd": "0.0810",
      "integratorFeeBps": 30,
      "integratorFeeUsd": "0.0060",
      "destActivationCostUsd": "0.0020"
    },
    "estimatedTimeMs": 1000,
    "destinationType": "spot",
    "originType": "spot",
    "steps": [ /* optional, see below */ ],
    "deposit": { /* one of evm | solana | hl */ }
  }
}

• intentId is the user-facing handle, format xxxxxxx-xxxxxxx-xxx (lowercase hex). Pass it to GET /status/:id or /status/:id/wait. There is also an on-chain bytes32 intent ID emitted by MobulaBridge on EVM deposits — both resolve in /status/:id, so use whichever you have. You must echo this exact intentId back via the intentId query param when submitting the signature — the signed payload binds to it.
• deadline is Unix seconds. The server rejects signed calls past this point.
• typedData is the EIP-712 structured-data payload your wallet should sign (see Signed-quote flow for the full schema).
• signatureRequired: true for evm:* and hl:mainnet origins. false for solana:solana (the depositor-signed memo replaces the signature).
• prediction.persisted indicates whether the server has committed your signed intent. false on the unsigned preview call; true after a successful signed call.
• steps lists the on-chain transactions for EVM origins: [{type:'bridge'}] for native, [{type:'approve'},{type:'bridgeToken'}] for direct-bridge tokens, [{type:'approve'},{type:'swapAndBridge'}] for other ERC-20s. Solana and HL deposits omit steps.
• recommendedSlippage is the slippage % we suggest signing with — the measured price impact of the quote’s swap leg(s) (max across the origin and destination swaps; 0 for a direct stable transfer) plus any fee-on-transfer tax, plus a 1% drift buffer, rounded up to 0.01 and capped at 50. Native-token destinations are floored at 2% (the fill is served by a market swap). Bridge fee and destination gas are not part of it — they’re already deducted from the quoted output. The solver refunds any fill below the signed minAmountOut (failure code slippage), so a tolerance under this value is a near-guaranteed refund. If your slippage is below it, re-quote at the recommendation before signing.
• fees are real, deducted amounts — there is no placeholder. bridgeFeeUsd is the Mobula protocol fee (bridgeFeeBps, currently 5); destFillGasUsd is what the solver pays to fill on the destination chain; gasFeeUsd equals destFillGasUsd. destActivationCostUsd appears only when the destination needs a one-off account-creation cost (e.g. Solana ATA rent for a first-time recipient) — it’s omitted otherwise. integratorFeeBps / integratorFeeUsd appear only when you pass feeBps + feeWallet (see Integrator fee). totalFeeUsd is bridgeFeeUsd + gasFeeUsd plus the integrator cut when present — it does not include destActivationCostUsd. estimatedAmountOut / estimatedAmountOutUsd are already net of every fee (activation cost included); the user additionally pays only origin-chain gas to broadcast the deposit.
• destinationType / originType are echoed back only for HyperLiquid routes (spot or perps), reflecting the venue the funds land in / are pulled from.

​

Integrator fee

• feeBps is your fee in basis points — integer 0–500 (up to 5%). It only applies when feeWallet is also present.
• The fee is paid in USDC on the destination chain, at fill time (not on the origin). feeWallet must therefore be a valid destination-ecosystem address (0x… for evm:*/hl:mainnet, base58 for solana:solana); a mismatch is rejected before the fee is charged. On HyperLiquid destinations a payout to an unactivated account is skipped (first receipt on an unactivated HL account costs the sender ~$1).
• The cut is folded into the signed minAmountOut, so it comes out of the bridged amount — the recipient still receives exactly estimatedAmountOut.
• When applied, the quote’s fees object echoes integratorFeeBps and integratorFeeUsd, and totalFeeUsd includes it.

GET /api/2/bridge/quote?...&feeBps=30&feeWallet=0xYourFeeWallet

​

deposit shapes

​

EVM origin (deposit.evm)

{
  "to": "0xa834E70303322D86E5DaE95ee47E9c6a073d9812",
  "data": "0x...",
  "value": "50000000000000000",
  "chainId": 8453,
  "approvalAddress": "0x...",      // present for ERC-20 origins
  "approvalToken": "0x...",        // present for ERC-20 origins
  "approvalAmount": "115792...255" // MAX_UINT256
}

• Native ETH/BNB/POL — single bridge() call on MobulaBridge. value is the raw amount in wei. steps has one bridge entry.
• Direct-bridge tokens — approve step to MobulaBridge, then bridgeToken(). value is "0". The set is exactly the chain’s canonical USDC (Base, BSC, Arbitrum, Polygon) — every other ERC-20, including USDbC and USDT, takes the swap-and-bridge path. Robinhood Chain has no USDC, so it’s native + swap only.
• Any other ERC-20 — approve step to SwapBridgeHelper, then swapAndBridge() — atomic swap to native + bridge in one TX. The embedded swap calldata is validated server-side to start with the MobulaRouter.executeRoute selector (0xa564dfa4); if it doesn’t, the quote returns "Swap quote failed: invalid calldata selector".

​

Solana origin (deposit.solana)

• Native SOL — { to, amount, memo }. Build a SystemProgram.transfer for amount lamports to to (the solver address), then add a memo instruction (program MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr) whose data is the memo string. The memo is a JSON blob the solver parses to recover intentId, destinationChainId, recipient, destinationToken, and minAmountOut.
• SPL — { type: "spl-transfer" | "swap-transfer", serializedTx }. The server has already built the full versioned transaction. Canonical USDC is a direct spl-transfer (SPL transfer + ATA creation if missing + memo); any other SPL token is swap-transfer — an atomic swap to USDC + transfer + memo in one transaction. Either way, just VersionedTransaction.deserialize, sign, and send.

​

HyperLiquid origin (deposit.hl)

{
  "type": "spotSend",
  "to": "0x74CfC17edF89aD6134c04c446c3Be6dD288F0B8d",
  "token": "USDH:0x54e00a5988577cb0b0c9ab0cb6ef7f4b",
  "amount": "1.0"
}

​

Same-chain quotes

​

Signed-quote flow

1. Preview call — GET /quote?... with no signature. Server returns the quote, the deposit calldata, and a typedData payload. Nothing is committed yet.
2. Sign — your wallet signs typedData (e.g. eth_signTypedData_v4 for injected wallets, walletClient.signTypedData with viem). The signer’s address must equal typedData.message.sender.
3. Commit call — GET /quote?...&signature=<sig>&intentId=<id>&deadline=<ts>&minAmountOut=<raw> with the same input params as call 1. Server reconstructs the typedData from the query params, recovers the signer, and commits your signed intent if everything lines up. Returns the same response shape with prediction.persisted: true.
4. Broadcast — submit deposit.evm (or deposit.hl) on chain.

​

EIP-712 schema

Domain:
  name:    "Mobula Bridge"
  version: "1"
  chainId: <numeric origin chain id>   // 8453, 56, 42161, 137, 4663 — and 1 (NOT 999) for hl:mainnet

BridgeIntent:
  intentId           string    — same as `data.intentId` (dashed hex, signed as a string)
  sender             address   — depositor EVM key (HL origin: HL spot wallet; EVM: walletAddress)
  originChainId      string    — e.g. "evm:8453"
  originToken        string    — "0x000…0" for native, or token address / HL token id
  amountIn           uint256   — raw origin-token units
  destinationChainId string
  destinationToken   string
  recipient          bytes32   — EVM dest: address left-padded; Solana dest: bs58-decoded
  minAmountOut       uint256   — raw destination-token units, echoed back as the `minAmountOut` query param
  deadline           uint64    — Unix seconds, echoed back as the `deadline` query param

​

Failure modes on the commit call

• HTTP 400 Signature recovers to 0x…; expected sender 0x… — the signature recovered to a different address than the expected signer. Re-check typedData.message.sender and the signer.
• HTTP 400 Invalid bridge intent signature: … — the signature is malformed (recovery itself threw).
• HTTP 200 { "error": "Signature deadline has expired or is invalid" } — deadline is past now. Re-quote.
• HTTP 200 { "error": "Signed-mode quote requires intentId, deadline, minAmountOut, and signature query params (echo the values returned by the unsigned call)" } — one of the four signed-mode params is missing.

​

Side effects

​

Example

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount("0xYourPrivKey");
const client = createWalletClient({ account, chain: base, transport: http() });

// 1. Preview call (no signature, nothing committed).
const baseParams = new URLSearchParams({
  originChainId: "evm:8453",
  destinationChainId: "evm:56",
  originToken: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", // USDC on Base
  destinationToken: "0x55d398326f99059fF775485246999027B3197955", // USDT on BSC
  amount: "100",
  walletAddress: account.address,
  senderAddress: account.address,
  apiKey: "YOUR_API_KEY",
});

const preview = await fetch(`https://api.mobula.io/api/2/bridge/quote?${baseParams}`)
  .then((r) => r.json());
if (preview.error) throw new Error(preview.error);
const { intentId, deadline, typedData, estimatedAmountOut } = preview.data;

// 2. Sign the typed data.
const signature = await client.signTypedData({
  account,
  domain: typedData.domain,
  types: typedData.types,
  primaryType: typedData.primaryType,
  message: typedData.message,
});

// 3. Commit call (server verifies + commits your signed intent).
const commitParams = new URLSearchParams(baseParams);
commitParams.set("intentId", intentId);
commitParams.set("deadline", String(deadline));
commitParams.set("minAmountOut", typedData.message.minAmountOut);
commitParams.set("signature", signature);

const committed = await fetch(`https://api.mobula.io/api/2/bridge/quote?${commitParams}`)
  .then((r) => r.json());
if (committed.error) throw new Error(committed.error);

// 4. Broadcast the on-chain deposit.
const tx = committed.data.deposit.evm; // approve+bridgeToken steps in committed.data.steps
const hash = await client.sendTransaction({
  to: tx.to,
  data: tx.data,
  value: BigInt(tx.value),
});
console.log("Deposit tx:", hash);
console.log("Poll status with:", intentId);