HIFI Docs

How Bridging Works

Bridging follows a straightforward process:

Create bridge request

Specify source chain, destination chain, and amount to bridge.

Processing

HIFI executes the cross-chain operations (burn on source, mint on destination).

Completion

Stablecoins arrive on the destination chain.

Creating Bridge Requests

Use the Create Bridge endpoint to initiate a cross-chain transfer. Request:

curl -X POST "https://sandbox.hifibridge.com/v2/wallets/bridges" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "1d860428-1d0b-47c5-9e65-98961ff59215",
    "amount": 10,
    "source": {
      "userId": "usr_abc123",
      "chain": "POLYGON",
      "currency": "usdc"
    },
    "destination": {
      "userId": "usr_abc123",
      "chain": "ETHEREUM",
      "currency": "usdc"
    }
  }'

The response contains the bridge request details:

Response

{
  "transferType": "WALLET.BRIDGE",
  "transferDetails": {
    "id": "brg_abc123",
    "requestId": "1d860428-1d0b-47c5-9e65-98961ff59215",
    "createdAt": "2025-02-24T17:44:54.781519+00:00",
    "updatedAt": "2025-02-24T17:44:54.781519+00:00",
    "amount": 10,
    "status": "CREATED",
    "source": {
      "userId": "usr_abc123",
      "walletAddress": "0xE9cfBf1D690565579D823264170eE357f80e9A34",
      "chain": "POLYGON",
      "currency": "usdc"
    },
    "destination": {
      "userId": "usr_abc123",
      "walletAddress": "0x17f043FB0a39334641beD627551AC095941157B0",
      "chain": "ETHEREUM",
      "currency": "usdc"
    },
    "receipt": {
      "transactionHash": null,
      "operations": {
        "mint": null,
        "burn": null,
        "approve": null
      }
    },
    "failedReason": null,
    "quoteInformation": {
      "sendGross": {
        "amount": "10.00",
        "currency": "usdc"
      },
      "sendNet": {
        "amount": "10.00",
        "currency": "usdc"
      },
      "receiveGross": {
        "amount": "10.00",
        "currency": "usdc"
      },
      "receiveNet": {
        "amount": "10.00",
        "currency": "usdc"
      },
      "rate": "1",
      "railFee": {
        "amount": "0",
        "currency": "usdc"
      }
    }
  }
}

string

Unique bridge ID. Use this to check status using the Retrieve Bridge endpoint.

string

Bridge status. Progression: CREATED → SOURCE_INITIATED → SOURCE_PROCESSED → DESTINATION_INITIATED → COMPLETED. See Transaction Status for details.

object

Source chain details including wallet address, chain, and currency.

object

Destination chain details including wallet address, chain, and currency.

number

Amount being bridged in the specified currency.

object

Bridge quote details including amounts and rate. For same-asset bridges, the rate is always “1”.

object

Transaction receipt. Contains transactionHash and operations (approve, burn, mint) once bridge operations are executed on-chain.

For detailed field documentation, see the Create Bridge API reference.

Transaction Status

Bridge transactions progress through several phases:

Source Chain Phase

Status	Description
CREATED	Bridge request created and awaiting processing
SOURCE_INITIATED	Burning tokens on source chain
SOURCE_PENDING	Waiting for source chain confirmation
SOURCE_PROCESSED	Tokens successfully burned on source chain
SOURCE_FAILED	Source chain operation failed

Destination Chain Phase

Status	Description
DESTINATION_INITIATED	Minting tokens on destination chain
DESTINATION_PENDING	Waiting for destination chain confirmation
COMPLETED	Tokens successfully minted on destination chain
DESTINATION_FAILED	Destination chain operation failed

Other Statuses

Status	Description
NOT_INITIATED	Bridge not submitted due to validation error
QUOTE_FAILED	Quote expired (bridges typically don’t use quotes)
UNKNOWN	Status could not be determined

Tracking Bridges

Status Updates: Subscribe to WALLET.BRIDGE.CREATE and WALLET.BRIDGE.UPDATE webhook events to receive real-time status notifications. See Webhooks for setup instructions.

Monitor bridge status using the Retrieve Bridge endpoint. Request:

curl -X GET "https://sandbox.hifibridge.com/v2/wallets/bridges/brg_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

When the bridge is completed, the response includes all operation hashes:

Response

{
  "transferType": "WALLET.BRIDGE",
  "transferDetails": {
    "id": "brg_abc123",
    "status": "COMPLETED",
    "receipt": {
      "transactionHash": "0x17f043FB0a39334641beD627551AC095941157B0",
      "operations": {
        "mint": {
          "transactionHash": "0x5784890f9efd0160e9401439a5cf2aa5350580ecf48f9ca2af617338ae089e53",
          "userOpHash": "0xef7bdb071b1fcfb5df629bd4d27ffa6dc32d0a5df676f26fb8c25311df1185ac",
          "chain": "ETHEREUM"
        },
        "burn": {
          "transactionHash": "0x8a95b01e9fed0270f0512550b6dg3bb6461691fdg59i0db3bg728449bf19017d",
          "userOpHash": "0xgh8cec182c2gdhgi6eg740c5e38gib7ed43e1b6eg787g37gc9d36412eg2296bd",
          "chain": "POLYGON"
        },
        "approve": {
          "transactionHash": "0x7j84j90h8hfe0160h8291228j4dg2jj4239469hd38h8dj1jg516227228jh078h42",
          "userOpHash": "0xij7iji061i1hidhj5ii518ij3i27iih5id22i0j4ii575i25hj7c15300ii1074ji",
          "chain": "POLYGON"
        }
      }
    }
  }
}

