`swapWithExactOut()`

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 swapWithExactOut() function to swap tokens with an exactly defined output amount. For example, if you want to get exactly 1 ETH on the destination but don’t care which amount of source funds are used to source the swap. You can however limit your source chains to a subset of the total supported chains.

Method signature

Typescript


async swapWithExactOut(
  input: ExactOutSwapInput,
  options?: OnEventParam,
): Promise<SwapResult>

Parameters

Typescript


export interface ExactOutSwapInput {
  fromSources?: Source[]; 
  toChainId: number;
  toTokenAddress: Hex;
  toAmount: bigint;
  toNativeAmount?: bigint;
}
 
export type Source = {
  tokenAddress: Hex;
  chainId: number;
};

ExactOutSwapInput: Parameters for the swapWithExactOut() function.
- toChainId (number, required): The chain ID of the destination chain where you want to receive tokens.
- toTokenAddress (Hex, required): The contract address of the token you want to receive.
- toAmount (bigint, required): The exact amount of tokens you want to receive on the destination chain (in the token’s smallest unit, e.g. 1_000_000n for 1 USDC).
- toNativeAmount (bigint, optional): Amount of native gas tokens to receive on the destination chain alongside the swap. Useful for ensuring the user has gas for subsequent transactions.
- fromSources (Source[], optional): Restrict which chains and tokens can be used as the swap source. If omitted, the SDK automatically selects the best sources from available balances.
  - tokenAddress (Hex): The contract address of the source token.
  - chainId (number): The chain ID of the source chain.
options: OnEventParam (optional): Callback to track transaction progress as it moves through each step.
- onEvent: Receives events as the swap progresses. Useful for displaying real-time status to the user.
  - SWAP_STEP_COMPLETE: Emitted after each completed step of the swap intent’s fulfillment.

Either of the Swap methods don’t emit STEPS_LIST events.
You can check out the type definitions for each step type in the Swap Events page.

Example

Typescript


import { SwapResult, NEXUS_EVENTS } from '@avail-project/nexus-core';
 
const swapWithExactOutResult = await sdk.swapWithExactOut({
  toChainId: 1,
  toTokenAddress: '0x...',
  toAmount: 1_000_000n,
}, {
  onEvent: (event) => {
    if (event.name === NEXUS_EVENTS.SWAP_STEP_COMPLETE) {
      console.log('Swap step complete:', event.args);
    }
  },
});
 
console.log('Swap with exact out result:', swapWithExactOutResult);

Return Value

The return value is a SwapResult object.

Typescript


export type SwapResult =
  | {
      success: true;
      result: SuccessfulSwapResult;
    }
  | { success: false; error: string };
 
export type SuccessfulSwapResult = {
  sourceSwaps: ChainSwap[];
  explorerURL: string;
  destinationSwap: ChainSwap | null;
};
 
export type ChainSwap = {
  chainId: number;
  swaps: Swap[];
  txHash: Hex;
};
 
export type Swap = {
  inputAmount: bigint;
  inputContract: Hex;
  inputDecimals: number;
  outputAmount: bigint;
  outputContract: Hex;
  outputDecimals: number;
};