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

# SocketFi Class — Client SDK Constructor Reference

> Create and configure a SocketFi client instance. The SocketFi constructor is the main entry point for passkey authentication and smart wallet operations.

The `SocketFi` class is the single entry point for all client-side SDK operations. Instantiating it with your application's `clientId` and desired configuration gives you an object from which you can authenticate users, request transactions, and read smart contract data. You create the instance once, configure it with your branding and network settings, and reuse it everywhere in your application.

## Constructor signature

```typescript theme={null}
import { SocketFi } from '@socketfi/react';

const socketfi = new SocketFi(config: SocketFiConfig);
```

## Configuration parameters

<ParamField path="clientId" type="string" required>
  Your application's unique SocketFi identifier, obtained from the [Developer Portal](https://portal.socketfi.com). This value scopes all authentication and transaction requests to your specific application.

  ```typescript theme={null}
  clientId: 'sf_live_xxxxx'
  ```
</ParamField>

<ParamField path="network" type="'TESTNET' | 'MAINNET'" default="'TESTNET'">
  The Stellar network to target. Use `'TESTNET'` during development and `'MAINNET'` for production. All wallet operations — including transaction submission and contract reads — are directed to the selected network.

  ```typescript theme={null}
  network: 'MAINNET'
  ```
</ParamField>

<ParamField path="brand" type="object">
  Optional branding overrides that appear inside the SocketFi hosted authentication popup. Customize these to keep the sign-in experience consistent with your product's visual identity.

  <Expandable title="brand fields">
    <ParamField path="brand.appName" type="string">
      Your application's display name, shown in the authentication popup header.

      ```typescript theme={null}
      appName: 'Acme Pay'
      ```
    </ParamField>

    <ParamField path="brand.primaryColor" type="string">
      A CSS hex color string used as the primary accent color inside the authentication popup.

      ```typescript theme={null}
      primaryColor: '#4F46E5'
      ```
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="onSuccess" type="(session: Session) => void">
  An optional callback invoked after the user successfully authenticates. Receives the full `Session` object, including the user profile and the SocketFi access token. Use this as an alternative to `await authenticate()` when you prefer an event-driven integration style.

  ```typescript theme={null}
  onSuccess: (session) => {
    console.log('Authenticated:', session.userProfile.id);
  }
  ```
</ParamField>

<ParamField path="onError" type="(error: SocketFiError) => void">
  An optional callback invoked when any SDK operation fails. Receives a `SocketFiError` with a `code` and `message`. See the [Errors reference](/api-reference/errors) for the full list of error codes.

  ```typescript theme={null}
  onError: (error) => {
    console.error('SocketFi error:', error.code, error.message);
  }
  ```
</ParamField>

## Initialization example

```typescript theme={null}
import { SocketFi } from '@socketfi/react';

const socketfi = new SocketFi({
  clientId: 'sf_live_xxxxx',
  network: 'MAINNET',
  brand: {
    appName: 'Acme Pay',
    primaryColor: '#4F46E5',
  },
  onSuccess: (session) => {
    console.log('User authenticated:', session.userProfile.id);
    console.log('Access token:', session.socketfiAccessToken);
  },
  onError: (error) => {
    console.error(`[${error.code}] ${error.message}`);
  },
});
```

## Singleton pattern

Create **one** `SocketFi` instance and export it for use across your application. Instantiating multiple instances can lead to duplicate authentication popups, inconsistent session state, and redundant network requests.

```typescript theme={null}
// lib/socketfi.ts
import { SocketFi } from '@socketfi/react';

export const socketfi = new SocketFi({
  clientId: process.env.NEXT_PUBLIC_SOCKETFI_CLIENT_ID!,
  network: process.env.NODE_ENV === 'production' ? 'MAINNET' : 'TESTNET',
  brand: {
    appName: 'My App',
    primaryColor: '#6366F1',
  },
});
```

```typescript theme={null}
// Any component or module
import { socketfi } from '@/lib/socketfi';

const session = await socketfi.authenticate();
```

<Note>
  Your `clientId` is available in the [SocketFi Developer Portal](https://portal.socketfi.com) under **Applications → Your App → Settings**. Keep your production `clientId` in an environment variable and never commit it directly to source control.
</Note>

## TypeScript interfaces

```typescript theme={null}
interface SocketFiConfig {
  clientId: string;
  network?: 'TESTNET' | 'MAINNET';
  brand?: {
    appName?: string;
    primaryColor?: string;
  };
  onSuccess?: (session: Session) => void;
  onError?: (error: SocketFiError) => void;
}

interface Session {
  userProfile: UserProfile;
  socketfiAccessToken: string;
}

interface UserProfile {
  id: string;
}

interface SocketFiError {
  code: string;
  message: string;
}
```