lifi.bridge

lifi.bridge sends a token from the flow’s chain to another chain through the LI.FI aggregator. It consumes a resource on amountIn and produces amountOut, a resource of the resourceOut token on the destination chain. At compile time the op fetches one LI.FI quote, which picks the bridge and any source-chain swap step. The transaction calls the LI.FI router with that quote’s calldata. For a swap on the same chain, use lifi.swap.

Ports

Port	Kind	Meaning
`amountIn`	input resource	The tokens to bridge, on the flow’s chain. Native coin or ERC-20.
`amountOut`	output resource, future	The tokens that arrive on the destination chain. It carries the quote’s minimum (`providesMinimum`).
`unspentIn`	output resource	Input above the quoted amount, in the input token. Omitted when zero.

amountOut is a future output: it takes no guards and can’t feed another op in the same flow, except a continuation.settle node. unspentIn follows the lifi.swap rules.

Config

Field	Type	Default	Meaning
`resourceOut`	resource	required	Token and chain to receive, e.g. `resources.erc20(BASE_USDC, 8453)` or `resources.native(8453)`. Must be on a different chain from `amountIn`.
`destination`	address	none	Address that receives `amountOut` on the destination chain. Required unless `amountOut` funds a `continuation.settle` node, in which case you must omit it.
`slippage`	number in `[0, 1]`	`0.03`	Slippage tolerance as a fraction: `0.005` is 0.5%. It sets the quote’s minimum output.
`order`	`'FASTEST'` \| `'CHEAPEST'`	LI.FI default	Which route the LI.FI API prefers.
`bridges`	`{ allow?, deny?, prefer? }`	none	Bridge tool keys to allow, deny or rank first, up to 50 per list. `allow` and `deny` can’t both be set.
`exchanges`	`{ allow?, deny?, prefer? }`	none	Same shape, for the DEXs a source-chain swap step can use.
`timing`	`{ swapStepTimingStrategies?, routeTimingStrategies? }`	Composer default	How long the LI.FI API waits for quotes before it answers. Same shape as the LI.FI API’s timing strategies.

Tool keys are the key values from the LI.FI API’s GET /v1/tools, for example across, stargateV2 or relaydepository.

Example

Bridge 1,000 USDC from Arbitrum to a recipient on Base:

import { createComposeSdk, materialisers, resources } from '@lifi/composer-sdk';

const ARBITRUM = 42161;
const BASE = 8453;
const ARB_USDC = '0xaf88d065e77c8cC2239327C5EDb3A432268e5831';
const BASE_USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
const RECIPIENT = '0xYourRecipientAddress';

const sdk = createComposeSdk({
  baseUrl: 'https://composer.li.quest',
  apiKey: process.env.LIFI_API_KEY!,
});

const builder = sdk.flow(ARBITRUM, {
  name: 'bridge-usdc-to-base',
  inputs: { amountIn: resources.erc20(ARB_USDC, ARBITRUM) },
});

builder.lifi.bridge('bridge', {
  bind: { amountIn: builder.inputs.amountIn },
  config: {
    resourceOut: resources.erc20(BASE_USDC, BASE),
    destination: RECIPIENT, // where the USDC lands on Base
    slippage: 0.005, // 0.5%; omit to use the 3% default
    order: 'CHEAPEST',
  },
});

const result = await builder.compile({
  signer: '0xYourSignerAddress',
  inputs: {
    amountIn: materialisers.directDeposit({ amount: '1000000000' }), // 1,000 USDC
  },
  sweepTo: builder.context.sender,
});

const out = result.outputs['bridge.amountOut'];
if (out?.role === 'terminal' && out.delivery.when === 'future') {
  console.log('floor on Base:', out.amount.minimum?.value);
  console.log('expected:', out.amount.estimate?.value);
  console.log('bridge tool:', out.delivery.provider, 'eta (s):', out.delivery.etaSeconds);
}

This is the deliver-only path: the tokens land at destination and nothing runs on Base. To run more steps once they arrive, see Bridge into a continuation; to pick between the two, see Which cross-chain path?.

Track the delivery

The compile result describes bridge.amountOut before you send anything:

amount.minimum.value is the floor the bridge quote guarantees on the destination chain. amount.estimate.value is the quote’s expected amount, which is not enforced.
delivery.provider is the LI.FI tool key of the chosen bridge, for example across.
delivery.etaSeconds is the quote’s estimated delivery time. It is absent when the bridge publishes no estimate.

After the source transaction confirms, poll the LI.FI API’s GET /v1/status with the transaction hash as txHash and delivery.provider as bridge. See Transaction status tracking for the status values. The bridge call’s sender is the signer’s execution proxy (result.userProxy), not the wallet: the quote names the proxy as fromAddress. So a bridge that fails and refunds on the source chain returns the tokens to the proxy. To move them to the wallet, compile a flow on the source chain for the same signer that reads the proxy’s balance with core.balanceOf and sends it to context.sender with core.transfer, as shown in Non-transferable terminal resources.

Bridge into a continuation

amountOut can fund a continuation.settle node on the destination chain. Bind the settle node’s input to bridge.amountOut and omit the bridge’s destination; the compiler quotes the bridge with the escrow as receiver. The settle node’s expiry must leave room for the bridge: at least three times the quoted ETA, and never less than 30 minutes. See Cross-chain flows and the Bridge and deposit recipe.

Errors

Error	Cause	Fix
`validation_error`: “source and destination are on the same chain; use lifi.swap”	`resourceOut` is on the input’s chain.	Use `lifi.swap`.
`validation_error`: “cannot spend a non-exact deposit token”	`amountIn` is a token whose transfers credit a wei or two less than sent, such as stETH or an Aave aToken.	Swap or unwrap it into a plain ERC-20 first.
`provider_error` naming a bridge tool	The quote has no usable minimum output, or the bridge charges a native-coin fee on an ERC-20 transfer. Composer can’t fund such a fee.	Steer the quote away from that bridge with `bridges: { deny: ['<tool>'] }`.
`no_route_error`	The LI.FI API found no route for this pair and amount.	Try another amount, token or `bridges` preference.
`price_impact_exceeded`	The LI.FI API found routes but dropped them all for price impact.	Bridge a smaller amount or a more liquid token.

lifiIntents.order: move tokens through a LI.FI Intents order instead.
continuation.settle: run more steps on the destination chain when the bridge delivers.
Bridge and deposit: a bridge into a cross-chain flow.

Introduction

Integrate via Composer API

Integrate via LI.FI API

Resources

Ports

Config

Example

Track the delivery

Bridge into a continuation

Errors

​Ports

​Config

​Example

​Track the delivery

​Bridge into a continuation

​Errors

​Related

Ports

Config

Example

Track the delivery

Bridge into a continuation

Errors

Related