Canton dApp quickstart: zero to a working wallet connection

Get a full wallet connection flow working in your React app in 3 steps. By the end of this guide, your users will be able to connect any Canton wallet.

Coming from Ethereum? The connect layer below will feel familiar, and wagmi for Canton maps the hooks you already know onto these ones. Read it before you port a read path, because that is the part that does not translate.

Which Canton SDK do you need?

Searching for a Canton Network SDK returns several packages that do different jobs, and picking the wrong one costs a day. Here is the honest layout, with each package described by what its own publisher says it is.

Before you start

• React 18 or 19 and Node 18 or newer. Every code block below has a Next.js and a Vite tab. The code is plain React, so another bundler will work, but those two are the ones actually shown.
• A wallet to connect to. On devnet you do not need one installed to see the flow: the modal lists registry wallets and shows install prompts for the ones you lack. To complete a real connection you need one of the wallets from the directory that supports your target network.
• No ledger credentials, no participant node, no Daml. Connecting a wallet and reading the connected party needs none of that. You need them when you start submitting transactions, which is Token transfers.

Step 1: Install

Add the PartyLayer packages to your existing React project. If you're starting fresh with Vite, run npm create vite@latest my-dapp -- --template react-ts first.

npm install @partylayer/sdk @partylayer/react @tanstack/react-query

Step 2: Wrap Your App

Add PartyLayerKit at the root of your component tree. It handles wallet discovery, session management, and theming automatically.

// src/main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { PartyLayerKit } from '@partylayer/react';
import App from './App';

const queryClient = new QueryClient();

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <PartyLayerKit network="mainnet" appName="My dApp">
        <App />
      </PartyLayerKit>
    </QueryClientProvider>
  </StrictMode>,
);

Step 3: Add ConnectButton

Drop ConnectButton anywhere in your app. It renders a connect button when disconnected and shows the connected address with a disconnect dropdown when connected.

// src/App.tsx
import { ConnectButton } from '@partylayer/react';

export default function App() {
  return (
    <div>
      <h1>My Canton dApp</h1>
      <ConnectButton />
    </div>
  );
}

That's it! Your app now has a complete wallet connection flow with a polished modal, wallet auto-discovery, and session management.

Complete Example

Here's the full setup in a single file:

// src/main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { PartyLayerKit, ConnectButton } from '@partylayer/react';

const queryClient = new QueryClient();

function App() {
  return (
    <>
      <nav>
        <h1>My dApp</h1>
        <ConnectButton />
      </nav>
      <main>
        <p>Your app content here</p>
      </main>
    </>
  );
}

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <PartyLayerKit network="mainnet" appName="My dApp">
        <App />
      </PartyLayerKit>
    </QueryClientProvider>
  </StrictMode>,
);

What's Happening Under the Hood?

When PartyLayerKit mounts, it:

1. Creates a PartyLayerClient: the core SDK instance that manages all wallet operations
2. Registers built-in adapters: Console, Loop, Cantor8, and Nightly wallet adapters (Send is served through the CIP-0103 announce path)
3. Fetches the wallet registry: verified wallet metadata from registry.partylayer.xyz
4. Groups CIP-0103 native wallets: those flagged cip0103.native: true in the registry render in a dedicated picker section
5. Restores existing sessions: if a user was previously connected, the session is restored automatically

Using Session Data

Once connected, read the session reactively from any component with useAccount:

import { useAccount } from '@partylayer/react';

function Profile() {
  const { isConnected, status, party, networkId } = useAccount();

  if (!isConnected) return <p>Not connected ({status})</p>;

  return (
    <div>
      <p>Party ID: {party}</p>
      <p>Network: {networkId}</p>
    </div>
  );
}

Verify it actually works

Three checks, in order. Each one fails differently, so knowing which passed tells you where to look.

1. The modal opens and lists wallets. If it opens empty, the registry did not load. Check the browser console for a registry fetch error; the SDK falls back to adapter-only discovery, so an empty list means neither the registry nor any adapter produced a wallet.
2. Selecting a wallet starts its flow. An extension wallet prompts, a QR wallet opens a window. If nothing happens for a relay wallet, you probably have not wired its pairing URI; see the per-wallet notes on the wallet directory.
3. useAccount() reports a party id. This is the one that matters. A connection that resolves without a party id is not a usable session, and the SDK now throws rather than inventing one, so you will see an error rather than a silent half-state.

If it does not work

Next Steps

Now that you have basic connectivity, explore more:

1. PartyLayerKit: Configuration options (network, adapters, theme)
2. ConnectButton: Customize the button appearance and behavior
3. React Hooks: Use useSignMessage, useSubmitTransaction, and the /query data hooks (useDamlContract, useChoice, cost hooks)
4. Pattern Cookbook: Copy-paste recipes for the data hooks, optimistic updates, and Suspense
5. Theming: Switch between light, dark, and custom themes
6. Wallets & Adapters: Add custom wallet adapters or the Bron enterprise wallet