`transfer()`

SET UP THE SDK BEFORE YOU START:

You can find the SDK setup instructions in the Overview page.

Use the transfer() function to source a token from multiple source chains to a single destination chain.

Method signature

Typescript


async transfer(params: TransferParams): Promise<TransferResult>
async simulateTransfer(params: TransferParams): Promise<SimulationResult>

Parameters

Typescript


/**
 * Parameters for transferring tokens.
 */
export interface TransferParams {
  token: SUPPORTED_TOKENS;
  amount: number | string;
  chainId: SUPPORTED_CHAINS_IDS;
  recipient: `0x${string}`;
  sourceChains?: number[];
}

chainID refers to the Chain ID of the recipient chain.
sourceChains is an optional param that takes an array of chainIDs. Use this if you want only some of your funds to be used for the transfer. Helpful if you want to maintain your holdings on some chains.

Example

Typescript


import type { TransferParams, TransferResult, SimulationResult } from '@avail-project/nexus-core';
 
// Smart transfer with automatic optimization
const result: TransferResult = await sdk.transfer({
  token: 'USDC', // Token to be bridged and transferred
  amount: 100,
  chainId: 42161, // Transfer selected funds to Arbitrum
  recipient: '0x...',
  sourceChains: [84532, 80002], // Only use ETH from `Base Sepolia` and `Polygon Amoy` as sources for the transfer
} as TransferParams);
 
// The SDK automatically:
// 1. Checks if you have USDC + native token for gas on destination chain
// 2. Uses the normal direct token transfer if sufficient funds are available on destination chain (faster, cheaper)
// 3. Falls back to chain abstraction and sources the token from other chains if local funds are insufficient
 
// Simulate transfer to preview costs and optimization path
const simulation: SimulationResult = await sdk.simulateTransfer({
  token: 'USDC',
  amount: 100,
  chainId: 42161,
  recipient: '0x...',
  sourceChains: [84532, 80002], 
});
 
// Check if direct transfer will be used
console.log('Fees:', simulation.intent.fees);
// For direct transfers: gasSupplied shows actual native token cost
// For CA transfers: includes additional CA routing fees

Return Value

The return value is a TransferResult object, which is a union type.

Typescript


/**
 * Result structure for transfer transactions.
 */
export type TransferResult =
 
// Upon success, returns the transaction hash and explorer url
  | {
      success: true;
      transactionHash: string;
      explorerUrl: string;
    }
  // Upon failure, returns the error message
  | {
      success: false;
      error: string;
    };