# PartyLayer

> CIP-0103 compliant Canton Network wallet connection kit. One React installation includes the SDK, supported wallet runtimes and a branded Connect Wallet UI.

Generated by scripts/gen-ai-docs.mjs from maintained guides, package manifests and both registry channels. Source versions below describe this deployed reference; check npm for current dist-tags.

## Reference versions

- @partylayer/react: 3.1.2
- @partylayer/sdk: 0.20.1
- create-partylayer-app: 0.7.0

## Wallet catalog and acceptance scope

| Wallet | Catalog networks | Channel | Application setup |
| --- | --- | --- | --- |
| Console Wallet | devnet, testnet, mainnet | stable | Included runtime |
| 5N Loop | devnet, mainnet | stable | Included runtime |
| Cantor8 | devnet, mainnet | stable | Included runtime |
| Bron | devnet, testnet, mainnet | stable | Your OAuth/API configuration |
| Nightly | devnet, testnet, mainnet | stable | Included runtime |
| Cauri Wallet | devnet, mainnet | stable | Included runtime |
| OneSwap V2 Wallet | devnet, mainnet | stable | Included runtime |
| Send | mainnet | stable | Included runtime |
| Walley | mainnet, testnet, devnet | stable | Included runtime |
| WalletConnect | devnet, testnet, mainnet | stable | Your WalletConnect project ID |
| Vala Wallet | devnet | beta | Included runtime |

