Wallet SDK

The public @supanovaapp/sdk provides React hooks for authentication, Canton account registration, balances, transfers and signing.

Use the Launchpad API guides for launch-coin market data and trading integrations. The Wallet SDK uses a separately configured backend; do not assume the Launchpad API base URL is interchangeable with it.

Install#

npm install @supanovaapp/sdk @privy-io/react-auth

The SDK supports React 18 and 19. Check the package's peer dependencies when selecting versions for your app.

Configure the provider#

You need a Privy application ID, the Wallet backend URL for your environment and its Canton node identifier. Obtain the values for your integration before starting; an example staging URL in a README is not a production configuration.

The example below keeps registration explicit with autoOnboarding: false. It contains no credentials and makes no transfer.

"use client";

import { SupaProvider, useAuth, useCanton } from "@supanovaapp/sdk";

type WalletConfig = {
  privyAppId: string;
  apiBaseUrl: string;
  nodeIdentifier: string;
  supaAppId?: string;
};

export function WalletApp({ config }: { config: WalletConfig }) {
  return (
    <SupaProvider config={{ ...config, autoOnboarding: false }}>
      <Account />
    </SupaProvider>
  );
}

function Account() {
  const { ready, authenticated, login } = useAuth();
  const { isRegistered, cantonUser } = useCanton();

  if (!ready) return <p>Loading account…</p>;
  if (!authenticated) {
    return <button onClick={() => login()}>Sign in</button>;
  }
  if (!isRegistered) return <p>Complete your app's account setup.</p>;

  return <p>Canton Party ID: {cantonUser?.partyId}</p>;
}

Call registerCanton() as part of your deliberate onboarding flow once any required access checks are complete. It accepts an optional invite code. Handle loading, rejection and backend errors in the UI.

Read balances#

Inside a component wrapped by the provider, call getBalances() from useCanton():

const { getBalances } = useCanton();
const balances = await getBalances();

for (const token of balances.tokens) {
  console.log({
    instrument: token.instrumentId,
    available: token.totalUnlockedBalance,
    locked: token.totalLockedBalance,
    total: token.totalBalance,
  });
}

Preserve decimal strings when calculating token amounts. Use a decimal library or fixed-point arithmetic for financial calculations. Do not derive spendable funds from the total alone.

Transfer and signing APIs#

For token transfers, use the correct instrumentId and instrumentAdmin in the options. Amulet identifies Canton Coin. A token symbol alone is not enough to identify every instrument.

Show the intent, recipient, amount and estimated cost before asking the user to confirm. Use the returned transaction result and completion state before reporting success. Check the public SDK source and usage guide for the exact option types in your installed version.

Registration and session state#

Authentication, Canton registration and a completed transaction are different states. Keep them separate in your application.

Use useSupa().logout() when ending the session so the SDK clears Canton state as well as authentication. Do not retain a previous user's balances or Party ID after logout.

Environment and permissions#

Configure the backend URL and node identifier explicitly for each environment. Test registration and transfers with that environment's accounts and assets.

Private-key export and smart-wallet support depend on provider configuration. The SDK exposing an option does not mean the standalone Wallet app enables it. Keep backend secrets out of browser code and never log access tokens or signing material.