> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hifi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bridging

> Bridging transfers stablecoins across different blockchain networks. Move assets from one chain to another, such as transferring USDC from Ethereum to Polygon or Solana.

## How Bridging Works

Bridging follows a straightforward process:

<Steps>
  <Step title="Create bridge request">
    Specify source chain, destination chain, and amount to bridge.
  </Step>

  <Step title="Processing">
    HIFI executes the cross-chain operations (burn on source, mint on
    destination).
  </Step>

  <Step title="Completion">Stablecoins arrive on the destination chain.</Step>
</Steps>

## Creating Bridge Requests

Use the [Create Bridge](https://docs.hifi.com/api-reference/bridge/create-a-bridge) endpoint to initiate a cross-chain transfer.

**Request:**

```bash theme={null}
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:

<Accordion title="Response">
  ```json theme={null}
  {
    "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"
        }
      }
    }
  }
  ```
</Accordion>

<ResponseField name="transferDetails.id" type="string">
  Unique bridge ID. Use this to check status using the [Retrieve
  Bridge](https://docs.hifi.com/api-reference/cross-chain-bridge/retrieve-a-bridging-request)
  endpoint.
</ResponseField>

<ResponseField name="transferDetails.status" type="string">
  Bridge status. Progression: `CREATED` → `SOURCE_INITIATED` →
  `SOURCE_PROCESSED` → `DESTINATION_INITIATED` → `COMPLETED`. See [Transaction
  Status](#transaction-status) for details.
</ResponseField>

<ResponseField name="transferDetails.source" type="object">
  Source chain details including wallet address, chain, and currency.
</ResponseField>

<ResponseField name="transferDetails.destination" type="object">
  Destination chain details including wallet address, chain, and currency.
</ResponseField>

<ResponseField name="transferDetails.amount" type="number">
  Amount being bridged in the specified currency.
</ResponseField>

<ResponseField name="transferDetails.quoteInformation" type="object">
  Bridge quote details including amounts and rate. For same-asset bridges, the
  rate is always "1".
</ResponseField>

<ResponseField name="transferDetails.receipt" type="object">
  Transaction receipt. Contains `transactionHash` and `operations` (approve,
  burn, mint) once bridge operations are executed on-chain.
</ResponseField>

<Info>
  For detailed field documentation, see the [Create
  Bridge](https://docs.hifi.com/api-reference/bridge/create-a-bridge) API
  reference.
</Info>

## 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

<Note>
  **Status Updates:** Subscribe to `WALLET.BRIDGE.CREATE` and
  `WALLET.BRIDGE.UPDATE` webhook events to receive real-time status
  notifications. See [Webhooks](/docs/webhooks) for setup instructions.
</Note>

Monitor bridge status using the [Retrieve Bridge](https://docs.hifi.com/api-reference/bridge/retrieve-a-bridge) endpoint.

**Request:**

```bash theme={null}
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:

<Accordion title="Response">
  ```json theme={null}
  {
    "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"
          }
        }
      }
    }
  }
  ```
</Accordion>

<ResponseField name="transferDetails.status" type="string">
  Bridge status. `COMPLETED` means tokens have been successfully minted on the
  destination chain.
</ResponseField>

<ResponseField name="transferDetails.receipt.operations" type="object">
  Blockchain operations that were executed during the bridge. Each operation
  (approve, burn, mint) contains `transactionHash`, `userOpHash`, and `chain`
  for verification on block explorers.
</ResponseField>

## 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

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

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="External Wallet Bridging">
    You can bridge to external wallet addresses (not managed by HIFI) by providing `walletAddress` instead of `userId` in the destination:

    ```json theme={null}
    {
      "destination": {
        "chain": "ETHEREUM",
        "currency": "usdc",
        "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
      }
    }
    ```

    <Warning>
      **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.
    </Warning>
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Sample Code

### Complete bridge flow

<Steps>
  <Step title="Create bridge request">
    ```bash theme={null}
    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"
        }
      }'
    ```
  </Step>

  <Step title="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
  </Step>

  <Step title="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)
  </Step>
</Steps>

### Bridge with approval

<Steps>
  <Step title="Create bridge with approval">
    Set `requireApproval: true` for multi-party authorization:

    ```bash theme={null}
    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
      }'
    ```
  </Step>

  <Step title="Review pending bridge">
    The bridge enters `PENDING_APPROVAL` status. Dashboard admins are notified to
    approve or reject via email and webhook.
  </Step>

  <Step title="Execution or rejection">
    If approved, the bridge proceeds through normal processing. If rejected, it is cancelled.
  </Step>
</Steps>

## Getting Help

* 📧 **Email:** [support@hifi.com](mailto:support@hifi.com)
* 💬 **Slack:** Message us in our shared Slack channel

## Related Resources

* [Wallet Transfers](/docs/transactions/transfers) - Same-chain transfers
* [Wallets](/docs/wallets) - Understand wallet addresses and balances
* [Webhooks](/docs/webhooks) - Real-time bridge status notifications
* [API Reference](https://docs.hifi.com/api-reference/bridge/create-a-bridge) - Complete endpoint documentation