Nexus Elements - Transfer

Install

• Install widget:

  • npx shadcn@latest add @nexus-elements/transfer

• Ensure

  NexusProvider

  is installed and initialized before rendering.

Required setup before rendering

• Ensure

  useNexus().nexusSDK

  is initialized.
• Ensure

  bridgableBalance

  has loaded.
• Ensure recipient is valid EVM address (prefill or user input).

Initialize SDK (required once per app)

• On wallet connect, resolve an EIP-1193 provider and call

  useNexus().handleInit(provider)

  .
• Wait for

  useNexus().nexusSDK

  before allowing transfer actions.
• Re-run init after reconnect if wallet session resets.

Render widget

"use client";

import FastTransfer from "@/components/transfer/transfer";
import { SUPPORTED_CHAINS } from "@avail-project/nexus-core";

export function TransferPanel() {
  return (
    <FastTransfer
      prefill={{
        token: "USDC",
        chainId: SUPPORTED_CHAINS.BASE,
        recipient: "0x000000000000000000000000000000000000dead",
      }}
      onStart={() => {
        // pending
      }}
      onComplete={() => {
        // success
      }}
      onError={(message) => {
        console.error(message);
      }}
    />
  );
}

Live prop contract

• prefill?

  :

  • token

    ,

    chainId

    , optional

    amount

    , optional

    recipient

    .

• maxAmount?

  : cap transferable amount.

• onStart?

  ,

  onComplete?

  ,

  onError?(message)

  callbacks.

SDK flow details (under the hood)

• Primary execute call:

  • sdk.bridgeAndTransfer({ token, amount, toChainId, recipient, sourceChains }, { onEvent })

• Pre-execution checks:
  • validate recipient + amount
  • compute max available via

    sdk.calculateMaxForBridge(...)

  • enforce selected-source sufficiency
• Hook usage:

  • intent.current

    for transfer intent preview/refresh/allow

  • allowance.current

    for source-specific allowance decisions
• Event mapping:

  • NEXUS_EVENTS.STEPS_LIST

    -> initialize step tracker

  • NEXUS_EVENTS.STEP_COMPLETE

    -> progress update and elapsed timer

Understand recipient behavior

• Transfer flow requires recipient address.
• Prefill recipient locks input.
• Without prefill, UI validates recipient and blocks invalid addresses.

E2E verification

• Fill token/chain/amount/recipient and confirm intent preview appears.
• Adjust source chains and confirm coverage indicators update.
• Accept and verify allowance step when required.
• Confirm success updates explorer URL and refreshes balances.
• Confirm history refresh event appears in

  ViewHistory

  (when present).

Common failure cases

• Invalid recipient:
  • pass a checksummed or valid hex address.
• Exceeds selected source max:
  • reduce amount or enable more source chains.
• Flow canceled:
  • expect

    onError

    with user-cancel message and reset state.