SocketFi React SDK Installation, Setup, and Config

Installing the SocketFi React SDK takes three steps: add the package, set your environment variables, and create a shared client instance. Once that’s done, every component in your app can authenticate users and submit transactions through a single import.

Install the package

npm install @socketfi/react

yarn add @socketfi/react

pnpm add @socketfi/react

Prerequisites

Before initializing the client, make sure you have:

A SocketFi account and a registered application in the Developer Portal
Your application’s Client ID (found on the application detail page)
React 18 or later installed in your project
TypeScript configured (recommended)

Set up environment variables

Store your Client ID in an environment variable rather than hard-coding it. The variable name you use depends on your build tool.

Vite
Next.js

Add the following to your .env file:

VITE_SOCKETFI_CLIENT_ID=your_client_id_here

Access it in your code with:

import.meta.env.VITE_SOCKETFI_CLIENT_ID

Add the following to your .env.local file:

NEXT_PUBLIC_SOCKETFI_CLIENT_ID=your_client_id_here

Access it in your code with:

process.env.NEXT_PUBLIC_SOCKETFI_CLIENT_ID

Never commit your .env or .env.local files to source control. Add them to .gitignore. Your Client ID ties requests to your registered application, so treat it like an API key.

Initialize the SocketFi client

Create a dedicated file (e.g. lib/socketfi.ts) that exports a single shared client instance. Import this instance wherever you need SDK functionality.

lib/socketfi.ts

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

export const socketfi = new SocketFi({
  clientId: import.meta.env.VITE_SOCKETFI_CLIENT_ID,
  network: "TESTNET",
});

Configuration options

string

required

Your SocketFi application Client ID, obtained from the Developer Portal. This value identifies your app during hosted authentication and transaction approval flows.

"TESTNET" | "MAINNET"

required

The Stellar/Soroban network to target. Use "TESTNET" during development and "MAINNET" for production. Defaults to "TESTNET".

string

The name of your application. Displayed on hosted authentication, sign-up, and transaction approval screens.

string

A hex color code (e.g. "#4F46E5") used as the primary accent color across hosted SocketFi screens.

(session: Session) => void

A global callback invoked after every successful authentication. Useful for updating application-level state without coupling the callback to a specific component.

(error: Error) => void

A global callback invoked when any SDK flow fails. You should still use try/catch around individual calls for component-level error handling.

Full configuration example

lib/socketfi.ts

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

export const socketfi = new SocketFi({
  clientId: import.meta.env.VITE_SOCKETFI_CLIENT_ID,
  network: "TESTNET",

  brand: {
    appName: "Acme Pay",
    primaryColor: "#4F46E5",
  },

  onSuccess(session) {
    console.log("SocketFi session created:", session);
  },

  onError(error) {
    console.error("SocketFi error:", error);
  },
});

Minimal working example

With the client initialized, you can authenticate a user from any component:

App.tsx

import { socketfi } from "./lib/socketfi";

export default function App() {
  async function handleLogin() {
    try {
      const session = await socketfi.authenticate();
      console.log("Signed in:", session.userProfile.id);
    } catch (error) {
      console.error("Login failed:", error);
    }
  }

  return <button onClick={handleLogin}>Continue with SocketFi</button>;
}

Switch network to "MAINNET" and update your environment variable when you’re ready for production. No other code changes are required.

React SDK

React Native SDK

Server SDK

API Reference

SocketFi React SDK Installation, Setup, and Config

Install the package

Prerequisites

Set up environment variables

Initialize the SocketFi client

Configuration options

Full configuration example

Minimal working example

​Install the package

​Prerequisites

​Set up environment variables

​Initialize the SocketFi client

​Configuration options

​Full configuration example

​Minimal working example

Install the package

Prerequisites

Set up environment variables

Initialize the SocketFi client

Configuration options

Full configuration example

Minimal working example