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.