Skip to main content

​
Quickstart

This guide walks you through the complete integration flow with Bridgfy, from creating your account to executing your first cross-chain transfer.

​
1. Create an Account

Sign up for Bridgfy at https://dashboard.bridgfy.com The dashboard supports multiple authentication methods:
  • Google OAuth - Sign in with your Google account
  • Email/Password - Create an account with email verification
  • Other OAuth providers - Additional options may be available
Once signed in, you’ll have access to the Bridgfy Dashboard where you can manage your organizations, API keys, and monitor execution history.

​
2. Create an Organization

API keys in Bridgfy belong to Organizations (also called Teams). This allows multiple team members to collaborate and share access to API keys and usage metrics. To create an Organization:
  1. Navigate to the Organizations section in the Dashboard
  2. Click “Create Organization”
  3. Provide a name and slug for your organization
  4. Invite team members (optional)
You can belong to multiple organizations and switch between them in the Dashboard. Each organization has its own set of API keys and usage tracking.

​
3. Generate API Key

Once you have an organization, generate an API key for programmatic access: In the Dashboard:
  1. Select your Organization
  2. Navigate to “API Keys”
  3. Click “Create API Key”
  4. Configure your key settings:
    • Label: A descriptive name (e.g., “Production API”, “Staging Integration”)
    • Role: CLIENT (for application integration)
    • Protocol Fee: Fee percentage in basis points (e.g., 50 = 0.5%)
    • Gas Sponsorship: Whether Bridgfy covers gas costs
      • true - Platform pays gas (better UX, simpler integration)
      • false - Gas deducted from user deposit (cost control)
  5. Copy the generated API key immediately (it won’t be shown again)
Important: Store your API key securely. It provides full access to create deposit intents and execute transactions for your organization.

​
4. Create Deposit Intent

Tell Bridgfy where funds for a specific user should go. This generates their unique deposit address. Request: 
POST https://api.bridgfy.com/api/deposit-intents
x-api-key: <your-api-key>
Content-Type: application/json

{
  "userId": "user-123",
  "targetChainId": 137,
  "targetTokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "targetAddress": "0x5555555555555555555555555555555555555555"
}
Response: 
{
  "userId": "user-123",
  "depositAddress": "0xABC...123",
  "targetChainKey": "polygon",
  "targetChainId": 137,
  "targetTokenAddress": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
  "targetAddress": "0x5555555555555555555555555555555555555555",
  "protocolFeeBps": 50,
  "sponsoredGas": false,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}
The depositAddress is the address your user should send funds to. It’s a deterministic smart contract wallet managed by Bridgfy.

​
5. Simulate Deposit (Optional)

Preview the route, fees, and output amount before sending real funds. This uses your stored Deposit Intent and live routing data. Request: 
POST https://api.bridgfy.com/api/routing/simulate-deposit
x-api-key: <your-api-key>
Content-Type: application/json

{
  "userId": "user-123",
  "fromChainId": 8453,
  "fromTokenSymbol": "USDC",
  "amountInAtomic": "10000000"
}
Optional Override Parameters: You can temporarily test different destinations without changing the stored intent: 
{
  "userId": "user-123",
  "fromChainId": 8453,
  "fromTokenSymbol": "USDC",
  "amountInAtomic": "10000000",
  "overrideTargetChainId": 1,
  "overrideTargetTokenAddress": "0x...",
  "overrideTargetAddress": "0x..."
}
Response: 
{
  "userId": "user-123",
  "hasIntent": true,
  "fromChainId": 8453,
  "fromChainKey": "base",
  "fromTokenSymbol": "USDC",
  "amountInAtomic": "10000000",
  "targetChainId": 137,
  "targetChainKey": "polygon",
  "targetTokenSymbol": "USDC",
  "targetAddress": "0x5555555555555555555555555555555555555555",
  "amountOutExpectedAtomic": "9950000",
  "gasFeeRaw": "25000",
  "gasFeeSkipReason": "NONE",
  "amountForSwapAtomic": "9925000",
  "provider": "lifi",
  "policy": {
    "slippageBps": 50,
    "minOutputBps": 9800,
    "maxDurationSeconds": 600,
    "maxHops": 3,
    "requiresSponsoredGas": false
  }
}
This shows you:
  • Expected output amount after fees and routing
  • Gas fees (if user pays)
  • The routing provider and policy being used

​
6. Send Funds

Have your user send funds to the depositAddress from Step 4. Example: Send 10 USDC from Base to the deposit address Once the transaction is confirmed on-chain, Bridgfy automatically:
  1. Detects the deposit via webhook
  2. Resolves the user’s Deposit Intent
  3. Gets a routing quote
  4. Calculates and deducts fees
  5. Executes the cross-chain transfer
No additional API calls required - the entire process happens automatically after the deposit is detected.

​
7. Observe Execution

Check the status of transactions for a user. Request: 
GET https://api.bridgfy.com/api/users/user-123/executions
x-api-key: <your-api-key>
Response: 
[
  {
    "id": "exec_abc123",
    "userId": "user-123",
    "status": "SUCCESS",
    "fromChainId": 8453,
    "fromChainKey": "base",
    "toChainId": 137,
    "toChainKey": "polygon",
    "fromTokenSymbol": "USDC",
    "toTokenSymbol": "USDC",
    "amountIn": "10000000",
    "amountOutExpected": "9950000",
    "txHash": "0x1234...",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "completedAt": "2024-01-01T00:01:30.000Z"
  }
]
Status values:
  • PENDING - Route resolved, preparing to execute
  • RUNNING - Transaction submitted to blockchain
  • SUCCESS - Transfer completed successfully
  • FAILED - Execution failed (see error details)
  • Various terminal error statuses (see Error Codes)

​
What’s Next?

  • Understand the flow: Read How It Works to understand the system architecture
  • Learn about fees: Check Fees and Gas to understand cost structure
  • Handle errors: Review Error Codes for troubleshooting
  • API Reference: Explore detailed endpoint documentation in the API Reference section

​
Testing Tips

For testnet integration:
  1. Use testnet chains (e.g., Base Sepolia, Ethereum Sepolia)
  2. Get testnet tokens from faucets
  3. Configure your API key with test settings
  4. Monitor executions in the Dashboard
Common issues:
  • Deposit not detected: Check that the funds were sent to the correct depositAddress
  • Execution failed: Review the execution error details - common causes include insufficient funds for fees or unsupported token pairs
  • Unexpected fees: Use the simulation endpoint before sending funds to preview exact amounts

​
Need Help?

  • Check the API Reference for detailed endpoint documentation
  • Review Error Codes for troubleshooting failed executions
  • Contact support through the Dashboard