> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privacyboost.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Api reference

# API Reference

Complete API reference for the Privacy Boost React SDK.

## Generated Documentation

Full API documentation can be generated using TypeDoc:

```bash theme={null}
# From packages/privacy-boost-react directory
npm run docs

# Documentation will be generated in docs/api/
```

The generated docs include:

* All hook signatures and return types
* JSDoc comments with usage examples
* Type definitions and interfaces

***

## Provider

### `PrivacyBoostProvider`

Main provider component that initializes the SDK.

```tsx theme={null}
<PrivacyBoostProvider
  config={PrivacyBoostConfig}
  loadingComponent?: ReactNode
  errorComponent?: (error: Error) => ReactNode
>
  {children}
</PrivacyBoostProvider>

// Or with pre-initialized SDK
<PrivacyBoostProvider sdk={PrivacyBoost}>
  {children}
</PrivacyBoostProvider>
```

***

## Context Hooks

### `usePrivacyBoost()`

Get direct access to the SDK instance.

```tsx theme={null}
function usePrivacyBoost(): PrivacyBoost | null
```

### `usePrivacyBoostState()`

Get provider initialization state.

```tsx theme={null}
function usePrivacyBoostState(): {
  loading: boolean;
  error: Error | null;
  initialized: boolean;
}
```

***

## useAuth

Authentication hook.

```tsx theme={null}
function useAuth(): UseAuthResult

interface UseAuthResult {
  // State
  isConnected: boolean;
  isAuthenticated: boolean;
  isWalletAvailable: boolean;
  address: string | null;
  privacyAddress: string | null;
  mpk: string | null;

  // Methods
  authenticate(adapter: WalletAdapter, options?: AuthenticateOptions): Promise<AuthResult>;
  authenticateWithWalletAdapter(options?: AuthenticateOptions): Promise<AuthResult>;
  logout(): Promise<void>;
  clearSession(): Promise<void>;
}
```

***

## useVault

Vault operations hook.

```tsx theme={null}
function useVault(): UseVaultResult

interface UseVaultResult {
  shield(params: SimpleShieldParams): Promise<ShieldResult>;
  unshield(params: SimpleUnshieldParams): Promise<UnshieldResult>;
  send(params: SimpleSendParams): Promise<TransactionResult>;
  getBalance(tokenAddress: string): Promise<TokenBalance>;
  getAllBalances(): Promise<TokenBalance[]>;
  getTokens(): Promise<TokenMetadata[]>;
  /** Force a server refresh of one token's balance. */
  refreshBalance(tokenAddress: Hex): Promise<void>;
  /** Force a server refresh of all tracked balances. */
  refreshBalances(): Promise<void>;
}

interface SimpleShieldParams {
  tokenAddress: Hex;
  /** Either a human-readable string (e.g. "1.5") or a wei `bigint`. Strings are parsed using the token's `decimals`. */
  amount: string | bigint;
  onProgress?: OnProgress;
}

interface SimpleUnshieldParams {
  tokenAddress: Hex;
  amount: string | bigint;
  /** Defaults to the connected wallet address. */
  recipientAddress?: Hex;
  onProgress?: OnProgress;
}

interface SimpleSendParams {
  to: Hex | string;
  tokenAddress: Hex;
  amount: string | bigint;
}
```

***

## useBalances

Reactive balance data hook.

```tsx theme={null}
function useBalances(): UseBalancesResult

interface UseBalancesResult {
  balances: FormattedBalance[];
  loading: boolean;
  lastSynced: number | null;
  getBalance(tokenAddress: string): FormattedBalance | undefined;
  getShieldedBalance(tokenAddress: string): bigint;
  getWalletBalance(tokenAddress: string): bigint;
  totalShielded: bigint;
  tokenCount: number;
}

interface FormattedBalance extends TokenBalance {
  formattedShielded: string;
  formattedWallet: string;
}
```

***

## useTransactions

Transaction history hook.

