SocketFi Class — Client SDK Constructor Reference

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

import { SocketFi } from '@socketfi/react';

const socketfi = new SocketFi(config: SocketFiConfig);

Configuration parameters

string

required

Your application’s unique SocketFi identifier, obtained from the Developer Portal. This value scopes all authentication and transaction requests to your specific application.

clientId: 'sf_live_xxxxx'

'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.

network: 'MAINNET'

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.

Show brand fields

string

Your application’s display name, shown in the authentication popup header.

appName: 'Acme Pay'

string

A CSS hex color string used as the primary accent color inside the authentication popup.

primaryColor: '#4F46E5'

(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.

onSuccess: (session) => {
  console.log('Authenticated:', session.userProfile.id);
}

(error: SocketFiError) => void

An optional callback invoked when any SDK operation fails. Receives a SocketFiError with a code and message. See the Errors reference for the full list of error codes.

onError: (error) => {
  console.error('SocketFi error:', error.code, error.message);
}

Initialization example

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.

// 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',
  },
});

// Any component or module
import { socketfi } from '@/lib/socketfi';

const session = await socketfi.authenticate();

Your clientId is available in the SocketFi Developer Portal under Applications → Your App → Settings. Keep your production clientId in an environment variable and never commit it directly to source control.

TypeScript interfaces

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;
}

React SDK

React Native SDK

Server SDK

API Reference

SocketFi Class — Client SDK Constructor Reference

Constructor signature

Configuration parameters

Initialization example

Singleton pattern

TypeScript interfaces

​Constructor signature

​Configuration parameters

​Initialization example

​Singleton pattern

​TypeScript interfaces

Constructor signature

Configuration parameters

Initialization example

Singleton pattern

TypeScript interfaces