Catalog membership and capability declarations are not completed live-wallet acceptance. Send is Mainnet-only in this catalog. Vala requires Devnet and the beta channel. Hosted-wallet login, approval and funding belong to the user and wallet provider. A connection or message signature does not establish a successful transfer or swap. Read the [wallet matrix](https://github.com/PartyLayer/PartyLayer/blob/main/docs/wallet-cip0103-matrix.md) and [release evidence](https://github.com/PartyLayer/PartyLayer/blob/main/docs/releasing.md#default-wallet-release-validation).

## React integration guide

Source: [docs/quick-start.md](https://github.com/PartyLayer/PartyLayer/blob/main/docs/quick-start.md).
Add PartyLayer's branded wallet picker and account menu to a React app. One npm command installs the kit, SDK and reviewed wallet runtimes. No wallet-specific imports or stylesheet import are required.

> **Version scope:** This guide requires React **3.1.0+** / SDK **0.20.0+**. See [release status](https://github.com/PartyLayer/PartyLayer/blob/main/docs/releasing.md#default-wallet-release-validation) for publication and acceptance evidence.

Use React 18+ in an existing application. Use a supported Node LTS version that meets your framework's requirements. Users need a wallet account or extension for the selected network to finish a real connection.

## Start a new app

If you do not have an app yet:

```bash
npm create partylayer-app@latest my-dapp -- --template react-vite --pm npm
cd my-dapp
npm run dev
```

The CLI generates the project and installs dependencies. Use `--template next-ssr` for Next.js App Router. See the [CLI guide](https://github.com/PartyLayer/PartyLayer/blob/main/packages/create-partylayer-app/README.md) for all six templates. Generated React apps already use the PartyLayer button and default attribution.

For an existing app, follow the steps below.

## Step 1: Install

Run this in your React project:

```bash
npm install @partylayer/react @tanstack/react-query
```

Use `pnpm add` or `yarn add` with the same package names if preferred. You do not need to install `@partylayer/sdk`, core packages or individual wallet SDKs separately.

TanStack Query is a required peer. The base connect UI works without `QueryClientProvider`; add that provider when using `@partylayer/react/query` data hooks.

## Step 2: Mount the kit

For a Vite React app, wrap the application in `src/main.tsx`:

```tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { PartyLayerKit } from '@partylayer/react';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <PartyLayerKit network="devnet" appName="My dApp">
      <App />
    </PartyLayerKit>
  </StrictMode>,
);
```

For Next.js App Router, create a client provider in `app/providers.tsx`:

```tsx
'use client';

import type { ReactNode } from 'react';
import { PartyLayerKit } from '@partylayer/react';

export function Providers({ children }: { children: ReactNode }) {
  return (
    <PartyLayerKit network="devnet" appName="My dApp">
      {children}
    </PartyLayerKit>
  );
}
```

Mount it in `app/layout.tsx`. Keep this file a Server Component:

```tsx
import type { ReactNode } from 'react';
import { Providers } from './providers';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body><Providers>{children}</Providers></body>
    </html>
  );
}
```

Use one kit at your application boundary. It owns discovery, client cleanup, theme and session context. Keep `walletConnect`, `bron` and `additionalAdapters` configuration objects stable outside render or with `useMemo`; changes recreate the client.

## Step 3: Add ConnectButton

In Vite, use `src/App.tsx`. In Next.js, use `app/page.tsx` with the client directive:

```tsx
'use client';

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

export default function Home() {
  return (
    <main>
      <h1>My Canton dApp</h1>
      <ConnectButton />
    </main>
  );
}
```

Users can open the picker, choose an available wallet and approve its connection. The connected button opens the account menu. The modal shows **Powered by PartyLayer** by default. Hosted-wallet login and extension installation are handled by the wallet.

## Read the connected account

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

export function Account() {
  const { isConnected, status, party, networkId } = useAccount();
  if (!isConnected) return <p>Wallet: {status}</p>;
  return <p>{party} · {networkId}</p>;
}
```

Render this inside the kit. A wallet session is not application authentication; use the [authentication guide](https://github.com/PartyLayer/PartyLayer/blob/main/docs/authentication.md) for server-verified sign-in.

For optional data hooks, wrap the kit in `QueryClientProvider`. In a Next.js client provider, create a stable `QueryClient` with `useState(() => new QueryClient())` rather than sharing one across server requests. See [data hooks](https://partylayer.xyz/docs/hooks#query-hooks).

## Configure wallets

| Need | Setting |
| --- | --- |
| Development network | `network="devnet"` |
| Testnet or Mainnet | Set `network` explicitly; the wallet list follows catalog network support |
| Vala | `network="devnet" channel="beta"` |
| Send | `network="mainnet"`; absent from the Devnet catalog |
| WalletConnect | `walletConnect={walletConnect}` with your own project ID |
| Bron | `bron={bron}` with your OAuth/API configuration |
| Add custom integrations | `additionalAdapters={customAdapters}` |
| Replace the default catalog | `adapters={customAdapters}` |
| Theme and language | `theme="auto" locale="en"`; Turkish and explicit RTL are supported |

For example, enable WalletConnect without an extra wallet package:

```tsx
const walletConnect = { projectId: 'YOUR_PROJECT_ID' };

<PartyLayerKit network="devnet" appName="My dApp" walletConnect={walletConnect}>
  <ConnectButton />
</PartyLayerKit>
```

Supported runtimes ship with the kit and load as needed. A registry listing or capability declaration is not proof of completed live testing. Check the [wallet matrix](https://github.com/PartyLayer/PartyLayer/blob/main/docs/wallet-cip0103-matrix.md) and [release evidence](https://github.com/PartyLayer/PartyLayer/blob/main/docs/releasing.md#default-wallet-release-validation).

## Verify the connection

1. Open Connect Wallet and check that wallets match the selected network/channel.
2. Select a wallet from the button's user-initiated flow. Complete login, installation and approval if required.
3. Confirm `useAccount()` reports a party and the actual wallet network.
4. Disconnect and check that the account UI clears. Reload and test restoration separately: a stored hint alone does not prove the wallet is connected.

A successful connection or message signature does not verify a token transfer or swap. Your app needs valid commands, test balance and independent ledger confirmation for those operations.

## Troubleshooting

| Symptom | Check |
| --- | --- |
| A wallet is missing | Network/channel support, WalletConnect/Bron configuration and whether `adapters` replaced the defaults. Send is Mainnet-only; Vala requires Devnet beta. |
| Wallet picker is empty | Registry/discovery errors, network/channel filters and custom adapter configuration. A failed registry fetch is only one possible cause. |
| Popup does not open | Start the flow directly from a user click and check popup blocking. Use the default button to preserve the supported popup flow. |
| Wallet rejects signing | Check the connected session's capabilities, network and current wallet authentication. Preserve the wallet's error when diagnosing a deployment problem. |
| Backend rejects a signature | Verify the exact challenged message/encoding, nonce, origin and independently authorized key. Do not infer a universal wallet algorithm. |
| Old native session is not restored | This release requires one reconnect for old caches without an official provider hint. Live party/network checks still apply. |
| Next.js hydration differs | Keep the kit in a client boundary. Treat SSR cookie state as a UI hint; use backend-verified sessions for protected server content. |

## Next steps

- [Kit configuration](https://partylayer.xyz/docs/partylayer-kit) and [ConnectButton](https://partylayer.xyz/docs/connect-button).
- [Authentication](https://github.com/PartyLayer/PartyLayer/blob/main/docs/authentication.md), [transaction lifecycle](https://github.com/PartyLayer/PartyLayer/blob/main/docs/transaction-lifecycle.md) and [wallet balances](https://github.com/PartyLayer/PartyLayer/blob/main/docs/wallet-balances.md).
- [Token transfer support](https://github.com/PartyLayer/PartyLayer/blob/main/docs/typed-transfer-support.md), including valid command and issuer requirements.
- [Protocol ownership and migration](https://github.com/PartyLayer/PartyLayer/blob/main/docs/protocol-ownership.md) for existing integrations.
- [Framework-independent SDK](https://github.com/PartyLayer/PartyLayer/blob/main/packages/sdk/README.md) or [Vue bindings](https://github.com/PartyLayer/PartyLayer/blob/main/packages/vue/README.md) for other application stacks.

## Framework-independent SDK guide

Source: [packages/sdk/README.md](https://github.com/PartyLayer/PartyLayer/blob/main/packages/sdk/README.md).
The framework-independent Canton wallet client. Discover supported wallets, connect through a shared API and use the connected wallet's capabilities. Reviewed wallet runtimes are included and load as needed.

[Documentation](https://partylayer.xyz/docs/vanilla-js) · [API reference](https://github.com/PartyLayer/PartyLayer/blob/main/docs/api.md) · [Wallets](https://partylayer.xyz/wallets)

> This guide covers **0.20.0+**. See [release validation](https://github.com/PartyLayer/PartyLayer/blob/main/docs/releasing.md#default-wallet-release-validation) for acceptance scope and release status.

## Installation

```bash
npm install @partylayer/sdk
```

React apps should use the ready-made kit instead. This single command includes the SDK and wallet runtimes:

```bash
npm install @partylayer/react @tanstack/react-query
```

See [the React quick start](https://partylayer.xyz/docs/quick-start). No separate PartyLayer wallet packages are required.

## Quick start

```ts
import { createPartyLayer } from '@partylayer/sdk';

const client = createPartyLayer({
  network: 'devnet',
  app: { name: 'My dApp' },
});

const wallets = await client.listWallets();
for (const wallet of wallets) {
  console.log(wallet.walletId, wallet.name, wallet.capabilities);
}

// Render these entries in your picker. Start connect from its click handler:
// await client.connect({ walletId: selectedWallet.walletId });

client.on('session:connected', ({ session }) => {
  console.log('Party:', session.partyId);
  console.log('Capabilities:', session.capabilitiesSnapshot);
});

// Read current/restored state; a cache alone does not establish a live connection.
const session = await client.getActiveSession();
console.log(session?.partyId);
```

Use one client for the lifetime of your application integration. Call `await client.disconnect()` for an explicit logout and `client.destroy()` when disposing an application-owned client. `PartyLayerKit` handles client disposal for React.

## Configuration

```ts
const walletConnect = { projectId: 'YOUR_PROJECT_ID' };

const client = createPartyLayer({
  network: 'devnet',
  app: { name: 'My dApp' },
  channel: 'stable',
  walletConnect,
});
```

| Option | Effect |
| --- | --- |
| `network` | Required: `devnet`, `testnet` or `mainnet`; filters the catalog |
| `app.name` | Required: application name presented during connection |
| `channel` | `stable` by default; `beta` on Devnet includes Vala |
| `walletConnect` | Project ID and optional pairing metadata; omitted means hidden |
| `bron` | Application-owned OAuth/API configuration; omitted means hidden |
| `additionalAdapters` | Extends the included catalog |
| `adapters` | Replaces the included catalog |
| `registryUrl` | Defaults to `https://registry.partylayer.xyz` |

Hosted wallets require the user's own login and approval. Send is Mainnet-only in the catalog. See [configuration and wallet limits](https://partylayer.xyz/docs/wallets).

## Supported wallets

Generated from the stable registry and active SDK integrations. This is capability metadata, not evidence that every live wallet journey passed.

<!-- WALLETS:START (generated by scripts/gen-readme.mjs, do not edit) -->
| Wallet | Networks | Capabilities | Opt-in | Additional setup |
|--------|----------|--------------|--------|---------|
| Console Wallet | devnet, testnet, mainnet | signMessage, submitTransaction, restore | No | Included |
| 5N Loop | devnet, mainnet | signMessage, submitTransaction, ledgerApi, restore, events | No | Included |
| Cantor8 | devnet, mainnet | submitTransaction, events | No | Included |
| Bron | devnet, testnet, mainnet | signMessage, signTransaction, ledgerApi, restore | Yes | Your OAuth/API configuration |
| Nightly | devnet, testnet, mainnet | signMessage, submitTransaction, ledgerApi, restore, events | No | Included |
| Cauri Wallet | devnet, mainnet | signMessage, submitTransaction | No | Included |
| OneSwap V2 Wallet | devnet, mainnet | signMessage, submitTransaction | No | Included |
| Send | mainnet | signMessage, submitTransaction, ledgerApi, restore, events | No | Included |
| Walley | mainnet, testnet, devnet | signMessage, submitTransaction | No | Included |
| WalletConnect | devnet, testnet, mainnet | signMessage, submitTransaction, ledgerApi, restore, events | Yes | Your project ID |
<!-- WALLETS:END -->

Vala is an additional Devnet **beta** entry, enabled with `channel: 'beta'`. The [integration matrix](https://github.com/PartyLayer/PartyLayer/blob/main/docs/wallet-cip0103-matrix.md) records integration paths, reviewed versions and restrictions.

## Message signing and authentication

Call `signMessage` only when the connected session supports it:

```ts
const session = await client.getActiveSession();
if (session?.capabilitiesSnapshot.includes('signMessage')) {
  const result = await client.signMessage({ message: 'Hello, Canton!' });
  console.log(result.signature);
}
```

A returned signature is not a server login. Authentication needs a backend-generated challenge, single-use nonce, origin binding and independent verification against an authorized party key. See [authentication](https://partylayer.xyz/docs/authentication).

## Transactions

There is no universal sign-then-submit sequence across Canton wallets. Some wallets combine approval and submission; others expose a separate signing operation or native CIP-0103 `prepareExecute`. Inspect capabilities and follow the wallet's command contract.

Your app constructs valid commands and independently confirms ledger settlement. A command ID, a resolved Promise or message signature is not proof of a successful transfer/swap. Uncertain outcomes must be reconciled without automatically submitting again. See [transaction lifecycle](https://partylayer.xyz/docs/transaction-lifecycle) and [token transfers](https://partylayer.xyz/docs/token-transfers).

## Native CIP-0103 provider and migration

Use `client.asProvider()` for the connected provider surface. Native connections use official Canton discovery and forward native accounts, events and Ledger API requests through a stable facade. Native Ledger API responses are **raw JSON**. Existing `client.ledgerApi()` and explicit `createProviderBridge(client)` compatibility paths retain their documented wrapper/limits.

Existing native caches without the official provider hint need one explicit reconnect. Restored state must agree with the wallet's live party, network, origin and expiry. See [protocol ownership and migration](https://github.com/PartyLayer/PartyLayer/blob/main/docs/protocol-ownership.md).

## Errors and cleanup

Handle user rejection, unavailable wallets, timeouts, network mismatch and unsupported capabilities as separate application states. Do not silently retry a ledger write after an ambiguous error. See [error handling](https://partylayer.xyz/docs/error-handling).

`client.on(event, handler)` returns an unsubscribe function. Release subscriptions and destroy clients you create when their owner is disposed. Never call `destroy()` on the client managed by a still-mounted React kit.

## License

MIT

## Documentation index

- [Introduction](https://partylayer.xyz/docs)
- [Installation and new-app CLI](https://partylayer.xyz/docs/installation)
- [React and Next.js quick start](https://partylayer.xyz/docs/quick-start)
- [Upgrade an existing application](https://partylayer.xyz/docs/migration)
- [AI-assisted integration and optional skill](https://partylayer.xyz/docs/ai-integration)
- [Coming from RainbowKit](https://partylayer.xyz/docs/rainbowkit-for-canton)
- [PartyLayerKit configuration](https://partylayer.xyz/docs/partylayer-kit)
- [ConnectButton](https://partylayer.xyz/docs/connect-button)
- [Wallet modal](https://partylayer.xyz/docs/wallet-modal)
- [Theming](https://partylayer.xyz/docs/theming)
- [React hooks and optional data hooks](https://partylayer.xyz/docs/hooks)
- [Framework-independent TypeScript SDK](https://partylayer.xyz/docs/vanilla-js)
- [Wallet networks and configuration](https://partylayer.xyz/docs/wallets)
- [CIP-0103 provider](https://partylayer.xyz/docs/cip-0103)
- [Generic provider bridge](https://partylayer.xyz/docs/generic-bridge)
- [Server-verified authentication](https://partylayer.xyz/docs/authentication)
- [Transaction lifecycle](https://partylayer.xyz/docs/transaction-lifecycle)
- [Token transfers and command requirements](https://partylayer.xyz/docs/token-transfers)
- [Production checklist](https://partylayer.xyz/docs/production-checklist)
- [Integration support](https://partylayer.xyz/docs/integration-support)

## Resources

- [Wallet directory](https://partylayer.xyz/wallets)
- [Interactive Devnet demo](https://partylayer.xyz/kit-demo)
- [Integration skill](https://github.com/PartyLayer/PartyLayer/blob/main/skills/partylayer-integration/SKILL.md)
- [GitHub](https://github.com/PartyLayer/PartyLayer)
- [npm React kit](https://www.npmjs.com/package/@partylayer/react)
- [Full text reference](https://partylayer.xyz/llms-full.txt)