```tsx theme={null}
function useTransactions(): UseTransactionsResult

interface UseTransactionsResult {
  transactions: Transaction[];
  recentTransactions: Transaction[];
  pending: Transaction[];
  isLoading: boolean;
  hasPending: boolean;
  pendingCount: number;
  deposits: Transaction[];
  withdrawals: Transaction[];
  transfers: Transaction[];
  fetchHistory(params?: TransactionHistoryParams): Promise<Transaction[]>;
  refreshPending(): Promise<number>;
  getByHash(txHash: string): Transaction | undefined;
  getByType(type: TransactionType): Transaction[];
  getByStatus(status: TransactionStatus): Transaction[];
}

interface TransactionHistoryParams {
  type?: 'shield' | 'unshield' | 'transfer';
  tokenAddress?: string;
  limit?: number;
}
```

***

## useChain

Get a chain-scoped client for [multi-chain](/sdk/concepts/multi-chain) operations.

```tsx theme={null}
function useChain(config: ChainClientConfig): ChainClient | null

interface ChainClientConfig {
  /** Server URL for the chain. Required. */
  serverUrl: string;
  /** EVM chain ID. Auto-discovered from the server when omitted. */
  chainId?: number;
  /** Shield contract address on this chain. Auto-discovered when omitted. */
  shieldContractAddress?: string;
  /** WETH address on this chain. Required for native-ETH flows. */
  wethContractAddress?: string;
  rpcUrl?: string;
  tokenRegistryAddress?: string;
}
```

The returned `ChainClient` exposes the same `vault`, `auth`, and `transactions` resources as the root SDK, scoped to the target chain. Returns `null` until the provider has finished initializing. The hook memoizes by `serverUrl`, so changing other fields between renders is ignored — pass a stable config or a new `serverUrl` to switch chains.

***

## Helper Functions

### `createWalletAdapter()`

Create wallet adapter from `window.ethereum`.

```tsx theme={null}
function createWalletAdapter(): WalletAdapter
```

***

## Types

### PrivacyBoostConfig

```typescript theme={null}
interface PrivacyBoostConfig {
  appId: string;
  serverUrl: string;
  chainId?: number;                 // Auto-discovered from server if omitted
  shieldContractAddress?: string;   // Auto-discovered from server if omitted
  wethContractAddress?: string;
  rpcUrl?: string;
  tokenRegistryAddress?: string;
  persistence?: {
    storage: 'localStorage' | 'indexedDB' | 'osKeychain';
    unlock?: 'none' | 'pin' | 'password';
  };
}
```

### Transaction

```typescript theme={null}
interface ReceiverTransfer {
  pubKey: Hex;
  amount: bigint;
}

interface Transaction {
  txHash: Hex;
  type: 'shield' | 'unshield' | 'transfer';
  direction: 'incoming' | 'outgoing';
  status: 'pending' | 'preconfirmed' | 'completed' | 'failed' | 'blocked';
  tokenAddress?: Hex;
  amount?: bigint;
  receivers: ReceiverTransfer[];
  createdAt: number;
  updatedAt: number;
  to?: Hex;
  from?: Hex;
  error?: string;
  tokenSymbol?: string;
  commitment?: Hex;
  complianceStatus?: ComplianceStatus;  // 'PENDING' | 'LEGIT' | 'ILLICIT'
}
```

### TokenBalance

```typescript theme={null}
interface TokenBalance {
  tokenAddress: Hex;
  /** Private balance held in the shielded pool, in token wei. */
  shieldedBalance: bigint;
  /** Public balance in the connected wallet, in token wei. */
  walletBalance: bigint;
  symbol?: string;
  decimals?: number;
  /** Number of unspent notes contributing to `shieldedBalance`. */
  noteCount?: number;
}
```

`useBalances()` returns `FormattedBalance` values, which extend `TokenBalance` with `formattedShielded` / `formattedWallet` strings already formatted with the token's `decimals`.

### OnProgress

```typescript theme={null}
type OnProgress = (progress: {
  step: ShieldStep | UnshieldStep;
  message: string;
  txHash?: Hex;
}) => void;
```

***

## Preview Features

The React SDK does not yet expose dedicated hooks for the two preview features
(pending external audit). Access them through the underlying SDK via
[`usePrivacyBoost()`](#context-hooks):

* [Claimable Transfers](/sdk/react/guides/claimable-transfers) — gifts, via `sdk.wasm`
* [Portal Deposits](/sdk/react/guides/portal-deposits) — via `sdk.portal`