Bridging Integration Guide - Relay

Before you start

While not mandatory for integration, doing the following will improve the UX for your users considerably:

• Verify user balance - Ensure the user has sufficient funds for the bridge amount plus fees
• Check chain support - Confirm both origin and destination chains are supported
• Validate quote - Quotes are revalidated when being filled, keep your quotes as fresh as possible.
• Handle errors - Implement proper error handling for API requests and transaction failures

Get a Quote

Every action in Relay starts with a Quote, this includes bridging. The quote provides all necessary information including fees, transaction data, and execution steps. Use the quote endpoint to request a bridge quote. Relay supports three trade types for bridging:

• EXACT_INPUT — specify the amount you want to send; the output amount may vary based on fees and slippage.
• EXPECTED_OUTPUT — specify the approximate amount you want to receive; the input amount is calculated accordingly and the output may vary slightly due to slippage.
• EXACT_OUTPUT — specify the exact amount you want to receive; the input amount is calculated accordingly. If the exact output cannot be filled, the request fails and the user is refunded on the origin chain.

curl -X POST "https://api.relay.link/quote/v2" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "0x03508bb71268bba25ecacc8f620e01866650532c",
    "originChainId": 1,
    "destinationChainId": 8453,
    "originCurrency": "0x0000000000000000000000000000000000000000",
    "destinationCurrency": "0x0000000000000000000000000000000000000000",
    "amount": "100000000000000000",
    "tradeType": "EXACT_INPUT"
  }'

curl -X POST "https://api.relay.link/quote/v2" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "0x03508bb71268bba25ecacc8f620e01866650532c",
    "originChainId": 1,
    "destinationChainId": 8453,
    "originCurrency": "0x0000000000000000000000000000000000000000",
    "destinationCurrency": "0x0000000000000000000000000000000000000000",
    "amount": "100000000000000000",
    "tradeType": "EXACT_OUTPUT"
  }'

{
  "steps": [
    {
      "id": "deposit",
      "action": "Confirm transaction in your wallet",
      "description": "Deposit funds for executing the bridge",
      "kind": "transaction",
      "requestId": "0x92b99e6e1ee1deeb9531b5ad7f87091b3d71254b3176de9e8b5f6c6d0bd3a331",
      "items": [
        {
          "status": "incomplete",
          "data": {
            "from": "0x742d35Cc6634C0532925a3b8D9d4DB0a2D7DD5B3",
            "to": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
            "data": "0x00fad611",
            "value": "100000000000000000",
            "chainId": 1
          },
          "check": {
            "endpoint": "/intents/status?requestId=0x92b99e6e1ee1deeb9531b5ad7f87091b3d71254b3176de9e8b5f6c6d0bd3a331",
            "method": "GET"
          }
        }
      ]
    }
  ],
  "fees": {
    "gas": {
      "amount": "21000000000000000",
      "currency": "eth"
    },
    "relayer": {
      "amount": "5000000000000000",
      "currency": "eth"
    }
  },
  "details": {
    "operation": "bridge",
    "timeEstimate": 30,
    "currencyIn": {
      "currency": {
        "chainId": 1,
        "address": "0x0000000000000000000000000000000000000000",
        "symbol": "ETH",
        "name": "Ethereum",
        "decimals": 18
      },
      "amount": "100000000000000000"
    },
    "currencyOut": {
      "currency": {
        "chainId": 8453,
        "address": "0x0000000000000000000000000000000000000000",
        "symbol": "ETH",
        "name": "Ethereum",
        "decimals": 18
      },
      "amount": "95000000000000000"
    }
  }
}

You can learn more about quote request parameters and response data here.

Create an API key in the Relay Dashboard to raise your rate limits.

Execute the Bridge

After receiving a bridge quote, execute it by processing each step in the response. The execution handles both the origin chain transaction and destination chain fulfillment.

Learn more about step execution using the API here.

Monitor Bridge Status

You can check the status of a bridge operation at any time using the status endpoint with the requestId located inside each step object in your quote response.

curl "https://api.relay.link/intents/status/v3?requestId=0xed42e2e48c56b06f8f384d66d5f3e6c450fc3a2c7cba19d92a01a649a31a0e94"

{
  "status": "success",
  "inTxHashes": [
    "0xae0a66324f82bc54299663972b3a48c939af777ff795b13bd72e7755a6a68bb3"
  ],
  "txHashes": [
    "3exJVjCEMfqVCBN6FBCXPFp6JUmm91pBp9Mp5XWwkoBVAgcr6fM4kZyzdAhoRWtWAvVESMZPGA7G1CibTF8uxaMk"
  ],
  "updatedAt": 1769988962883,
  "originChainId": 8453,
  "destinationChainId": 792703809
}

Poll this endpoint once per second. For a real-time status stream you can subscribe to Relay’s websocket server.

Learn more about how to check the status of the fill here. Learn more about the status lifecycle, see the status lifecycle diagram.