Swap Exact Out

Swap tokens with an exact output amount across chains — e.g. get exactly 100 USDC on the destination.

Note

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

Use the swapWithExactOut() function to swap tokens with an exactly defined output amount. For example, if you want to get exactly 100 USDC 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 and tokens to a subset of the total supported holdings. Swaps are routed through multiple DEX aggregators (such as LiFi, Bebop, and 0x), quoted in parallel. Execution runs through a per-chain smart account chosen automatically — an ephemeral key delegated via EIP-7702 on 7702-enabled chains, or a deterministic Safe owned by the ephemeral key elsewhere. The connected EOA is never used to dispatch a swap directly.

Method signature

TypeScript

swapWithExactOut(
  input: SwapExactOutParams,
  options?: SwapOperationOptions,
): Promise<SwapResult>

Parameters

TypeScript

export interface SwapExactOutParams {
  sources?: Source[];
  toChainId: number;
  toTokenAddress: Hex;
  toAmountRaw: bigint;
  toNativeAmountRaw?: bigint;
}
 
export type Source = {
  tokenAddress: Hex;
  chainId: number;
};

SwapExactOutParams: Parameters for the swapWithExactOut() function.
- sources (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.
- 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.
- toAmountRaw (bigint, required): The exact amount of tokens you want to receive on the destination chain, in raw integer units (e.g. 1_000_000n for 1 USDC).
- toNativeAmountRaw (bigint, optional): Amount of native gas tokens to receive on the destination chain alongside the swap, in raw integer units (wei). Useful for ensuring the user has gas for subsequent transactions.
options: SwapOperationOptions (optional): Callbacks to track and gate the swap operation.

TypeScript

export type SwapOperationOptions = {
  onEvent?: (event: SwapEvent) => void;
  hooks?: {
    onIntent?: (data: OnIntentHookData) => void;
  };
  slippageTolerance?: number;
};

onEvent (optional): Receives status, plan_preview, plan_confirmed, and plan_progress updates as the swap progresses. See the Swap Events page for the full typed union.
hooks.onIntent (optional): Called with the resolved swap intent before execution. Call allow() to proceed, deny() to cancel, or refresh(sources?) to re-quote.
slippageTolerance (number, optional): Slippage override as a fraction (default 0.005, i.e. 0.5%).

Example

TypeScript

import type {
  SwapExactOutParams,
  SwapOperationOptions,
  SwapResult,
} from '@avail-project/nexus-core';
 
const result = await client.swapWithExactOut(
  {
    toChainId: 42161,
    toTokenAddress: '0xaf88d065e77c8cc2239327c5edb3a432268e5831', // USDC on Arbitrum
    toAmountRaw: 100_000_000n, // 100 USDC (6 decimals)
    // Optional: also fund destination native gas
    toNativeAmountRaw: 100_000_000_000_000n,
    // Optional: restrict route planning to specific source tokens/chains
    sources: [{ chainId: 8453, tokenAddress: '0x...' }],
  },
  {
    onEvent: (event) => {
      if (event.type === 'status') {
        console.log('Swap status:', event.status);
      }
      if (event.type === 'plan_preview') {
        console.log('Swap plan:', event.plan.steps);
        console.log('Has bridge:', event.plan.hasBridge);
        console.log('Has destination swap:', event.plan.hasDestinationSwap);
      }
    },
    hooks: {
      onIntent: ({ allow, deny, refresh, intent }) => {
        console.log('Swap intent:', intent);
        allow();
      },
    },
  },
);
 
console.log('Swap with exact out result:', result);

Return Value

The return value is a SwapResult object.

TypeScript

export type SwapResult = {
  sourceSwaps: ChainSwap[];
  intentExplorerUrl: string;
  destinationSwap: ChainSwap | null;
  intent: SwapIntent;
};
 
export type ChainSwap = {
  chainId: number;
  swaps: Swap[];
  txHash: Hex;
};
 
export type Swap = {
  inputAmount: bigint;
  inputContract: Hex;
  inputDecimals: number;
  outputAmount: bigint;
  outputContract: Hex;
  outputDecimals: number;
};

Note

On failure the method throws a typed NexusError subclass rather than returning an error result. See the full type definitions on GitHub.

How is this guide?

Exact In

Swap & Execute

Method signature Parameters Example Return Value

Edit in GitHub

export interface SwapExactOutParams { sources?: Source[]; toChainId: number; toTokenAddress: Hex; toAmountRaw: bigint; toNativeAmountRaw?: bigint; } export type Source = { tokenAddress: Hex; chainId: number; };

import type { SwapExactOutParams, SwapOperationOptions, SwapResult, } from '@avail-project/nexus-core'; const result = await client.swapWithExactOut( { toChainId: 42161, toTokenAddress: '0xaf88d065e77c8cc2239327c5edb3a432268e5831', // USDC on Arbitrum toAmountRaw: 100_000_000n, // 100 USDC (6 decimals) // Optional: also fund destination native gas toNativeAmountRaw: 100_000_000_000_000n, // Optional: restrict route planning to specific source tokens/chains sources: [{ chainId: 8453, tokenAddress: '0x...' }], }, { onEvent: (event) => { if (event.type === 'status') { console.log('Swap status:', event.status); } if (event.type === 'plan_preview') { console.log('Swap plan:', event.plan.steps); console.log('Has bridge:', event.plan.hasBridge); console.log('Has destination swap:', event.plan.hasDestinationSwap); } }, hooks: { onIntent: ({ allow, deny, refresh, intent }) => { console.log('Swap intent:', intent); allow(); }, }, }, ); console.log('Swap with exact out result:', result);

export type SwapResult = { sourceSwaps: ChainSwap[]; intentExplorerUrl: string; destinationSwap: ChainSwap | null; intent: SwapIntent; }; export type ChainSwap = { chainId: number; swaps: Swap[]; txHash: Hex; }; export type Swap = { inputAmount: bigint; inputContract: Hex; inputDecimals: number; outputAmount: bigint; outputContract: Hex; outputDecimals: number; };

Search Documentation

Swap Exact Out

Method signature

Parameters

Example

Return Value

Search Documentation

Swap Exact Out

Method signature

Parameters

Example

Return Value