bridge Bridge tokens from one or more source chains to a destination chain. The SDK automatically selects the most efficient source chains if not specified.
await sdk . bridge ( params : BridgeParams , options ?: OnEventParam ): Promise < BridgeResult >
Parameters Bridge operation parameters Token symbol to bridge: 'ETH', 'USDC', 'USDT', or 'USDM'
Amount in smallest unit (e.g., 6 decimals for USDC: 100_000_000n = 100 USDC)
Destination chain ID (e.g., 1 for Ethereum, 137 for Polygon)
Recipient address (defaults to connected wallet address)
Specific source chain IDs to use (auto-selected if omitted for optimal routing)
Gas amount to supply on destination chain for recipient
Event callbacks for tracking progress onEvent
(event: EventUnion) => void
Returns Destination chain block explorer URL for tracking the intent
Array of source chain transactions Show SourceTxs properties
Block explorer URL for this transaction
Complete intent details including sources, destination, and fees
Example Basic Bridge
With Progress Tracking
Specific Source Chains
Bridge to Another Address
With Gas Supply
const result = await sdk . bridge ({ token: 'USDC' , amount: 100_000_000 n , // 100 USDC (6 decimals) toChainId: 137 , // Polygon }); console . log ( 'Bridge complete!' ); console . log ( 'Explorer URL:' , result . explorerUrl ); console . log ( 'Source transactions:' , result . sourceTxs );
Error Handling import { NexusError , ERROR_CODES } from '@avail-project/nexus-core' ; try { const result = await sdk . bridge ({ token: 'USDC' , amount: 100_000_000 n , toChainId: 137 , }); } catch ( error ) { if ( error instanceof NexusError ) { switch ( error . code ) { case ERROR_CODES . INSUFFICIENT_BALANCE : console . error ( 'Insufficient balance for bridge' ); // Show user their available balance break ; case ERROR_CODES . USER_DENIED_INTENT : console . log ( 'User cancelled bridge' ); break ; case ERROR_CODES . USER_DENIED_ALLOWANCE : console . log ( 'User denied token approval' ); break ; case ERROR_CODES . LIQUIDITY_TIMEOUT : console . error ( 'Solver liquidity timeout - try again later' ); break ; case ERROR_CODES . TRANSACTION_TIMEOUT : console . error ( 'Transaction timed out' ); // Check explorer URL if available break ; default : console . error ( 'Bridge failed:' , error . message ); } } }
simulateBridge Simulate a bridge operation to preview fees, sources, and intent details without executing.
await sdk . simulateBridge ( params : BridgeParams ): Promise < SimulationResult >
Parameters Same parameters as bridge() method
Returns Complete intent preview with sources, fees, and destination details
Example Preview Fees
Show Confirmation UI
Compare Routes
const simulation = await sdk . simulateBridge ({ token: 'USDC' , amount: 100_000_000 n , toChainId: 137 , }); console . log ( 'Preview:' ); console . log ( 'Total fees:' , simulation . intent . fees . total ); console . log ( 'Protocol fee:' , simulation . intent . fees . protocol ); console . log ( 'Solver fee:' , simulation . intent . fees . solver ); console . log ( 'Gas fee:' , simulation . intent . fees . caGas ); console . log ( 'Sources:' , simulation . intent . sources );
calculateMaxForBridge Calculate the maximum amount that can be bridged for a given token and destination.
await sdk . calculateMaxForBridge ( params : Omit < BridgeParams , 'amount' > ): Promise < BridgeMaxResult >
Parameters params
Omit<BridgeParams, 'amount'>
required
Bridge parameters without the amount field Specific source chains (auto-selected if omitted)
Returns Maximum amount in smallest unit (raw bigint)
Maximum amount (human-readable)
Chain IDs where funds will be sourced from
Example Get Max Amount
Button
Validation
const max = await sdk . calculateMaxForBridge ({ token: 'USDC' , toChainId: 137 , }); console . log ( `Max bridgeable: ${ max . amount } ${ max . symbol } ` ); console . log ( `From chains: ${ max . sourceChainIds . join ( ', ' ) } ` ); console . log ( `Raw amount: ${ max . amountRaw } ` );
bridgeAndTransfer Bridge tokens and send to a specific recipient address (Attribution use case).
await sdk . bridgeAndTransfer ( params : TransferParams , options ?: OnEventParam ): Promise < TransferResult >
Parameters Transfer operation parameters Recipient address (different from sender)
Returns Execute transaction hash on destination chain
Block explorer URL for the execute transaction
Example Basic Transfer
Payment Flow
const result = await sdk . bridgeAndTransfer ({ token: 'USDC' , amount: 50_000_000 n , // 50 USDC toChainId: 42161 , // Arbitrum recipient: '0x742d35Cc6634C0532925a3b8D4C9db96c4b4Db45' , }); console . log ( 'Transfer complete!' ); console . log ( 'Transaction:' , result . transactionHash ); console . log ( 'Explorer:' , result . explorerUrl );
simulateBridgeAndTransfer Simulate a bridge-and-transfer operation.
await sdk . simulateBridgeAndTransfer ( params : TransferParams ): Promise < BridgeAndExecuteSimulationResult >
Parameters Same parameters as bridgeAndTransfer()
Returns BridgeAndExecuteSimulationResult
Bridge simulation (null if bridge not needed)
Execute simulation with gas estimates
Example const simulation = await sdk . simulateBridgeAndTransfer ({ token: 'USDC' , amount: 50_000_000 n , toChainId: 42161 , recipient: '0x...' , }); if ( simulation . bridgeSimulation ) { console . log ( 'Bridge fees:' , simulation . bridgeSimulation . intent . fees . total ); } console . log ( 'Execute gas:' , simulation . executeSimulation . gasUsed ); console . log ( 'Execute fee:' , simulation . executeSimulation . gasFee );
Execute Operations Bridge and execute smart contracts
Events & Steps Track bridge progress