nexus-sdk-swap-flows

name	nexus-sdk-swap-flows
description	Implement swapWithExactIn, swapWithExactOut, and swapAndExecute flows with Nexus SDK. Use when wiring swap operations, swap intent hooks, or swap event progress updates.

Swap Flows

Call swapWithExactIn(input, options?)

• Use when input amount is fixed and sources are known.
• Signature:
  • sdk.swapWithExactIn(input, { onEvent? })
• Params (ExactInSwapInput):
  • from: { chainId: number; amount: bigint; tokenAddress: Hex }[]
  • toChainId: number
  • toTokenAddress: Hex
• Notes:
  • Ensure from amounts are in smallest units.
  • Use chain-specific token addresses (see TOKEN_CONTRACT_ADDRESSES).
• Result (SwapResult):
  • { success: true; result: SuccessfulSwapResult }

Call swapWithExactOut(input, options?)

• Use when desired output amount is fixed.
• Signature:
  • sdk.swapWithExactOut(input, { onEvent? })
• Params (ExactOutSwapInput):
  • toChainId: number
  • toTokenAddress: Hex
  • toAmount: bigint
  • toNativeAmount?: bigint (optional native token output)
  • fromSources?: { chainId: number; tokenAddress: Hex }[] (optional)
• Notes:
  • If fromSources is omitted, SDK auto-selects sources.

Call swapAndExecute(input, options?)

• Use to perform swap (if needed) and then execute a contract call.
• Signature:
  • sdk.swapAndExecute(input, { onEvent? })
• Params (SwapAndExecuteParams):
  • toChainId: number
  • toTokenAddress: Hex
  • toAmount: bigint
  • fromSources?: { chainId: number; tokenAddress: Hex }[]
  • execute: SwapExecuteParams
• SwapExecuteParams:
  • to: Hex
  • data?: Hex
  • value?: bigint
  • gas: bigint
  • gasPrice?: 'low' | 'medium' | 'high'
  • tokenApproval?: { token: Hex; amount: bigint; spender: Hex }
• Result (SwapAndExecuteResult):
  • swapResult: SuccessfulSwapResult | null (null if swap skipped)

Use token addresses and chains

• Use SDK constants for addresses and chain IDs:
  • SUPPORTED_CHAINS
  • TOKEN_CONTRACT_ADDRESSES

Attach swap intent hook

• Set sdk.setOnSwapIntentHook(...) and call allow() to proceed.
• If the hook is not set, the SDK auto-approves.

Stream swap events

• Listen for NEXUS_EVENTS.SWAP_STEP_COMPLETE.
• Handle special cases like swap skipped (e.g., already on destination token).

Convert amounts to bigint

• Use sdk.utils.parseUnits(value, decimals) or
• sdk.convertTokenReadableAmountToBigInt(value, tokenSymbol, chainId) when decimals vary by chain.