Bridge Tokens
Bridge a token from one or many source chains to a single destination chain using the Nexus SDK.
Note
SET UP THE SDK BEFORE YOU START:Install and initialize the client first — see Installation and SDK Setup.
bridge() function to bridge a specific token from one (or many) chains to a single chain.
Use the simulateBridge() function to simulate the bridge transaction to preview the costs and fees, before actually executing the transaction.
Method signature
bridge(
params: BridgeParams,
options?: BridgeOperationOptions,
): Promise<BridgeResult>
simulateBridge(
params: BridgeParams,
): Promise<BridgeSimulationResult>Parameters
/**
* Parameters for bridging tokens.
*/
export interface BridgeParams {
recipient?: Hex;
toTokenSymbol: string;
toAmountRaw: bigint;
toChainId: number;
toNativeAmountRaw?: bigint;
sources?: number[];
}BridgeParams: Parameters for bridging tokens.recipient(Hex, optional): The recipient address. Defaults to the address of the connected user.toTokenSymbol(string, required): The symbol of the token to be bridged (e.g.'USDC').toAmountRaw(bigint, required): The amount of tokens to receive on the destination chain, in raw integer units.toChainId(number, required): The chain ID of the destination chain.toNativeAmountRaw(bigint, optional): Amount of destination-chain native gas to also deliver to the recipient, in raw integer units.sources(number[], optional): The chain IDs of the source chains to be used for the bridge. Useful if you want to maintain your holdings on some chains.
options:BridgeOperationOptions(optional): Per-operation hooks, event listener, and fill timeout.
export type BridgeOperationOptions = {
hooks?: {
onIntent?: (data: OnIntentHookData) => void;
onAllowance?: (data: OnAllowanceHookData) => void;
};
onEvent?: (event: BridgeEvent) => void;
fillTimeoutMinutes?: number;
};hooks.onIntent(optional): Called with the resolved intent before execution. Calldata.allow()/data.deny(), ordata.refresh(sources?)to re-quote. When omitted, the intent is auto-approved.hooks.onAllowance(optional): Called when ERC-20 allowances are required. Calldata.allow([...])with a strategy per source. When omitted, allowances default to'min'.onEvent(optional): Callback that receives the typedBridgeEventunion as the operation progresses. Use it to render progress to the user.fillTimeoutMinutes(optional): How long to wait for the bridge to be filled before timing out. Defaults to2.
Note
The
onEvent callback receives a typed discriminated union (status / plan_preview / plan_confirmed / plan_progress). See the Bridge Events page for the full event shapes.Example
import type { BridgeParams, BridgeResult } from '@avail-project/nexus-core';
const bridgeResult: BridgeResult = await client.bridge(
{
toTokenSymbol: 'USDC',
toAmountRaw: 83_500_000n, // 83.5 USDC (6 decimals)
toChainId: 137, // Polygon
} satisfies BridgeParams,
{
onEvent: (event) => {
switch (event.type) {
case 'plan_preview':
// Ordered list of steps about to run — render them if you wish
console.log('Steps:', event.plan.steps);
break;
case 'plan_progress':
// Granular per-step progress
if (event.stepType === 'request_submission' && event.state === 'completed') {
console.log('Explorer:', event.explorerUrl);
}
break;
}
},
},
);
console.log('Bridge result:', bridgeResult);
// Simulate bridge to preview costs.
// You can use the convertTokenReadableAmountToBigInt helper to build the raw amount.
const toAmountRaw = client.convertTokenReadableAmountToBigInt('83.5', 'USDC', 137);
const bridgeSimulation = await client.simulateBridge({
toTokenSymbol: 'USDC',
toAmountRaw,
toChainId: 137,
});
console.log('Bridge simulation:', bridgeSimulation);Warning
bridge() and simulateBridge() throw typed NexusError subclasses on failure (e.g. UserActionError on a wallet rejection, ValidationError on bad input). Branch on error.category / error.code.Return Value
bridge()
BridgeResult object.
/**
* Result structure for bridge transactions.
*/
export type BridgeResult = {
intentExplorerUrl: string;
sourceTxs: SourceTxs; // array of per-source deposit transactions
intent: BridgeIntent;
};
export type TxResult = {
txHash: Hex;
txExplorerUrl: string;
receipt?: TransactionReceipt;
};
export type SourceTxs = (TxResult & {
chain: { id: number; name: string; logo: string };
})[];simulateBridge()
BridgeSimulationResult object.
export interface BridgeSimulationResult {
intent: BridgeIntent;
token: TokenInfo;
}
export type BridgeIntent = {
provider: 'nexus' | 'mayan';
availableSources: {
amount: string;
amountRaw: bigint;
chain: { id: number; name: string; logo: string };
token: { decimals: number; symbol: string; logo: string; contractAddress: Hex };
value: string;
}[];
destination: {
amount: string;
amountRaw: bigint;
chain: { id: number; name: string; logo: string };
token: { decimals: number; symbol: string; logo: string; contractAddress: Hex };
value: string;
nativeAmount: string;
nativeAmountRaw: bigint;
nativeAmountValue: string;
nativeAmountInToken: string;
nativeToken: { decimals: number; symbol: string; logo: string; contractAddress: Hex };
};
fees: {
caGas: string;
protocol: string;
solver: string;
total: string;
totalValue: string;
};
selectedSources: {
amount: string;
amountRaw: bigint;
chain: { id: number; name: string; logo: string };
token: { decimals: number; symbol: string; logo: string; contractAddress: Hex };
value: string;
}[];
sourcesTotal: string;
sourcesTotalValue: string;
};
type TokenInfo = {
contractAddress: `0x${string}`;
decimals: number;
logo: string;
name: string;
symbol: string;
};Note
BridgeIntent replaces the v1 ReadableIntent type: sources → selectedSources, allSources → availableSources, and chain fields are nested under chain: { id, name, logo }. See the full type definitions on GitHub.How is this guide?