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,
    "appliedSlippage": 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, or pass slippage=auto to apply it while the quote is built (see Auto slippage).
• appliedSlippage appears only when you request slippage=auto: the recommendation used to calculate the quote’s signed minAmountOut. It is absent on numeric-slippage calls, where the value you supplied is applied.
• 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. On a gasless=true quote, originSponsorGasUsd appears in fees and that origin gas is deducted too — the user pays nothing on the origin chain (see Gasless EVM deposits).
• 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

​

Gasless EVM deposits

GET /api/2/bridge/quote?...&gasless=true
→ { data: { intentId, typedData, steps, sponsorGate: { … },
            fees: { originSponsorGasUsd: "0.0123", … }, … } }

​

sponsorGate

"sponsorGate": {
  "batchExecutor": "0x29440460fbdda286fe259b0b1cbfbc018d47dfda",
  "gasToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "minBalance": "1000000"
}

• The origin gas is not free — it’s priced into this quote: fees.originSponsorGasUsd is deducted from estimatedAmountOut, folded into totalFeeUsd, and baked into the signed minAmountOut. It’s the only way /execute can recover what it spends, which is why an intent quoted without gasless=true is refused there.
• steps are the batch the user signs (approve + bridgeToken / swapAndBridge) — carry them verbatim, in order, into /execute.
• The quote is refused when the route can’t be sponsored: "Gasless deposits are not available on <chain>" (no executor deployed there), "Gasless is not available for same-chain swaps", "Gasless is not available for a native or wrapped-native origin: that deposit must carry native value", or "Amount does not cover the sponsored origin gas ($…)".
• You can skip the signed-quote confirm call entirely on this path: sign the returned typedData and send that signature in the /execute body instead — the server persists the intent from the values this quote already computed.

​

Gasless Solana deposits

GET /api/2/bridge/quote?...&originChainId=solana:solana&gasless=true
→ deposit.solana = {
    type: "spl-transfer" | "swap-transfer",
    serializedTx: "<base64, fee-payer signature already attached>",
    coSigned: true,
    feePayer: "<Mobula fee payer>",
    blockhash: "<the blockhash that signature covers>"
  }

• Do not touch recentBlockhash. It is part of what our signature covers; replacing it voids the co-signature. The transaction is good for as long as that blockhash lives (~60s), which is also when you should re-quote.
• The fee is priced into the quote as fees.originSponsorGasUsd, deducted from estimatedAmountOut and baked into the memo’s minAmountOut — the same accounting as the EVM path.
• Native SOL origins are refused: that deposit is the gas token itself. So are same-chain swaps, and a request that also sets feePayerAddress.

​

Priority send

GET /api/2/bridge/quote?...&originChainId=solana:solana&prioritySend=helius
→ deposit.solana.prioritySend = {
    provider: "helius",
    tipAccount: "<the account the built tip pays>",
    tipLamports: 5000
  }

• Who pays the tip follows who pays the transaction. On a self-paid deposit it comes out of the sender’s SOL like the fee does. On a gasless=true deposit we pay it, so it is priced into fees.originSponsorGasUsd and deducted from estimatedAmountOut — the quote you get already accounts for it.
• Native SOL origins build their own transaction client-side, so there the prioritySend block also carries computeUnitPriceMicroLamports and you add the tip transfer + compute-budget instructions yourself.
• Omitting the parameter changes nothing: no extra call is made and the deposit is built exactly as before.

​

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 a recognised MobulaRouter.executeRoute selector (0x1688b026 for v2.19.0, or 0xa564dfa4 for v2.17.0); 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. On a gasless=true quote the same shape carries coSigned: true, feePayer and blockhash, and the transaction is already signed by that payer — see Gasless Solana deposits.

​

HyperLiquid origin (deposit.hl)

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

​

Same-chain quotes

​

Auto slippage

GET /api/2/bridge/quote?...&slippage=auto
→ { data: { typedData, appliedSlippage: 4.2, deposit, ... } }

​

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