Nexus SDK Setup

Initialize the Nexus SDK with a connected wallet and fetch your first unified balance.

You are viewing the Nexus SDK v2 docs. For the current SDK, see the v3 docs and the v2 → v3 migration guide.

In this guide you will create a Nexus SDK instance, connect it to a wallet provider, and fetch unified balances across all supported chains. By the end you will have a minimal Next.js app with four buttons that demonstrate the full SDK lifecycle.

Prerequisites

Node.js version 18 or higher, with npm 9 or higher
A package manager — this guide uses pnpm, but npm and yarn work too
An EIP-1193 compatible wallet (e.g. MetaMask) installed in your browser
@avail-project/nexus-core installed in your project (see Installation)

What you will build

A minimal Next.js page with four buttons:

Connect Wallet — connects an EIP-1193 wallet
Initialize Nexus — passes the wallet provider to the SDK
Fetch Balances — retrieves token balances across all supported chains
De-initialize — tears down the SDK instance

Balance methods

The SDK provides two balance methods: getBalancesForBridge() returns tokens available for bridging, while getBalancesForSwap() returns tokens available for cross-chain swaps. Learn more in the Bridge vs Swap concept page.

Step 1 — Create a Next.js project

If you don't have an existing project, scaffold one:

pnpm create next-app@latest my-nexus-app --ts --eslint --app --src-dir
cd my-nexus-app

Install the Nexus SDK:

pnpm add @avail-project/nexus-core

Step 2 — Create the SDK instance

Create a single shared SDK instance that the rest of the app will import. This file lives outside of React so it has no component lifecycle concerns.

src/lib/nexus.ts

import { createNexusClient, type NexusClient } from "@avail-project/nexus-core";
 
// Create a single client instance.
// Pass { network: 'testnet' } to use testnet chains.
// Defaults to 'mainnet' if omitted.
export const client: NexusClient = createNexusClient({ network: "testnet" });
 
export async function initializeWithProvider(provider: any) {
  if (!provider)
    throw new Error("No EIP-1193 provider (e.g. MetaMask) found");
  if (client.hasEvmProvider) return;
  await client.initialize();             // loads deployment info from the middleware
  await client.setEVMProvider(provider); // attaches the connected wallet
}
 
export function destroy() {
  client.destroy();
}
 
export async function getBalancesForBridge() {
  return await client.getBalancesForBridge();
}
 
export async function getBalancesForSwap() {
  return await client.getBalancesForSwap();
}

What each part does

Export	Type	Description
`client`	`NexusClient`	The shared Nexus client, created once with `createNexusClient()`.
`client.hasEvmProvider`	`boolean`	Getter that returns `true` once `setEVMProvider()` has attached a wallet.
`initializeWithProvider(provider)`	`(provider: any) => Promise<void>`	Runs `client.initialize()` then `client.setEVMProvider(provider)`. Must be called after a wallet is connected.
`destroy()`	`() => void`	Tears down the client (synchronous).
`getBalancesForBridge()`	`() => Promise<TokenBalance[]>`	Returns bridgeable token balances across all supported chains.
`getBalancesForSwap()`	`() => Promise<TokenBalance[]>`	Returns swappable token balances across all supported chains.

Two-step initialization

v2 splits startup into two calls: client.initialize() loads deployment data from the middleware, and client.setEVMProvider(provider) attaches the connected wallet. You can call them in either order, but wallet-dependent methods only work once setEVMProvider() has resolved.

Step 3 — Create the UI components

Create four button components in the src/components directory.

connect-button.tsx

Connects an EIP-1193 wallet using the browser's injected provider (window.ethereum).

src/components/connect-button.tsx

"use client";
 
export default function ConnectButton({
  className,
}: {
  className?: string;
}) {
  const onClick = async () => {
    const eth = (window as any)?.ethereum;
    if (!eth)
      return alert("Install an EIP-1193 wallet (e.g. MetaMask)");
    await eth.request?.({ method: "eth_requestAccounts" });
    alert("Wallet connected");
  };
  return (
    <button className={className} onClick={onClick}>
      Connect Wallet
    </button>
  );
}

init-button.tsx

Initializes the Nexus SDK with the connected wallet's provider.

src/components/init-button.tsx

"use client";
 
import { initializeWithProvider, client } from "../lib/nexus";
 
export default function InitButton({
  className,
  onReady,
}: {
  className?: string;
  onReady?: () => void;
}) {
  const onClick = async () => {
    const eth = (window as any)?.ethereum;
    try {
      await initializeWithProvider(eth);
      onReady?.();
      alert("Nexus initialized");
    } catch (e: any) {
      alert(e?.message ?? "Init failed");
    }
  };
  return (
    <button
      className={className}
      onClick={onClick}
      disabled={client.hasEvmProvider}
    >
      Initialize Nexus
    </button>
  );
}

