Swap Exact Output

Receive an exact destination amount, funded from the wallet's balances on any supported chain.

swapWithExactOut() delivers the exact raw amount you request and lets the quote decide which balances fund it. It needs an initialized client with a connected wallet.

Signature

TypeScript

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

Parameters

Name	Type	Description
`toChainId`	`number`	Required. Destination chain ID.
`toTokenAddress`	`Hex`	Required. Destination token address.
`toAmountRaw`	`bigint`	Required, greater than `0n`. Amount to receive, in the destination token's base units.
`sources`	`Array<{ chainId: number; tokenAddress?: Hex }>`	Optional. Omit or pass `[]` to fund from any wallet balance. Otherwise, only the listed chains and tokens are used.
`toNativeAmountRaw`	`bigint`	Optional, default `0n`. Extra destination native token for gas, in native base units.
`options`	`SwapOperationOptions`	Optional. Slippage, timeouts, quote review, and events. See review quotes.

A source with only chainId allows any token on that chain. Sources are alternatives, not a required mix: the quote may use some or all of them. To list compatible sources, call getAvailableSourceTokens(destination, [], query). Resolve toAmountRaw with the destination token's decimals and toNativeAmountRaw with the chain's nativeCurrency.decimals.

Example

TypeScript

import { parseUnits } from '@avail-project/nexus-core/utils';
 
const destination = {
  chainId: 8453,
  tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
} as const;
const token = await client.getToken(destination);
const base = client.getSupportedChains().find((chain) => chain.id === destination.chainId)!;
 
const result = await client.swapWithExactOut({
  toChainId: destination.chainId,
  toTokenAddress: destination.tokenAddress,
  toAmountRaw: parseUnits('100', token.decimals),
  toNativeAmountRaw: parseUnits('0.0005', base.nativeCurrency.decimals),
  sources: [
    { chainId: 42161 }, // any token on Arbitrum
    { chainId: 1, tokenAddress: '0xA0b86991c6218b36c1d19d4a2e9eb0cE3606eB48' }, // USDC on Ethereum
  ],
});
 
console.log(result.intentId, result.intentExplorerUrl);

Without an onIntent hook, the SDK accepts the first quote automatically.

Returns

A promise that resolves with an IntentResult after the destination fill.

Errors

Code (`ERROR_CODES.*`)	Cause
`WALLET_NOT_CONNECTED`	No wallet is connected.
`INVALID_INPUT`	`toAmountRaw` is not positive, `toNativeAmountRaw` is negative, no provider serves the destination, no listed source shares a provider with it, or `slippageBps` is out of range.
`USER_INTENT_HOOK_DENIED`	Your hook called `deny()`.
`BACKEND_INSUFFICIENT_BALANCE`	The eligible balances cannot cover the quote.
`BACKEND_SAME_CHAIN_GAS_DROP_UNSUPPORTED`	`toNativeAmountRaw` is set on a same-chain route.
`BACKEND_FULFILMENT_WAIT_TIMEOUT`	No fill within `fillTimeoutMinutes`. The intent can still fill.
`ENVIRONMENT_NOT_SUPPORTED`	The client uses `network: 'testnet'`.

For quote diagnostics and recovery, see hooks and errors.

How is this guide?

Exact In

Swap & Execute

Signature Parameters Example Returns Errors

Edit in GitHub

Name

Type

Description

toChainId

number

Required. Destination chain ID.

toTokenAddress

Hex

Required. Destination token address.

toAmountRaw

bigint

Required, greater than 0n. Amount to receive, in the destination token's base units.

sources

Array<{ chainId: number; tokenAddress?: Hex }>

Optional. Omit or pass [] to fund from any wallet balance. Otherwise, only the listed chains and tokens are used.

toNativeAmountRaw

bigint

Optional, default 0n. Extra destination native token for gas, in native base units.

options

SwapOperationOptions

Optional. Slippage, timeouts, quote review, and events. See review quotes.

import { parseUnits } from '@avail-project/nexus-core/utils'; const destination = { chainId: 8453, tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base } as const; const token = await client.getToken(destination); const base = client.getSupportedChains().find((chain) => chain.id === destination.chainId)!; const result = await client.swapWithExactOut({ toChainId: destination.chainId, toTokenAddress: destination.tokenAddress, toAmountRaw: parseUnits('100', token.decimals), toNativeAmountRaw: parseUnits('0.0005', base.nativeCurrency.decimals), sources: [ { chainId: 42161 }, // any token on Arbitrum { chainId: 1, tokenAddress: '0xA0b86991c6218b36c1d19d4a2e9eb0cE3606eB48' }, // USDC on Ethereum ], }); console.log(result.intentId, result.intentExplorerUrl);

Code (ERROR_CODES.*)

Cause

WALLET_NOT_CONNECTED

No wallet is connected.

INVALID_INPUT

toAmountRaw is not positive, toNativeAmountRaw is negative, no provider serves the destination, no listed source shares a provider with it, or slippageBps is out of range.

USER_INTENT_HOOK_DENIED

Your hook called deny().

BACKEND_INSUFFICIENT_BALANCE

The eligible balances cannot cover the quote.

BACKEND_SAME_CHAIN_GAS_DROP_UNSUPPORTED

toNativeAmountRaw is set on a same-chain route.

BACKEND_FULFILMENT_WAIT_TIMEOUT

No fill within fillTimeoutMinutes. The intent can still fill.

ENVIRONMENT_NOT_SUPPORTED

The client uses network: 'testnet'.

Search Documentation

Swap Exact Output

Signature

Parameters

Example

Returns

Errors

Search Documentation

Swap Exact Output

Signature

Parameters

Example

Returns

Errors