Bridge and Transfer

Source a token from multiple chains and transfer it to a single destination chain using bridgeAndTransfer().

Note

SET UP THE SDK BEFORE YOU START:Install and initialize the client first — see Installation and SDK Setup.

Use the bridgeAndTransfer() function to source a token from multiple source chains to a single destination chain. Use the simulateBridgeAndTransfer() function to simulate the bridge and transfer transaction to preview the costs and fees, before actually executing the transaction.

Note

Note: Check out the API reference for a full list of supported tokens and chains.

Method signature

TypeScript

bridgeAndTransfer(
  params: TransferParams,
  options?: BridgeOperationOptions,
): Promise<TransferResult>
 
simulateBridgeAndTransfer(
  params: TransferParams,
): Promise<BridgeAndExecuteSimulationResult>

Parameters

TypeScript

/**
 * Parameters for bridging and transferring tokens.
 */
export interface TransferParams {
  toTokenSymbol: string;
  toAmountRaw: bigint;
  toChainId: number;
  recipient: `0x${string}`;
  sources?: number[];
}

TransferParams: Parameters for transferring tokens.
- toTokenSymbol (string, required): The symbol of the token to be bridged and transferred (e.g. 'USDC').
- toAmountRaw (bigint, required): The amount of tokens to transfer to the recipient, in raw integer units.
- toChainId (number, required): The chain ID of the destination chain.
- recipient (0x${string}, required): The recipient address.
- sources (number[], optional): The chain IDs of the source chains to be used for the transfer. Useful if you want to maintain your holdings on some chains.
options: BridgeOperationOptions (optional): Per-operation hooks, event listener, and fill timeout — the same options object accepted by bridge().

TypeScript

export type BridgeOperationOptions = {
  hooks?: {
    onIntent?: (data: OnIntentHookData) => void;
    onAllowance?: (data: OnAllowanceHookData) => void;
  };
  onEvent?: (event: BridgeEvent) => void;
  fillTimeoutMinutes?: number;
};

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

TypeScript

import type { TransferParams, TransferResult } from '@avail-project/nexus-core';
 
// Smart transfer with automatic optimization
const bridgeAndTransferResult: TransferResult = await client.bridgeAndTransfer(
  {
    toTokenSymbol: 'USDC',
    toAmountRaw: 1_530_000n, // 1.53 USDC (6 decimals)
    toChainId: 1, // Ethereum
    recipient: '0x742d35Cc6634C0532925a3b8D4C9db96c4b4Db45',
  },
  {
    onEvent: (event) => {
      if (event.type === 'plan_preview') console.log('Transfer steps:', event.plan.steps);
      if (event.type === 'plan_progress') console.log('Step progress:', event.stepType, event.state);
    },
  },
);
 
console.log('Bridge and transfer result:', bridgeAndTransferResult);
 
const bridgeAndTransferSimulation = await client.simulateBridgeAndTransfer({
  toTokenSymbol: 'USDC',
  toAmountRaw: 1_530_000n, // 1.53 USDC (6 decimals)
  toChainId: 1,
  recipient: '0x742d35Cc6634C0532925a3b8D4C9db96c4b4Db45',
});
 
console.log('Bridge and transfer simulation:', bridgeAndTransferSimulation);

Warning

bridgeAndTransfer() throws typed NexusError subclasses on failure. Branch on error.category / error.code.

Return Value

`bridgeAndTransfer()`

The return value is a TransferResult object, which is an alias for BridgeAndExecuteResult.

TypeScript

/**
 * Result structure for transfer transactions.
 */
export type TransferResult = BridgeAndExecuteResult;
 
export type BridgeAndExecuteResult = {
  approval?: TxResult;
  execute: TxResult;
} & (
  | { bridgeSkipped: false; bridgeResult: BridgeResult }
  | { bridgeSkipped: true; bridgeResult?: undefined }
);

`simulateBridgeAndTransfer()`

The return value is a BridgeAndExecuteSimulationResult object.

TypeScript

export type BridgeAndExecuteSimulationResult = {
  bridgeSimulation: BridgeSimulationResult | null; // null when bridging is skipped
  executeSimulation: ExecuteSimulation;
};

How is this guide?

Bridge Tokens

Bridge & Execute

Method signature Parameters Example Return Value bridgeAndTransfer()simulateBridgeAndTransfer()

Edit in GitHub

bridgeAndTransfer( params: TransferParams, options?: BridgeOperationOptions, ): Promise<TransferResult> simulateBridgeAndTransfer( params: TransferParams, ): Promise<BridgeAndExecuteSimulationResult>

/** * Parameters for bridging and transferring tokens. */ export interface TransferParams { toTokenSymbol: string; toAmountRaw: bigint; toChainId: number; recipient: `0x${string}`; sources?: number[]; }

export type BridgeOperationOptions = { hooks?: { onIntent?: (data: OnIntentHookData) => void; onAllowance?: (data: OnAllowanceHookData) => void; }; onEvent?: (event: BridgeEvent) => void; fillTimeoutMinutes?: number; };

import type { TransferParams, TransferResult } from '@avail-project/nexus-core'; // Smart transfer with automatic optimization const bridgeAndTransferResult: TransferResult = await client.bridgeAndTransfer( { toTokenSymbol: 'USDC', toAmountRaw: 1_530_000n, // 1.53 USDC (6 decimals) toChainId: 1, // Ethereum recipient: '0x742d35Cc6634C0532925a3b8D4C9db96c4b4Db45', }, { onEvent: (event) => { if (event.type === 'plan_preview') console.log('Transfer steps:', event.plan.steps); if (event.type === 'plan_progress') console.log('Step progress:', event.stepType, event.state); }, }, ); console.log('Bridge and transfer result:', bridgeAndTransferResult); const bridgeAndTransferSimulation = await client.simulateBridgeAndTransfer({ toTokenSymbol: 'USDC', toAmountRaw: 1_530_000n, // 1.53 USDC (6 decimals) toChainId: 1, recipient: '0x742d35Cc6634C0532925a3b8D4C9db96c4b4Db45', }); console.log('Bridge and transfer simulation:', bridgeAndTransferSimulation);

/** * Result structure for transfer transactions. */ export type TransferResult = BridgeAndExecuteResult; export type BridgeAndExecuteResult = { approval?: TxResult; execute: TxResult; } & ( | { bridgeSkipped: false; bridgeResult: BridgeResult } | { bridgeSkipped: true; bridgeResult?: undefined } );

Search Documentation

Bridge and Transfer

Method signature

Parameters

Example

Return Value

bridgeAndTransfer()

simulateBridgeAndTransfer()

Search Documentation

Bridge and Transfer

Method signature

Parameters

Example

Return Value

bridgeAndTransfer()

simulateBridgeAndTransfer()

`bridgeAndTransfer()`

`simulateBridgeAndTransfer()`

`bridgeAndTransfer()`

`simulateBridgeAndTransfer()`