Skip to main content

​
How It Works

This guide explains how Bridgfy routes cross-chain transactions and the key components involved in the process.

​
Multi-Tenant Architecture

Bridgfy operates as a multi-tenant SaaS platform with a hierarchical access model: Flow:
  1. Users sign up and authenticate via the Dashboard
  2. Organizations represent teams or businesses
  3. API Keys are created within Organizations with specific fee configurations
  4. Executions are tracked per API key for usage monitoring
This model allows teams to collaborate, share access, and track usage together.

​
Cross-Chain Routing Flow

Here’s how Bridgfy handles a deposit from start to finish:

​
Step-by-Step Process

1. Create Deposit Intent
  • Your application calls the Bridgfy API with the user’s destination preferences
  • Bridgfy provisions a deterministic smart contract wallet (Modular Account) for that user
  • Fee settings from your API key are captured on the intent
2. Receive Deposit Address
  • Bridgfy returns a unique deposit address for the user
  • This address is the same across all supported EVM chains
  • The address is stable and can be reused for multiple deposits
3. User Sends Funds
  • Your user sends tokens to the deposit address on any supported source chain
  • No wallet connection or transaction signing required from the user’s side
  • Just a simple token transfer to the provided address
4. Automatic Detection
  • Bridgfy detects the deposit via blockchain webhooks
  • The system validates the deposit and matches it to the user’s Deposit Intent
5. Route Resolution
  • Bridgfy queries cross-chain routing providers to find the optimal path
  • Factors considered: gas costs, slippage, bridge fees, estimated time
  • Multiple routing providers may be used for redundancy
6. Fee Calculation
  • Protocol Fee: Deducted based on your API key settings (e.g., 0.5%)
  • Gas Fee: Either sponsored by Bridgfy or deducted from the deposit
  • Fees are calculated on the source chain before bridging
7. Execution
  • If fees are covered and a valid route exists, the transaction is submitted
  • The smart contract wallet approves and executes the cross-chain transfer
  • Users can track progress via execution status
8. Delivery
  • Assets are bridged to the destination chain
  • Funds arrive at the target address specified in the Deposit Intent
  • The execution is marked as SUCCESS

​
Key Components

​
Modular Accounts

Bridgfy uses Modular Accounts (smart contract wallets) to hold user deposits temporarily:
  • Deterministic: Same address for a user across all chains
  • Non-custodial: Controlled by Bridgfy’s system, but only acts on predefined intents
  • Secure: Funds are only moved according to the user’s Deposit Intent

​
Deposit Intents

A Deposit Intent stores the routing configuration for a user: 
{
  "userId": "user-123",
  "depositAddress": "0xABC...123",
  "targetChainId": 137,
  "targetTokenAddress": "0x...",
  "targetAddress": "0x...",
  "protocolFeeBps": 50,
  "sponsoredGas": false
}
Key features:
  • One intent per user (can be updated)
  • Fee settings are snapshotted from your API key
  • Determines where all future deposits for that user will go

​
Executions

Every deposit triggers an Execution record that tracks the transaction lifecycle: Execution States:
  • PENDING - Route found, preparing to execute
  • RUNNING - Transaction submitted to blockchain
  • SUCCESS - Transfer completed
  • FAILED - Execution failed (may be retried automatically)
  • Terminal error states (see Error Codes)
What’s tracked:
  • Source and destination chains
  • Token amounts (in/out)
  • Transaction hashes
  • Timestamps
  • Error details (if failed)

​
API Key Configuration

Each API key in your Organization can be configured with:

​
Protocol Fee

  • Set in basis points (bps)
  • Example: 50 bps = 0.5% fee
  • Deducted from deposits before bridging
  • Snapshotted onto Deposit Intents at creation time

​
Gas Sponsorship

Sponsored Gas (true):
  • Bridgfy pays all gas costs
  • Users receive full amount minus only protocol fee
  • Better user experience
  • Simpler integration
User-Paid Gas (false):
  • Gas fee deducted from user deposit
  • Live gas estimation on source chain
  • Better cost control for high-volume operations

​
Routing and Bridging

Bridgfy uses third-party routing aggregators to find optimal cross-chain paths: Routing Factors:
  • Available bridge providers
  • Liquidity depth
  • Gas costs on source and destination
  • Estimated completion time
  • Slippage tolerance
Supported Routing:
  • Direct bridges (when available)
  • Multi-hop routes (when necessary)
  • Automatic provider selection
  • Fallback options for reliability

​
Security

​
API Key Authentication

All programmatic API access requires an API key: 
POST /api/deposit-intents
x-api-key: bfy_your_api_key_here
  • Keys are scoped to Organizations
  • Can be revoked instantly from the Dashboard
  • Usage is tracked per key

​
Token Security

Bridgfy maintains a security blacklist to prevent interaction with:
  • Sanctioned tokens
  • Known scam tokens
  • Malicious contracts
The blacklist is managed by the platform and not user-configurable.

​
Fund Safety

  • Funds are held in smart contract wallets only during routing
  • Executions are deterministic based on Deposit Intents
  • No manual intervention in the routing process
  • Failed executions don’t result in lost funds (tokens remain in the Modular Account)

​
Monitoring and Tracking

​
In the Dashboard

  • View all executions across your Organization
  • Filter by API key, status, chain, or time range
  • See detailed fee breakdowns
  • Track success rates and volumes

​
Via API

GET /api/users/:userId/executions
x-api-key: your_api_key
Returns execution history with:
  • Transaction hashes
  • Status and timestamps
  • Amount in/out
  • Error details (if failed)

​
Next Steps