`bridge()`

SET UP THE SDK BEFORE YOU START:

You can find the SDK setup instructions in the Quickstart page.
We also created a tutorial to make it easier to understand how devs need to initialize the Nexus SDK in their project.

Use the 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.

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

Method signature

Typescript


async bridge(
  params: BridgeParams,
  options?: OnEventParam,
): Promise<BridgeResult>
 
async simulateBridge(
  params: BridgeParams,
): Promise<SimulationResult>

Parameters

Typescript


/**
 * Parameters for bridging tokens.
 */
export interface BridgeParams {
  recipient?: Hex;
  token: string;
  amount: bigint;
  toChainId: number;
  gas?: bigint;
  sourceChains?: number[];
}

BridgeParams: Parameters for bridging tokens.
- recipient (Hex, optional): The recipient address. Default’s to the address of the user.
- token (string, required): The token to be bridged.
- amount (bigint, required): The amount of tokens to be bridged.
- toChainId (number, required): The chain ID of the destination chain.
- gas (bigint, optional): The gas limit for the bridge transaction.
- sourceChains (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: OnEventParam (optional): Optional callback function to listen to the events emitted by the bridge operation.
- onEvent: SDK emits these events as the transaction progresses. This is helpful to add when trying to display transaction progress to the user. With this you receive:
  - STEPS_LIST: An ordered array of BridgeStepType objects. This array contains the steps that will be executed to fulfill the intent.
  - STEP_COMPLETE: A single BridgeStepType that is emitted for each completed step of the intent’s fulfillment.

You can check out the type definitions for each step type in the Bridge Events page.

Example

Typescript


import { BridgeParams, BridgeResult, NEXUS_EVENTS } from '@avail-project/nexus-core';
 
const bridgeResult: BridgeResult = await sdk.bridge(
  {
    token: 'USDC',
    amount: 83_500_000n, // 83.5 USDC (6 decimals)
    toChainId: 137, // Polygon
  } satisfies BridgeParams,
  {
    onEvent: (event) => {
      if (event.name === NEXUS_EVENTS.STEPS_LIST) {
        // render steps if you wish to display them to the user
      } else if (event.name === NEXUS_EVENTS.STEP_COMPLETE) {
        // Returned per step of intent fulfillment. You can use this to mark the step as done and show the explorer URL if present.
        const step = event.args;
        if (step.type === 'INTENT_SUBMITTED') {
          const url = (step as any).data?.explorerURL;
          if (url) console.log('Explorer:', url);
        }
      }
    },
  }
);
 
console.log('Bridge result:', bridgeResult);
 
 
// Simulate bridge to preview costs
// Note that you can avoid using optional params
const amount = sdk.convertTokenReadableAmountToBigInt('83.5', 'USDC', 137); // Alternative way to pass the amount using a helper function from the SDK
const bridgeSimulation = await sdk.simulateBridge({
  token: 'USDC',
  amount,
  toChainId: 137,
});
 
console.log('Bridge simulation:', bridgeSimulation);

Return Value

`bridge()`

The return value is a BridgeResult object.

Typescript


/**
 * Result structure for bridge transactions.
 */
export type BridgeResult = {
  explorerUrl: string;
};

`simulateBridge()`

The return value is a SimulationResult object.

Typescript


export interface SimulationResult {
  intent: ReadableIntent;
  token: TokenInfo;
}
 
export type ReadableIntent = {
  allSources: {
    amount: string;
    chainID: number;
    chainLogo: string | undefined;
    chainName: string;
    contractAddress: `0x${string}`;
  }[];
  destination: {
    amount: string;
    chainID: number;
    chainLogo: string | undefined;
    chainName: string;
  };
  fees: {
    caGas: string;
    gasSupplied: string;
    protocol: string;
    solver: string;
    total: string;
  };
  sources: {
    amount: string;
    chainID: number;
    chainLogo: string | undefined;
    chainName: string;
    contractAddress: `0x${string}`;
  }[];
  sourcesTotal: string;
  token: {
    decimals: number;
    logo: string | undefined;
    name: string;
    symbol: string;
  };
};
 
 
type TokenInfo = {
  contractAddress: `0x${string}`;
  decimals: number;
  logo: string;
  name: string;
  symbol: string;
};