Using a wallet library?

This tutorial uses window.ethereum directly for simplicity. If you use wagmi, RainbowKit, or another wallet library, see Initializing Nexus with RainbowKit for how to retrieve the provider from a connector.

fetch-balances-button.tsx

Fetches the user's balances across all supported chains.

src/components/fetch-balances-button.tsx

"use client";
 
import { getBalancesForBridge, getBalancesForSwap, client } from "../lib/nexus";
 
export default function FetchBalancesButton({
  className,
  onResult,
}: {
  className?: string;
  onResult?: (r: any) => void;
}) {
  const onClick = async () => {
    if (!client.hasEvmProvider) return alert("Initialize first");
    // Use getBalancesForBridge() for bridgeable tokens
    // Use getBalancesForSwap() for swappable tokens
    const bridgeBalances = await getBalancesForBridge();
    const swapBalances = await getBalancesForSwap();
    const res = { bridgeBalances, swapBalances };
    onResult?.(res);
    console.log(res);
  };
  return (
    <button
      className={className}
      onClick={onClick}
      disabled={!client.hasEvmProvider}
    >
      Fetch Balances
    </button>
  );
}

de-init-button.tsx

Destroys the client and resets state.

src/components/de-init-button.tsx

"use client";
 
import { destroy, client } from "../lib/nexus";
 
export default function DeinitButton({
  className,
  onDone,
}: {
  className?: string;
  onDone?: () => void;
}) {
  const onClick = async () => {
    destroy();
    onDone?.();
    alert("Nexus de-initialized");
  };
  return (
    <button
      className={className}
      onClick={onClick}
      disabled={!client.hasEvmProvider}
    >
      De-initialize
    </button>
  );
}

Step 4 — Assemble the page

Wire all four components together in a single page:

src/app/page.tsx

"use client";
 
import { useState } from "react";
import ConnectButton from "@/components/connect-button";
import InitButton from "@/components/init-button";
import FetchBalancesButton from "@/components/fetch-balances-button";
import DeinitButton from "@/components/de-init-button";
import { client } from "@/lib/nexus";
 
export default function Page() {
  const [initialized, setInitialized] = useState(client.hasEvmProvider);
  const [balances, setBalances] = useState<any>(null);
 
  const btn =
    "px-4 py-2 rounded-md bg-blue-600 text-white hover:bg-blue-700 " +
    "disabled:opacity-50 disabled:cursor-not-allowed";
 
  return (
    <main className="min-h-screen flex items-center justify-center">
      <div className="flex flex-col items-center gap-4">
        <ConnectButton className={btn} />
        <InitButton
          className={btn}
          onReady={() => setInitialized(true)}
        />
        <FetchBalancesButton
          className={btn}
          onResult={(r) => setBalances(r)}
        />
        <DeinitButton
          className={btn}
          onDone={() => {
            setInitialized(false);
            setBalances(null);
          }}
        />
 
        <div className="mt-2">
          <b>SDK Status:</b>{" "}
          {initialized ? "Initialized" : "Not initialized"}
        </div>
 
        {balances && (
          <pre className="whitespace-pre-wrap">
            {JSON.stringify(balances, null, 2)}
          </pre>
        )}
      </div>
    </main>
  );
}

Step 5 — Run and test

pnpm dev

Open http://localhost:3000 and click through the buttons in order:

Connect Wallet — approve the wallet prompt in MetaMask
Initialize Nexus — the SDK connects to the wallet provider
Fetch Balances — a JSON object appears showing your tokens across chains
De-initialize — the SDK resets

What you just built

In a few lines of code you connected to a wallet, initialized the Nexus SDK, and fetched a cross-chain view of every token the user holds. From here you can bridge tokens, execute swaps, or build any custom UI on top of the headless SDK.

Next step

Upgrade your wallet connection experience by replacing window.ethereum with RainbowKit.

Initializing Nexus with RainbowKit

How is this guide?

Installation

Initializing Nexus with RainbowKit

Prerequisites What you will build Step 1 — Create a Next.js project Step 2 — Create the SDK instance What each part does Step 3 — Create the UI components connect-button.tsx init-button.tsx fetch-balances-button.tsx de-init-button.tsx Step 4 — Assemble the page Step 5 — Run and test Next step

Edit in GitHub

import { createNexusClient, type NexusClient } from "@avail-project/nexus-core"; // Create a single client instance. // Pass { network: 'testnet' } to use testnet chains. // Defaults to 'mainnet' if omitted. export const client: NexusClient = createNexusClient({ network: "testnet" }); export async function initializeWithProvider(provider: any) { if (!provider) throw new Error("No EIP-1193 provider (e.g. MetaMask) found"); if (client.hasEvmProvider) return; await client.initialize(); // loads deployment info from the middleware await client.setEVMProvider(provider); // attaches the connected wallet } export function destroy() { client.destroy(); } export async function getBalancesForBridge() { return await client.getBalancesForBridge(); } export async function getBalancesForSwap() { return await client.getBalancesForSwap(); }