string

Bridge status. COMPLETED means tokens have been successfully minted on the destination chain.

object

Blockchain operations that were executed during the bridge. Each operation (approve, burn, mint) contains transactionHash, userOpHash, and chain for verification on block explorers.

Bridge Operations

Bridging involves three blockchain operations tracked in the receipt.operations object:

Operation	Description	Chain
Approve	Authorizes bridge contract to spend your tokens	Source chain
Burn	Destroys tokens on the source chain	Source chain
Mint	Creates equivalent tokens on the destination chain	Destination

Each operation includes:

transactionHash - Blockchain transaction hash (view on block explorer)
userOpHash - User operation hash for account abstraction wallets
chain - Which blockchain the operation occurred on

Processing Time: Bridge operations typically complete within 2-5 minutes depending on network congestion. Use the transaction hashes to track progress on block explorers.

Supported Routes

Currently supported bridging routes:

Source Chain	Destination Chains
Polygon	Ethereum, Base, Optimism, Arbitrum, Solana
Ethereum	Polygon, Base, Optimism, Arbitrum, Solana
Solana	Polygon, Ethereum, Base, Optimism, Arbitrum
Base	Polygon, Ethereum, Solana, Optimism, Arbitrum
Optimism	Polygon, Ethereum, Solana, Base, Arbitrum
Arbitrum	Polygon, Ethereum, Solana, Base, Optimism

Supported currencies: USDC, USDT

Key Concepts

1:1 Transfers

Bridges maintain a 1:1 ratio when transferring the same asset across chains. When you bridge 10 USDC from Polygon to Ethereum, you receive 10 USDC on Ethereum (minus any network fees).The quoteInformation.rate will always be “1” for same-asset bridges.

External Wallet Bridging

You can bridge to external wallet addresses (not managed by HIFI) by providing walletAddress instead of userId in the destination:

{
  "destination": {
    "chain": "ETHEREUM",
    "currency": "usdc",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  }
}

Gas Sponsorship Required: To bridge to external addresses, you must be enrolled in HIFI’s Gas Sponsorship Program. Otherwise, provide a userId to bridge to a HIFI wallet.

Bridge vs Transfer

Bridges move assets across different blockchains (e.g., Polygon → Ethereum).Transfers move assets within the same blockchain (e.g., Polygon wallet A → Polygon wallet B).Use bridges when you need assets on a different chain. Use transfers for same-chain movements.

Sample Code

Complete bridge flow

Create bridge request

curl -X POST "https://sandbox.hifibridge.com/v2/wallets/bridges" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "1d860428-1d0b-47c5-9e65-98961ff59215",
    "amount": 10,
    "source": {
      "userId": "usr_abc123",
      "chain": "POLYGON",
      "currency": "usdc"
    },
    "destination": {
      "userId": "usr_abc123",
      "chain": "ETHEREUM",
      "currency": "usdc"
    }
  }'

Monitor progress

Poll the retrieve endpoint or subscribe to WALLET.BRIDGE.UPDATE webhooks. Track through statuses: 1. SOURCE_INITIATED → SOURCE_PENDING → SOURCE_PROCESSED 2. DESTINATION_INITIATED → DESTINATION_PENDING → COMPLETED

Verify on block explorers

Once COMPLETED, use transaction hashes from receipt.operations to verify:

Check burn transaction on source chain explorer (Polygonscan)
Check mint transaction on destination chain explorer (Etherscan)

Bridge with approval

Create bridge with approval

Set requireApproval: true for multi-party authorization:

curl -X POST "https://sandbox.hifibridge.com/v2/wallets/bridges" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "1d860428-1d0b-47c5-9e65-98961ff59215",
    "amount": 100,
    "source": {
      "userId": "usr_abc123",
      "chain": "POLYGON",
      "currency": "usdc"
    },
    "destination": {
      "userId": "usr_abc123",
      "chain": "ETHEREUM",
      "currency": "usdc"
    },
    "requireApproval": true
  }'

Review pending bridge

The bridge enters PENDING_APPROVAL status. Dashboard admins are notified to approve or reject via email and webhook.

Execution or rejection

If approved, the bridge proceeds through normal processing. If rejected, it is cancelled.

Getting Help

📧 Email: support@hifi.com
💬 Slack: Message us in our shared Slack channel

Wallet Transfers - Same-chain transfers
Wallets - Understand wallet addresses and balances
Webhooks - Real-time bridge status notifications
API Reference - Complete endpoint documentation

Introduction

Core concepts

Features

Compliance

Payments

References

Bridging

How Bridging Works

Creating Bridge Requests

Transaction Status

Source Chain Phase

Destination Chain Phase

Other Statuses

Tracking Bridges

Bridge Operations

Supported Routes

Key Concepts

Sample Code

Complete bridge flow

Bridge with approval

Getting Help

​How Bridging Works

​Creating Bridge Requests

​Transaction Status

​Source Chain Phase

​Destination Chain Phase

​Other Statuses

​Tracking Bridges

​Bridge Operations

​Supported Routes

​Key Concepts

​Sample Code

​Complete bridge flow

​Bridge with approval

​Getting Help

​Related Resources

How Bridging Works

Creating Bridge Requests

Transaction Status

Source Chain Phase

Destination Chain Phase

Other Statuses

Tracking Bridges

Bridge Operations

Supported Routes

Key Concepts

Sample Code

Complete bridge flow

Bridge with approval

Getting Help

Related Resources