Swap Exact Input

Swap tokens with an exact input amount across chains — e.g. swap 1 USDC for whatever you can get on the destination.

Note

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

Use the swapWithExactIn() function to swap tokens with an exactly defined input amount. For example, if you want to swap 1 USDC into whatever amount of the destination token you can get on the destination chain. 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

swapWithExactIn(
  input: SwapExactInParams,
  options?: SwapOperationOptions,
): Promise<SwapResult>

Parameters

TypeScript

export interface SwapExactInParams {
  sources?: (Source & { amountRaw?: bigint })[];
  toChainId: number;
  toTokenAddress: Hex;
}
 
export type Source = {
  tokenAddress: Hex;
  chainId: number;
};

SwapExactInParams: Parameters for using the swapWithExactIn() function.
- sources (Array<Source & { amountRaw? }>, optional): The source tokens and amounts to swap from. Omit to let the SDK use all available holdings.
  - chainId (number, required): The chain ID of the source chain.
  - tokenAddress (Hex, required): The contract address of the source token.
  - amountRaw (bigint, optional): The amount of the source token to swap, in raw integer units (e.g. 1_000_000n for 1 USDC).
- toChainId (number, required): The chain ID of the destination chain.
- toTokenAddress (Hex, required): The contract address of the token to receive on the destination chain.
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 {
  SwapExactInParams,
  SwapOperationOptions,
  SwapResult,
} from '@avail-project/nexus-core';
 
const result = await client.swapWithExactIn(
  {
    sources: [
      { chainId: 10, amountRaw: 1_000_000n, tokenAddress: '0x...' },
      { chainId: 42161, amountRaw: 500_000n, tokenAddress: '0x...' },
    ],
    toChainId: 8453,
    toTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  },
  {
    onEvent: (event) => {
      if (event.type === 'plan_progress') {
        console.log('Swap progress:', event.step.type, event.state);
      }
    },
    hooks: {
      onIntent: ({ intent, allow }) => {
        console.log('Swap intent:', intent);
        allow();
      },
    },
    slippageTolerance: 0.005,
  },
);
 
console.log('Swap with exact in 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?

Fetch Balances

Exact Out

Method signature Parameters Example Return Value

Edit in GitHub

export interface SwapExactInParams { sources?: (Source & { amountRaw?: bigint })[]; toChainId: number; toTokenAddress: Hex; } export type Source = { tokenAddress: Hex; chainId: number; };

import type { SwapExactInParams, SwapOperationOptions, SwapResult, } from '@avail-project/nexus-core'; const result = await client.swapWithExactIn( { sources: [ { chainId: 10, amountRaw: 1_000_000n, tokenAddress: '0x...' }, { chainId: 42161, amountRaw: 500_000n, tokenAddress: '0x...' }, ], toChainId: 8453, toTokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', }, { onEvent: (event) => { if (event.type === 'plan_progress') { console.log('Swap progress:', event.step.type, event.state); } }, hooks: { onIntent: ({ intent, allow }) => { console.log('Swap intent:', intent); allow(); }, }, slippageTolerance: 0.005, }, ); console.log('Swap with exact in 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 Input

Method signature

Parameters

Example

Return Value

Search Documentation

Swap Exact Input

Method signature

Parameters

Example

Return Value