# The connection API.

Source: https://docs.privatar.app/api

A small browser interface for explicit wallet access. All wallet results come from the approved connection.

## createPrivatarClient

TypeScript

```
createPrivatarClient({
  relayUrl: string,
  appName: string,
  onPairing?: (info) => void,
  onTransport?: (transport) => void,
  sessionStorage?: ClientSessionStorage,
})
```

Creates a client for this browser origin. Pairing updates include the real URI, expiry, status, and comparison code when available. The application name is display metadata.

## client.beginConnect

TypeScript

```
const pairing = await client.beginConnect({
  network: 'preprod', // 'preview' | 'mainnet'
  transport: 'auto', // 'app' | 'extension'
  permissions: ['addresses', 'signData'],
});

if (pairing.transport === 'app') {
  pairing.uri;        // Actual app pairing link
  pairing.expiresAt;  // App pairing expiration
}
pairing.cancel();   // Cancel pending pairing
await pairing.connection; // Approved PrivatarConnection
```

An extension pending connection exposes transport, connection and cancel, with no URI. Auto selects the extension only when available on desktop; the default remains app. With browser session storage configured, `client.resume()` can resume an app handoff after returning to the same origin. It does not silently approve or restore an extension session.

## connection.getAddresses

TypeScript

```
await connection.getAddresses();
// { network, shielded, unshielded, dust }
```

Requires `addresses`. The network belongs to the approved session. DUST is a generation address, not a NIGHT receive address.

## connection.getBalances

TypeScript

```
await connection.getBalances();
```

Requires `balances`. Amounts are decimal strings in atomic units. Preserve them as strings or bigint; never convert wallet balances to JavaScript floating-point numbers. Results include `syncStatus` and `observedAt`. Balances during sync can be partial; connection approval does not imply full synchronization. Unavailable synchronization must not be displayed as a zero balance. See [sync details](https://docs.privatar.app/sync).

## connection.signData

TypeScript

```
const proof = await connection.signData({ message });
// { data, signature, verifyingKey, scheme: 'schnorr_bip340' }
```

Requires `signData` and explicit approval of the supported seven-line sign-in challenge. The server must verify the response before login.

## connection.fundingReceipt

The contract integration is shipped in SDK `0.1.2`, published on [npm](https://www.npmjs.com/package/@privatar-wallet/sdk). Request `fundingReceipts` on Preview to protect or recover encrypted on-chain envelopes. Recovery returns read-only receipt fields without withdrawal authorizers. Restoring the original recovery phrase inside Privatar restores receipt access. Claim preparation also requires `proving` and `transactions`; the resulting proven transaction still needs the normal balance, sign and submission reviews.

Contribution amounts and campaign totals remain public. Older campaigns without encrypted receipt envelopes require their original private backup. Never ask for recovery words on a website.

## Disconnect

TypeScript

```
const unsubscribe = connection.onDisconnect(() => {
  clearWalletState();
});

await connection.disconnect();
unsubscribe();
```

Handle disconnection, revoked permissions, declined requests, expiry, and relay failures as normal user-facing states. Clear access-dependent UI when the session ends.