Export

Type

Description

client

NexusClient

The shared Nexus client, created once with createNexusClient().

client.hasEvmProvider

boolean

Getter that returns true once setEVMProvider() has attached a wallet.

initializeWithProvider(provider)

(provider: any) => Promise<void>

Runs client.initialize() then client.setEVMProvider(provider). Must be called after a wallet is connected.

destroy()

() => void

Tears down the client (synchronous).

getBalancesForBridge()

() => Promise<TokenBalance[]>

Returns bridgeable token balances across all supported chains.

getBalancesForSwap()

() => Promise<TokenBalance[]>

Returns swappable token balances across all supported chains.

"use client"; export default function ConnectButton({ className, }: { className?: string; }) { const onClick = async () => { const eth = (window as any)?.ethereum; if (!eth) return alert("Install an EIP-1193 wallet (e.g. MetaMask)"); await eth.request?.({ method: "eth_requestAccounts" }); alert("Wallet connected"); }; return ( <button className={className} onClick={onClick}> Connect Wallet </button> ); }

"use client"; import { initializeWithProvider, client } from "../lib/nexus"; export default function InitButton({ className, onReady, }: { className?: string; onReady?: () => void; }) { const onClick = async () => { const eth = (window as any)?.ethereum; try { await initializeWithProvider(eth); onReady?.(); alert("Nexus initialized"); } catch (e: any) { alert(e?.message ?? "Init failed"); } }; return ( <button className={className} onClick={onClick} disabled={client.hasEvmProvider} > Initialize Nexus </button> ); }

"use client"; import { getBalancesForBridge, getBalancesForSwap, client } from "../lib/nexus"; export default function FetchBalancesButton({ className, onResult, }: { className?: string; onResult?: (r: any) => void; }) { const onClick = async () => { if (!client.hasEvmProvider) return alert("Initialize first"); // Use getBalancesForBridge() for bridgeable tokens // Use getBalancesForSwap() for swappable tokens const bridgeBalances = await getBalancesForBridge(); const swapBalances = await getBalancesForSwap(); const res = { bridgeBalances, swapBalances }; onResult?.(res); console.log(res); }; return ( <button className={className} onClick={onClick} disabled={!client.hasEvmProvider} > Fetch Balances </button> ); }

"use client"; import { destroy, client } from "../lib/nexus"; export default function DeinitButton({ className, onDone, }: { className?: string; onDone?: () => void; }) { const onClick = async () => { destroy(); onDone?.(); alert("Nexus de-initialized"); }; return ( <button className={className} onClick={onClick} disabled={!client.hasEvmProvider} > De-initialize </button> ); }

"use client"; import { useState } from "react"; import ConnectButton from "@/components/connect-button"; import InitButton from "@/components/init-button"; import FetchBalancesButton from "@/components/fetch-balances-button"; import DeinitButton from "@/components/de-init-button"; import { client } from "@/lib/nexus"; export default function Page() { const [initialized, setInitialized] = useState(client.hasEvmProvider); const [balances, setBalances] = useState<any>(null); const btn = "px-4 py-2 rounded-md bg-blue-600 text-white hover:bg-blue-700 " + "disabled:opacity-50 disabled:cursor-not-allowed"; return ( <main className="min-h-screen flex items-center justify-center"> <div className="flex flex-col items-center gap-4"> <ConnectButton className={btn} /> <InitButton className={btn} onReady={() => setInitialized(true)} /> <FetchBalancesButton className={btn} onResult={(r) => setBalances(r)} /> <DeinitButton className={btn} onDone={() => { setInitialized(false); setBalances(null); }} /> <div className="mt-2"> <b>SDK Status:</b>{" "} {initialized ? "Initialized" : "Not initialized"} </div> {balances && ( <pre className="whitespace-pre-wrap"> {JSON.stringify(balances, null, 2)} </pre> )} </div> </main> ); }

Search Documentation

Nexus SDK Setup

Prerequisites

What you will build

Step 1 — Create a Next.js project

Step 2 — Create the SDK instance

What each part does

Step 3 — Create the UI components

connect-button.tsx

init-button.tsx

fetch-balances-button.tsx

de-init-button.tsx

Step 4 — Assemble the page

Step 5 — Run and test

Next step

Search Documentation

Nexus SDK Setup

Prerequisites

What you will build

Step 1 — Create a Next.js project

Step 2 — Create the SDK instance

What each part does

Step 3 — Create the UI components

connect-button.tsx

init-button.tsx

fetch-balances-button.tsx

de-init-button.tsx

Step 4 — Assemble the page

Step 5 — Run and test

Next step