Bridging
How to implement token bridging
Summary
Get a Quote
To bridge assets, you first need to get a quote that provides all necessary information including fees, transaction data, and execution steps. Use the quote endpoint to request bridging information.
Basic Quote Request
Quote Response Structure
The quote response contains all information needed to execute the bridge:
Quote Parameters
Parameter | Type | Required | Description |
---|---|---|---|
user | string | Yes | Address that will deposit funds and submit transactions |
originChainId | number | Yes | Source chain ID (e.g., 1 for Ethereum) |
destinationChainId | number | Yes | Destination chain ID (e.g., 8453 for Base) |
originCurrency | string | Yes | Currency contract on source chain (e.g., “0x0000000000000000000000000000000000000000”, “0x833589fcd6edb6e08f4c7c32d4f71b54bda02913”) |
destinationCurrency | string | Yes | Currency contract on destination chain |
amount | string | Yes | Amount in wei/smallest unit |
tradeType | string | Yes | ”EXACT_INPUT” or “EXACT_OUTPUT” |
recipient | string | No | Recipient address (defaults to user) |
slippageTolerance | string | No | Slippage in basis points (e.g., “50” for 0.5%) |
useExternalLiquidity | boolean | No | Use canonical+ bridging for more liquidity |
referrer | string | No | Identifier that can be used to monitor transactions from a specific source. |
refundTo | string | No | Address to send the refund to in the case of failure, if not specified the user address is used |
topupGas | boolean | No | If set, the destination fill will include a gas topup to the recipient (only supported for EVM chains if the requested currency is not the gas currency on the destination chain) |
topupGasAmount | string | No | The destination gas topup amount in USD decimal format, e.g 100000 = $1. topupGas is required to be enabled. Defaults to 2000000 ($2) |
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 /intents/status
endpoint:
Status Values
Status | Description |
---|---|
waiting | Deposit tx for the request is yet to be indexed |
pending | Deposit tx was indexed, now the fill is pending |
success | Relay completed successfully |
failure | Relay failed |
refund | Funds were refunded due to failure |
Advanced Features
App Fees
You can include app fees in your bridge requests to monetize your integration:
Custom Slippage
Control slippage tolerance for your bridges:
Preflight Checklist
☐ 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 expire after 30 seconds, so fetch fresh quotes before execution
☐ Handle errors - Implement proper error handling for API requests and transaction failures
☐ Monitor progress - Use the status endpoints to track bridge completion