PrivatarSDK preview

SDK quickstart.

Start a permission-based connection from your application with @privatar-wallet/sdk.

1. Install the preview SDK

Current SDK preview
npm install @privatar-wallet/sdk@0.1.4

SDK 0.1.4 is published on npm and is the current latest release. Its published archive matches the verified release artifact. Create the client in client-side code and start pairing from a user action. Review the supported permissions and security boundaries before enabling requests.

2. Create a client

TypeScript
import { createPrivatarClient } from '@privatar-wallet/sdk';

const client = createPrivatarClient({
  appName: 'My application',
  onPairing(info) {
    // Update the pending app handoff status, expiry and legacy comparison code.
    updatePairingStatus(info);
  },
});

The SDK uses https://relay.privatar.app by default. Users do not run a relay. The SDK obtains the application origin from the browser. Do not substitute an app-provided name for that origin when explaining a request.

3. Request only what you need

TypeScript
const pairing = await client.beginConnect({
  network: 'preprod',
  transport: 'auto',
  permissions: ['addresses', 'signData'],
});

if (pairing.transport === 'app') {
  // Open pairing.uri on this phone, or render it as a QR on desktop.
  showAppHandoff(pairing);
}
// Allow pairing.cancel() while approval is pending.
const connection = await pairing.connection;
const addresses = await connection.getAddresses();

connection.onDisconnect(() => {
  clearWalletState();
  signOutOfYourApplication();
});

See extension connections for explicit desktop transport selection. The SDK returns the same approved connection API for either wallet. Keep pending, rejected, expired, connected, and disconnected states distinct. Never invent a QR, comparison code, address, or successful status.

4. Verify sign-in on your server

TypeScript
const challenge = await fetch('/api/challenge', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    network: addresses.network,
    address: addresses.unshielded,
  }),
}).then(response => response.json());

const proof = await connection.signData({
  message: challenge.message,
});

// Your server verifies and consumes the challenge before login.
await fetch('/api/verify', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(proof),
});

Check non-success HTTP responses before showing success. The demo includes a complete backend with origin binding, expiry, replay rejection, and signature-to-address verification.

5. End access cleanly

TypeScript
await connection.disconnect();
await fetch('/api/logout', { method: 'POST' });

Clear addresses and balances on disconnect. Your application owns the lifetime of its authenticated session.

Privatar · Midnight wallet & connection SDKPreview documentation · October 2026