Skip to main content

​
Fees and Gas

Bridgfy employs a best-effort fee model to cover the costs of cross-chain routing. Fee settings are configured per API key in your Organization, making it easy to customize pricing for different use cases.
Note: Fee settings (protocolFeeBps and sponsoredGas) are configured when you create an API key in the Dashboard. These settings are snapshotted onto Deposit Intents at creation time.

​
Gas Sponsorship

Bridgfy supports two gas payment modes configured per API key:
  • Platform pays: Bridgfy covers all gas costs
  • User receives: Full deposit amount minus protocol fee
  • Use case: Optimal user experience, simpler onboarding
  • Best for: Consumer-facing applications where UX is critical

​
User-Paid Gas (sponsoredGas: false)

  • User pays: Gas fee deducted from deposit on source chain
  • Calculation: Live gas estimation + token swap quote
  • Fallback: If estimation fails, reverts to sponsored mode
  • Use case: Cost control, high-volume operations
  • Best for: B2B applications or high-frequency trading
The sponsoredGas flag is set on API keys and snapshotted onto Deposit Intents at creation time.

​
Core Mechanics

​
1. Source of Truth: totalReceivedRaw

Bridgfy verifies the actual on-chain balance before routing. The system queries the balance of the Modular Account to confirm the exact amount received.
  • This value is stored as totalReceivedRaw
  • All fee calculations use this confirmed on-chain balance
  • Webhook-reported amounts are validated against on-chain data

​
2. Protocol Fee

The protocol fee is configured on the API Key used to create the Deposit Intent.
  • Snapshot: The fee (in bps) is “snapped” onto the DepositIntent at creation. Changing the API key fee later does not affect existing intents
  • Calculation: protocolFeeRaw = totalReceivedRaw * (protocolFeeBps / 10000)
  • Clamping: The fee is capped at 10% (1000 bps)
Example:
  • Deposit: 100 USDC
  • Protocol Fee: 50 bps (0.5%)
  • Fee Amount: 0.5 USDC

​
3. Gas Fee (Best-Effort)

Gas handling depends on the sponsoredGas flag: When sponsoredGas = true (Platform Pays):
  • No gas fee deducted from user deposit
  • gasFeeRaw = 0
  • Execution uses platform’s gas sponsorship
When sponsoredGas = false (User Pays):
  • Bridgfy estimates gas cost on source chain:
    1. Estimation: Builds transaction and estimates gas limit
    2. Pricing: Quotes native gas → deposit token conversion
    3. Buffer: Applies safety margin (typically 20%) for gas price volatility
    4. Result: gasFeeRaw is the deposit token amount needed for gas
  • Fallback: If estimation fails, gasFeeRaw = 0, execution falls back to sponsored mode

​
4. Hard Stop

The final amount available for the bridge swap is: 
amountForSwapRaw = totalReceivedRaw - protocolFeeEffective - gasFeeRaw
If amountForSwapRaw <= 0, the execution is aborted with status FAILED_INSUFFICIENT_AFTER_FEES. No transaction is submitted.

​
Scenarios

​
Scenario A: Normal Flow (User-Paid Gas)

  • Deposit: 100 USDC (100,000,000 units)
  • Protocol Fee: 1% (100 bps) → 1 USDC
  • Gas Fee: Estimated at 0.5 USDC
  • Result:
    • Fee Transfer: 1.5 USDC (Protocol + Gas) sent to platform
    • Swap: 98.5 USDC bridged to destination

​
Scenario B: Gas Estimation Skipped

  • Deposit: 100 USDC
  • Protocol Fee: 1% → 1 USDC
  • Gas Fee: Estimation failed → 0 USDC (fallback to sponsored)
  • Result:
    • Fee Transfer: 1 USDC
    • Swap: 99 USDC bridged. Platform absorbs gas cost

​
Scenario C: Protocol Fee Forgiven

Fees are applied in a “waterfall”: Gas is prioritized over Protocol Fee.
  • Deposit: 1.5 USDC (1,500,000 atomic units)
  • Protocol Fee (Calculated): 1% → 0.015 USDC (15,000 units)
  • Gas Fee: 1.0 USDC (1,000,000 units)
  • Available After Gas: 1,500,000 - 1,000,000 = 500,000 units
  • Protocol Fee Fits? No. Only 500,000 available but 15,000 expected
  • Result:
    • protocolFeeEffective = 500,000 (what’s actually collected)
    • protocolFeeForgiven = tracked as foregone revenue
    • totalFeeTransfer = 1,000,000 (gas) + 500,000 (protocol) = 1,500,000
    • amountForSwap = 0
    • Status: FAILED_INSUFFICIENT_AFTER_FEES (nothing left to swap)

​
Scenario D: Insufficient After Fees

  • Deposit: 0.5 USDC (500,000 atomic units)
  • Gas Fee: 1.0 USDC (1,000,000 units)
  • Protocol Fee: 1% → 5,000 units
  • Result: Gas alone exceeds deposit. amountForSwap would be negative
  • Status: FAILED_INSUFFICIENT_AFTER_FEES (transaction aborted, no on-chain submission)

​
Scenario E: Sponsored Gas (Platform Pays)

  • Deposit: 100 USDC (100,000,000 units)
  • Protocol Fee: 1% → 1,000,000 units (1 USDC)
  • Gas Fee: 0 (sponsored by platform)
  • Result:
    • Fee Transfer: 1 USDC to platform
    • Swap: 99 USDC bridged to destination
    • User receives full amount minus only protocol fee

​
Fee Transparency

​
Via Simulation API

Before sending funds, use the simulation endpoint to preview exact fees: 
POST /api/routing/simulate-deposit
x-api-key: your_api_key
Content-Type: application/json

{
  "userId": "user-123",
  "fromChainId": 8453,
  "fromTokenSymbol": "USDC",
  "amountInAtomic": "10000000"
}
Response includes:
  • amountOutExpectedAtomic - Expected output after all fees
  • gasFeeRaw - Gas fee amount (if user pays)
  • gasFeeSkipReason - Why gas wasn’t charged (if sponsored)
  • Full policy details

​
In Execution Records

After execution, query execution history to see actual fees charged: 
GET /api/users/:userId/executions
x-api-key: your_api_key
Each execution record includes:
  • amountIn - Total deposit received
  • amountOutExpected - Amount after fees
  • Protocol fee and gas fee breakdowns (in execution context)

​
Best Practices

​
Choosing Gas Sponsorship

Use Sponsored Gas (true) when:
  • Building consumer-facing applications
  • UX is more important than cost control
  • Deposit amounts are unpredictable
  • You want to simplify integration
Use User-Paid Gas (false) when:
  • Running high-volume operations
  • Need precise cost attribution
  • Users understand gas fees
  • Deposit amounts are large enough to cover gas

​
Minimum Deposit Amounts

To avoid FAILED_INSUFFICIENT_AFTER_FEES errors:
  1. Use simulation API to determine minimum viable amounts
  2. Communicate minimums to your users
  3. For user-paid gas: Ensure deposits are at least 2-3x the estimated gas cost
  4. Consider sponsored gas for small-value transactions
Example minimum calculation: 
Minimum = (Gas Fee Estimate * 1.5) + (Protocol Fee) + (Bridge Fees)

​
Testing Fee Scenarios

Before going to production:
  1. Test with various deposit amounts
  2. Try both gas sponsorship modes
  3. Simulate on different chains (gas costs vary significantly)
  4. Test failure scenarios (very small deposits)

​
Next Steps